STM32实战：RGB三色灯数据通过串口帧上报调试助手

简介：这是一套基于STM32单片机的多功能综合实训源码，面向嵌入式初学者和电子设计爱好者，解决RGB三色灯控制、OLED显示、蜂鸣器报警及串口数据调试的一体化开发需求。项目使用C语言编写，涵盖GPIO、定时器PWM、I2C/SPI驱动OLED、串口通信等关键知识点，配套工程文件可直接编译烧录，便于二次扩展。压缩包共232个文件，以.c/.h源码、编译生成的.o/.d/.crf中间文件为主，另含.uvprojx工程文件、启动文件及烧录脚本，整体大小6.45MB，结构清晰。已有384人学习下载。通过阅读源码可掌握STM32外设驱动写法，理解多模块协同逻辑，同时蜂鸣器报警和串口发送功能为系统监控与调试提供完整参考，具备较强的实践与教学价值。

1. 一套源码四条链路，串口收尾才是主线

这套题到手，多数人的第一反应是先孤立的点亮一个外设：RGB灯用 GPIO 戳两下亮了，OLED 用现成驱动弄出字符，蜂鸣器喂个频率响一声，串口助手发几串 HEX 收回来觉得能交差。但“三色灯数据发送到串口调试助手”才是真正卡人的地方：串口里跑的不能是随手拼的十六进制字符串，而是能让上位机准确切分、校验、反推出“当前红绿蓝各占多少亮度”的状态帧。A5 81 05 64 46 28 00 0x?? A6 这种字节序列，要定义帧头、命令字、数据段和校验和，否则换个接收端就没人读得懂。这篇不按“五个外设各演示一遍”的套路写，而是把硬件选型、CubeMX 初始化、串口协议、报警联动放到一条完整数据链上看：先定引脚和驱动电路，再让 PWM、I2C、USART 各自跑通，最后把 RGB 占空比、报警标志和 OLED 状态统一收进一帧数据里。

2. RGB三色灯、无源蜂鸣器与OLED驱动电路的选型与接线

2.1 三色灯选共阴还是共阳：先看 GPIO 电平再定限流电阻

市面上的三色灯模块按公共端分成两类：共阴模块引出 GND、R、G、B 四个脚，GPIO 高电平点亮；共阳模块引出 VCC、R、G、B，GPIO 低电平点亮。STM32F103 的 GPIO 推挽输出高电平约 3.3V，共阴接法逻辑更顺，PWM 占空比越大灯越亮，调色的时候不会因为电平反相把“占空比 10%”和“亮度 10%”对应错。

限流电阻要按 3.3V 电平重算，不能直接照抄 5V 单片机的经验值。红、绿、蓝三色的管压降不同，典型值分别为 2.0V、3.0V、3.0V，GPIO 输出高电平时内部 MOS 管压降约 0.2V，单路电流按 8~10mA 取，计算公式为 R = (3.3 - VF - 0.2) / IF。

2.1.1 共阴 RGB 模块接线与限流电阻参考

绿色和蓝色在 3.3V 下压差很小，很多模块自带电阻只能保证 5V 电平下的亮度；如果发现绿色蓝色很暗，直接短接板载电阻换成 0Ω 或 10Ω 再试。注意，三路 PWM 的频率一致、占空比独立变化时，混色结果才稳定。

2.2 无源蜂鸣器驱动电路：GPIO 翻转生成方波

题目检索里大量出现“无源蜂鸣器驱动电路图”，说明多数课设套件配的是无源蜂鸣器，它内部没有振荡源，必须由外部方波驱动。有源蜂鸣器接高电平就响，无源蜂鸣器要不断翻转 GPIO 才能发声。

无源蜂鸣器工作电流通常在 20~30mA，超过 STM32 GPIO 直接驱动能力，常见做法是加一个 NPN 三极管做开关。PB12 输出 1kHz~4kHz 方波，正常驱动电路为：PB12 串 1kΩ 基极电阻接 8050 基极；8050 发射极接 GND；蜂鸣器负极接集电极，正极接 3.3V 或 5V VCC；蜂鸣器两端反向并联 1N4148 续流二极管，防止关断瞬间感生电压打坏三极管。蜂鸣器正极接 3.3V 时 8050 导通压降约 0.2V，音量已经足够。

先用 GPIO 直接验证蜂鸣器，不依赖定时器：

