示例14:RGB彩灯（WS2812B）

实验概述

通过单线协议驱动 WS2812B（NeoPixel）RGB LED 灯珠，实现全彩色控制。FastBee 内置 NEO_PIXEL 外设类型（type: 45），支持设置颜色、亮度和灯珠数量。

硬件接线

开发板标识	GPIO引脚	连接设备
DATA	GPIO4	WS2812B 数据引脚（DIN）

WS2812B 供电建议使用 5V，数据线可直接接 3.3V GPIO（大多数 WS2812B 兼容）。

JSON 配置示例

{
  "peripherals": [
    {
      "id": "ws2812b",
      "name": "WS2812B彩灯",
      "type": 45,
      "enabled": true,
      "pins": [4],
      "params": {
        "count": 8,
        "brightness": 64
      }
    }
  ]
}

参数说明

参数	说明	范围
count	灯珠数量	1~255
brightness	全局亮度	0~255

外设执行联动

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：创建规则

1. 点击左侧菜单 外设配置 → 切换到 外设执行管理 标签
2. 点击 新增规则 按钮
3. 填写基础配置：
   • 规则名称：定时亮红灯
   • 上报数据：✅ 启用
   • 启用：✅ 启用

步骤2：配置触发器

1. 点击 添加触发 按钮

2. 填写触发器配置：

   字段	填写内容	说明
   触发类型	选择 定时触发	按时间间隔触发
   定时模式	选择 间隔模式	固定间隔
   间隔秒数	5	每 5 秒

步骤3：配置动作

1. 点击 添加动作 按钮

2. 填写：

   • 动作类型：选择 灯效控制（actionType=11，在"高级功能"分组中）
   • 目标外设：选择 ws2812b
   • 预设灯效：选择 红色（自动保存为 red）

3. 点击 保存 按钮

---

场景2：平台动态控制颜色（平台触发）

功能：云平台下发颜色指令，设备实时显示

Web界面配置步骤

1. 创建规则，名称：平台控灯
2. 触发器配置：
   • 触发类型：选择 平台触发
   • 处理方式：选择 设置
3. 动作配置：
   • 动作类型：选择 灯效控制（actionType=11）
   • 目标外设：选择 ws2812b
   • 预设灯效：选择 平台下发颜色（保存为 $value）
4. 点击 保存

平台下发颜色名（如 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	灭灯

注意事项

1. 电源：每颗 WS2812B 满亮度约 60mA，多颗灯珠需独立 5V 供电
2. 电平：部分 WS2812B 需要 5V 逻辑电平，可加电平转换或在 DIN 串联 330Ω 电阻
3. 时序敏感：WS2812B 对时序要求严格，建议使用 RMT 外设（ESP32 默认使用）
4. 刷新率：灯珠越多刷新越慢，100 颗约 3ms
5. 数据顺序：颜色顺序可能是 GRB 而非 RGB，取决于型号