STM32 SPI+DMA驱动WS2811灯带：稳定时序与完整代码

之前在PHP直接驱动WS2811灯带时最烦的一件事就是“明明照着教程写的延时灯却随机乱闪”。尤其当项目里还跑着串口打印、ADC采样和按键扫描灯带就像有了自己的想法。后来把STM32F103C8T6的SPIDMA方案调通之后整套驱动就再也没闹过脾气。这篇就把我最终调通的整套思路写清楚包括WS2811协议本身、为什么最后选SPIDMA、HAL库下的完整代码以及我在实测中踩过的一串坑。如果你是正准备用STM32做氛围灯、鱼缸灯、毕业设计灯板或者已经在用GPIO点灯但觉得刷新率和稳定性都不够这篇文章可以直接给你一套能抄作业的方案。1. 先搞懂WS2811的协议才知道为什么方案选型会打架1.1 单总线串行协议不是“高低电平”这么简单WS2811和WS2812B这类芯片用的都是单线串行协议。数据引脚就一根芯片之间通过DI进、DO出级联后面一颗芯片的数据是从前面一颗“吃剩下的”数据流里截取出来的。每颗灯需要24bit数据常见格式是GRB高位在前。注意不是RGB。这个顺序在后面的代码里会反复出现很多第一次做的人都是在这里翻车的。最关键的一点是0码和1码不是靠“高还是低”来区分而是靠高电平持续时间的长短。两种码都是先高后低但高电平宽度不一样。参考典型时序码型高电平时间低电平时间周期0码0.25~0.6us0.7~1.2us约1.25us1码0.5~1.0us0.3~0.7us约1.25us传输完一整帧灯带数据后还要拉低至少50us某些WS2811版本要更久保守按300us写让芯片收到复位信号然后把当前移位寄存器里的数据锁存到输出端。这也是为什么灯带驱动代码最后总要有一大串全0的原因。用生活里的话说这有点像摩尔斯电码里的“点”和“划”区别不在有没有信号而在信号持续的时间长短。理解了这一点就明白为什么驱动WS2811本质上是“生成一串宽度精确的方波”而不是简单地把GPIO拉高拉低。1.2 为什么用GPIO手撕时序容易随缘闪灯网上大量例程是用GPIO翻转加延时函数来模拟这个时序比如GPIO_SetBits(GPIOB, GPIO_Pin_1); // 拉高 delay_ns(350); // 延时 GPIO_ResetBits(GPIOB, GPIO_Pin_1); // 拉低 delay_ns(800);在没有其它干扰的时候这个写法确实能点灯。但一旦工程变大问题就来了中断打断滴答定时器、串口接收、ADC采样任何一个中断穿插进来时序就变形了。表现就是灯带偶尔闪一下或者某个颜色跳变。延时精度不可控delay_ns()如果内部是靠空循环实现的编译器优化等级开高开低实际时间完全不同。换一颗跑得快一点的芯片时序又变了。CPU占用率拉满传输一帧数据期间CPU全程在翻转GPIO什么都干不了。灯带数量一多刷新一帧卡半天整个系统像被拖死。所以GPIO方案只适合几颗灯、不追求稳定的临时demo。只要想把它变成可靠的东西就必须把“时序活”交给硬件外设去做。接下来对比一下我实际测过的三种方案。2. 三种方案实测对比为什么SPIDMA最省心2.1 直接GPIO翻转简单但扛不住干扰这个方案的优点就是代码直观不依赖外设随便哪个引脚都能接。缺点是前面说过的时序精度和CPU占用问题。我一开始还用过一个变体把翻转代码放在定时器中断里利用定时器周期来校准延时。确实比裸延时稳定一些但每颗灯的bit传输都要进中断翻转灯带一多中断频率高得可怕严重挤占主循环。调试起来也很痛苦因为你永远不知道下一秒是哪段中断把时序吃掉了。2.2 定时器PWMDMA精度高但配置繁琐这个方案的思路是用定时器的PWM输出每个WS2811 bit对应一个PWM周期。0码和1码通过改变比较寄存器值输出不同占空比的波形然后用DMA把比较值数据按节奏喂给定时器。精度上是三种方案里最高的波形每个bit都是严格的1.25us周期。但配置也很繁琐要同时处理定时器时基、PWM模式、DMA触发源、比较值更新时机中间任何一个参数不对输出就是乱的。我在一个双路灯带项目里试过两路需要用两个定时器通道DMA请求优先级、中断回调、buffer更新逻辑越堆越复杂。如果只是想快速稳定地驱动一路或多路灯带这套方案的性价比不高。2.3 SPIDMA外设自动输出码流CPU几乎零开销SPIDMA的原理很简单用SPI的MOSI引脚当作WS2811的数据线把要发送的灯带数据预先编码成SPI发送用的buffer然后启动SPI DMA传输。传输过程中CPU完全不用介入发完触发中断通知主程序。为什么能这么干因为我们可以用多个SPI数据位来拼出一个WS2811 bit。我的驱动里用的是3个SPI bit代表1个WS2811 bit逻辑0100即一个SPI bit高、两个SPI bit低逻辑1110即两个SPI bit高、一个SPI bit低关键是SPI时钟要选对。WS2811的标准bit周期大约1.25us3个SPI bit组成一个周期SPI时钟应该取1.25us / 3 ≈ 0.417us per SPI bit折算频率约2.4MHz。在STM32F103上SPI1挂在APB2总线上72MHz主频。预分频选32得72MHz / 32 2.25MHz对应每个SPI bit是444ns。3个bit是1.333us和标准1.25us偏差约6.6%在WS2811的高电平/低电平宽度允许范围内实测完全稳定。SPI时钟3bit周期0码高电平宽度1码高电平宽度结论2.25MHz1.333us444ns888ns稳定推荐2.4MHz理论值1.25us417ns833ns最理想8MHz网上常见375ns125ns250ns已超出多数芯片规格容易随机闪网上很多例程直接把SPI设成8MHz还觉得能亮其实是因为某些批次芯片对时序容差大能“勉强识别”但换一批灯珠或者温度一变就翻车。这也是为什么我坚持把SPI预分频调成32而不是照抄网上的8MHz配置。3. 基于HAL库的完整驱动代码与关键参数3.1 CubeMX侧时钟、SPI、DMA配置要点我用的板子是STM32F103C8T6IDE环境是STM32CubeMX生成工程代码 Keil MDK编译。烧录用ST-Link串口用CH340这些驱动安装细节就不展开了网上教程一大堆。重点说CubeMX里的配置。时钟树里外部HSE如果用的8MHz晶振PLL倍频到72MHz。注意SPI1最大支持18MHz这里2.25MHz完全没问题。SPI1配置Mode选Transmit Only Master硬件NSS不用。数据大小8bit。时钟极性CPOLLow相位CPHA1 Edge。预分频选Prescaler 32这样波特率就是2.25MHz。先发送高位MSB First。DMA配置给SPI1_TX添加一个DMA通道方向Memory To Peripheral模式Normal数据宽度Byte优先级设High。用Normal而不是Circular因为灯带每帧数据发送完之后必须有一段复位低电平不能自动循环。GPIO方面我用的SPI1默认引脚PA5SCK和PA7MOSI。数据只走PA7PA5可以不接灯带但CubeMX里这两个脚还是要配成复用推挽输出。3.2 核心发送代码核心思路是先把每个灯的颜色数据转换成一段连续的SPI码流然后一次性用DMA发出去。下面这段是驱动模块里最核心的部分#define LED_NUM 60 // 灯带灯珠数量 #define LED_RESET 64 // 结尾复位字节数量总低电平时间约227us static uint8_t spiBuf[LED_NUM * 9 LED_RESET]; // 每颗灯24bit*3/89字节外加复位段 // 将一颗灯的颜色写入发送缓存index从0开始 void ws2811_set_pixel(uint16_t index, uint8_t r, uint8_t g, uint8_t b) { if (index LED_NUM) { return; } uint8_t *dst spiBuf[index * 9]; for (int i 0; i 9; i) { dst[i] 0; // 先清零避免残留 } uint32_t grb ((uint32_t)g 16) | ((uint32_t)r 8) | b; uint32_t bitPos 0; for (int i 23; i 0; i--) { uint8_t part (grb (1U i)) ? 0x06 : 0x04; // 110 / 100 for (int j 2; j 0; j--) { if (part (1U j)) { dst[bitPos 3] | (0x80U (bitPos 7)); } bitPos; } } } // 清空整条灯带 void ws2811_clear(void) { for (int i 0; i LED_NUM; i) { ws2811_set_pixel(i, 0, 0, 0); } } // 启动DMA发送 void ws2811_update(void) { // 等待上一次DMA传输完成 while (hspi1.State HAL_SPI_STATE_BUSY_TX) { // 轮询等待 } HAL_SPI_Transmit_DMA(hspi1, spiBuf, LED_NUM * 9 LED_RESET); }这里0x06就是二进制00000110的前三位1100x04是100。因为SPI是高位先出所以写入时从最高位开始判断。灯带发送顺序是先从0号灯开始然后1号、2号……这个顺序由buffer里数据的排列决定。调用方式很简单// 点亮第0颗灯为红色 ws2811_set_pixel(0, 255, 0, 0); // 点亮第1颗灯为绿色 ws2811_set_pixel(1, 0, 255, 0); // 刷新灯带 ws2811_update();3.3 刷新率、内存和DMA回调我用的发送buffer大小是60*9 64 604字节对STM32F103来说非常小。即使驱动200颗灯也就是200*9641864字节一点压力都没有。刷新率也要心里有数。每颗灯位对应9字节SPI数据每字节8bitSPI时钟2.25MHz单颗灯时间 9 * 8 / 2.25MHz 32us60颗灯需要60 * 32us 1.92ms加上尾部复位段64*8/2.25MHz ≈ 227us一帧总耗时约2.15ms。换算成刷新率大约是465Hz。实际人眼有120Hz就非常流畅了这个余量很充足后续如果想再叠加屏幕刷新或传感器扫描CPU压力也很小。DMA传输完成后的回调可以这样写volatile uint8_t ws2811_tx_done 0; void HAL_SPI_TxCpltCallback(SPI_HandleTypeDef *hspi) { if (hspi-Instance SPI1) { ws2811_tx_done 1; } }主循环里如果使用DMA发送注意发送期间不能立刻修改spiBuf否则会破坏正在发送的数据。一般做法是发送前更新好buffer发送完成后通过回调置标志下一次更新再改buffer。3.4 验证颜色顺序的小函数不同厂家、不同批次灯珠的颜色顺序可能是GRB、RGB、BRG等等。这里推荐先写一个简单的测试函数void ws2811_test_sequence(void) { ws2811_clear(); ws2811_set_pixel(0, 255, 0, 0); // 如果0号灯亮红色说明当前顺序正确 ws2811_update(); }如果亮的是绿色或者蓝色就在ws2811_set_pixel里把入参顺序换一下或者把grb拼装顺序换掉。这是最省事的判定方法。4. 实测中反复踩到的坑与排查思路4.1 现象整条灯带随机闪、颜色错乱这个是我见过最多的。排查链路是这样的第一步先用示波器抓数据线波形。如果没有示波器用几十块逻辑分析仪也能看个大概。正常波形应当是每个WS2811 bit周期约1.2~1.4us高电平看起来只有两种宽度。第二步发现波形周期整体偏短只有0.4us左右。再回头查CubeMX里SPI配置发现用的是默认分频8当时主频72MHzSPI时钟9MHz3个SPI bit拼出来的波形周期只有0.333us远远偏离芯片规格。第三步把预分频改成32SPI时钟降到2.25MHz波形恢复正常问题消失。所以如果你在网上抄的代码里看到SPI配置是8MHz或者9MHz还能亮真的只是运气好。建议上手第一步就检查SPI时钟别等到随机闪了才开始怀疑。4.2 现象最后一颗灯常亮不灭这个坑的根源是DMA发送结束后MOSI引脚的电平停在最后一个数据位上。如果最后一位恰好是高电平灯带最后一颗芯片就会一直收到高电平无法进入复位状态。解决方法是尾部补足够长的全0复位段。我的代码里专门加了LED_RESET的64字节按2.25MHz算每个字节8bit一共64*8/2.25MHz ≈ 227us远大于50us复位要求。而且全0意味着MOSI持续拉低DMA结束后引脚也停在低电平。如果尾灯还是常亮检查复位段长度尤其要确认发送buffer总长度里包含了LED_RESET。有些人直接在HAL_SPI_Transmit_DMA里只传了LED_NUM*9漏了复位段就很容易出这个问题。4.3 现象颜色对不上红绿互换或者蓝绿乱跳多半是颜色顺序问题。WS2811芯片本身协议规定GRB但有些灯板厂家出厂时已经做过处理你送GRB进去亮出来是RGB就说明板子内部已经帮你换过顺序了。解决办法不是硬改芯片而是在测试阶段根据实际显示效果调整驱动函数里的参数顺序。我之前因为这个问题反复烧了好多遍固件后来学乖了每拿到一盒新灯珠先跑一遍颜色顺序测试函数把顺序记在标签上再也不猜了。4.4 现象电压正常但亮度不均匀末端偏色偏暗这个十有八九是供电问题。WS2811驱动灯珠时电流是脉冲式的瞬间电流很大。细长的灯带加上细的供电线线上压降会很严重。我踩过最深刻的一次60颗灯全亮白色靠近供电端是正白到末端变成黄白色甚至微微闪烁。用万用表量末端电压只有3.8V而输入端有5.1V。处理办法电源电流余量至少按单颗60mA估算60颗全白就是3.6A电源需要支持更大电流。灯带两端同时供电不要只在一端喂电。长灯带中间最好也加供电点。电源线用粗一点至少0.75平方毫米以上。在灯带电源输入端并一个大电容比如470uF到1000uF可以吸收电流尖峰。还有一个容易忽略的电源的GND和控制板GND必须共地。如果控制板和灯带电源隔离了数据传输电平就没有参考点灯带只会输出无规律的花色。4.5 现象开中断后SPI DMA灯带开始闪如果已经用了SPIDMA还出现闪灯就不要怀疑时序了优先怀疑DMA是否被反复打断或者buffer是否被误改。我遇到过一次在ADC采样完成中断里调用了一个公共函数那个函数里偷偷改了spiBuf的内容结果每次ADC中断一来灯带就跳一下颜色。排查方法很笨但有效把所有中断注释掉只留SPI DMA再逐个放出来看是哪个中断和灯带抢了数据。还有一个常见的就是在ws2811_update()里没有等待上一次DMA传输完成就再次调用。DMA传输还在进行你改了buffer后半帧数据就乱了表现为前半段正常、后半段闪烁。所以我在发送函数开头加了while (hspi1.State HAL_SPI_STATE_BUSY_TX);虽然粗暴但有效。另外如果使用了RTOS不要把ws2811_update()直接放在定时器任务里高频轮询容易和低优先级任务的buffer更新冲突。比较好的做法是主循环统一更新颜色用标志位控制在DMA完成后再启动下一次发送。4.6 现象数据线一长信号就乱了STM32的3.3V电平直接驱动5V供电的WS2812B灯带短距离20cm以内没问题。但如果数据线超过30cm或者靠近电机、开关电源这类干扰源波形会畸变。我的处理方式是数据线上串一个100Ω左右的电阻放在靠近MCU这边能抑制振铃。优先级高的方案是用74LVC245或者SN74AHCT125做电平转换把3.3V信号抬到5V长线传输明显更放心。数据线尽量和电源线分开走不要贴着交流电或电机线。如果是WS2811外置驱动芯片的12V灯带逻辑电平阈值可能和WS2812B不一样更不能直接拿3.3V去怼看规格该加电平转换就加。5. 写在最后的个人体会从最早用GPIO延时点到半夜看灯带随机闪到后来换成SPIDMA再也不用管时序这个项目让我最大的收获是能用外设硬件解决的事就不要让CPU去硬扛。GPIO翻转看起来简单但工程化之后全是坑SPIDMA看起来复杂但原理捋顺了代码反而是最简洁的。真正上手做的时候我建议你严格按照“先查时序、再查供电、最后查软件逻辑”的顺序来排错。很多时候灯带不亮不是代码问题而是你把一个demo级的驱动放在了产品级的场景里迟早要还债。如果后续要做多路灯带可以考虑用SPI的多个空闲引脚分别控制或者用定时器PWMDMA但那是另一个话题了。至少在你手里这块灯带稳定点亮之前SPIDMA这套方案足够走完整个项目。