示例14:RGB彩灯（WS2812B）
实验概述
通过单线协议驱动 WS2812B（NeoPixel）RGB LED 灯珠，实现全彩色控制。FastBee 内置 NEO_PIXEL 外设类型（type: 45），支持设置颜色、亮度和灯珠数量。
硬件接线
| 开发板标识 | GPIO引脚 | 连接设备 |
|---|---|---|
| DATA | GPIO4 | WS2812B 数据引脚（DIN） |
WS2812B 供电建议使用 5V，数据输入高电平门槛按具体灯珠确认，必要时使用合适的逻辑电平转换。
JSON 配置示例
{
"peripherals": [
{
"id": "ws2812b",
"name": "WS2812B彩灯",
"type": 45,
"enabled": false,
"pins": [4],
"params": {
"count": 8,
"brightness": 64
}
}
]
}参数说明
| 参数 | 说明 | 范围 |
|---|---|---|
| count | 灯珠数量 | 默认编译上限 64；超范围按候选编译上限钳制 |
| brightness | 全局亮度 | 0~255 |
后继候选新增传输失败检查，尚待集中门禁和实物验收。所有灯效在 SDK 发送完成后才推进下一帧；对象 allocated 不证明灯带实际输出。RMT 初始化、发送超时、释放失败会保留可能仍在使用的缓冲与 pin，状态为 cleanup_pending，需要排障和确认现场条件后受控重启；不能以反复删除/重建外设释放该 pin。失败不意味着灯带已熄灭。
50 ms mutex 等待和 100 ms 传输事件等待不等于 SDK 整体硬实时上界；真实 RMT 竞争、内存峰值、颜色/供电与长稳仍须单独验收。详见 NeoPixel 外设说明。
任何清理失败（包括发送前内存不足/繁忙）都会额外保留项目对象与 pin，错误配置继续可见，阻止配置回滚后旧对象向其他外设占用的引脚补发关闭帧；需排障后受控重启。
外设执行联动
NeoPixel 可通过以下两种 actionType 进行控制：
| actionType | 名称 | 说明 |
|---|---|---|
| 11 | 灯效控制 | 推荐。选择后自动显示预设灯效下拉框，保存简单文本（如 red、rainbow） |
| 10 | 发送指令 | 通用模式，手动填写 JSON（向后兼容） |
预设灯效选项（actionType=11）
| 下拉框显示 | 保存的 actionValue | 说明 |
|---|---|---|
| red-红色 | red | 固定红色 |
| green-绿色 | green | 固定绿色 |
| blue-蓝色 | blue | 固定蓝色 |
| yellow-黄色 | yellow | 固定黄色 |
| orange-橙色 | orange | 固定橙色 |
| purple-紫色 | purple | 固定紫色 |
| cyan-青色 | cyan | 固定青色 |
| white-白色 | white | 固定白色 |
| off-关闭 | off | 全部灯珠熄灭 |
| rainbow-彩虹循环 | rainbow | 每次触发切换下一帧彩虹色 |
| chase-流水灯 | chase | 逐灯点亮，每次前进一灯 |
| theater_chase-剧院追逐 | theater_chase | 每3灯亮1灯，每次偏移 |
| strobe-频闪 | strobe | 交替全亮/全灭 |
| twinkle-闪烁 | twinkle | 随机灯珠亮随机颜色 |
| fade-渐变 | fade | 亮度从0渐增到目标色 |
| breathing-呼吸 | breathing | 亮度来回循环 |
| color_wipe-色彩擦除 | color_wipe | 逐灯填充，每次多亮一颗 |
| fire-火焰 | fire | 随机红/橙/黄色填充随机灯珠 |
| $value-平台下发 | $value | 由平台动态指定颜色 |
| custom-自定义 | 用户手动填写 | 显示动作参数输入框，支持自定义 HEX/RGB 颜色、亮度调节等高级 JSON 参数 |
颜色值支持三种格式：英文名（red/green/blue/yellow/orange/cyan/purple/white/off）、HEX（#FF0000）、RGB（255,0,0）。
custom-自定义 用法
选择“custom-自定义”后，预设下拉框下方会显示“动作参数”输入框，可手动输入 JSON 格式的高级参数：
| 输入内容 | 说明 |
|---|---|
{"action":"color","color":"#FF6600"} | 自定义 HEX 颜色 |
{"action":"color","color":"255,102,0"} | 自定义 RGB 颜色 |
{"action":"brightness","value":128} | 设置亮度（0-255） |
{"action":"color","color":"#00FF00","brightness":200} | 同时指定颜色和亮度 |
$value | 由平台动态下发颜色值 |
提示：其他预设选项（red/rainbow 等）选中时会自动隐藏输入框，直接保存预设名作为 actionValue。只有选择“custom-自定义”或输入框为空时才显示输入框。
actionType=10 JSON 格式（向后兼容）
使用通用"发送指令"时，actionValue 为 JSON 格式：
{"action":"color","color":"red"}— 设置颜色{"action":"off"}— 关灯{"action":"rainbow"}— 彩虹循环{"action":"brightness","value":128}— 设置亮度- 支持
$value占位符接收平台下发的值
场景1：定时亮红灯
功能：每 5 秒亮一次红灯
Web界面配置步骤
步骤1：创建规则
- 点击左侧菜单 外设执行
- 点击 新增规则 按钮
- 填写基础配置：
- 规则名称：
定时亮红灯 - 上报数据：✅ 启用
- 启用：✅ 启用
- 规则名称：
步骤2：配置触发器
点击 添加触发 按钮
填写触发器配置：
字段 填写内容 说明 触发类型 选择 定时触发 按时间间隔触发 定时模式 选择 间隔模式 固定间隔 间隔秒数 5每 5 秒
步骤3：配置动作
点击 添加动作 按钮
填写：
- 动作类型：选择 灯效控制（actionType=11，在"高级功能"分组中）
- 目标外设：选择
ws2812b - 预设灯效：选择 红色（自动保存为
red）
点击 保存 按钮
场景2：平台动态控制颜色（平台触发）
功能：云平台下发颜色指令，设备实时显示
Web界面配置步骤
- 创建规则，名称：
平台控灯 - 触发器配置：
- 触发类型：选择 平台触发
- 处理方式：选择 设置
- 动作配置：
- 动作类型：选择 灯效控制（actionType=11）
- 目标外设：选择
ws2812b - 预设灯效：选择 平台下发颜色（保存为
$value）
- 点击 保存
平台下发颜色名（如 red、green、blue）或 HEX 值（如 #FF8800），设备自动匹配显示。
常用颜色对照表
| 颜色 | 英文名 | HEX | RGB | 说明 |
|---|---|---|---|---|
| 红色 | red | #FF0000 | 255,0,0 | 纯红 |
| 绿色 | green | #00FF00 | 0,255,0 | 纯绿 |
| 蓝色 | blue | #0000FF | 0,0,255 | 纯蓝 |
| 白色 | white | #FFFFFF | 255,255,255 | 白色 |
| 黄色 | yellow | #FFFF00 | 255,255,0 | 黄 |
| 橙色 | orange | #FF8800 | 255,136,0 | 橙 |
| 紫色 | purple | #800080 | 128,0,128 | 紫 |
| 青色 | cyan | #00FFFF | 0,255,255 | 青 |
| 关闭 | off | #000000 | 0,0,0 | 灭灯 |
注意事项
- 电源：每颗 WS2812B 满亮度约 60mA，多颗灯珠需独立 5V 供电
- 电平：部分 WS2812B 需要 5V 逻辑电平，应使用电平转换；DIN串联330Ω仅用于信号保护/抑制振铃，不能替代电平转换
- 时序敏感：WS2812B 对时序要求严格，建议使用 RMT 外设（ESP32 默认使用）
- 刷新率：灯珠越多刷新越慢，100 颗约 3ms
- 数据顺序：颜色顺序可能是 GRB 而非 RGB，取决于型号