简介：这是一份基于STM32F103C8微控制器，通过SPI+DMA方式驱动WS2812B RGB LED灯条的完整工程资源，适合嵌入式初学者、LED显示控制开发者以及准备学习STM32外设协同工作的工程师。工程不仅提供可直接编译运行的Keil及IAR项目，还包括CubeMX的.ioc配置文件、558个C源码、243个H头文件、汇编启动文件、DSP数学库、链接脚本以及编译批处理脚本，共897个文件，整体约15.9MB，结构清晰，便于定位驱动逻辑与修改配置。该项目重点展示了如何用CubeMX快速初始化SPI和DMA，借助DMA减轻CPU负担，满足WS2812B高达800kHz的时序要求，实现流畅的RGB动画；同时包含颜色数据转换、灯串级联发送等实用代码，可直接移植到其他类似项目。目前已有1941人学习下载，适合对照源码理解时序适配与外设分工，也可作为二次开发的稳定起点。 正好手头在做一个小型桌面氛围灯的项目，当时为了方便调试和验证方案，就把核心代码和资料打包成了这样一个压缩包。后来发现不少朋友在折腾STM32F103C8和WS2812B组合时遇到了各种问题，尤其是网上那个高频搜索词“WS2812B第一个灯永远是绿的”，基本每个新手都会撞上。这篇文章就结合我实际调试的经验，把STM32F103C8驱动WS2812B灯带从原理到代码再到避坑，一次性讲透。
1. 整体设计思路与方案选型
1.1 为什么选择STM32F103C8T6 + WS2812B
先说结论：这套组合是入门级单片机驱动可寻址LED灯带最经典、最不容易翻车的搭配，没有之一。
STM32F103C8T6（也就是大家常说的“C8T6”或“蓝丸”）主频72MHz，自带256KB Flash、64KB SRAM，价格便宜、资料丰富、生态成熟。虽然现在ARM Cortex-M4/M7的芯片满天飞，但C8T6这颗Cortex-M3内核的老将，在处理WS2812B这种对时序要求苛刻的外设时，性能完全够用，而且不用担心买到假货的问题——因为实在太多了，假货性能也足够跑这个项目。
WS2812B则是目前市面上最流行的智能外控集成LED，内部集成了控制电路和RGB三色芯片，只需要一根信号线就能串联驱动任意数量的灯珠，每颗灯珠可独立显示1670万种颜色。它内部有一个800Kbps（也就是1.25微秒一个bit）的数据协议，每个bit的时长由高低电平的占空比决定。这个“单总线”协议用起来极其方便，但对MCU的时序精度要求比较高，恰好STM32的定时器+PWM+DMA就是为这种场景量身定做的。
1.2 技术方案对比：为什么不用GPIO延时模拟
先说很多新手一上来就会选用的方式：直接拉GPIO，然后用delay_us()延时翻转电平。这个方法行不行？行，但只适用于灯珠数量少、对刷新率不敏感的场景。原因有三：
第一，WS2812B的0码和1码差异是微妙级的。0码要求高电平0.4us、低电平0.85us，1码要求高电平0.8us、低电平0.45us。虽然数据手册上有个容差范围（±150ns），但在72MHz下用软件延时模拟，一个for循环的误差就可能达到100ns以上，再加上中断干扰，极易造成灯珠颜色漂移、闪烁。
第二，GPIO翻转模式下，CPU必须全程占用。每颗灯珠需要24bit数据，100颗灯就是2400bit，按照每bit约2.5us的翻转时间算，刷新一轮就需要6ms以上。这期间你什么都干不了，CPU资源严重浪费。
第三，也是最容易被忽略的：软件延时方案对中断是“裸奔”的。只要系统里开了定时器中断、串口中断，哪怕只打断一次，整条数据链路就乱了，表现就是灯珠乱闪、颜色不对。
所以我最终选择的是**“定时器PWM + DMA + 内存映射”**方案。核心思路是：用定时器产生固定频率的PWM波形，DMA直接把内存中的数据搬运到定时器的比较寄存器，从而在不需要CPU干预的情况下精确控制每一个bit的高低电平时长。这样CPU全程解放，即使灯珠数量增加到几百颗，CPU占用率也基本可以忽略不计。
这个方案的底层原理，其实就是用PWM的占空比来模拟WS2812B的0码和1码。假设定时器时钟72MHz，我们配置PWM频率为800kHz（即1.25us一个周期），那么每个周期对应72000000 / 800000 = 90个计数单位。0码需要高电平占空比约1/3（高电平约0.4us），也就是比较值设为30；1码需要高电平占空比约2/3（高电平约0.8us），比较值设为60。这样就不需要每bit都去翻转GPIO，而是直接把bit值映射成比较寄存器值，用DMA连续写入即可。
2. 硬件连接与电源设计
2.1 引脚选择与连接
WS2812B灯带一般引出来三根线：VCC（5V）、GND（地线）、DIN（数据输入）。STM32F103C8T6的GPIO输出电压是3.3V，而WS2812B的数据信号高电平阈值大约在2.5V左右，理论上是能识别的。但实际工程里，我强烈建议在数据线上加一个电平转换电路，或者至少串联一个100Ω~330Ω的电阻。
不要小看这个电阻，它有两个作用：一是限制信号边沿的上升/下降速度，减少EMI辐射；二是匹配阻抗，防止数据线过长时产生反射导致信号畸变。我实测下来，当灯带线长超过30cm时，不加电阻会出现偶发性的灯珠错乱，加了之后问题立刻消失。
具体连接方式如下：
| 灯带引脚 | 连接目标 | 说明 |
|---|---|---|
| VCC | 5V电源正极 | 需要独立电源，不能直接吃MCU的3.3V |
| GND | 电源地 + MCU地 | 必须共地，否则信号无参考电平 |
| DIN | STM32 PA0（或其他引脚） | 通过100~330Ω电阻连接 |
这里特别提醒一点：WS2812B的数据信号不能直接和5V电源共地之外再共用一根线。有些新手图省事，把DIN直接接到MCU引脚，然后在Proteus里仿真通过了，就以为实物没问题。Proteus里那个“怎么为STM32F103C8设置电源”的热词，其实就是在仿真时被这个坑卡住了——仿真软件里默认忽略了很多硬件上的细节，实物永远不会按仿真的逻辑跑。
2.2 电源设计是重中之重
这是整个项目里最容易翻车、也是翻车之后最难看出来的地方。WS2812B单颗灯珠在**全白（R=G=B=255）**情况下，最大电流约为60mA。如果你用了一米灯带（60颗灯珠），理论上最大电流就是3.6A！这个电流完全超出了USB口（一般500mA~1A）和线性稳压器（如AMS1117-3.3）的供电能力。
我的经验做法是：
- 灯珠数量≤30颗：可以直接用5V 2A的电源适配器供电，但必须在灯带电源输入端并联一个1000μF电解电容（越大越好），用来吸收灯珠切换瞬间的电流尖峰。同时每颗灯珠的VCC和GND之间要尽量靠近放置一个0.1μF去耦电容，虽然WS2812B内部已经有稳压电路，但外部去耦能大幅提升稳定性。
- 灯珠数量>30颗：采用分段供电。每50颗左右从电源处单独拉一对VCC/GND线，不要指望一根线从头串到尾。电源线线径也要加粗，建议使用22AWG以上的硅胶线，否则压降会非常明显，表现为灯带尾部颜色偏暗、偏黄。
再强调一遍：MCU的电源和灯带的电源必须隔离。MCU用3.3V供电（蓝丸板载稳压器），灯带用5V供电，两者只需要共GND即可。这样即使灯带瞬间拉低电压，也不会导致MCU复位重启。
3. WS2812B驱动协议与时序解析
3.1 数据协议格式
WS2812B的数据协议采用NRZ（非归零）编码方式，每颗灯珠固定需要24bit数据，格式是G（绿色）8bit + R（红色）8bit + B（蓝色）8bit，注意这个顺序和大多数人的直觉不一样——不是RGB，而是GRB。
数据传输顺序是从第一颗灯珠开始，依次向后。每一颗灯珠会将收到的前24bit数据锁存给自己，然后把后面的数据整形后通过DOUT转发给下一颗灯珠。这个“整形转发”的机制非常巧妙，它保证了信号在长距离传输时不会衰减，但也意味着：一旦前面的灯珠数据错了，后面所有灯珠都会跟着错。
完整的发送时序如下：
| 时序阶段 | 电平要求 | 时长 |
|---|---|---|
| Reset码 | 低电平 | ≥50μs（推荐80μs以上） |
| 0码 | 高电平0.4μs + 低电平0.85μs | 总时长约1.25μs |
| 1码 | 高电平0.8μs + 低电平0.45μs | 总时长约1.25μs |
也就是说，每bit数据的速率是800Kbps，发送完所有灯珠的数据后，必须再发送一个至少50μs的低电平作为“锁存信号”，灯珠才会把收到的数据真正显示出来。这个Reset信号是很多新手忽略的重点——如果发送完数据后直接结束，灯带不会呈现任何颜色。
3.2 为什么“第一个灯永远是绿的”
这是我们在实际项目里踩过的最典型的坑，也是网上搜索量极高的一个问题。网上很多帖子给出的解释“因为第一个灯的数据发错了”，这个说法对，但不够准确。
真正的原因主要有三种，我按出现概率从高到低排列：
第一，上电瞬间多发了4字节全0数据。很多开发板的USB转串口芯片（如CH340、CP2102）在上电时，会在TX引脚（对应MCU的RX）产生一个短暂的低电平脉冲。如果你的DIN接到了PA0，恰好PA0的代码初始化时默认是浮空输入，那么这个脉冲就会被WS2812B“吃掉”，导致第一颗灯珠默默吞掉全0数据。由于GRB全0是黑色（不亮），看起来没什么问题，但问题在于：这个脉冲破坏了数据帧对齐，第一颗灯珠会认为自己收到的数据就是那一帧的24bit，后续真正的数据链路整体错位，导致第一颗灯珠永远显示“上一帧最后一个灯珠的颜色”，或者干脆就是绿的——因为绿色通道是数据帧中最先到达的8bit。
第二，GPIO初始化时电平状态未处理。如果你在初始化GPIO时，先把引脚配置为推挽输出且默认输出高电平，再配置为复用功能，这个“先高后低”的过程会产生一个毛刺。这个毛刺恰好可能被WS2812B识别为0码或1码，破坏首帧数据。
第三，上电复位后数据引脚悬空。如果MCU复位后引脚处于高阻态（浮空输入），外部干扰会在这个引脚上产生随机噪声，灯珠上电初始化后就会接收到这些垃圾数据。
解决办法也很简单：在发送第一帧有效数据之前，先发送一个至少100μs的Reset信号（拉低数据线），强制清空所有灯珠的内部缓冲区。同时，在GPIO初始化时，先将引脚配置为输出模式并拉低，再切换到复用功能。这两个操作加起来就能解决99%的“第一个灯永远是绿的”问题。
3.3 高电平电压不够
这个问题经常出现在使用3.3V MCU直接驱动WS2812B的场景。WS2812B的数据输入高电平阈值虽然标称是0.7×VCC（3.5V），但实际上，由于芯片内部有电平判断电路，3.3V的高电平在很多批次下可以正常工作。不过，当灯带供电电压偏低（比如只有4.8V），或者MCU引脚负载较大时，就可能出现临界状态，表现为第一颗灯珠正常，后面灯珠偶尔错乱。
这里我的建议是：Debug阶段先用一颗灯珠 + 示波器/逻辑分析仪验证时序，再上整条灯带。如果示波器上看到的波形高电平只有2.8V左右，建议加一个74HCT245或SN74LVC4245芯片做电平转换。不要相信网上说的“3.3V直接驱动没问题”，那是运气好，工程上稳才是第一位的。
4. 驱动代码实现：定时器PWM + DMA方案
4.1 底层原理
我们前面提到，用PWM波形的占空比来模拟WS2812B的协议是效率最高的方式。但在实际编码时，需要解决一个关键问题：如何把bit映射为定时器比较值。
以STM32F103C8的TIM1为例，该定时器挂载在APB2总线上，时钟为72MHz。我们将TIM1的PWM频率设为800kHz，这样每个bit周期为1 / 800000 = 1.25μs。为了留够操作余量，我采用4分频的方式，把PWM频率设为3.2MHz，这样每个计数单位对应1 / 3200000 = 0.3125μs。在这个时间精度下，我们可以用整数倍来模拟时序：
- 0码：高电平占1个计数单位（约0.3125μs，实际会偏短），低电平3个计数单位，总计约1.25μs。
- 1码：高电平3个计数单位（约0.9375μs，偏长），低电平1个计数单位，总计约1.25μs。
为了更精确，我实际采用的方案是把PWM频率设为2.5MHz（即分频系数72 / 2.5 = 28.8不整除，所以我改成28MHz分频，时序会有一点误差但可用）。这里有一个更推荐的方案：把PWM周期设为定时器溢出值90，PWM频率为72MHz / 90 = 800kHz，比较值设两个档位：
- 0码：比较值
CCR = 30（高电平30个计数，约0.416μs） - 1码：比较值
CCR = 60（高电平60个计数，约0.833μs）
这样每个bit严格占用90个计数周期（1.25μs），完全符合数据手册要求。这个方案的实现方式就是典型的“分段查找表”：
#define BIT_0_COMPARE 30 #define BIT_1_COMPARE 60 #define RESET_COMPARE 0 // 持续低电平发送每个字节时，从高位到低位逐bit判断，把比较值写入缓冲区，然后由DMA搬移到定时器的CCR寄存器。
4.2 完整代码实现
下面是我在项目中实际使用的代码（基于标准外设库，HAL库同理）：
#include "stm32f10x.h" #include "ws2812b.h" #define WS2812B_PIN GPIO_Pin_0 #define WS2812B_PORT GPIOA #define WS2812B_TIM TIM1 #define WS2812B_DMA_CH DMA1_Channel4 #define LED_COUNT 60 #define DMA_BUFFER_SIZE (LED_COUNT * 24) /* 一帧完整数据：每个bit对应一个DMA缓冲区单元 */ uint32_t dma_buffer[DMA_BUFFER_SIZE]; uint8_t led_data[LED_COUNT][3]; // 存储GRB颜色 void ws2812b_init(void) { GPIO_InitTypeDef GPIO_InitStructure; TIM_TimeBaseInitTypeDef TIM_TimeBaseStructure; TIM_OCInitTypeDef TIM_OCInitStructure; DMA_InitTypeDef DMA_InitStructure; /* 1. 初始化GPIO为复用功能推挽输出 */ RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA | RCC_APB2Periph_TIM1, ENABLE); RCC_AHBPeriphClockCmd(RCC_AHBPeriph_DMA1, ENABLE); GPIO_InitStructure.GPIO_Pin = WS2812B_PIN; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_AF_PP; GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(WS2812B_PORT, &GPIO_InitStructure); /* 2. 初始化定时器为PWM模式，周期为90个计数单位，即1.25us */ TIM_TimeBaseStructure.TIM_Period = 90 - 1; TIM_TimeBaseStructure.TIM_Prescaler = 0; TIM_TimeBaseStructure.TIM_ClockDivision = 0; TIM_TimeBaseStructure.TIM_CounterMode = TIM_CounterMode_Up; TIM_TimeBaseInit(WS2812B_TIM, &TIM_TimeBaseStructure); TIM_OCInitStructure.TIM_OCMode = TIM_OCMode_PWM1; TIM_OCInitStructure.TIM_OutputState = TIM_OutputState_Enable; TIM_OCInitStructure.TIM_Pulse = 0; TIM_OCInitStructure.TIM_OCPolarity = TIM_OCPolarity_High; TIM_OC1Init(WS2812B_TIM, &TIM_OCInitStructure); TIM_OC1PreloadConfig(WS2812B_TIM, TIM_OCPreload_Enable); /* 3. 配置DMA，内存到外设模式 */ DMA_DeInit(WS2812B_DMA_CH); DMA_InitStructure.DMA_PeripheralBaseAddr = (uint32_t)&WS2812B_TIM->CCR1; DMA_InitStructure.DMA_MemoryBaseAddr = (uint32_t)dma_buffer; DMA_InitStructure.DMA_DIR = DMA_DIR_PeripheralDST; DMA_InitStructure.DMA_BufferSize = DMA_BUFFER_SIZE; DMA_InitStructure.DMA_PeripheralInc = DMA_PeripheralInc_Disable; DMA_InitStructure.DMA_MemoryInc = DMA_MemoryInc_Enable; DMA_InitStructure.DMA_PeripheralDataSize = DMA_PeripheralDataSize_Word; DMA_InitStructure.DMA_MemoryDataSize = DMA_MemoryDataSize_Word; DMA_InitStructure.DMA_Mode = DMA_Mode_Normal; DMA_InitStructure.DMA_Priority = DMA_Priority_High; DMA_InitStructure.DMA_M2M = DMA_M2M_Disable; DMA_Init(WS2812B_DMA_CH, &DMA_InitStructure); /* 4. 使能TIM1的PWM输出和DMA请求 */ TIM_CtrlPWMOutputs(WS2812B_TIM, ENABLE); TIM_DMACmd(WS2812B_TIM, TIM_DMA_CC1, ENABLE); TIM_Cmd(WS2812B_TIM, ENABLE); } void ws2812b_set_pixel(uint16_t index, uint8_t r, uint8_t g, uint8_t b) { if (index >= LED_COUNT) return; led_data[index][0] = g; // 注意：GRB顺序 led_data[index][1] = r; led_data[index][2] = b; } void ws2812b_update(void) { uint32_t pos = 0; for (uint16_t i = 0; i < LED_COUNT; i++) { for (uint8_t j = 0; j < 3; j++) { uint8_t byte = led_data[i][j]; for (int8_t k = 7; k >= 0; k--) { if (byte & (1 << k)) { dma_buffer[pos++] = BIT_1_COMPARE; } else { dma_buffer[pos++] = BIT_0_COMPARE; } } } } // 发送Reset信号：所有比较值设为0，持续低电平远超50us for (uint8_t i = 0; i < 20; i++) { dma_buffer[pos++] = RESET_COMPARE; } DMA_Cmd(WS2812B_DMA_CH, DISABLE); DMA_SetCurrDataCounter(WS2812B_DMA_CH, pos); DMA_Cmd(WS2812B_DMA_CH, ENABLE); }这段代码有几个值得注意的细节：
dma_buffer[pos++] = BIT_1_COMPARE这里的pos变量，我用了uint32_t而不是uint8_t，因为当灯珠数量超过85颗时（85 * 24 = 2040bit），缓冲区索引会超过255。用8位变量会溢出，导致死循环或者乱码。- DMA发送完一帧后，会在数据末尾追加20个
RESET_COMPARE（即60个计数周期的低电平，约75μs），确保灯珠正确锁存。这个数字其实可以再大一点，但20已经足够了。 - 每次调用
ws2812b_update()时，我会重新关闭再打开DMA，目的是为了让DMA从头开始搬运。DMA_SetCurrDataCounter这个函数非常关键，如果不重新设置计数，第二次调用时DMA不会工作。
4.3 使用HAL库时的差异
如果你使用的是HAL库（CubeMX生成），核心区别在于DMA的初始化方式和DMA中断回调函数。PWM+DMA的注册方式类似，但需要注意：
- CubeMX里要配置TIM1的Channel1为PWM Generation，并把DMA_Settings设置为
Memory To Peripheral，模式Normal。 - DMA句柄
hdma_tim1_ch1需要在启动DMA之前手动调用HAL_DMA_Start_IT()或HAL_DMA_Start()。 - 因为WS2812B是没有时钟线的，所以不能使用半字或字节传输模式，必须使用32位字传输，否则DMA搬运的字节顺序会错乱。
4.4 优化：用双缓冲避免闪烁
当你灯珠数量比较多（比如超过144颗）时，一次ws2812b_update()发送的数据量比较大，期间如果CPU尝试修改led_data数组，就会导致画面撕裂或者闪烁。解决办法是使用双缓冲：定义两组led_data和dma_buffer，在DMA发送期间修改“备用缓冲区”，发送完成后再交换。这个优化在写动态动画效果时非常实用，但初版代码可以先不用，等动画做复杂了再加。
5. 常见问题排查与避坑实录
下面这些问题，是我在帮网友调试过程中遇到频率最高的，整理成了一个速查表，建议收藏：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 第一个灯永远是绿色 | 上电毛刺/GPIO初始化时序问题 | 发送前加100μs Reset信号；初始化时先拉低GPIO |
| 灯带完全不亮 | 供电不足/数据线接反 | 检查5V供电容量；确认DIN接对，不是DOUT |
| 后面灯珠颜色错乱 | 信号反射/电平衰减 | 数据线串联100~330Ω电阻；缩短线长；共地 |
| 颜色偏暗或偏黄 | 电源压降严重 | 分段供电；加粗电源线；增大滤波电容 |
| 刷新时闪烁 | 未加Reset信号或Reset时长不足 | 确保Reset信号≥50μs，推荐100μs |
| 第一个灯熄灭了 | 数据帧发送失败 | 检查DMA通道配置和缓冲区大小 |
5.1 Proteus仿真中的电源设置问题
顺着开头的热词“proteus怎么为stm32f103c8设置电源”再多说一句。Proteus的STM32仿真模型默认使用VCC引脚供电，但C8T6属于3.3V器件。在Proteus的“Design > Configure Power Rails”里，你需要把VCC设置为3.3V（或使用3.3V端子），并把所有VDD引脚都连到这个电源网络上。很多人在仿真里发现WS2812B颜色不对，其实是因为仿真模型里电源设置成了默认5V，MCU引脚输出的逻辑电平和真实不符。
仿真可以快速验证逻辑，但请记住：仿真通过 ≠ 实物能跑。时序、竞争冒险、电源完整性这些问题，仿真模型根本不模拟。所以我调试这类项目时，永远用逻辑分析仪或示波器当作最终裁判，别只盯仿真。
5.2 关于“WS2812B STC8G”热词的一点建议
有相当一部分人也在搜“ws2812b stc8g”，说明有人想用STC8G系列单片机驱动WS2812B。STC8G是国产51内核的单片机，主频最高24MHz，驱动WS2812B需要非常精细的汇编或状态机，而且没有DMA，CPU占用率极高。虽然可行，但体验远不如直接用STM32或者ESP32。如果你手头恰好只有STC8G，建议把时序宏定义好，然后严格关中断发送，否则必然出问题。但如果你还在选型阶段，我的建议是别纠结了，直接用STM32F103，省心太多。
6. 拓展玩法与经验总结
调试完基本的点灯之后，这个项目的可玩性马上就出来了。我基于这套驱动做了几个有意思的功能，这里分享下思路：
第一个是音乐频谱灯效。用ADC采集音频信号，做FFT变换（STM32F103的运算力做64点FFT够用），然后根据频段能量映射到灯带位置和颜色。实现时需要在DMA发送期间进行FFT计算，这时候双缓冲的作用就体现出来了。
第二个是环境光自适应。加一个光敏电阻或者环境光传感器，根据光照强度自动调整灯带亮度和色温。这个实现起来很简单，核心就是ADC采样 + 线性映射，但效果非常实用。
第三个是和ESP8266/ESP32组网联动。用ESP8266的串口透传，让灯带接入智能家居网关，这样就能用手机App控制灯带的颜色和模式。需要注意的是，ESP8266的GPIO输出也是3.3V，同样的电平转换问题需要处理。
最后再分享一个实际使用的小技巧：如果你的灯带需要长时间固定一个颜色（比如白色背景灯），可以考虑把颜色值存在Flash里，上电直接读取，不用每次计算。另外，代码里加一个ws2812b_set_all(r, g, b)批量函数，调试的时候非常方便，填三组数就能看整条灯带效果，省得写循环。
这套“STM32F103C8 + WS2812B”组合，是我玩灯带以来最顺手的方案，成本极低、调试方便、上限很高。希望这次把代码和思路完整展开后，能帮你少踩几个我当年踩过的坑，特别是那个“第一个灯永远是绿色”的玄学问题。如果你在调试中还有其他奇怪的现象，欢迎留言交流，大家一起研究。
本文还有配套的精品资源，点击获取
