RT-Thread WS2812B 软件包完成重构:多灯带、动态灯效与更灵活的 SPI 驱动

摘要:RT-Thread 的 WS2812B SPI 软件包已合并重构,新增多设备配置、可选时序编码、亮度与 Gamma 校正及动态灯效。结合单线控制原理,介绍此次优化、实际使用方法,以及原软件包与在线文档的关系。

在这里插入图片描述

[TOC]

WS2812B 是一种集成控制电路的可寻址 RGB LED 灯珠。普通 RGB 灯带通常整段显示同一种颜色,而 WS2812B 灯带可以通过一根数据线,让不同位置的灯珠分别显示不同颜色。它常用于设备状态灯、氛围灯、流水灯、机箱灯光和交互指示。[S4]

面向 RT-Thread 的 rt_ws2812b 软件包现已完成一轮较大规模的重构:上游 PR #5:扩展 WS2812B SPI 驱动,支持多灯带、动态灯效与自动化构建 于 2026 年 11 月 9 日合并。原本只需几行代码就能点亮灯带的简单驱动,如今也能够承担多路设备、可配置 SPI 时序和应用可选灯效的场景。[S1]

WS2812B 灯带颜色轮换实拍,来源于项目仓库

图:仓库提供的颜色轮换实拍预览。更多原始视频和照片见灯效演示资料;视频与具体内置灯效的对应关系以演示说明为准。

一根数据线,为什么能控制一整条灯带?

每颗 WS2812B 内部有红、绿、蓝三个发光通道和一个数字控制电路。MCU 从第一颗灯珠的 DIN 输入连续发送颜色数据,第一颗读取属于自己的 24 bit,把后续数据从 DOUT 传给下一颗;后面的灯珠重复同样的动作。没有为每颗灯珠单独分配一个数据地址,灯珠的位置就是数据在串行序列中的顺序。[S4]

1
2
3
4
5
flowchart LR
A["MCU 数据输出"] --> B["LED0 DIN"]
B -->|"DOUT"| C["LED1 DIN"]
C -->|"DOUT"| D["LED2 DIN"]
D --> E["后续灯珠"]

每颗灯珠接收三个 8 bit 颜色通道,排列顺序是 G → R → B(GRB),而不是应用中常见的 RGB。比如软件调用 ws2812_set_pixel(dev, 0, 0x00112233),表示 R=0x11、G=0x22、B=0x33,实际发送的三个字节顺序为 0x22、0x11、0x33,并且每个字节的高位在前。[S3][S4]

WS2812B 也不使用普通 UART 那种固定的 0/1 电平编码。其数据位由先高后低的脉冲构成:逻辑 0 的高电平较短,逻辑 1 的高电平较长,灯珠通过高、低电平持续时间识别数据。整帧发送后,数据线保持足够长的低电平(RESET / Latch),灯珠才更新显示。[S4]

SPI 为什么可以驱动没有 SCK 引脚的 WS2812B?

WS2812B 本身不是 SPI 从设备,它不接收 SPI 时钟,也没有标准 SPI 片选命令。这里借用 MCU 的 SPI 外设产生精准、连续的 MOSI 高低电平波形:一个 WS2812B 逻辑位可以展开成多个 SPI 位,以 SPI 时钟周期的数量控制高电平和低电平时长。[S3][S4]

例如实际 SPI 时钟为 9 MHz,使用 12 个 SPI 时钟表示一个灯珠数据位,逻辑 0 的高电平占 3 个时钟,逻辑 1 占 6 个时钟,则可按下面方式生成 MOSI 输出:

1
2
逻辑 0  →  111000000000  →  高电平约 0.333 μs,低电平约 1.000 μs
逻辑 1 → 111111000000 → 高电平约 0.667 μs,低电平约 0.667 μs

