[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79665":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":28,"discoverSource":29},79665,"cursor_agent_status_light","JasonLam08\u002Fcursor_agent_status_light","JasonLam08","A BLE-powered status light for Cursor Agent, using ESP32-C3 to visualize AI coding states such as thinking, busy,  success, error, and waiting for user action. 基于 ESP32-C3 的 Cursor Agent BLE 状态灯，用红绿灯直观显示 AI 编程过程中的思考、忙碌、成功、错误以及等待用户操作 等状态。",null,"C++",221,31,118,2,0,3,16,92,14,4.52,false,"main",true,[],"2026-06-12 02:03:54","# CursorLight\n\n[English](#cursorlight-english)\n\n一个基于 **ESP32-C3 SuperMini + BLE 蓝牙** 的桌面状态灯项目，用红绿灯挂件直观显示 Cursor Agent \u002F AI 编程过程中的状态，例如思考中、执行中、成功、失败、等待用户操作等。\n\n> A BLE-powered status light for Cursor Agent, using ESP32-C3 to visualize AI coding states.\n\n---\n\n## 1. 项目简介\n\nCursorLight 将一个普通的红绿灯挂件改造成可由电脑控制的桌面状态灯。\n\n核心思路：\n\n- 使用 **ESP32-C3 SuperMini** 作为主控。\n- 复用红绿灯挂件内部原有三色灯板。\n- 通过 **BLE 蓝牙** 接收电脑端脚本发送的状态指令。\n- 结合 Cursor Hooks，让 Cursor Agent 的工作状态自动映射到灯效。\n\n本项目不依赖 Wi-Fi，电脑可以继续连接 5GHz 网络。ESP32-C3 只负责 BLE 通信和灯效控制。\n\n---\n\n## 2. 效果预览\n\n典型状态映射：\n\n| 场景 | 模式 | 灯效 |\n|---|---|---|\n| 开机展示 | `demo` | 自动展示多种灯效 |\n| AI 正在分析 | `thinking` | 连贯跑马灯 |\n| AI 正在生成 | `ai` | 柔和慢速跑马灯 |\n| 正在执行命令 | `busy` | 黄灯慢闪 |\n| 任务成功 | `success` | 绿灯常亮 |\n| 任务失败 | `error` | 红灯快闪 |\n| 严重异常 \u002F 阻塞 | `alarm` | 红黄交替警灯 |\n| 展示模式 | `traffic` | 模拟红绿灯 |\n| 关闭 | `off` | 全灭 |\n\n---\n\n## 3. 硬件清单\n\n| 类别 | 物料 | 数量 | 说明 |\n|---|---|---:|---|\n| 主体 | 红绿灯挂件 \u002F 玩具交通信号灯模型 | 1 个 | 淘宝 \u002F 1688 搜“红绿灯挂件”“交通信号灯挂件” |\n| 主控 | ESP32-C3 SuperMini 开发板 | 1 块 | 建议购买已焊针版本，USB-C 更方便 |\n| 限流 | 220Ω 1\u002F4w 电阻 | 3 只 | 建议买 10 只装备用 |\n| 连线 | 细导线 \u002F 飞线 | 若干 | 推荐 30AWG 硅胶线或漆包线 |\n| 供电 | USB-C 数据线 | 1 条 | 必须支持数据传输 |\n| 绝缘 | 热缩管 \u002F 绝缘胶带 | 少量 | 用于保护焊点 |\n| 工具 | 电烙铁、焊锡丝、镊子、剪线钳 | 若干 | 需要基础焊接工具 |\n| 检测 | 万用表 | 可选 | 推荐用于确认焊点和短路 |\n\n说明：\n\n- 本方案复用原玩具灯板，不需要额外购买红、黄、绿三颗 LED。\n- 改装后建议使用 USB 供电，不建议继续使用纽扣电池。\n- 每路灯建议串联 220Ω 电阻，用于保护 ESP32-C3 和原灯板。\n\n---\n\n## 4. 硬件接线\n\n本项目当前适配的是 **公共正极灯板**。\n\n实测灯位：\n\n| 灯位 | 实际颜色 | ESP32 引脚 |\n|---|---|---|\n| L1 | 绿灯 | IO2 |\n| L2 | 黄灯 | IO3 |\n| L3 | 红灯 | IO4 |\n\n接线方式：\n\n```text\nESP32 3.3V  -> 原灯板 + \u002F 原电池正极\nESP32 IO2   -> 220Ω -> L1 控制点 = 绿灯\nESP32 IO3   -> 220Ω -> L2 控制点 = 黄灯\nESP32 IO4   -> 220Ω -> L3 控制点 = 红灯\n\n原灯板 - \u002F 原电池负极：第一版先不要接\n```\n\n公共正极逻辑：\n\n```text\nGPIO LOW  = 灯亮\nGPIO HIGH = 灯灭\n```\n\n固件中已经处理了反相输出，正常使用时不需要手动关心高低电平。\n\n注意事项：\n\n- 只焊接在露出的金属焊盘、元件焊脚或电阻焊点上。\n- 不要焊在绿色阻焊层表面。\n- 焊接完成后，先用万用表检查是否短路，再接入电脑 USB 供电。\n- 如果用于成品交付，建议用热熔胶或 UV 胶固定飞线，避免拉断焊点。\n\n---\n\n## 5. 固件说明\n\n固件文件：\n\n```text\nESP32_C3_ToyBoard_CommonAnode_BLE_Enhanced_CursorLight.ino\n```\n\n固件特性：\n\n- BLE 广播名：`CursorLight`\n- 通信方式：BLE GATT 写入字符串\n- 默认开机模式：`demo`\n- 支持多种状态灯效\n- 内置自动超时，避免灯长时间高亮\n\nBLE 参数：\n\n```text\nDevice Name: CursorLight\nService UUID: b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001\nMode Characteristic UUID: b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001\n```\n\n---\n\n## 6. 烧录固件\n\n### 6.1 安装 Arduino IDE\n\n前往 Arduino 官方页面下载 Arduino IDE 2.x：\n\n```text\nhttps:\u002F\u002Fwww.arduino.cc\u002Fen\u002Fsoftware\n```\n\nmacOS：\n\n1. 下载 macOS 版本。\n2. 打开 `.dmg`。\n3. 将 Arduino IDE 拖入 Applications。\n4. 首次打开如有安全提示，按系统提示允许。\n\nWindows：\n\n1. 下载 Windows 安装包。\n2. 按安装向导完成安装。\n3. 如果系统提示安装驱动或允许网络访问，按需允许。\n\n---\n\n### 6.2 安装 ESP32 开发板包\n\n打开 Arduino IDE 后：\n\n1. 进入左侧 **Boards Manager**。\n2. 搜索 `esp32`。\n3. 安装 **esp32 by Espressif Systems**。\n4. 安装完成后重启 Arduino IDE。\n\n注意：不要把 **Arduino ESP32 Boards by Arduino** 作为本项目的主要板包。\n\n---\n\n### 6.3 选择开发板和端口\n\n连接 ESP32-C3 SuperMini 后，在 Arduino IDE 中选择：\n\n```text\nBoard: ESP32C3 Dev Module\nPort: 选择带 USB 标识的串口\n```\n\n常见端口：\n\n| 系统 | 端口示例 |\n|---|---|\n| macOS | `\u002Fdev\u002Fcu.usbmodemxxxx Serial Port (USB)` |\n| Windows | `COM3` \u002F `COM5` 等 |\n\n推荐设置：\n\n| 设置项 | 建议值 |\n|---|---|\n| USB CDC On Boot | Enabled |\n| Upload Speed | 921600 或默认值 |\n| Flash Size | 4MB 或默认值 |\n\n如果串口监视器没有输出，优先确认 `USB CDC On Boot` 是否已设为 `Enabled`，然后重新上传固件。\n\n---\n\n### 6.4 上传固件\n\n1. 用 Arduino IDE 打开 `.ino` 文件。\n2. 确认 Board 和 Port。\n3. 点击左上角 **Upload** 按钮。\n4. 上传成功时，Output 区域通常会看到：\n\n```text\nWriting at ... 100%\nHash of data verified.\nHard resetting via RTS pin...\n```\n\n如果出现 `Connecting...` 后失败，可尝试：\n\n```text\n按住 BOOT -> 点击 Upload -> 开始 Writing 后松开 BOOT\n```\n\n---\n\n### 6.5 串口检查\n\n打开 Serial Monitor，波特率选择：\n\n```text\n115200\n```\n\n按一下开发板 `RST`，正常会看到类似日志：\n\n```text\nPower on. Default mode: demo\nCommon anode BLE enhanced version.\nBLE device name: CursorLight\nBLE advertising started.\nSupported modes:\ndemo \u002F thinking \u002F ai \u002F busy \u002F success \u002F error \u002F alarm \u002F traffic \u002F off \u002F red \u002F yellow \u002F green\n```\n\n---\n\n## 7. BLE 控制脚本\n\n电脑端通过 Python 脚本控制灯效：\n\n```text\ncursor_light_ble_enhanced.py\n```\n\n### 7.1 安装依赖\n\nmacOS：\n\n```bash\npython3 -m pip install bleak\n```\n\nWindows：\n\n```powershell\npy -3 -m pip install bleak\n```\n\nmacOS 如果提示 `Bluetooth device is turned off`，但系统蓝牙已经打开，请到：\n\n```text\n系统设置 -> 隐私与安全性 -> 蓝牙\n```\n\n给 Terminal、iTerm、Cursor 或当前终端应用授权。\n\n---\n\n### 7.2 手动测试\n\nmacOS：\n\n```bash\npython3 cursor_light_ble_enhanced.py demo\npython3 cursor_light_ble_enhanced.py thinking\npython3 cursor_light_ble_enhanced.py ai\npython3 cursor_light_ble_enhanced.py busy\npython3 cursor_light_ble_enhanced.py success\npython3 cursor_light_ble_enhanced.py error\npython3 cursor_light_ble_enhanced.py alarm\npython3 cursor_light_ble_enhanced.py traffic\npython3 cursor_light_ble_enhanced.py off\n```\n\nWindows：\n\n```powershell\npy -3 cursor_light_ble_enhanced.py demo\npy -3 cursor_light_ble_enhanced.py thinking\npy -3 cursor_light_ble_enhanced.py ai\npy -3 cursor_light_ble_enhanced.py busy\npy -3 cursor_light_ble_enhanced.py success\npy -3 cursor_light_ble_enhanced.py error\npy -3 cursor_light_ble_enhanced.py alarm\npy -3 cursor_light_ble_enhanced.py traffic\npy -3 cursor_light_ble_enhanced.py off\n```\n\n---\n\n## 8. 固件模式\n\n| mode | 灯效说明 | 典型用途 |\n|---|---|---|\n| `demo` | 默认开机展示，循环展示多种灯效 | 演示、待机展示 |\n| `thinking` | 连贯跑马灯：L1 绿 -> L2 黄 -> L3 红 | AI 分析、规划中 |\n| `ai` | 柔和慢速跑马灯 | AI 生成内容、长任务处理中 |\n| `busy` | 黄灯慢闪 | 构建、测试、安装依赖 |\n| `success` | 绿灯常亮 | 任务成功 |\n| `error` | 红灯快闪 | 普通失败或报错 |\n| `alarm` | 红黄交替警灯，带短渐变 | 严重异常或阻塞 |\n| `traffic` | 红灯闪变绿，绿灯闪变黄，循环 | 展示或自动过渡 |\n| `off` | 全部关闭 | 关闭灯效 |\n| `red` | 红灯常亮 | 单灯测试 |\n| `yellow` | 黄灯常亮 | 等待人工处理 \u002F 单灯测试 |\n| `green` | 绿灯常亮 | 空闲 \u002F 单灯测试 |\n\n---\n\n## 9. 自动超时规则\n\n固件内置自动超时，避免状态灯长时间保持高亮。\n\n| 当前模式 | 自动行为 |\n|---|---|\n| `demo` \u002F `thinking` \u002F `ai` \u002F `busy` \u002F `success` \u002F `error` \u002F `alarm` \u002F `red` \u002F `yellow` \u002F `green` | 最多运行 5 分钟，然后自动进入 `traffic` |\n| `traffic` | 最多运行 10 分钟，然后自动 `off` |\n| `off` | 不自动切换 |\n\n---\n\n## 10. Cursor Hooks 集成\n\nCursorLight 可以通过用户目录下的 `.cursor\u002Fhooks` 与 Cursor Agent 联动。\n\n推荐安装目录：\n\n| 平台 | 目录 |\n|---|---|\n| macOS | `~\u002F.cursor\u002Fhooks\u002Fcursor-light\u002F` |\n| Windows | `%USERPROFILE%\\.cursor\\hooks\\cursor-light\\` |\n\n典型文件结构：\n\n```text\ncursor-light\u002F\n├─ install-cursor-light.sh\n├─ hooks.json.snippet\n├─ agent-light.sh\n├─ ble_gate.py\n├─ cursor_light_ble_enhanced.py\n├─ hook-*.sh\n└─ README.md\n```\n\n说明：\n\n- `cursor_light_ble_enhanced.py`：向 ESP32-C3 BLE GATT 特征写入 mode。\n- `ble_gate.py`：防抖、并发去重，避免多个 Hook 同时触发导致灯效乱跳。\n- `agent-light.sh`：统一处理 Agent 状态判断与模式切换。\n- `hook-*.sh`：各类 Cursor Hook 事件入口。\n- `hooks.json.snippet`：Cursor Hooks 配置片段。\n\n---\n\n## 11. macOS 安装 Cursor Hooks\n\n```bash\nmkdir -p ~\u002F.cursor\u002Fhooks\u002Fcursor-light\ncd ~\u002F.cursor\u002Fhooks\u002Fcursor-light\nunzip ~\u002FDownloads\u002Fcursor-light-bundle.zip\nchmod +x *.sh\n```\n\n安装依赖：\n\n```bash\npython3 -m pip install --user bleak\n```\n\n配置 Hooks：\n\n```bash\nmkdir -p ~\u002F.cursor\ncp hooks.json.snippet ~\u002F.cursor\u002Fhooks.json\n```\n\n如果已经存在 `~\u002F.cursor\u002Fhooks.json`，请手动合并，不要直接覆盖。\n\n自检：\n\n```bash\ncd ~\u002F.cursor\u002Fhooks\u002Fcursor-light\npython3 cursor_light_ble_enhanced.py green\npython3 cursor_light_ble_enhanced.py thinking\npython3 cursor_light_ble_enhanced.py busy\npython3 cursor_light_ble_enhanced.py alarm\npython3 cursor_light_ble_enhanced.py success\n```\n\n---\n\n## 12. Windows 安装 Cursor Hooks\n\n如果当前发布包只有 `.sh` Hook 入口，Windows 需要通过 Git Bash 执行，或后续提供 `.ps1` 版本入口。\n\nPowerShell 示例：\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\nExpand-Archive \"$env:USERPROFILE\\Downloads\\cursor-light-bundle.zip\" \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\" -Force\nSet-Location \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\n```\n\n安装依赖：\n\n```powershell\npy --version\npy -m pip install --user bleak\n```\n\n配置 Hooks：\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.cursor\"\nCopy-Item \".\\hooks.json.snippet\" \"$env:USERPROFILE\\.cursor\\hooks.json\"\n```\n\n如果已经存在 `hooks.json`，请手动合并。\n\n自检：\n\n```powershell\npy .\\cursor_light_ble_enhanced.py green\npy .\\cursor_light_ble_enhanced.py thinking\npy .\\cursor_light_ble_enhanced.py busy\npy .\\cursor_light_ble_enhanced.py alarm\npy .\\cursor_light_ble_enhanced.py success\n```\n\n---\n\n## 13. 推荐状态映射\n\n| Cursor \u002F 开发场景 | 推荐 mode |\n|---|---|\n| Agent 开始分析需求 | `thinking` |\n| Agent 正在生成或修改代码 | `ai` |\n| 执行终端命令 \u002F 构建 \u002F 测试 | `busy` |\n| 命令成功 \u002F 构建通过 \u002F 测试通过 | `success` |\n| 普通失败 \u002F 报错 | `error` |\n| 严重阻塞 \u002F 需要立即处理 | `alarm` |\n| 等待用户确认 | `yellow` |\n| 关闭灯效 | `off` |\n\n常见流程：\n\n```text\n普通任务：thinking -> busy -> success \u002F error\n等待确认：thinking -> yellow\n严重异常：busy -> alarm\n```\n\n---\n\n## 14. 日志与调试\n\nmacOS：\n\n```bash\ntail -f ~\u002F.cursor\u002Fhooks\u002Fcursor-light\u002Fble.log\n```\n\nWindows PowerShell：\n\n```powershell\nGet-Content \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\\ble.log\" -Wait\n```\n\n常见现象：\n\n| 现象 | 优先检查 |\n|---|---|\n| 找不到设备 | ESP32-C3 是否供电、BLE 广播名是否为 CursorLight、距离是否过远、系统蓝牙是否开启 |\n| 写入失败 | GATT UUID 是否一致 |\n| 灯效频繁跳变 | `ble_gate.py` 是否存在，Hook 是否重复注册 |\n| Cursor 没有触发 | `hooks.json` 是否加载，路径是否正确，是否重启 Cursor |\n| 一直停在 busy \u002F thinking | 可能是状态没有正确收口，检查 `ble_gate.py` 和 `state.json` |\n| 灯色不对应 | 确认 IO2=L1 绿，IO3=L2 黄，IO4=L3 红 |\n\n---\n\n## 15. 常见问题\n\n### Arduino IDE 搜不到 ESP32C3 Dev Module\n\n确认已安装：\n\n```text\nesp32 by Espressif Systems\n```\n\n安装后重启 Arduino IDE，并在：\n\n```text\nTools -> Board -> esp32\n```\n\n中查找 `ESP32C3 Dev Module`。\n\n### 看不到串口端口\n\n优先检查：\n\n- USB 线是否支持数据传输。\n- 是否换过 USB 口。\n- Windows 是否能在设备管理器中看到 COM 口。\n\n### 上传失败\n\n尝试：\n\n```text\n按住 BOOT -> 点击 Upload -> 开始 Writing 后松开 BOOT\n```\n\n同时关闭 Serial Monitor，避免串口被占用。\n\n### 串口无输出\n\n确认：\n\n```text\nUSB CDC On Boot = Enabled\n```\n\n然后重新上传固件，并打开 115200 波特率串口监视器。\n\n### 找不到 BLE 设备 CursorLight\n\n检查：\n\n- ESP32-C3 是否已通电。\n- 固件是否已成功运行。\n- BLE 名称是否为 `CursorLight`。\n- 电脑蓝牙是否打开。\n- macOS 是否给 Terminal \u002F Cursor 蓝牙权限。\n\n### macOS 提示 Bluetooth device is turned off\n\n即使系统蓝牙已打开，也可能是终端没有蓝牙权限。请到：\n\n```text\n系统设置 -> 隐私与安全性 -> 蓝牙\n```\n\n授权当前终端应用，然后重启终端。\n\n### python 命令不存在\n\nmacOS 默认通常使用：\n\n```bash\npython3\n```\n\nWindows 推荐使用：\n\n```powershell\npy -3\n```\n\n---\n\n## 16. 卸载\n\nmacOS：\n\n```bash\nrm -rf ~\u002F.cursor\u002Fhooks\u002Fcursor-light\nnano ~\u002F.cursor\u002Fhooks.json\n```\n\nWindows PowerShell：\n\n```powershell\nRemove-Item -Recurse -Force \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\nnotepad \"$env:USERPROFILE\\.cursor\\hooks.json\"\n```\n\n删除 `hooks.json` 中 cursor-light 相关配置后，重启 Cursor。\n\n---\n\n## 17. 参考链接\n\n- Arduino IDE 下载页：`https:\u002F\u002Fwww.arduino.cc\u002Fen\u002Fsoftware`\n- Arduino IDE 安装说明：`https:\u002F\u002Fsupport.arduino.cc\u002Fhc\u002Fen-us\u002Farticles\u002F360019833020-Download-and-install-Arduino-IDE`\n- Arduino-ESP32 安装文档：`https:\u002F\u002Fdocs.espressif.com\u002Fprojects\u002Farduino-esp32\u002Fen\u002Flatest\u002Finstalling.html`\n\n---\n\n# CursorLight (English)\n\n[中文](#cursorlight)\n\nA desktop status light project based on **ESP32-C3 SuperMini + BLE Bluetooth**. It turns a toy traffic-light ornament into a visual indicator for Cursor Agent \u002F AI coding states—thinking, executing, success, failure, waiting for user input, and more.\n\n> A BLE-powered status light for Cursor Agent, using ESP32-C3 to visualize AI coding states.\n\n---\n\n## 1. Project Overview\n\nCursorLight repurposes an ordinary traffic-light desk ornament into a computer-controlled status lamp.\n\nCore ideas:\n\n- Use **ESP32-C3 SuperMini** as the main controller.\n- Reuse the original three-color lamp board inside the ornament.\n- Receive status commands from a host script over **BLE Bluetooth**.\n- Integrate with Cursor Hooks so Cursor Agent activity maps automatically to light patterns.\n\nThis project does not use Wi-Fi. Your computer can stay on 5 GHz Wi-Fi; the ESP32-C3 only handles BLE and lighting.\n\n---\n\n## 2. Preview\n\nTypical state mapping:\n\n| Scenario | Mode | Effect |\n|---|---|---|\n| Power-on demo | `demo` | Cycles through multiple effects |\n| AI analyzing | `thinking` | Smooth chasing lights |\n| AI generating | `ai` | Soft, slow chasing lights |\n| Running commands | `busy` | Yellow slow blink |\n| Task succeeded | `success` | Green solid |\n| Task failed | `error` | Red fast blink |\n| Critical \u002F blocked | `alarm` | Alternating red\u002Fyellow warning |\n| Display mode | `traffic` | Simulated traffic light |\n| Off | `off` | All off |\n\n---\n\n## 3. Hardware Bill of Materials\n\n| Category | Item | Qty | Notes |\n|---|---|---:|---|\n| Body | Traffic-light ornament \u002F toy signal model | 1 | Search Taobao \u002F 1688 for “traffic light ornament” or “signal light ornament” |\n| MCU | ESP32-C3 SuperMini dev board | 1 | Pre-soldered headers and USB-C recommended |\n| Current limit | 220Ω resistors | 3 | Buy ~10 for spares |\n| Wire | Thin wire \u002F jumper wire | some | 30 AWG silicone or magnet wire recommended |\n| Power | USB-C data cable | 1 | Must support data, not charge-only |\n| Insulation | Heat shrink \u002F electrical tape | small | Protect solder joints |\n| Tools | Soldering iron, solder, tweezers, wire cutters | — | Basic soldering kit |\n| Test | Multimeter | optional | Check joints and shorts |\n\nNotes:\n\n- Reuses the toy lamp board; no separate red\u002Fyellow\u002Fgreen LEDs needed.\n- After mod, power via USB; coin cells are not recommended.\n- Use 220Ω in series per channel to protect the ESP32-C3 and original board.\n\n---\n\n## 4. Wiring\n\nThis build targets a **common-anode** lamp board.\n\nMeasured lamp positions:\n\n| Position | Color | ESP32 pin |\n|---|---|---|\n| L1 | Green | IO2 |\n| L2 | Yellow | IO3 |\n| L3 | Red | IO4 |\n\nWiring:\n\n```text\nESP32 3.3V  -> board + \u002F original battery +\nESP32 IO2   -> 220Ω -> L1 control = green\nESP32 IO3   -> 220Ω -> L2 control = yellow\nESP32 IO4   -> 220Ω -> L3 control = red\n\nboard - \u002F original battery -: leave disconnected in v1\n```\n\nCommon-anode logic:\n\n```text\nGPIO LOW  = lamp on\nGPIO HIGH = lamp off\n```\n\nFirmware inverts output as needed; you normally do not need to manage levels manually.\n\nCautions:\n\n- Solder only to exposed pads, component leads, or resistor joints.\n- Do not solder on the green solder mask surface.\n- After soldering, check for shorts with a multimeter before USB power.\n- For finished units, secure flying wires with hot glue or UV resin to avoid broken joints.\n\n---\n\n## 5. Firmware\n\nFirmware file:\n\n```text\nESP32_C3_ToyBoard_CommonAnode_BLE_Enhanced_CursorLight.ino\n```\n\nFeatures:\n\n- BLE advertised name: `CursorLight`\n- Control: BLE GATT write (string mode name)\n- Default on boot: `demo`\n- Multiple status effects\n- Built-in auto timeout to avoid leaving lamps on too long\n\nBLE parameters:\n\n```text\nDevice Name: CursorLight\nService UUID: b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001\nMode Characteristic UUID: b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001\n```\n\n---\n\n## 6. Flashing Firmware\n\n### 6.1 Install Arduino IDE\n\nDownload Arduino IDE 2.x:\n\n```text\nhttps:\u002F\u002Fwww.arduino.cc\u002Fen\u002Fsoftware\n```\n\nmacOS:\n\n1. Download the macOS build.\n2. Open the `.dmg`.\n3. Drag Arduino IDE into Applications.\n4. Allow on first launch if macOS prompts.\n\nWindows:\n\n1. Download the Windows installer.\n2. Complete the wizard.\n3. Allow drivers or network access if prompted.\n\n---\n\n### 6.2 Install ESP32 board package\n\nIn Arduino IDE:\n\n1. Open **Boards Manager** (left sidebar).\n2. Search `esp32`.\n3. Install **esp32 by Espressif Systems**.\n4. Restart Arduino IDE when done.\n\nDo not use **Arduino ESP32 Boards by Arduino** as the primary package for this project.\n\n---\n\n### 6.3 Select board and port\n\nWith ESP32-C3 SuperMini connected:\n\n```text\nBoard: ESP32C3 Dev Module\nPort: USB serial port\n```\n\nTypical ports:\n\n| OS | Example |\n|---|---|\n| macOS | `\u002Fdev\u002Fcu.usbmodemxxxx Serial Port (USB)` |\n| Windows | `COM3` \u002F `COM5` etc. |\n\nRecommended settings:\n\n| Setting | Value |\n|---|---|\n| USB CDC On Boot | Enabled |\n| Upload Speed | 921600 or default |\n| Flash Size | 4MB or default |\n\nIf Serial Monitor shows nothing, set `USB CDC On Boot` to `Enabled` and upload again.\n\n---\n\n### 6.4 Upload firmware\n\n1. Open the `.ino` in Arduino IDE.\n2. Confirm Board and Port.\n3. Click **Upload**.\n4. On success, Output often shows:\n\n```text\nWriting at ... 100%\nHash of data verified.\nHard resetting via RTS pin...\n```\n\nIf upload stalls at `Connecting...`:\n\n```text\nHold BOOT -> click Upload -> release BOOT when Writing starts\n```\n\n---\n\n### 6.5 Serial check\n\nOpen Serial Monitor at:\n\n```text\n115200\n```\n\nPress `RST` on the board. Expected log:\n\n```text\nPower on. Default mode: demo\nCommon anode BLE enhanced version.\nBLE device name: CursorLight\nBLE advertising started.\nSupported modes:\ndemo \u002F thinking \u002F ai \u002F busy \u002F success \u002F error \u002F alarm \u002F traffic \u002F off \u002F red \u002F yellow \u002F green\n```\n\n---\n\n## 7. BLE Control Script\n\nHost control via Python:\n\n```text\ncursor_light_ble_enhanced.py\n```\n\n### 7.1 Install dependencies\n\nmacOS:\n\n```bash\npython3 -m pip install bleak\n```\n\nWindows:\n\n```powershell\npy -3 -m pip install bleak\n```\n\nIf macOS reports `Bluetooth device is turned off` while Bluetooth is on:\n\n```text\nSettings -> Privacy & Security -> Bluetooth\n```\n\nGrant access to Terminal, iTerm, Cursor, or your shell app.\n\n---\n\n### 7.2 Manual test\n\nmacOS:\n\n```bash\npython3 cursor_light_ble_enhanced.py demo\npython3 cursor_light_ble_enhanced.py thinking\npython3 cursor_light_ble_enhanced.py ai\npython3 cursor_light_ble_enhanced.py busy\npython3 cursor_light_ble_enhanced.py success\npython3 cursor_light_ble_enhanced.py error\npython3 cursor_light_ble_enhanced.py alarm\npython3 cursor_light_ble_enhanced.py traffic\npython3 cursor_light_ble_enhanced.py off\n```\n\nWindows:\n\n```powershell\npy -3 cursor_light_ble_enhanced.py demo\npy -3 cursor_light_ble_enhanced.py thinking\npy -3 cursor_light_ble_enhanced.py ai\npy -3 cursor_light_ble_enhanced.py busy\npy -3 cursor_light_ble_enhanced.py success\npy -3 cursor_light_ble_enhanced.py error\npy -3 cursor_light_ble_enhanced.py alarm\npy -3 cursor_light_ble_enhanced.py traffic\npy -3 cursor_light_ble_enhanced.py off\n```\n\n---\n\n## 8. Firmware Modes\n\n| mode | Effect | Typical use |\n|---|---|---|\n| `demo` | Boot demo; cycles effects | Demo, idle display |\n| `thinking` | Chasing: L1 green -> L2 yellow -> L3 red | AI analysis, planning |\n| `ai` | Soft slow chase | AI generation, long tasks |\n| `busy` | Yellow slow blink | Build, test, install deps |\n| `success` | Green solid | Task succeeded |\n| `error` | Red fast blink | Failure or error |\n| `alarm` | Red\u002Fyellow alternate with short fade | Critical block |\n| `traffic` | Red flash to green, green flash to yellow, loop | Display \u002F auto transition |\n| `off` | All off | Turn off |\n| `red` | Red solid | Single-lamp test |\n| `yellow` | Yellow solid | Waiting for user \u002F test |\n| `green` | Green solid | Idle \u002F test |\n\n---\n\n## 9. Auto Timeout Rules\n\nFirmware auto-timeout prevents lamps staying on too long.\n\n| Current mode | Behavior |\n|---|---|\n| `demo` \u002F `thinking` \u002F `ai` \u002F `busy` \u002F `success` \u002F `error` \u002F `alarm` \u002F `red` \u002F `yellow` \u002F `green` | Max 5 minutes, then `traffic` |\n| `traffic` | Max 10 minutes, then `off` |\n| `off` | No auto change |\n\n---\n\n## 10. Cursor Hooks Integration\n\nCursorLight can hook into Cursor Agent via `.cursor\u002Fhooks` in your user directory.\n\nRecommended install path:\n\n| Platform | Path |\n|---|---|\n| macOS | `~\u002F.cursor\u002Fhooks\u002Fcursor-light\u002F` |\n| Windows | `%USERPROFILE%\\.cursor\\hooks\\cursor-light\\` |\n\nTypical layout:\n\n```text\ncursor-light\u002F\n├─ install-cursor-light.sh\n├─ hooks.json.snippet\n├─ agent-light.sh\n├─ ble_gate.py\n├─ cursor_light_ble_enhanced.py\n├─ hook-*.sh\n└─ README.md\n```\n\nRoles:\n\n- `cursor_light_ble_enhanced.py`: writes mode to ESP32-C3 BLE GATT characteristic.\n- `ble_gate.py`: debounce and dedupe; avoids flicker when multiple hooks fire.\n- `agent-light.sh`: maps Agent state to modes.\n- `hook-*.sh`: Cursor Hook event entry points.\n- `hooks.json.snippet`: Cursor Hooks config fragment.\n\n---\n\n## 11. macOS: Install Cursor Hooks\n\n```bash\nmkdir -p ~\u002F.cursor\u002Fhooks\u002Fcursor-light\ncd ~\u002F.cursor\u002Fhooks\u002Fcursor-light\nunzip ~\u002FDownloads\u002Fcursor-light-bundle.zip\nchmod +x *.sh\n```\n\nDependencies:\n\n```bash\npython3 -m pip install --user bleak\n```\n\nConfigure hooks:\n\n```bash\nmkdir -p ~\u002F.cursor\ncp hooks.json.snippet ~\u002F.cursor\u002Fhooks.json\n```\n\nIf `~\u002F.cursor\u002Fhooks.json` already exists, merge manually—do not overwrite blindly.\n\nSelf-test:\n\n```bash\ncd ~\u002F.cursor\u002Fhooks\u002Fcursor-light\npython3 cursor_light_ble_enhanced.py green\npython3 cursor_light_ble_enhanced.py thinking\npython3 cursor_light_ble_enhanced.py busy\npython3 cursor_light_ble_enhanced.py alarm\npython3 cursor_light_ble_enhanced.py success\n```\n\n---\n\n## 12. Windows: Install Cursor Hooks\n\nIf the bundle only ships `.sh` hook entry points, use Git Bash on Windows, or a future `.ps1` release.\n\nPowerShell example:\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\nExpand-Archive \"$env:USERPROFILE\\Downloads\\cursor-light-bundle.zip\" \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\" -Force\nSet-Location \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\n```\n\nDependencies:\n\n```powershell\npy --version\npy -m pip install --user bleak\n```\n\nConfigure hooks:\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.cursor\"\nCopy-Item \".\\hooks.json.snippet\" \"$env:USERPROFILE\\.cursor\\hooks.json\"\n```\n\nIf `hooks.json` already exists, merge manually.\n\nSelf-test:\n\n```powershell\npy .\\cursor_light_ble_enhanced.py green\npy .\\cursor_light_ble_enhanced.py thinking\npy .\\cursor_light_ble_enhanced.py busy\npy .\\cursor_light_ble_enhanced.py alarm\npy .\\cursor_light_ble_enhanced.py success\n```\n\n---\n\n## 13. Recommended State Mapping\n\n| Cursor \u002F dev scenario | Suggested mode |\n|---|---|\n| Agent analyzing requirements | `thinking` |\n| Agent generating or editing code | `ai` |\n| Terminal \u002F build \u002F test | `busy` |\n| Command OK \u002F build pass \u002F tests pass | `success` |\n| Ordinary failure \u002F error | `error` |\n| Severe block \u002F needs immediate attention | `alarm` |\n| Waiting for user confirmation | `yellow` |\n| Turn off lamp | `off` |\n\nCommon flows:\n\n```text\nNormal task: thinking -> busy -> success \u002F error\nWaiting for user: thinking -> yellow\nCritical: busy -> alarm\n```\n\n---\n\n## 14. Logs and Debugging\n\nmacOS:\n\n```bash\ntail -f ~\u002F.cursor\u002Fhooks\u002Fcursor-light\u002Fble.log\n```\n\nWindows PowerShell:\n\n```powershell\nGet-Content \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\\ble.log\" -Wait\n```\n\nCommon issues:\n\n| Symptom | Check first |\n|---|---|\n| Device not found | ESP32-C3 powered? BLE name `CursorLight`? Range? System Bluetooth on? |\n| Write failed | GATT UUIDs match firmware? |\n| Effects jumping | `ble_gate.py` present? Duplicate hook registration? |\n| Cursor not triggering | `hooks.json` loaded? Paths correct? Restart Cursor? |\n| Stuck on busy \u002F thinking | State not closed; check `ble_gate.py` and `state.json` |\n| Wrong colors | IO2=L1 green, IO3=L2 yellow, IO4=L3 red |\n\n---\n\n## 15. FAQ\n\n### Arduino IDE: cannot find ESP32C3 Dev Module\n\nConfirm installed:\n\n```text\nesp32 by Espressif Systems\n```\n\nRestart Arduino IDE, then:\n\n```text\nTools -> Board -> esp32\n```\n\nSelect `ESP32C3 Dev Module`.\n\n### No serial port\n\nCheck:\n\n- USB cable supports data.\n- Try another USB port.\n- On Windows, Device Manager shows a COM port.\n\n### Upload fails\n\nTry:\n\n```text\nHold BOOT -> click Upload -> release BOOT when Writing starts\n```\n\nClose Serial Monitor so the port is free.\n\n### No serial output\n\nConfirm:\n\n```text\nUSB CDC On Boot = Enabled\n```\n\nRe-upload and open Serial Monitor at 115200 baud.\n\n### Cannot find BLE device CursorLight\n\nCheck:\n\n- ESP32-C3 powered.\n- Firmware running.\n- BLE name `CursorLight`.\n- Host Bluetooth on.\n- macOS: Bluetooth permission for Terminal \u002F Cursor.\n\n### macOS: Bluetooth device is turned off\n\nBluetooth may be on but the terminal lacks permission:\n\n```text\nSettings -> Privacy & Security -> Bluetooth\n```\n\nAllow your terminal app, then restart the terminal.\n\n### python command not found\n\nmacOS typically:\n\n```bash\npython3\n```\n\nWindows:\n\n```powershell\npy -3\n```\n\n---\n\n## 16. Uninstall\n\nmacOS:\n\n```bash\nrm -rf ~\u002F.cursor\u002Fhooks\u002Fcursor-light\nnano ~\u002F.cursor\u002Fhooks.json\n```\n\nWindows PowerShell:\n\n```powershell\nRemove-Item -Recurse -Force \"$env:USERPROFILE\\.cursor\\hooks\\cursor-light\"\nnotepad \"$env:USERPROFILE\\.cursor\\hooks.json\"\n```\n\nRemove cursor-light entries from `hooks.json`, then restart Cursor.\n\n---\n\n## 17. References\n\n- Arduino IDE download: `https:\u002F\u002Fwww.arduino.cc\u002Fen\u002Fsoftware`\n- Arduino IDE install guide: `https:\u002F\u002Fsupport.arduino.cc\u002Fhc\u002Fen-us\u002Farticles\u002F360019833020-Download-and-install-Arduino-IDE`\n- Arduino-ESP32 install docs: `https:\u002F\u002Fdocs.espressif.com\u002Fprojects\u002Farduino-esp32\u002Fen\u002Flatest\u002Finstalling.html`\n","CursorLight 是一个基于 ESP32-C3 SuperMini 和 BLE 蓝牙的桌面状态灯项目，通过红绿灯直观显示 AI 编程过程中的思考、忙碌、成功、错误以及等待用户操作等状态。该项目利用 ESP32-C3 作为主控芯片，通过 BLE 通信接收来自电脑端的状态指令，并控制红绿灯挂件内部原有的三色灯板展示不同的灯效。其核心功能包括多种预设模式（如思考、生成、执行、成功、失败等），并通过 Cursor Hooks 自动映射 Cursor Agent 的工作状态到相应的灯效。此项目适用于需要可视化 AI 编程状态的场景，特别适合开发者和编程爱好者在使用 Cursor Agent 或类似工具时提高工作效率。","2026-06-11 03:58:12","CREATED_QUERY"]