WS2812B NeoPixel 灯珠

功能说明

WS2812B（NeoPixel）是一种可寻址 RGB LED 灯珠，通过单根数据线级联控制多颗灯珠，每颗灯珠可独立设置颜色。适用于氛围灯、状态指示、灯带等应用。

支持的外设类型

类型	type值	说明
NEO_PIXEL	45	WS2812B/WS2811 可寻址LED

硬件接线

NeoPixel 引脚	连接	说明
VCC	与灯珠型号匹配的外部电源	按实际灯珠手册、电流及线材额定值设计
GND	GND	地
DIN	GPIO	数据输入（建议串联330Ω电阻）

配置方式

方式1：Web界面配置（推荐）

NeoPixel 保存前重点核对数据引脚、灯珠数量及独立供电；当前传输固定GRB顺序和800kHz，没有通用颜色顺序选择参数。

步骤1：进入外设管理页面

1. 打开浏览器访问 ESP32 IP 地址
2. 登录后点击左侧菜单 外设配置

步骤2：添加NeoPixel灯带外设

1. 点击 新增外设 按钮

2. 填写配置：

   字段	填写内容	说明
   外设ID	neopixel1	唯一标识符
   名称	RGB灯带	显示名称
   外设类型	NeoPixel灯珠 (type: 45)	WS2812B驱动
   引脚配置	经当前板型能力检查的 GPIO	下方 JSON 的 16 只是示例，须排除板载器件、Flash/PSRAM 和其它占用
   灯珠数量	8	当前默认固件 1-64 颗；以候选编译上限为准
   全局亮度	50	0-255

3. 点击 保存

步骤3：验证配置

1. 在外设列表中找到刚添加的外设
2. 点击 启用 开关
3. 使用下面的 CALL_PERIPHERAL 规则发送单帧颜色；先确认供电、接线及当前设备固件具备该功能

灯带供电容量应按实际型号、数量及最大亮度核算；不能以“少于 10 颗”认定开发板供电足够。

---

方式2：JSON配置文件导入

将以下配置添加到 data/config/peripherals.json 的 peripherals 数组中：

{
  "id": "neopixel1",
  "name": "RGB灯带",
  "type": 45,
  "enabled": false,
  "pins": [16],
  "params": {
    "count": 8,
    "brightness": 50
  }
}

参数说明

参数	说明	范围
count	灯珠数量	当前默认编译上限 64；定制固件以编译值为准
brightness	全局亮度	0-255

与外设执行联动

NeoPixel 使用 CALL_PERIPHERAL（10）动作控制。当前命令脚本没有 PERIPH id COLOR 路由，不应使用旧版文档中的该示例。

Web界面配置步骤

发送一帧红色

1. 点击左侧菜单 外设执行
2. 点击 新增规则 按钮
3. 配置触发器（如定时触发、事件触发）
4. 添加动作，选择 调用外设（CALL_PERIPHERAL），目标填写 neopixel1，动作参数填写 {"action":"color","value":"#FF0000"}，关闭“使用接收值”
5. 点击 保存

需要连续颜色时，添加多个 CALL_PERIPHERAL 动作并设置动作间隔。动画每次调用只产生一帧，没有自动启动的后台动画定时器。

---

JSON配置示例

单帧动作示例

{
  "targetPeriphId": "neopixel1",
  "actionType": 10,
  "actionValue": "{\"action\":\"color\",\"value\":\"#FF0000\"}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

平台下发控制

先配置 MQTT 数据触发规则，由规则执行上述 CALL_PERIPHERAL 动作。当前通用 MQTT 直接输出分支只覆盖支持的数字/PWM/AO目标，不能把未匹配规则的 neopixel1 颜色消息当作已支持的直接控制接口。

控制来源与停止

开发候选每帧校验规则/手动来源、配置版本及操作编号；无可信来源、过期或已经结束的旧操作不能发送。冲突不会隐式抢占，受控手动覆盖须满足目标、版本和占用代际确认。

brightness 只接受 0～255 的十进制整数，修改运行配置而不立即发送，结果为 CONTROL_ACCEPTED_CONFIG_ONLY、attempted=false；未承诺持久化。普通 stop 撤销该操作的后续帧，保留当前颜色，不发黑帧、不销毁驱动对象。需要熄灭时应明确发送颜色 #000000 并检查结果。生命周期清理另行发送黑帧、确认传输及释放，任一步失败都保留诊断和占用；这仍不证明实际灯珠已熄灭。

注意事项

1. 供电：按具体灯珠手册核算电源、布线与保护；勿从 GPIO 供电，共地并避免向开发板电源反灌
2. 电平转换：依据灯珠供电与输入高电平门槛选择兼容的电平转换；不能仅按线短就假定 3.3V 直连可靠
3. 串联电阻：数据线建议串联 330Ω 电阻保护 GPIO
4. 电容滤波：电源端建议并联 100μF 电容防止电压波动
5. 最大数量：当前默认 FASTBEE_NEOPIXEL_MAX_LEDS=64，驱动按编译上限钳制；不能用表单允许填写的数量推断实际支持的灯珠数。RGB 像素及 RMT 符号至少约 99 B/颗，还需 SDK、对象及系统运行余量。

输出失败与状态边界（后继候选待验收）

2026-10-04 集成定向 r3 共 284 项通过，其中包含真实普通来源/NeoPixel 路径及 checked transport 故障回归；这只是 Host 软件证据。完整固件门禁与实物验收仍待完成，不能据此认定现场固件已更新。普通颜色与所有动画在传输失败时返回失败，动画帧序号只在完成时推进。allocated 仅说明对象生命周期，不代表 RMT 通道健康，也不代表灯带实际亮起。

S3/C6 的早期 r20 预检曾因依赖编译缺少 checked transport 头文件失败；该处已越过，最新 r5 又因普通仲裁源文件缺锁头而编译失败。锁头已补，仍须重新取得实际目标构建结果；原 FAIL 保留。此前 LTO 体积实验不是当前候选的发布证明。

运行资源候选分别显示项目对象及其真实外设 ID、pin、配置 LED 数量、最近发送/释放结果和清理保留状态。capacity=1 是项目单例限制，不是 RMT 通道数量，配置 LED 数不代表识别到实际灯珠；只有明确 attempted 的操作才有有效结果码。忙锁或同步未建立表示本次未观测，不是资源为零。查询只复制被动记录，不发送颜色或清理资源；相关 Host 子集已测，仍需完整候选和设备实测。

RMT 初始化/发送/释放失败或检测到引脚 owner 改变时，候选会保留可能仍被 SDK 使用的缓冲、对象和引脚，显示 cleanup_pending，阻止改配或其他外设复用该 pin。配置失败回滚也不能让遗留 pin 变成可用。排查供电、内存与 RMT 竞争并确认现场条件后，通过受控重启恢复；晚到的发送完成不会自动清除故障。失败状态不等于灯带已熄灭。

mutex 与传输事件分别使用 50 ms、100 ms 有限外部等待，并保留 latch 间隔。SDK 内部锁/初始化并无已证明的硬实时上界，因此不是整个调用的固定耗时保证。发送前内存不足或 mutex 繁忙会报告失败，可在业务路径重试。

清理/退役阶段更严格：即使尚未发送的内存不足或繁忙，只要清理失败，项目对象仍会保留该 pin，错误配置继续可见，禁止之后用旧对象向已改配引脚补发“关闭”。此状态也需受控重启，不适用普通业务发送的重试语义。

RGB 实际颜色/熄灭、长灯带供电、DHT/IR 等 RMT 竞争、真实内存峰值和长稳仍需实物测试。当前本轮不执行物理输出。