# AgentLight

**Repository Path**: ustin_le/agentlight

## Basic Information

- **Project Name**: AgentLight
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![AgentLight](media/AgentLight.png)

# AgentLight

AI 工作状态物理指示灯，基于 ESP32 的下位机固件，通过 UDP/BLE 接收上位机命令驱动 LED 显示 AI 状态。

支持双板卡：**ESP32-S3** (LCD 桌面 + 外设) 和 **ESP32-C3** (精简纯灯控)，通信协议完全兼容。

## 快速开始

```bash
# S3 版本 (LCD 桌面)
idf.py set-target esp32s3
idf.py build
idf.py -p /dev/cu.usbmodem* flash

# C3 精简版 (仅灯控)
cd AgentLight_C3
idf.py set-target esp32c3
idf.py build
idf.py -p /dev/cu.usbmodem* flash
```

> 烧录后连接 WiFi 即自动广播，open code 插件自动发现并接管控制。

## ESP32 配网

### S3 (LCD 桌面)

1. 通过按键导航到 **WiFi Setup** 子应用
2. 切换到 AP 模式，设备创建热点 `AgentLight`（无密码）
3. 手机连接 `AgentLight` WiFi，浏览器访问任意网页进入配网页面
4. 选择目标 WiFi 输入密码，连接成功后可关闭 AP

或通过控制台:

```
agentlight> wifi
wifi> ap on                 # 开启配网热点
wifi> scan                  # 扫描附近 WiFi
wifi> connect <ssid> <pwd>  # 连接指定 WiFi
wifi> status                # 查看连接状态
```

### C3 (USB CDC 控制台)

连接 USB 后打开串口终端 (115200 8N1):

```bash
screen /dev/cu.usbmodem* 115200
```

在 `agentlight>` 提示符下:

```
agentlight> wifi
wifi> scan                  # 扫描可用 WiFi
wifi> connect SOC mypassword
wifi> status
# Connected: SOC rssi:-30
```

连接成功后将自动启动 UDP 服务 (3333) 和广播 (3334)，上位机插件即可发现。

## 部署 opencode 插件

### 自动安装

```bash
# 复制到项目级和全局插件目录
cp agentplugin/agentlight.js .opencode/plugins/
cp agentplugin/agentlight.js ~/.config/opencode/plugins/
```

插件配置 `.opencode/agentlight.json`:

```json
{
  "host": "",
  "port": 3333
}
```

> `host` 留空使用自动发现，指定 IP 则直连（跳过广播握手）。

重启 opencode 后插件生效。

### 工作原理

```
opencode session 事件 ──→ agentlight.js ──→ UDP/BLE ──→ ESP32 ──→ LED
                              │
                              ├── 监听 UDP 3334 自动发现广播 (AGENTLIGHT v1 <ip> 3333)
                              ├── 发送 CONNECT → 收到 CONNECT_OK → 连接建立
                              └── 每 5s PING keepalive, 3 次丢包自动重连
```

事件映射:

| opencode 事件 | 灯效命令 |
|---------------|---------|
| `streaming` / `message.part.updated` (reasoning) | `RED_BREATHE` |
| `tool.execute.before` (bash 等) | `YELLOW_BREATHE` |
| `tool.execute.before` (edit/write) | `YELLOW_BLINK` |
| `permission.asked` | `RED_BLINK` |
| `session.idle` / `tool.execute.after` | `GREEN` |
| `session.error` | `RED` |

## 系统架构

### S3 桌面菜单

```
主页
├── LED Switch        — GPIO3 开关
├── Decibel Meter     — I2S 麦克风分贝计
├── File Manager      — SD 卡文件浏览
├── WiFi Setup        — STA/AP 模式切换 + 扫描列表
├── BLE Setup         — 蓝牙连接状态 + 广播开关
├── Agent Light       — AI 状态指示灯 (命令驱动)
└── Screen Test       — 屏幕颜色测试
```

WiFi Setup: AP 模式自动启动配网门户 (SoftAP + HTTP 网页)，STA 模式显示 SSID/IP/RSSI。

BLE Setup: 查看蓝牙命令通道连接状态，提供广播开关。

### 双串口架构 (S3)

```
[硬串口] 电脑USB → CH340 → ESP32 UART0(TX0/RX0)
         ├── 系统启动日志 + 运行日志(ESP_LOGI/W/E)
         └── ROM bootloader 输出(不可拦截)

[软串口] 电脑USB → ESP32 原生 USB(D+/D-)
         ├── 控制台终端(agentlight> 提示符)
         ├── 功能级交互(light/wifi/ble 子Shell)
         └── 不输出任何 ESP 日志(保持交互界面洁净)
```

### 控制台终端

```
agentlight> light          → 进入指示灯子Shell
light> RED GREEN YELLOW ...
light> exit

agentlight> wifi            → 进入 WiFi 子Shell
wifi> scan | status | connect <ssid> [pwd] | ap on|off
wifi> exit

agentlight> ble             → 进入 BLE 子Shell
ble> status | adv on|off
ble> exit

agentlight> free | uptime | version | router | reboot
```

