STM32串口控制LED+OLED显示实战：从硬件连接到代码调试全流程

STM32串口控制LED+OLED显示实战：从硬件连接到代码调试全流程

很多刚接触STM32的朋友，拿到开发板后，面对一堆外设和库函数，常常感到无从下手。理论看了不少，但一到动手环节，硬件怎么连、代码怎么写、出了问题怎么找，这些具体的“路”却走不通。今天，我们就来“修”一条从零到一的路，目标很明确：通过电脑串口发送一个命令，让STM32板子上的LED灯亮灭，同时把接收到的命令实时显示在OLED屏幕上。

这个项目麻雀虽小，五脏俱全。它串联了GPIO输出控制（LED）、串口通信（命令接收与反馈）和OLED显示（信息可视化）这三个嵌入式开发中最基础也最核心的技能点。完成它，你不仅能点亮一盏灯、显示一行字，更重要的是，你能建立起一个完整的“感知-决策-执行”的嵌入式系统思维闭环。无论你是电子专业的学生，还是希望转型硬件的软件工程师，这个实战项目都将是你STM32学习路上一个扎实的起点。下面，我们就从硬件清单开始，一步步拆解，直到项目完美运行。

1. 硬件准备与电路连接

动手写代码之前，确保手头的“积木”齐全并且正确搭建，是成功的第一步。这个项目对硬件要求非常友好，大部分STM32入门套件都能满足。

1.1 所需物料清单

你需要准备以下核心部件：

• STM32最小系统板：以最常见的STM32F103C8T6（蓝色药丸板）为例，它资源足够，性价比极高。
• OLED显示屏：推荐使用0.96英寸、128x64分辨率的I2C接口OLED模块。I2C通信仅需两根信号线，接线简单，库也成熟。
• LED灯：如果开发板上已集成用户LED（通常连接在PA5或PC13引脚），则直接使用。如果没有，准备一个直插或贴片LED，并搭配一个220Ω-1kΩ的限流电阻。
• USB转TTL串口模块：这是连接电脑和STM32串口的桥梁，常用芯片有CH340、CP2102等。
• 杜邦线：若干，用于连接。
• 电脑一台：用于编写代码、下载程序和发送串口命令。

提示：购买OLED模块时，务必确认其驱动芯片是SSD1306，这是最通用的型号，网上资料和驱动库最丰富。

1.2 电路连接详解

连接遵循“电源-地-信号”的顺序，务必在断电状态下操作。

首先，连接OLED模块（I2C接口）：OLED模块通常有4个引脚：VCC、GND、SCL、SDA。

• VCC-> STM32板的3.3V引脚。
• GND-> STM32板的GND引脚。
• SCL（时钟线）-> STM32板的PB6（或PB8，根据你的板子定义，这里以PB6为例）。
• SDA（数据线）-> STM32板的PB7（或PB9）。

其次，连接USB转TTL模块：

• TTL模块的VCC-> STM32板的3.3V（切勿接5V，可能烧坏芯片！）。
• TTL模块的GND-> STM32板的GND。
• TTL模块的TXD-> STM32板的PA10（USART1_RX）。
• TTL模块的RXD-> STM32板的PA9（USART1_TX）。

注意：串口连接是“交叉”的，即发送端（TXD）接接收端（RX），接收端（RXD）接发送端（TX）。这是初学者最容易接错的地方。

最后，确认LED连接：如果使用板载LED，通常已连接好，例如在STM32F103C8T6核心板上，用户LED常接在PA5。如果外接LED，则需将LED正极通过限流电阻连接到STM32的某个GPIO引脚（如PA5），负极接GND。

为了更清晰地展示核心信号连接关系，可以参考下表：

连接完成后，硬件部分就准备好了。接下来，我们进入软件开发环境搭建环节。

2. 开发环境搭建与工程创建

工欲善其事，必先利其器。一个顺手的开发环境能极大提升效率，减少环境问题带来的困扰。

2.1 工具链安装与配置

对于STM32开发，Keil MDK（ARMCC编译器）和STM32CubeMX是黄金组合。前者是强大的集成开发环境（IDE），后者是图形化的引脚配置与代码生成工具。