#define BUZZER_PIN GPIO_PIN_12 #define BUZZER_PORT GPIOB void buzzer_toggle_test(void) { for (int i = 0; i < 1000; i++) { // 输出约 1kHz 方波 HAL_GPIO_WritePin(BUZZER_PORT, BUZZER_PIN, GPIO_PIN_SET); HAL_Delay(1); // 延时 1ms，高电平持续 1ms HAL_GPIO_WritePin(BUZZER_PORT, BUZZER_PIN, GPIO_PIN_RESET); HAL_Delay(1); // 低电平持续 1ms，周期正好 2ms } }

这段代码只是验证通路：周期 2ms 对应 500Hz，听起来是有明显蜂鸣感的低频。HAL_Delay 基于 SysTick，延时期间 CPU 空转，不适合放到业务逻辑里长时间执行，但用来排除接线问题非常高效。后续报警功能建议用定时器中断翻转或者 PWM 输出驱动，避免阻塞串口接收。

2.3 OLED 用 I2C 硬件外设还是软件模拟

0.96 寸 OLED 模块核心是 SSD1306，它支持 6800/8080 并口、SPI、I2C 几种接口，市面上最常见的四针/六针模块带 I2C 模式，地址默认 0x3C。CubeMX 工程里把 I2C1 配在 PB6（SCL）、PB7（SDA），接线是 OLED 的 SCL、SDA、VCC、GND 分别接 PB6、PB7、3.3V、GND。模块自带 4.7k 上拉电阻时不需要外部上拉；没有上拉电阻的板子要在 I2C 线上补两个 4.7k 到 3.3V，否则上拉不足会导致通信偶然失败。

软件模拟 I2C 的好处是引脚任意、时序直观，坏处是刷屏占 CPU，整屏刷新时可能把蜂鸣器翻转和串口接收节奏打乱。这里使用 STM32 的 I2C1 硬件外设，初始化由 CubeMX 生成，驱动层只需要封装 SSD1306 的写命令与写数据函数。

#include "ssd1306.h" #define SSD1306_ADDR 0x3C // 7 位地址，HAL 会自动左移成 8 位写地址 #define SSD1306_CMD 0x00 // control byte: 后面跟命令 #define SSD1306_DATA 0x40 // control byte: 后面跟显存数据 bool ssd1306_write_cmd(uint8_t cmd) { return HAL_I2C_Mem_Write(&hi2c1, SSD1306_ADDR, SSD1306_CMD, I2C_MEMADD_SIZE_8BIT, &cmd, 1, 50) == HAL_OK; } bool ssd1306_write_data(uint8_t *data, uint16_t len) { return HAL_I2C_Mem_Write(&hi2c1, SSD1306_ADDR, SSD1306_DATA, I2C_MEMADD_SIZE_8BIT, data, len, 50) == HAL_OK; }

逻辑说明：HAL_I2C_Mem_Write 的第三个参数是写入 SSD1306 寄存器的首地址，这里借用的是“先发控制字节，再发数据字节”的 I2C 帧格式，MemAddress 填 0x00 表示命令流、0x40 表示数据流，正好对应 SSD1306 的控制字节定义。50ms 超时在 400kHz 速率下足够，如果 OLED 初始化失败，优先检查地址左移写法、上拉电阻和接线。

3. CubeMX 下时钟、PWM、I2C 与串口的初始化顺序

3.1 引脚分配表：把五路外设钉在 TIM2 和 USART1 上

3.1.1 时钟树配置要点：APB1 定时器时钟翻倍逻辑

STM32F103 的 TIM2 挂在 APB1 上，系统时钟配 72MHz 时 APB1 预分频为 2，APB1 外设时钟 36MHz，但定时器时钟会自动乘 2 变成 72MHz。这个“翻倍”只作用于定时器，不作用于 APB1 上的其他外设，初学经常在这里算错 PWM 频率。

CubeMX 时钟页面按默认的 HSE 8MHz 晶振、PLL 倍频到 72MHz 后，进入 TIM2 的时钟就固定为 72MHz。PWM 频率计算公式是 f = 72000000 / ((PSC+1) * (ARR+1))，PSC=71、ARR=999 时得到 1kHz；要想改成 500Hz，把 ARR 改成 1999 即可，不需要动 PSC。占空比由 CCR 决定：ARR=999 时，CCR=500 表示 50% 占空比。

3.2 HAL 库点亮 OLED 全流程：初始化顺序与 PWM 启动