## 通信流水线

```
            WiFi-UDP (3333)
                  │
             BLE GATT
                  │
         通讯路由(优先级: WiFi > BLE)
                  │
          led_light_handle_cmd
                  │
              AI 指示灯
```

路由将 WiFi-UDP / BLE 传入的数据统一转发，低优先级通道数据在高优先级活动时丢弃。自动发现广播端口 3334。

## 灯效命令

| 命令 | 效果 | 典型含义 |
|------|------|---------|
| `RED_BREATHE` | 红灯呼吸 | AI 思考中 |
| `YELLOW_BREATHE` | 黄灯呼吸 | 执行工具 |
| `YELLOW_BLINK` | 黄灯闪烁 | 编辑文件 |
| `RED_BLINK` | 红灯闪烁 | 等待审批 |
| `RED` | 红灯常亮 | 发生错误 |
| `GREEN` | 绿灯常亮 | 空闲就绪 |
| `ALL` / `ALL_BLINK` / `ALL_BREATHE` | 三色同时 | — |
| `OFF` | 全部熄灭 | — |

## 功能对比

| 功能 | S3 | C3 |
|------|----|----|
| LCD 桌面菜单 | ✅ ILI9341 + LVGL | — |
| 物理 LED 信号灯 | — | ✅ 红黄绿 LEDC PWM |
| 板载状态指示 | GPIO3 | GPIO12/13 |
| I2S 麦克风 | ✅ | — |
| SD 卡 | ✅ | — |
| ADC 按键 | ✅ | — |
| WiFi UDP 命令 | ✅ | ✅ |
| BLE GATT 命令 | ✅ | ✅ |
| 自动发现广播 | ✅ | ✅ |
| USB CDC 控制台 | ✅ | ✅ |
| open code 插件支持 | ✅ | ✅ |

## C3 LED 灯语

| LED | 引脚 | 作用 | 效果 |
|-----|------|------|------|
| 红 | GPIO8 | AI 状态 | 呼吸/闪烁/常亮 (LEDC CH0) |
| 黄 | GPIO4 | AI 状态 | 同上 (LEDC CH1) |
| 绿 | GPIO5 | AI 状态 | 同上 (LEDC CH2) |
| LED0 | GPIO12 | 连接状态 | 慢呼吸=广播中 / 快闪=握手 / 常亮=已连接 / 灭=断连 |
| LED1 | GPIO13 | 活动指示 | 收到命令时短呼吸一次 |

## 项目结构

```
AgentLight/
├── CMakeLists.txt           # 顶层入口
├── Kconfig.projbuild        # 板卡选择 (BOARD_TYPE)
├── README.md
├── AGENTS.md                # AI 开发指南
│
├── main/
│   ├── CMakeLists.txt       # 条件编译 (shared + app + ui + hal + comm + bsp)
│   ├── idf_component.yml    # LVGL/ILI9341 依赖 (S3)
│   │
│   ├── app/main.c           # S3 启动流程
│   │
│   ├── bsp/                 # 板级支持包
│   │   ├── bsp.h            #   统一抽象接口
│   │   ├── Kconfig          #   硬件能力声明 + 功能开关
│   │   ├── esp32s3/         #   S3 板级实现 (GPIO3 LED)
│   │   └── esp32c3/         #   C3 板级实现 (GPIO8/4/5/12/13 + LEDC)
│   │
│   ├── shared/              # 共享通信模块 (S3+C3 通用)
│   │   ├── comm_router.c/h  #   优先级仲裁 (WiFi > BLE)
│   │   ├── udp_server.c/h   #   UDP 命令服务 (3333)
│   │   ├── discovery.c/h    #   自动发现广播 (3334)
│   │   ├── ble_light.c/h    #   BLE GATT (0xFF01/0xFF02)
│   │   └── wifi_ap.c/h      #   WiFi AP 网页配网
│   │
│   ├── ui/                  # S3 LCD 桌面 (7 个子应用 + LVGL)
│   ├── hal/                 # S3 硬件驱动 (按键/日志转发)
│   └── comm/                # S3 控制台 (子 shell REPL)
│
├── AgentLight_C3/           # C3 独立构建根目录
│   └── main/                # (同步 shared/ + bsp/, 精简启动)
│
├── bsp/                     # 板级连接说明
├── media/                   # 架构图等资源
├── plan/                    # 方案设计文档
├── log/                     # 实现日志
├── partition_table/         # Flash 分区表
│
├── agentplugin/             # open code 插件 (JS)
├── .opencode/plugins/       # open code 项目级插件
├── .devcontainer/           # Docker 开发环境
└── .vscode/                 # VSCode 配置
```

## 技术栈

- **MCU**: ESP32-S3 / ESP32-C3
- **SDK**: ESP-IDF v5.5.4
- **GUI**: LVGL 8.3 + ILI9341 (S3 only)
- **LED**: LEDC PWM 5kHz 13bit (C3)
- **协议**: WiFi-UDP (3333) + BLE GATT (0xFF01/0xFF02) + 自动发现 (3334)