每个灯珠数据位的总时长为 12 / 9 MHz ≈ 1.333 μs。这是一组针对项目所支持的 WS2812B-V5 时序的配置示例,不能仅凭“都是 WS2812B”就将它无条件用于经典版或其他兼容器件。软件包分别提供 WS2812_VARIANT_LEGACY 与 WS2812_VARIANT_V5,实际波形仍需按对应器件数据手册与真实 SPI 分频核对。[S3][S4]

为什么原来的驱动需要重构?

原版驱动的优点是直接:找到 SPI 设备,把 RGB 颜色按固定方式转换成 SPI 数据,再调用 rt_spi_send()。但它的源码内固定使用 6 MHz SPI、0xC0 / 0xF0 编码与 SPI Mode 3;头文件还包含了特定 STM32L4 的依赖。随着 BSP 种类、灯带型号和效果需求增加,这种固定方式不够灵活。[S2]

原实现还使用全局的单像素临时编码缓冲区,创建对象时直接调用 rt_malloc(),缺少多设备集中配置、设备级亮度/Gamma 管理及独立灯效模块。对于“点亮几颗 LED”的场景,这些限制可能不明显;但对不同 SPI 外设、不同灯珠修订、不同长度的灯带和多路同步动画,就会增加应用层的重复开发量。[S2]

重构后的主要变化如下:[S1][S2][S3]

对比维度 旧版驱动 PR #5 合并后的实现
SPI 时序 固定 6 MHz 与 0xC0/0xF0 直接配置、预设时序表、搜索回退三种策略
多灯带 主要面向简单单设备使用 Kconfig 最多 3 个命名槽,并可按容量创建其他实例
编码 按 24 个数据位逐位生成 16 项四位查表编码,可选逐位回退
内存 使用 Heap 创建对象及缓冲区 可选静态对象/像素/帧池或 Heap
颜色处理 直接写入 RGB 数据 每设备亮度缩放、Gamma 2.2/2.8 与可选自定义 Gamma
灯效 应用自行组织 7 种可裁剪内置效果,并允许注册自定义方法
交互与验证 基础函数调用为主 可选 MSH 调试、配置检查、STM32F407 编译矩阵与文档

重构不是把硬件发送改为另一种接口:底层依旧是 RT-Thread SPI。变化在于把“颜色、时序、设备资源、灯效更新”分开管理,使应用不必再把每个功能都混写在业务线程里。

这次 PR 带来了哪些实用优化?

1. 一个软件包管理多条灯带

每路灯带可以拥有独立的 SPI 设备名、灯珠数量、时序参数、亮度、Gamma 与灯效状态。Kconfig 可展示最多三个命名设备槽;WS2812B_MAX_DEVICES 管理设备注册表的总容量,手工通过 C API 创建的设备也计入其中,不能把“三个命名槽”误理解为驱动的全部实例数量。[S3]

BSP 如果已经注册 SPI 设备,应用可以直接使用;否则在初始化前注册 ws2812_set_kconfig_attach() 回调,由板级代码执行实际的 SPI attach。引脚、片选与外设初始化仍属于 BSP 职责,软件包不会凭一个设备名自动把硬件连接好。[S3]

2. 快速编码降低重复计算

新方案在设备初始化时,预先生成 16 种 4 bit 数据组合对应的 SPI 波形模板。编码一颗 RGB 灯珠时,将 G、R、B 三个字节各分为高四位、低四位,使用 6 次模板复制填充帧数据;不再每次都对 24 bit 逐个展开波形。[S3]

可选的 WS2812B_ENCODER_AUTO 能在快速编码不适用时回退到通用逐位实现。需要注意的是,这项优化减少的是 CPU 编码操作,不会凭空缩短协议要求的物理波形或减少 SPI 实际必须发送的数据量。

3. 亮度与 Gamma 调整更方便

新 API ws2812_set_brightness() 以 0~255 设置亮度;Gamma 处理支持关闭、2.2 查表、2.8 查表以及需要额外编译选项的自定义指数。软件包保留原始 RGB888 像素值,调整亮度或 Gamma 后重新生成编码数据,因此不必让应用重新保存整条灯带的颜色表。[S3]

