# 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. 点击 **<i class="fas fa-plus"></i> 新增外设** 按钮

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` 数组中：

```json
{
  "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. 点击 **<i class="fas fa-plus"></i> 新增规则** 按钮
3. 配置触发器（如定时触发、事件触发）
4. 添加动作，选择 **调用外设（CALL\_PERIPHERAL）**，目标填写 `neopixel1`，动作参数填写 `{"action":"color","value":"#FF0000"}`，关闭“使用接收值”
5. 点击 **保存**

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

***

### JSON配置示例

### 单帧动作示例

```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 竞争、真实内存峰值和长稳仍需实物测试。当前本轮不执行物理输出。