1. 安装Keil MDK：从ARM官网下载并安装Keil MDK，注意需要申请License（社区版有代码大小限制，但对此项目足够）。安装过程中，会同时安装ARM Compiler。
2. 安装STM32CubeMX：从ST官网下载安装。它内置了STM32全系列芯片的硬件抽象层（HAL）库，以及LL库。
3. 安装芯片支持包：在Keil中，通过Pack Installer（图标像一个小盒子）安装你所用芯片的Device Family Pack（DFP），例如Keil::STM32F1xx_DFP。
4. 安装串口调试助手：用于从电脑发送命令和接收STM32的反馈。推荐使用SecureCRT、MobaXterm或免费的Putty、AccessPort。

2.2 使用CubeMX初始化工程

CubeMX能可视化配置时钟、引脚和外设，生成初始化代码，避免手动编写底层配置的繁琐和错误。

• 新建项目：打开CubeMX，选择New Project，在芯片选择器中输入你的型号（如STM32F103C8），双击选中。
• 配置系统核心（SYS）：在Pinout & Configuration标签页，左侧找到System Core->SYS。将Debug改为Serial Wire。这为后续使用ST-Link下载调试预留了接口。
• 配置时钟（RCC）：找到RCC，将High Speed Clock (HSE)设置为Crystal/Ceramic Resonator。我们的外部晶振通常是8MHz。
• 配置GPIO（LED）：在芯片图形上找到PA5，左键点击，选择GPIO_Output。然后在左侧System Core->GPIO中，点击PA5，可以配置其输出模式和默认电平。我们将其初始化为高电平（LED灭），用户标签可设为USER_LED。
• 配置USART1（串口）：找到PA9和PA10，分别设置为USART1_TX和USART1_RX。然后在左侧Connectivity->USART1中，将模式设为Asynchronous（异步通信），参数保持默认波特率9600、数据位8、停止位1、无校验。别忘了在NVIC Settings中勾选USART1 global interrupt使能串口接收中断。
• 配置I2C1（OLED）：找到PB6和PB7，分别设置为I2C1_SCL和I2C1_SDA。然后在左侧Connectivity->I2C1中，模式选择I2C，参数通常保持默认即可。
• 生成工程代码：点击上方Project Manager标签。
  • Project页：设置工程名称、存储路径，选择Toolchain / IDE为MDK-ARM V5。
  • Code Generator页：建议勾选Generate peripheral initialization as a pair of '.c/.h' files per peripheral，这样每个外设的代码会单独成对文件，结构更清晰。再勾选Copy all used libraries into the project folder，便于工程迁移。
• 点击GENERATE CODE，生成Keil工程文件。

至此，一个包含时钟、GPIO、USART、I2C基础配置的工程框架就由CubeMX自动生成了。我们接下来要做的，就是在这个框架里填充我们的业务逻辑代码。

3. 外设驱动集成与业务逻辑实现

CubeMX生成了硬件底层的“骨架”，我们现在需要为OLED屏幕添加“眼睛”，并编写让系统“动起来”的“大脑”程序。

3.1 集成OLED驱动库

STM32的HAL库不包含SSD1306 OLED的驱动，我们需要自行添加一个。网上有大量开源驱动，这里我们使用一个经过简化的版本。

1. 在Keil工程文件夹中，新建一个Middlewares/SSD1306文件夹。
2. 将下载或编写的ssd1306.h、ssd1306.c、ssd1306_fonts.h文件放入该文件夹。
3. 在Keil工程中，右键Application/User组，选择Add Existing Files...，添加ssd1306.c。
4. 在Core/Inc/main.h中，确保包含了HAL库头文件。然后在ssd1306.h中，主要需要实现以下关键函数：

// ssd1306.h 中的关键函数声明 void SSD1306_Init(void); void SSD1306_UpdateScreen(void); void SSD1306_Clear(void); void SSD1306_WriteString(uint8_t x, uint8_t y, char* str, FontDef font);

5. 在ssd1306.c中，最核心的是I2C写入函数，它依赖于HAL库：

// 基于HAL_I2C_Mem_Write的底层写函数 void SSD1306_WriteCommand(uint8_t cmd) { uint8_t data[2] = {0x00, cmd}; // 控制字节0x00表示命令 HAL_I2C_Master_Transmit(&hi2c1, SSD1306_I2C_ADDR, data, 2, HAL_MAX_DELAY); } void SSD1306_WriteData(uint8_t* data, uint16_t size) { uint8_t *p = (uint8_t *)malloc(size + 1); if(p) { p[0] = 0x40; // 控制字节0x40表示数据 memcpy(&p[1], data, size); HAL_I2C_Master_Transmit(&hi2c1, SSD1306_I2C_ADDR, p, size + 1, HAL_MAX_DELAY); free(p); } }

