ai-status-light/firmware

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 并重启：

{
  "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 字段自定义

  # 示例：使用 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 配置动态修改，无需重新烧录：

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

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

烧录方法

1. 安装 Arduino IDE 2.x
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。