Gamma 校正用于改善低亮度区域的视觉变化规律,并不替代电源限流、硬件恒流与 LED 真实亮度标定。固定查表需要相应编译选项,自定义计算还需要数学库支持。

4. 七种动态灯效,按需编译

内置灯效 效果
Solid 整条灯带显示固定颜色
Blink 在前景色和背景色之间切换
Breathe 周期性渐亮、渐暗
Gradient 整条灯带在两种颜色之间随时间过渡
Gradation 不同位置形成空间颜色渐变,并随时间变化
Chase 高亮像素沿灯带移动
Sequence 按预设颜色与 Tick 时长循环切换

这些效果是可选模块,SConscript 根据 Kconfig 决定编译哪些源文件。应用也可以注册自定义效果方法。[S3]

软件包不创建专门的灯效线程,也不会自动轮询。 应用需要在已有线程或事件循环里调用 ws2812_effect_poll_all(rt_tick_get())。效果模块只在像素确实变化时发出完整 SPI 帧,可以避免不必要的重复刷新;同一设备的轮询、效果切换与 MSH 操作需由应用串行化。[S3]

5. 保留旧接口,增加可检查错误的新接口

ws2812_create()、ws2812_clear_buff()、ws2812_write_rgb_to_node()、ws2812_write_rgb_to_all()、ws2812_send() 这五个原公开 API 保持原函数名和参数签名。同时增加 ws2812_create_with_config()、ws2812_set_pixel()、ws2812_fill()、ws2812_send_frame() 等接口,供需要设备级配置和返回值判断的应用使用。[S3]

不过,函数签名兼容不意味着内部结构和资源释放方式完全不变。新对象可能来自静态内存池,也可能由 Heap 分配,当前没有公开的设备销毁 API;旧示例若直接对设备对象使用 rt_free(),不能照搬到新版。

在 RT-Thread 中怎样使用?

第一步:准备硬件与软件包

灯带的 DIN 连接到 MCU 实际用于输出数据的 SPI MOSI,灯带接好对应电源和公共地。SCK 并不连接到灯带的时钟输入,因为 WS2812B 没有这个引脚。板级还需确认 MOSI 空闲电平、输出逻辑电平与灯珠供电是否兼容。[S4]

在 RT-Thread 中启用 SPI 设备框架和 PKG_USING_WS2812B,确保 BSP 已创建期望的 SPI 设备,例如 spi10。软件包通过 rt_device_find() 找到它,不负责代替 BSP 创建 SPI 总线、GPIO 或 DMA 配置。[S3]

配置同步提示: 截至本文检查时,功能代码已经进入 maplerian/rt_ws2812b,但独立维护的 RT-Thread/packages 索引中,peripherals/ws2812b/Kconfig 仍保留旧版菜单。若 menuconfig 看不到多设备、Gamma、灯效等新选项,需要先确保项目使用的新 Kconfig 与已获取的软件包源码同步;仅拉取最新版驱动源码并不一定自动出现这些菜单。[S1][S6]

第二步:先让单条灯带点亮

在已同步新版 Kconfig 且启用设备槽 0 的项目中,设置 SPI bus/device 名称、灯珠数量、真实 SPI 时钟、灯珠版本及脉冲参数。下面的应用代码假设 SPI 设备已由 BSP 注册,且启用了 WS2812B_USING_KCONFIG_DEVICES:[S3]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#include "ws2812.h"

static rt_err_t app_led_show(void)
{
ws2812_t strip;
rt_err_t err;

err = ws2812_init_all();
if (err != RT_EOK)
return err;

strip = ws2812_get_kconfig_device(0U);
if (strip == RT_NULL)
return -RT_ERROR;

err = ws2812_fill(strip, 0x00000000U);
if (err != RT_EOK)
return err;

err = ws2812_set_pixel(strip, 0U, 0x00FF0000U);
if (err != RT_EOK)
return err;

return ws2812_send_frame(strip);
}