注意：不同的OLED模块I2C地址可能不同，常见的是0x78或0x7A，需要在ssd1306.h中宏定义SSD1306_I2C_ADDR，并根据你的模块手册修改。

3.2 编写串口命令解析与LED控制逻辑

现在，我们来编写核心的业务代码。主要工作集中在main.c和串口中断回调函数中。

首先，在main.c的/* USER CODE BEGIN PV */区域定义全局变量：

/* Private variables ---------------------------------------------------------*/ char uart_rx_buffer[100]; // 串口接收缓冲区 uint8_t uart_rx_len = 0; // 接收到的数据长度 uint8_t command_ready = 0; // 命令接收完成标志

然后，在/* USER CODE BEGIN 2 */区域，初始化OLED并打印欢迎信息：

/* USER CODE BEGIN 2 */ SSD1306_Init(); SSD1306_Clear(); SSD1306_WriteString(0, 0, "UART CMD TEST", Font_7x10); SSD1306_WriteString(0, 20, "Waiting...", Font_7x10); SSD1306_UpdateScreen(); // 启动串口接收中断（CubeMX已配置好） HAL_UART_Receive_IT(&huart1, (uint8_t*)&uart_rx_buffer[uart_rx_len], 1); /* USER CODE END 2 */

接下来是关键：重写串口接收中断回调函数。在main.c文件末尾的/* USER CODE BEGIN 4 */区域添加：

/* USER CODE BEGIN 4 */ // 串口接收中断回调函数 void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart->Instance == USART1) { // 检查是否收到回车符（\r 或 \n）作为命令结束符 if (uart_rx_buffer[uart_rx_len] == '\r' || uart_rx_buffer[uart_rx_len] == '\n') { if (uart_rx_len > 0) { // 确保不是空命令 uart_rx_buffer[uart_rx_len] = '\0'; // 添加字符串结束符 command_ready = 1; // 设置命令就绪标志 } uart_rx_len = 0; // 重置长度，准备接收下一条命令 } else { uart_rx_len++; // 长度增加 if (uart_rx_len >= sizeof(uart_rx_buffer) - 1) { // 缓冲区即将溢出，清空并重新开始 uart_rx_len = 0; } } // 重新启动中断接收，等待下一个字符 HAL_UART_Receive_IT(&huart1, (uint8_t*)&uart_rx_buffer[uart_rx_len], 1); } } /* USER CODE END 4 */

最后，在主循环/* USER CODE BEGIN WHILE */中，处理就绪的命令：

