Tu IA no necesita tu pantalla: ¡Un semáforo te lo dirá todo!

Descripción general: Cómo funciona CursorLight

CursorLight convierte un económico juguete de semáforo de escritorio en una lámpara de estado física para Cursor Agent, para que no tengas que mirar la pantalla mientras la IA trabaja. Un vistazo muestra si el agente está pensando, ocupado, esperando una entrada o ha terminado, y si lo hizo con éxito o falló.

El juguete se recablea para que un ESP32‑C3 SuperMini controle sus tres LEDs originales. El ESP32 actúa como periférico BLE (sin Wi‑Fi). Un script Python en el ordenador envía cadenas cortas de modo (thinking, success, etc.) por BLE, y el firmware las traduce en efectos de persecución, parpadeo o luz fija con tiempos de espera automáticos. Cursor Hooks ubicados en ~/.cursor/hooks ejecutan el script ante eventos del agente, haciendo la lámpara completamente automática.

Hardware y cableado

Cableado (placa de ánodo común):
3.3 V del ESP32 → terminal + de la lámpara (ánodo común).
IO2 → 220Ω → L1 (verde), IO3 → 220Ω → L2 (amarillo), IO4 → 220Ω → L3 (rojo).
Dejar el cable negativo de la lámpara desconectado.

Precauciones: Soldar solo en las pistas expuestas o patillas de componentes. Comprobar que no haya cortocircuitos con un multímetro antes de alimentar. Para un montaje permanente, aliviar la tensión de los cables con pegamento termofusible.

Configuración del software y flasheo

Instalar Arduino IDE 2.x y añadir el paquete de placa esp32 de Espressif Systems (Gestor de placas → buscar “esp32” → instalar “esp32 by Espressif Systems”). En el ordenador, instalar la librería Python bleak:

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

En Arduino IDE, seleccionar la placa ESP32C3 Dev Module, establecer USB CDC On Boot en Enabled, abrir el sketch del firmware y hacer clic en Upload. Si la carga se detiene en “Connecting…”, mantener pulsado BOOT, hacer clic en Upload, y soltar BOOT cuando comience la escritura.

Abrir el Monitor Serie (115200 baudios) y presionar RST. Deberías ver:
BLE device name: CursorLight
y una lista de modos soportados.

Control manual y modos de luz

Prueba la lámpara directamente con el script Python:

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

Integración automática con Cursor Agent

Colocar el conjunto de hooks dentro de ~/.cursor/hooks/cursor-light/ (macOS) o %USERPROFILE%\.cursor\hooks\cursor-light\ (Windows). Contiene:

• agent‑light.sh – decide el modo a partir del estado del agente
• ble_gate.py – filtra llamadas rápidas para que la lámpara no parpadee
• cursor_light_ble_enhanced.py – el escritor BLE directo
• hook‑*.sh – puntos de entrada para Cursor Hook

Fusionar el hooks.json.snippet incluido en tu ~/.cursor/hooks.json existente (no sobrescribir a ciegas). Reiniciar Cursor – la lámpara se encenderá automáticamente mientras el agente trabaja. La siguiente parte muestra los comandos de instalación exactos.

# 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"

Configuración, tiempos de espera y limitaciones

Parámetros BLE (fijos):
Nombre del dispositivo: CursorLight
UUID del servicio: b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001
UUID de la característica: b8b7e002-…
No se requiere emparejamiento.

Asignación de GPIO: IO2 → verde (L1), IO3 → amarillo (L2), IO4 → rojo (L3).

Auto‑timeout: Después de 5 minutos en cualquier modo activo (thinking, busy, success, error, etc.), la lámpara cambia a traffic.
Después de 10 minutos en traffic se apaga.
Esto evita que una lámpara permanezca encendida indefinidamente si un hook no cierra un estado.

Limitaciones conocidas:
• Solo placas de lámpara de ánodo común.
• Sin Wi‑Fi: el control es por BLE directo desde el host; el alcance es aproximadamente la misma habitación.
• Los scripts de hooks en Windows necesitan Git Bash actualmente.
• No hay actualizaciones de firmware OTA (solo flasheo por USB).
• Se pueden producir daños en el hardware si se omiten las resistencias o el cableado es incorrecto; usa un multímetro.

Solución de problemas y Best Practices

Best practices

• Habilita siempre USB CDC On Boot en el Arduino IDE antes de flashear.
• Después de cualquier cambio en el cableado, prueba todos los modos manualmente (green, thinking, busy, alarm, success, off).
• Deja que ble_gate.py gestione la concurrencia; nunca llames al escritor BLE directamente desde varios hooks.
• Fusiona hooks.json con cuidado y reinicia Cursor después.
• En macOS, otorga permiso a tu terminal para Bluetooth en System Settings → Privacy & Security → Bluetooth.
• Deja que el auto‑timeout actúe como red de seguridad: tus scripts pueden simplemente lanzar la orden y olvidarse.
• Asegura todas las conexiones de cables con pegamento termofusible o resina UV.

Síntomas comunes

• Lámpara no encontrada – verifica la alimentación del ESP32, el nombre BLE CursorLight, el Bluetooth del ordenador y los permisos del terminal en macOS.
• Fallo de escritura – comprueba que los UUID de servicio y característica coinciden con los del firmware.
• El efecto parpadea – asegúrate de que ble_gate.py está en la cadena de hooks.
• Cursor no activa los hooks – revisa que hooks.json se haya fusionado correctamente y reinicia Cursor.
• La lámpara se queda atascada en busy/thinking – el auto‑timeout la limpiará tras 5 minutos; revisa ble.log en la carpeta del bundle.
• Colores incorrectos – confirma el cableado: IO2→green, IO3→yellow, IO4→red.