这段代码把灯带清为黑色、将第 0 颗灯珠设置为红色,再发送一整帧。ws2812_set_pixel() 只修改内存中的像素和编码数据,真正的硬件发送发生在 ws2812_send_frame()。ws2812_init_all() 应在启动时只执行一次,不应放进周期性刷新循环。[S3]

如果继续使用原有 API,也可以在具备合适运行时内存和已注册 SPI 设备的配置下调用 ws2812_create("spi10", LED数量),然后用 ws2812_write_rgb_to_node() 与 ws2812_send() 控制颜色;该兼容创建函数仍按旧版 6 MHz、SPI Mode 3、固定编码 工作,并不是自动适配所有灯珠和 BSP。[S3]

第三步:按需启动动态灯效

启用 WS2812B_USING_EFFECT 以及所需具体方法后,初始化顺序为:先注册内置方法,再创建设备,最后加载 Kconfig 默认效果。默认效果的启动过程不会立即发送 SPI,首帧仍依靠应用轮询。[S3]

1
2
3
4
5
6
7
8
9
10
11
12
/* 启动阶段,检查每一步是否返回 RT_EOK。 */
rt_err_t err = ws2812_effect_register_builtins();
if (err == RT_EOK)
err = ws2812_init_all();
if (err == RT_EOK)
err = ws2812_effect_init_kconfig();

/* 上述调用成功后,在应用已有线程的周期循环中执行。 */
if (err == RT_EOK)
{
(void)ws2812_effect_poll_all(rt_tick_get());
}

最后一段是单次轮询示意,需由应用自行放进周期性线程或事件循环,并处理返回值;例如应用可自行选择约 20 ms 的轮询间隔,该间隔并不是 WS2812B 协议的硬要求。Sequence 的颜色步骤时长使用 RT-Thread Tick,而不是毫秒。[S3]

若额外启用 WS2812B_USING_MSH,还可以在 FinSH/MSH 中调试:

1
2
3
4
5
6
7
8
ws2812b list
ws2812b bright 64
ws2812b s red
ws2812b bl
ws2812b gd
ws2812b seq
ws2812b reset
ws2812b help

以上命令及具体颜色参数可以通过 ws2812b help 查询。调试命令依赖对应编译选项,并非安装软件包后必然出现。[S3]

关于 RAM、时序与移植,有几点需要明确

WS2812B 每颗灯珠为 24 bit,假设每个逻辑数据位展开成 C 个 SPI 时钟,则 N 颗灯珠仅编码数据就需要 3 × N × C 字节;新版驱动还在帧前、帧后分别填充 RESET 低电平数据。灯珠多、SPI 展开倍数高时,发送缓冲区可能占用较多 RAM。[S3][S4]

采用静态模式时,Kconfig 预留的像素池和 SPI 发送帧必须足够;采用动态模式时,需要项目启用 Heap,并关注内存分配结果。快速查表减少 CPU 编码量,不等于零内存开销。对于 SPI DMA、片选控制、传输完成后的 MOSI 空闲状态和 RESET 低电平,仍应在目标 BSP 上测量确认。PR 中记录的 STM32F407 10 组编译与 ELF 链接成功属于构建验证,不能替代真实灯带的波形与电气测试。[S1][S3][S4]

原软件包已经合并功能,进一步说明去哪看?

此次重构通过 PR #5 合并回原始软件包仓库,因此日常使用、软件包下载和上游问题反馈仍可以原仓库为主;它不是一套必须切换到 Fork 才能使用的独立驱动。[S1]

