# AI-Light 固件

基于 **ESP32-C3 SuperMini** 的桌面状态灯固件，通过 BLE 蓝牙或 MQTT 接收状态指令，控制红绿灯挂件显示 AI 工作状态。

## 固件

`ai_light.ino` 支持 BLE + MQTT 双模式，通过 BOOT 按钮切换。

| 通信方式 | 灯效控制 | 配置修改 |
|---------|---------|---------|
| BLE | ✅ | ✅ |
| MQTT | ✅ | ✅ |

## BLE 参数（双模式版）

```
Device Name:          AI-Light
Service UUID:         b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001
Mode Characteristic:  b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001  (灯效控制)
Config Characteristic: b8b7e003-7a6b-4f4f-9a8b-11c0ffee0001  (WiFi/MQTT 配置)
```

### 灯效控制

向 Mode 特征写入 UTF-8 字符串即可控制灯效：

| 模式 | 灯效 | 典型场景 |
|------|------|----------|
| `init` | 开机初始化 | 启动 |
| `thinking` | 跑马灯 | AI 分析中 |
| `ai` | 慢速跑马灯 | AI 生成中 |
| `busy` | 黄灯慢闪 | 命令执行中 |
| `success` | 绿灯常亮 | 任务成功 |
| `error` | 红灯快闪 | 任务失败 |
| `alarm` | 红黄交替警灯 | 严重异常 |
| `traffic` | 模拟红绿灯 | 展示模式 |
| `red` | 红灯常亮 | 手动控制 |
| `yellow` | 黄灯常亮 | 手动控制 |
| `green` | 绿灯常亮 | 手动控制 |
| `idle` | 同 traffic | 空闲状态 |
| `off` | 全灭 | 关闭 |

### WiFi/MQTT 配置

配置可通过 BLE 或 MQTT 进行：

#### BLE 配置

向 Config 特征写入 JSON 配置，设备自动保存到 NVS 并重启：

```json
{
  "wifi_ssid": "你的WiFi名",
  "wifi_pass": "你的WiFi密码",
  "mqtt_broker": "192.168.1.100",
  "mqtt_port": 1883,
  "mqtt_user": "mqtt用户名",
  "mqtt_pass": "mqtt密码",
  "mqtt_client": "AI-Light",
  "mqtt_topic": "agent/status",
  "mqtt_status": "agentLight/status",
  "mqtt_topic_config": "agent/status/config",
  "pin_red": 4,
  "pin_green": 3,
  "pin_yellow": 2,
  "factory_reset": true
}
```

#### MQTT 配置

向配置 topic 发送 JSON 配置，设备自动保存到 NVS 并重启：

- 默认 topic：`agent/status/config`
- 可通过 `mqtt_topic_config` 字段自定义

```bash
# 示例：使用 mosquitto_pub 配置设备
mosquitto_pub -h 192.168.1.100 -t "agent/status/config" -m '{
  "wifi_ssid": "你的WiFi名",
  "wifi_pass": "你的WiFi密码",
  "mqtt_broker": "192.168.1.100"
}'
```

### 恢复出厂设置

连续短按 BOOT 按钮 3 下（1.5 秒内）可恢复出厂设置：
- 红灯闪烁 5 次表示正在清除配置
- 清除完成后设备自动重启
- 重启后进入 BLE 配置模式

## 双模式版

`ai_light.ino` 同时支持 BLE 和 MQTT：

| 操作 | 效果 |
|------|------|
| 长按 BOOT 3 秒 | 切换 BLE/MQTT 模式并重启 |
| 连续短按 BOOT 3 下 | 恢复出厂设置（清除所有配置） |

- **开机始终启动 BLE**，可用于灯效控制和 WiFi/MQTT 配置
- 默认 MQTT 模式，切换后自动保存到 NVS

## 硬件接线

基于公共正极灯板（默认引脚，可通过配置修改）：

```
ESP32 3.3V  -> 灯板正极
ESP32 IO4   -> 220Ω -> 红灯（默认）
ESP32 IO3   -> 220Ω -> 绿灯（默认）
ESP32 IO2   -> 220Ω -> 黄灯（默认）
ESP32 IO8   -> 状态 LED（固定）
ESP32 IO9   -> BOOT 按钮（固定）
```

公共正极逻辑：GPIO LOW = 灯亮，GPIO HIGH = 灯灭

### 引脚配置

灯引脚可通过 BLE 或 MQTT 配置动态修改，无需重新烧录：

```json
{
  "pin_red": 4,
  "pin_green": 3,
  "pin_yellow": 2
}
```

配置后设备自动重启生效。状态 LED (IO8) 和 BOOT 按钮 (IO9) 固定不可修改。

## 烧录方法

1. 安装 [Arduino IDE 2.x](https://www.arduino.cc/en/software)
2. 安装 ESP32 开发板包：`esp32 by Espressif Systems`
3. 选择开发板：`ESP32C3 Dev Module`
4. 打开 `.ino` 文件，点击 Upload
5. 串口监视器波特率：`115200`

## 依赖库

- `WiFi.h`（ESP32 内置）
- `PubSubClient.h`
- `ArduinoJson.h`
- `BLEDevice.h`（ESP32 内置）
- `Preferences.h`（ESP32 内置）

通过 Arduino IDE → Sketch → Include Library → Manage Libraries 安装。

## 配置持久化

配置保存在 ESP32 的 NVS（Non-Volatile Storage）分区，与固件分区独立：

| 操作 | 配置保留？ |
|------|-----------|
| Arduino IDE 正常上传 | ✅ 保留 |
| 只刷写固件（不擦除 flash） | ✅ 保留 |
| 擦除整个 flash 后刷写 | ❌ 丢失 |

如需完全重置，可连续短按 BOOT 按钮 3 下或在 Arduino IDE 中擦除 flash。