/* USER CODE BEGIN WHILE */ while (1) { /* USER CODE END WHILE */ /* USER CODE BEGIN 3 */ if (command_ready) { command_ready = 0; // 清除标志 // 在OLED上显示收到的命令 SSD1306_Clear(); SSD1306_WriteString(0, 0, "CMD Received:", Font_7x10); SSD1306_WriteString(0, 20, uart_rx_buffer, Font_7x10); SSD1306_UpdateScreen(); // 解析命令并控制LED if (strcmp(uart_rx_buffer, "LED_ON") == 0) { HAL_GPIO_WritePin(USER_LED_GPIO_Port, USER_LED_Pin, GPIO_PIN_RESET); // LED亮 HAL_UART_Transmit(&huart1, (uint8_t*)"LED is ON\r\n", strlen("LED is ON\r\n"), 100); } else if (strcmp(uart_rx_buffer, "LED_OFF") == 0) { HAL_GPIO_WritePin(USER_LED_GPIO_Port, USER_LED_Pin, GPIO_PIN_SET); // LED灭 HAL_UART_Transmit(&huart1, (uint8_t*)"LED is OFF\r\n", strlen("LED is OFF\r\n"), 100); } else { // 未知命令反馈 char err_msg[50]; sprintf(err_msg, "Unknown CMD: %s\r\n", uart_rx_buffer); HAL_UART_Transmit(&huart1, (uint8_t*)err_msg, strlen(err_msg), 100); SSD1306_WriteString(0, 40, "Unknown CMD!", Font_7x10); SSD1306_UpdateScreen(); } // 清空缓冲区，为下一条命令做准备 memset(uart_rx_buffer, 0, sizeof(uart_rx_buffer)); uart_rx_len = 0; } // 可以添加一些其他任务或延时 HAL_Delay(10); } /* USER CODE END 3 */

代码的核心逻辑是：中断负责高效接收字符并组装成字符串命令，主循环负责解析执行命令并更新显示。这种“中断+主循环”的结构是嵌入式系统的典型设计模式。

4. 编译、下载与调试实战

代码写完只是第一步，让它跑起来并稳定工作，才是真正的挑战。这个环节我们会遇到最多的问题，也是成长最快的地方。

4.1 工程编译与常见错误解决

在Keil中点击Rebuild（F7）按钮。如果一切顺利，你会在Build Output窗口看到"0 Error(s), 0 Warning(s)"。但更常见的是遇到一些错误和警告。

• 错误：undefined symbol HAL_I2C_Master_Transmit

  • 原因：I2C的HAL库文件没有被添加到工程中。
  • 解决：CubeMX生成工程时，如果未使用I2C，可能不会链接I2C库。确保在Project->Manage->Project Items->Folders/Extensions中，STM32Cube_FW_F1_VX.X.X\Drivers\STM32F1xx_HAL_Driver路径已被包含。或者，直接在ssd1306.c中包含stm32f1xx_hal_i2c.h头文件。

• 警告：variable "xxx" was set but never used

  • 原因：定义了变量但未使用。可能是调试遗留或代码逻辑变更。
  • 解决：如果确实不需要，可以删除该变量定义；如果暂时不用但后续需要，可以使用(void)xxx;来显式忽略此警告。

• 错误：No space in execution regions

  • 原因：代码或数据量超过了芯片的Flash或RAM容量。对于STM32F103C8T6，Flash为64KB。
  • 解决：检查是否添加了过大的字体数组或缓冲区。优化代码，使用const将常量数组存放到Flash。在Target选项卡中，确认IROM和IRAM的起始地址和大小设置正确。

4.2 程序下载与硬件调试

编译通过后，将生成project.hex或project.bin文件。你需要一个下载器，如ST-Link。

1. 连接下载器：ST-Link的SWDIO、SWCLK、GND、3.3V分别连接STM32的对应引脚。
2. Keil配置：点击Options for Target（魔术棒图标）->Debug选项卡。
   • 选择你的调试器（如ST-Link Debugger）。
   • 点击Settings，在Debug页确认SWD协议和芯片被识别。
   • 在Flash Download页，勾选Reset and Run，这样下载后程序会自动运行。
3. 下载程序：点击Load（F8）或Download按钮。看到"Flash Load finished at ..."即表示成功。
4. 连接串口调试助手：
   • 将USB转TTL模块插入电脑USB口。
   • 打开设备管理器，查看分配的COM口号（如COM3）。
   • 打开串口调试助手（如Putty），选择正确的COM口，波特率设置为9600，数据位8，停止位1，无校验，无流控。
   • 打开串口。

4.3 功能测试与问题排查

现在是最激动人心的时刻。给开发板上电。

• 预期现象1：OLED屏幕点亮，显示"UART CMD TEST"和"Waiting..."。
• 预期现象2：板载LED（PA5）处于熄灭状态。

在串口调试助手的发送框中，输入LED_ON，然后点击发送（确保发送选项是“发送新行”，即包含\r\n）。

• 预期现象3：板载LED立即点亮。
• 预期现象4：OLED屏幕刷新，第一行显示"CMD Received:"，第二行显示"LED_ON"。
• 预期现象5：串口调试助手的接收框显示"LED is ON"。

发送LED_OFF，LED应熄灭，OLED更新显示，串口返回"LED is OFF"。

如果任何一步不符合预期，请按以下思路排查：

• OLED不显示：
  • 检查I2C接线（SCL、SDA）是否接反、虚焊。
  • 用万用表测量OLED模块VCC是否有3.3V。
  • 在代码中，检查SSD1306_I2C_ADDR地址是否正确。可以写一个简单的I2C扫描程序来探测设备地址。
  • 检查ssd1306.c中的初始化序列是否与你的屏幕型号匹配。
• 串口无反应：
  • 检查USB-TTL的TX/RX线与STM32的PA9/PA10是否交叉连接正确。
  • 检查串口助手参数（波特率、COM口）是否设置正确。
  • 尝试发送其他字符，在串口中断回调函数中设置断点，看是否能进入中断。
  • 检查huart1实例在CubeMX中是否已正确关联USART1。
• LED不亮/不灭：
  • 检查LED对应的GPIO引脚（PA5）配置是否为输出模式。
  • 使用万用表测量该引脚在发送命令前后的电压变化（灭时应为高电平~3.3V，亮时应为低电平~0V）。
  • 确认USER_LED_GPIO_Port和USER_LED_Pin这两个宏定义是否在main.h中正确生成。

调试过程就是不断假设、验证、修正的过程。充分利用Keil的在线调试功能（设置断点、查看变量、单步执行），能极大提升效率。记得，硬件问题往往比软件问题更常见，耐心检查每一根连线。

5. 项目优化与扩展思路

当基础功能跑通后，我们可以从稳定性、可维护性和功能扩展性上思考如何让这个小项目变得更“专业”。

5.1 代码结构优化

目前的逻辑都写在main.c里，随着功能增加会变得臃肿。良好的模块化是必须的。

• 创建命令解析模块：新建command_parser.h和command_parser.c。
  • 在头文件中定义命令枚举和解析函数：typedef enum {CMD_LED_ON, CMD_LED_OFF, CMD_UNKNOWN} Command_t; Command_t ParseCommand(char* str);
  • 在.c文件中实现ParseCommand函数，使用strcmp或更高效的查找算法（如字典树）来匹配命令。
• 创建显示管理模块：新建display_manager.h和display_manager.c。
  • 封装OLED显示的各种页面，如ShowWelcomePage(),ShowCommandPage(char* cmd),ShowErrorPage(char* err)。
  • 这样，主循环中只需调用ShowCommandPage(uart_rx_buffer)，显示逻辑被隔离，易于修改。

5.2 通信协议与稳定性增强

我们目前用\r\n作为命令结束符，这在简单的调试中可行，但不够健壮。

• 添加帧头帧尾：例如，定义命令格式为@命令字符串$。在串口中断中，只有检测到以@开始、以$结束的数据才被认为是有效命令。这能有效过滤干扰数据。
• 实现环形缓冲区：当前线性数组在快速接收数据时可能溢出。实现一个环形缓冲区（FIFO）来接收串口数据，由后台任务从缓冲区中取出并解析完整帧。HAL库本身支持DMA+空闲中断的方式接收不定长数据，这是更高级、更高效的做法。
• 增加校验和：在帧尾加入一个简单的校验和（如所有字节的异或值），接收方验证校验和，不正确则丢弃，提高通信可靠性。

5.3 功能扩展实战

在这个框架上，你可以轻松添加更多功能，把它变成一个小型物联网终端。

• 控制多个LED或继电器：定义命令如LED1_ON,LED2_OFF，在解析函数中增加分支，控制不同的GPIO引脚。
• 读取传感器并显示：接入一个温湿度传感器（如DHT11，单总线协议）或光照传感器（BH1750，I2C协议）。定时读取传感器数据，并显示在OLED上。可以定义命令GET_TEMP来主动查询。
• 实现PWM调光：将LED的控制从简单的开关改为PWM输出。定义命令LED_BRIGHT 50，解析数字参数，调用HAL_TIM_PWM_Start和__HAL_TIM_SET_COMPARE函数来设置占空比，实现LED亮度调节。这涉及到TIM定时器PWM模式的配置。
• 与上位机交互：设计一个简单的文本协议或JSON格式的命令集。上位机（电脑上的Python/C#程序）可以发送更复杂的指令，STM32解析后执行并返回结构化的数据（如{"status":"ok", "led":"on", "temp":25}）。这为后续开发图形化控制界面打下了基础。

项目做完了，灯亮了，字显示了，但这只是开始。我自己的经验是，第一个能稳定运行的项目，其价值远超它本身的功能。它给你建立了从硬件到软件、从配置到调试的完整信心链条。下次当你面对更复杂的传感器、通信协议（如SPI、CAN）或实时操作系统（RTOS）时，你会知道，所有复杂系统都是由这样一个个简单的“输入-处理-输出”环节构建起来的。不妨试着去实现一下PWM调光，当你看到LED的亮度能随着你的命令平滑变化时，那种对硬件直接编程的掌控感，正是嵌入式开发的乐趣所在。