扩展仓库配置了 MkDocs 文档及 GitHub Pages 发布工作流,文档包括硬件时序、配置说明、架构和灯效实拍。原仓库负责承接并合并软件包功能,扩展仓库则方便通过在线文档查阅更详细的技术资料;二者的当前驱动功能不应在宣传中人为区分成两个版本。在线站点若暂时无法访问,也可以直接阅读仓库 doc/ 下的 Markdown 文件。[S5]

欢迎使用与反馈

WS2812B 软件包已经不再局限于固定 SPI 编码的点灯示例。对于需要多路状态指示、呼吸灯、流水灯、颜色序列或定制灯效的 RT-Thread 项目,可以直接尝试这次重构后的实现。

同时欢迎在不同 BSP 上验证 SPI 实际时钟、MOSI 逻辑电平、RESET 时序、多路设备与灯效表现;反馈时提供 MCU/BSP、SPI 设备名、灯珠版本、时序配置和复现现象,能够帮助后续提高跨平台可用性。构建通过与目标板实测是两件事,欢迎结合实际灯带提出 Issue 或改进 PR。

资料来源

[S1] PR #5 的合并记录与测试说明

  • 版本:2026-11-09 合并;PR #5
  • 2026-11-09 合并至上游;扩展 WS2812B SPI 驱动,支持多灯带、动态灯效与自动化构建。用于确认功能范围、PR 状态、10 组编译矩阵及尚未提供目标板实测证据。
  • 使用位置:开场消息、重构功能、验证边界
  • 支撑内容:合并日期、PR 声明的功能和 STM32F407 十组编译/链接结果

[S2] 重构前的源码

  • 版本:c17c13abff1dcf9fcecf3c76943578c87dab5658
  • PR base c17c13abff1dcf9fcecf3c76943578c87dab5658;原版 ws2812.c 和 原版 ws2812.h。用于对照固定 SPI 编码、Heap 使用和 STM32 专用头文件。
  • 使用位置:为什么原来的驱动需要重构
  • 支撑内容:旧版固定 6 MHz SPI 编码、动态分配、全局临时缓冲和 STM32 专用头文件

[S3] 合并后的软件包与 API

  • 版本:3de8be384a7580cf540024cfa7936cc0ea5701de
  • merge commit 3de8be384a7580cf540024cfa7936cc0ea5701de;ws2812.c、ws2812.h、Kconfig、灯效 API。用于确认新设备管理、快速编码、像素/发送 API、效果注册和编译裁剪行为。
  • 使用位置:重构优化、如何使用、内存限制
  • 支撑内容:新版 Kconfig、编解码、设备管理、灯效 API 和兼容接口

[S4] WS2812B 协议与 SPI 编码说明

  • 版本:2026-11-15 访问时的项目文档
  • 项目单线时序文档,该文档列有 Worldsemi 经典版与 V5 数据手册以及 RT-Thread SPI 设备文档来源。用于说明 GRB、级联、脉宽编码、SPI MOSI 波形、RESET 与帧长度。
  • 使用位置:单线通信原理、SPI 编码、移植边界
  • 支撑内容:DIN/DOUT 级联、GRB 数据顺序、逻辑位脉宽、RESET 和 SPI 波形

[S5] 扩展仓库在线文档

  • 版本:2026-11-15 访问时的 Fork master 文档
  • 项目文档目录、MkDocs 配置、Pages 发布工作流。用于说明在线文档的构建形式和技术资料入口。
  • 使用位置:原软件包与在线文档的关系
  • 支撑内容:Fork 的 MkDocs 文档内容以及 Pages 工作流配置

[S6] RT-Thread 软件包索引

  • 版本:2026-11-15 访问时的 RT-Thread/packages master
  • RT-Thread/packages 的 WS2812B Kconfig 与 package.json。用于说明软件包代码仓库与独立 Kconfig 索引的集成边界;状态检查于 2026-11-15。
  • 使用位置:安装和 menuconfig 配置同步提示
  • 支撑内容:软件包索引单独维护且其 Kconfig 尚未同步新增选项