在 CubeMX 的 Clock Configuration 里先把 HCLK 拉到 72MHz，然后依次打开 RCC 的 HSE、TIM2 的 PWM Generation CH1/CH2/CH3、I2C1 的 I2C 模式、USART1 的 Asynchronous 模式并设置波特率 115200、8 位数据、无校验、1 位停止位。NVIC 设置里打开 USART1 全局中断和 DMA 通道，TIM2 不使用中断，只做输出比较。

CubeMX 生成的 MX_TIM2_Init 只管配置定时器模式，PWM 输出还必须手动启动，否则 CCR 再大引脚也没有波形。OLED 与 PWM 的初始化顺序没有强依赖，但只要 PSC、ARR 写错，后面调色一定是乱的。

#include "main.h" #include "tim.h" #include "usart.h" #include "gpio.h" #include "ssd1306.h" static void rgb_pwm_start(void) { HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_1); HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_2); HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_3); } static void set_rgb_pwm(uint16_t r_percent, uint16_t g_percent, uint16_t b_percent) { // 0~100 百分比换算成 0~999 的 CCR 值 __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, r_percent * 10); __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_2, g_percent * 10); __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_3, b_percent * 10); } int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_TIM2_Init(); MX_I2C1_Init(); MX_USART1_UART_Init(); rgb_pwm_start(); ssd1306_init(); ssd1306_fill(Black); ssd1306_SetCursor(0, 0); ssd1306_DisplayString("RGB Ready"); set_rgb_pwm(100, 0, 0); // 纯红，验证 PWM 通道是否正确 while (1) { // 串口命令处理放在这里 } }

逻辑说明：HAL_TIM_PWM_Start 把对应通道的 PWM 输出使能，三个通道共用同一套 PSC、ARR，因此频率一致，改变 CCR 即可独立调整三路占空比。__HAL_TIM_SET_COMPARE 是直接写寄存器 CCRx 的宏，比调用 HAL_TIM_PWM_SetCompare 少一次函数跳转；这里百分之几乘 10 得到千分之几，正好把 0~100 映射到 0~999。

3.3 串口初始化与 OLED 刷屏的先后关系

串口初始化放在外设初始化阶段，但串口接收机制要等 DMA 配置完成后才能开启，这个动作不要放在 MX_USART1_UART_Init 里做，而应在所有外设初始化之后调用串口接收启动函数。OLED 初始化失败不影响串口工作，反之也一样；但业务上最好先 OLED 打印一条启动信息，再启用串口 DMA 接收，否则登录助手后立刻收到无意义字符，容易误判为乱码。

// 在 main 函数里、主循环之前调用 static void uart_rx_idle_start(void) { // 使用空闲中断 + DMA 接收，一帧数据完整到达后触发回调 HAL_UARTEx_ReceiveToIdle_DMA(&huart1, rx_buf, RX_BUF_LEN); __HAL_UART_ENABLE_IT(&huart1, UART_IT_IDLE); }

逻辑说明：HAL_UARTEx_ReceiveToIdle_DMA 把接收到的数据直接搬进 rx_buf，硬件检测到总线空闲后产生空闲中断；__HAL_UART_ENABLE_IT 单独打开 IDLE 中断位，这样 115200 波特率下即便对方发来的是不完整帧，也能在总线静默时立刻得到回调。RX_BUF_LEN 取 64，足够容纳本项目的 10 字节状态帧。

4. 三色灯数据发到串口调试助手：帧格式、空闲中断与报警联动

4.1 自定义数据帧：帧头、命令字、RGB 占空比与校验和

串口调试助手只是字节通道，上位机要区分“谁是谁”，必须靠应用层帧格式。常见做法是：帧头 + 命令字 + 长度 + 数据段 + 校验和 + 帧尾。本项目的 RGB 占空比按 0~100 的百分比传输，单个字节就能表达，帧结构就比较紧凑。

（该表对应“设备上报帧”格式；若是 PC 下发设置命令，帧头不变，命令字换 0x01，数据段只放 R、G、B 三字节，总帧长 8 字节。）

校验和算法在这里用累加取低 8 位：从帧头累加到报警标志位，等于 0x5A 表示帧尾。这样写的好处是单片机实现简单，串口助手端用计算器也能快速核对：A5 加 81 加 05 加 64 加 46 加 1E 加 00，结果是 0x1F3，取低 8 位就是 0xF3。

