Il Tuo Semaforo da Scrivania È Molto Più di un Giocattolo

Panoramica: Come Funziona CursorLight

CursorLight trasforma un economico giocattolo da scrivania a forma di semaforo in una lampada di stato fisica per Cursor Agent, così non devi guardare lo schermo mentre l'IA lavora. Basta un'occhiata per sapere se l'agente sta pensando, è occupato, in attesa di input, o ha finito — e se l'operazione è riuscita o fallita.

Il giocattolo viene ricablato in modo che un ESP32‑C3 SuperMini controlli i suoi tre LED originali. L'ESP32 funge da periferica BLE (senza Wi‑Fi). Uno script Python sul computer invia brevi stringhe di modalità (thinking, success, ecc.) via BLE, e il firmware le traduce in effetti di inseguimento, lampeggio o luce fissa con timeout automatici. Gli Hook di Cursor posizionati in ~/.cursor/hooks attivano lo script in risposta agli eventi dell'agente, rendendo la lampada completamente automatica.

Hardware e Cablaggio

Cablaggio (scheda ad anodo comune):
ESP32 3.3 V → terminale + della lampada (anodo comune).
IO2 → 220Ω → L1 (verde), IO3 → 220Ω → L2 (giallo), IO4 → 220Ω → L3 (rosso).
Lascia scollegato il filo negativo della lampada.

Attenzione: Saldare solo su piazzole esposte o terminali dei componenti. Verificare l'assenza di cortocircuiti con un multimetro prima di alimentare. Per una costruzione permanente, fissare i fili con colla a caldo per alleviare la tensione.

Configurazione Software e Flashing

Installa Arduino IDE 2.x e aggiungi il pacchetto schede esp32 di Espressif Systems (Gestione Schede → cerca "esp32" → installa "esp32 by Espressif Systems"). Sul computer, installa la libreria Python bleak:

macOS: python3 -m pip install bleak
Windows: py -3 -m pip install bleak

Nell'IDE Arduino, seleziona la scheda ESP32C3 Dev Module, imposta USB CDC On Boot su Enabled, apri lo sketch del firmware e clicca Upload. Se il caricamento si blocca su "Connecting…", tieni premuto BOOT, clicca Upload, e rilascia BOOT quando inizia la scrittura.

Apri il Monitor Seriale (115 200 baud) e premi RST. Dovresti vedere:
BLE device name: CursorLight
e un elenco delle modalità supportate.

Controllo Manuale e Modalità Luminose

Prova la lampada direttamente con lo script Python:

macOS: python3 cursor_light_ble_enhanced.py thinking
Windows: py -3 cursor_light_ble_enhanced.py thinking

Integrazione Automatica con Cursor Agent

Posiziona il pacchetto di hook all'interno di ~/.cursor/hooks/cursor-light/ (macOS) o %USERPROFILE%\.cursor\hooks\cursor-light\ (Windows). Contiene:

• agent‑light.sh – decide la modalità in base allo stato dell'agente
• ble_gate.py – attenua le chiamate rapide così la lampada non sfarfalla
• cursor_light_ble_enhanced.py – lo scrittore BLE diretto
• hook‑*.sh – punti di ingresso degli Hook di Cursor

Unisci il file hooks.json.snippet incluso nel tuo ~/.cursor/hooks.json esistente (non sovrascrivere ciecamente). Riavvia Cursor – la lampada ora si illuminerà automaticamente mentre l'agente lavora. La parte successiva mostra i comandi esatti per l'installazione.

# macOS install
mkdir -p ~/.cursor/hooks/cursor-light
cd ~/.cursor/hooks/cursor-light
unzip ~/Downloads/cursor-light-bundle.zip
chmod +x *.sh
python3 -m pip install --user bleak
mkdir -p ~/.cursor
cp hooks.json.snippet ~/.cursor/hooks.json   # merge manually if the file already exists

# Windows install (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.cursor\hooks\cursor-light"
Expand-Archive "$env:USERPROFILE\Downloads\cursor-light-bundle.zip" "$env:USERPROFILE\.cursor\hooks\cursor-light" -Force
Set-Location "$env:USERPROFILE\.cursor\hooks\cursor-light"
py -m pip install --user bleak
New-Item -ItemType Directory -Force "$env:USERPROFILE\.cursor"
Copy-Item ".\hooks.json.snippet" "$env:USERPROFILE\.cursor\hooks.json"

Configurazione, Timeout e Limitazioni

Parametri BLE (fissi):
Nome dispositivo: CursorLight
Service UUID: b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001
Characteristic UUID: b8b7e002-…
Nessun pairing richiesto.

Assegnazione GPIO: IO2 → verde (L1), IO3 → giallo (L2), IO4 → rosso (L3).

Auto‑timeout: Dopo 5 minuti in qualsiasi modalità attiva (thinking, busy, success, error, ecc.) la lampada passa a traffic. Dopo 10 minuti in traffic si spegne. Ciò impedisce che la lampada rimanga accesa a tempo indeterminato se un hook non riesce a chiudere uno stato.

Limitazioni note:
• Solo schede lampade ad anodo comune.
• Nessun Wi‑Fi – il controllo è diretto via BLE dall'host; la portata è approssimativamente la stessa stanza.
• Gli script hook su Windows necessitano attualmente di Git Bash.
• Nessun aggiornamento firmware OTA (solo flashing via USB).
• Possibili danni hardware se si omettono le resistenze o il cablaggio è errato; utilizzare un multimetro.

Risoluzione dei problemi e Best Practices

Best practices

• Abilitare sempre USB CDC On Boot nell'IDE di Arduino prima del flashing.
• Dopo ogni modifica del cablaggio, testare manualmente tutte le modalità (green, thinking, busy, alarm, success, off).
• Lasciare che ble_gate.py gestisca la concorrenza – non chiamare mai lo scrittore BLE direttamente da più hook.
• Unire con attenzione hooks.json e riavviare Cursor successivamente.
• Su macOS, consentire al terminale l'accesso Bluetooth in System Settings → Privacy & Security → Bluetooth.
• Lasciare che l'auto‑timeout funga da rete di sicurezza – gli script possono essere semplicemente lanciati e dimenticati (fire and forget).
• Fissare tutte le connessioni dei fili con colla a caldo o resina UV.

Sintomi comuni

• Lampada non trovata – verificare l'alimentazione dell'ESP32, il nome BLE CursorLight, il Bluetooth del computer, i permessi del terminale su macOS.
• Scrittura fallita – verificare che gli UUID di servizio e caratteristica corrispondano al firmware.
• Effetti lampeggianti – assicurarsi che ble_gate.py sia nella catena di hook.
• Cursor non attiva gli hook – verificare che hooks.json sia stato unito correttamente e riavviare Cursor.
• Lampada bloccata in busy/thinking – l'auto‑timeout la ripristinerà dopo 5 minuti; controllare ble.log nella cartella bundle.
• Colori errati – confermare il cablaggio: IO2→verde, IO3→giallo, IO4→rosso.