4.2 DMA 空闲中断接收与状态机解析

在 HAL_UARTEx_RxEventCallback 中拿到整帧数据后，立刻按状态机解析。状态机比一次性判断数组更稳，因为 DMA 空闲中断可能把多条帧的不同残余拼在一起。

typedef enum { FRAME_WAIT_HEAD, FRAME_WAIT_CMD, FRAME_WAIT_LEN, FRAME_WAIT_DATA, FRAME_WAIT_CHECK, FRAME_WAIT_TAIL } frame_state_t; frame_state_t rx_state = FRAME_WAIT_HEAD; uint8_t frame_data[8]; uint8_t frame_index = 0; uint8_t frame_len = 0; uint8_t frame_sum = 0; void parse_rx_byte(uint8_t byte) { switch (rx_state) { case FRAME_WAIT_HEAD: if (byte == 0xA5) { rx_state = FRAME_WAIT_CMD; frame_sum = 0xA5; } break; case FRAME_WAIT_CMD: frame_data[0] = byte; frame_sum += byte; rx_state = FRAME_WAIT_LEN; break; case FRAME_WAIT_LEN: frame_len = byte; frame_sum += byte; frame_index = 0; rx_state = (frame_len <= 5) ? FRAME_WAIT_DATA : FRAME_WAIT_HEAD; break; case FRAME_WAIT_DATA: frame_data[1 + frame_index] = byte; frame_sum += byte; frame_index++; if (frame_index >= frame_len) { rx_state = FRAME_WAIT_CHECK; } break; case FRAME_WAIT_CHECK: if (byte == (frame_sum & 0xFF)) { rx_state = FRAME_WAIT_TAIL; } else { rx_state = FRAME_WAIT_HEAD; send_error_frame(0xE1); // 校验失败的错误码 } break; case FRAME_WAIT_TAIL: if (byte == 0x5A) { handle_rgb_frame(frame_data); // 校验通过，执行命令 } rx_state = FRAME_WAIT_HEAD; break; } }

逻辑说明：状态机的核心思想是每收到一个字节只推进一步，帧头、命令、长度、数据依次进入。frame_len 限制在 5 以内，是为了防止异常数据把内存填爆；校验和比对失败时直接回传 0xE1 错误码，方便串口调试助手里定位是发送端拼错帧还是接收端解析错位。handle_rgb_frame 内部读取 frame_data[1]、frame_data[2]、frame_data[3]，分别作为红、绿、蓝占空比调用 set_rgb_pwm。

4.2.1 空闲中断回调里搬数据，不要在中断里跑 OLED

接收回调里只做“把 DMA 缓冲区里的数据拷贝到业务环形缓冲”这件事，解析、刷新 OLED、启动蜂鸣器都放到主循环执行。空闲中断频率不高，但 OLED 的 I2C 写操作在中断里会阻塞串口接收，一帧 10 字节在 115200 波特率下约 0.87ms 内全部到达，I2C 整屏刷新动辄 10ms 以上，必然丢字节。

void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t Size) { if (huart->Instance == USART1) { memcpy(rx_ring, rx_buf, Size); // 简单起见直接覆盖拷贝 rx_len = Size; // 主循环里处理 rx_len HAL_UARTEx_ReceiveToIdle_DMA(&huart1, rx_buf, RX_BUF_LEN); __HAL_UART_ENABLE_IT(&huart1, UART_IT_IDLE); } }

注意：HAL_UARTEx_RxEventCallback 被调用后，DMA 接收就停止工作，所以回调末尾必须重新启动接收，否则串口只收第一帧就再也不进中断。这种“收到一帧就重新挂接收”的模式，是 UART DMA 空闲接收最常见的遗漏点。

4.3 越限报警联动：占空比超 95% 拒绝写入并驱动蜂鸣器

串口下发的占空比不是无条件执行。RGB 灯长时间超亮工作会加速灯珠老化，也可以用来演示“非法指令拒绝执行”这类安全逻辑：判断任一通道占空比大于 95，拒绝写入 PWM，置报警标志，让蜂鸣器响 2 秒，并上报一帧报警状态。

void handle_rgb_frame(uint8_t *data) { uint8_t r = data[1]; uint8_t g = data[2]; uint8_t b = data[3]; if (r > 95 || g > 95 || b > 95) { alarm_flag = 1; // 置报警标志，OLED 显示报警信息 buzzer_alarm_start(2); // 蜂鸣器响 2 秒 set_rgb_pwm(0, 0, 0); // 拒绝非法占空比，并熄灭 RGB send_status_frame(); return; } set_rgb_pwm(r, g, b); alarm_flag = 0; oled_show_rgb_status(r, g, b); send_status_frame(); // 成功执行后立刻回传一次状态帧 }

逻辑说明：data[0] 是命令字，这里默认处理的是 0x01 设置命令；95 这个阈值取整容易理解，实际产品可以改成配置文件里可调参数。buzzer_alarm_start 用定时器计数实现非阻塞报警，2 秒后自动关闭，不能写成 HAL_Delay(2000)，否则串口解析在报警期间完全停摆。

4.4 定时上报 vs 变化上报：串口助手里的数据节奏

项目标题里说“数据发送到串口调试助手”，上报策略决定助手窗口里数据刷新的节奏。只在上报状态变化时发送，数据量小、可读性强；定时上报适合上位机做连续趋势曲线。两类策略不互斥：每次执行命令后立即上报一次状态帧，另外用 SysTick 计时每 3 秒补发一次心跳帧。

volatile uint32_t tick_1s = 0; void HAL_SYSTICK_Callback(void) { tick_1s++; // 每 1ms 一次，累计到 3000 触发上报 if ((tick_1s % 3000) == 0) { send_status_frame(); } }

逻辑说明：心跳帧和命令回执共用 send_status_frame 函数，上位机靠命令字区分是“响应”还是“主动上报”。开发时建议把主动上报间隔设成 0，先观察命令回执是否正确，确认协议无误后再打开周期上报，避免窗口刷屏掩盖调试信息。

5. 验证三色灯数据一致性：逻辑分析仪与串口回环的 3 个技巧

5.1 逻辑分析仪抓 PWM 引脚，对比串口帧里的占空比

把逻辑分析仪通道接到 PA0、PA1、PA2，在软件里设置 1kHz 触发条件，观察每个通道高电平时间占比。比如下发 R=50、G=30、B=80，PA0 高电平应占 50%，PA1 占 30%，PA2 占 80%。数据不一致时，优先检查串口帧里 R、G、B 的字节顺序是否和 handle_rgb_frame 里读取顺序一致，这类问题先是逻辑层面的解析错位，不是硬件问题。

5.2 串口助手勾选 HEX 显示，核对帧头帧尾与校验和

SSCOM、正点原子 XCOM 这类助手都支持十六进制显示。接收窗里看到 A5 81 05 64 1E 46 00 F3 5A 这样的完整帧，说明链路正常；如果看到 A5 81 05 64 1E 46 00 和帧尾之间夹着别的字节，说明上位机或单片机某侧把两条帧拼到了一起。对照第 4 节的帧格式表，用计算器手算一遍校验和，能快速确认是发送端组帧错误还是接收端状态机跳转错误。注意串口助手的波特率、数据位、停止位必须与 CubeMX 配置一致，115200-8-N-1 是最稳妥的起点。

5.3 OLED 只刷变化区域，避免报警时整屏刷新拖慢上报节奏

整屏刷新 SSD1306 在 I2C 400kHz 下约 12ms，报警期间如果每 200ms 刷一次“Alarm！RGB over range”，串口上报帧会被 I2C 总线占用挤在间隙里，抖动明显。常见做法是封装一个局部刷新函数，只重写报警状态对应的那一行区域：

void oled_refresh_alarm_line(uint8_t row) { uint8_t page = row / 8; ssd1306_WriteCmd(0xB0 + page); // 设置页地址（0~7） ssd1306_WriteCmd(0x00); // 列地址低 4 位 ssd1306_WriteCmd(0x10); // 列地址高 4 位 ssd1306_write_data(&frame_buffer[page * 128], 128); }

逻辑说明：SSD1306 的显存按 128×8 排列，每 8 行像素为一页，操作前先写页地址和列地址，然后整页写 128 字节数据。这样报警文字变化时只重写一页，耗时约 0.3ms，对串口上报节奏几乎没有影响。整个工程调试到能稳定看到“状态帧连续刷新、OLED 同步显示、越限触发报警、校验错误回传 0xE1”这四个现象，说明代码链路已经收敛到可交付状态，剩下的就是按 GPIO 分配表整理一份硬件接线说明，方便别人拿到源码后直接还原环境。

本文还有配套的精品资源，点击获取