简介面向STM32嵌入式开发者这份UART通信代码覆盖F1与F4两大主流系列同时兼容标准库与HAL库两种开发方式解决了不同项目在串口通信上的移植与适配难题。压缩包共4个文件包含2个头文件与2个C源文件整体仅33KB结构紧凑便于直接放入工程中引用。代码给出了完整的初始化流程、数据发送接收处理、中断管理及错误处理逻辑源码中带有调试信息与注释方便开发者理解每一步的作用并可根据实际场景进行定制化修改。无论是连接GPS、蓝牙模块还是与PC机通信都能借助这组代码快速打通UART链路。目前已有268人学习下载适合正在学习STM32串口开发或需要快速集成UART功能的初中级工程师也可作为标准库与HAL库编程思路的对照范例。1. 为什么要一份同时兼容 F1/F4、标准库/HAL 库的 UART 代码如果你同时维护过 F1 和 F4 两个平台的串口代码大概率经历过这种尴尬F1 上用得好好的标准库驱动拷到 F4 工程里要么编译不过、要么串口死活不进中断。UART 通信本身不复杂但同样是 STM32 的串口标准和 HAL 两套库的写法差异巨大F1 和 F4 的时钟源、引脚复用方式、中断服务函数又不一样代码基本没法直接复用。这份代码包的核心价值是把「芯片型号差异」和「固件库差异」剥离开底层用条件编译分别实现标准库和 HAL 库的驱动上层统一暴露一套 UART 接口。你只需要在工程里定义一个宏就能在 F1 和 F4 之间来回切换不必再为每种组合单独维护一份串口代码。适合那些手里有一堆老标准库项目、又需要接 F4 新项目的人也适合刚入门想少踩坑的人照着复现。2. 先分清外设差异F1 与 F4 的时钟、引脚和中断号不能混用2.1 时钟树差异APB1 与 APB2 上的串口分布波特率误差从这里来F1 和 F4 的外设时钟挂载点不一样这是很多串口乱码问题的根源。F1 系列的 USART1 挂在 APB2 上USART2 和 USART3 挂在 APB1 上F4 系列除了 USART1 和 USART6 在 APB2USART2、USART3、UART4、UART5 都在 APB1 上。你把 F1 工程里的 RCC 时钟使能代码直接拷到 F4 上使能的总线可能对应了错误的外设。芯片平台挂在 APB1 上的串口挂在 APB2 上的串口F1USART2、USART3USART1F4USART2、USART3、UART4、UART5USART1、USART6这个差异直接影响波特率生成。串口波特率寄存器 BRR 的计算公式是fck / (16 * USARTDIV)其中 fck 是串口所在总线的时钟。以默认主频为例F103 的主频常见配置是 72MHz但 APB1 总线时钟只有 36MHz如果你在 USART2 上误用了 72MHz 去算波特率实际跑出来的速率会偏移近一倍。我一般会在配置波特率之前先用一个脚本把所有候选频率下的误差算一遍确认小数分频寄存器能否整除。clock 36000000 bauds [9600, 19200, 38400, 115200, 921600] for baud in bauds: usart_div clock / (16 * baud) mantissa int(usart_div) fraction int((usart_div - mantissa) * 16 0.5) actual clock / (16 * (mantissa fraction / 16)) error (actual - baud) / baud * 100 print(f{baud:7} - actual {actual:10.2f}, error {error:.3f}%)这段脚本把整数部分和小数部分分别截出来再反算实际波特率。注意小数部分寄存器只保留 4 位*16 0.5是四舍五入误差超过 2% 时通信就会开始不稳定。如果误差大优先改主频配置而不是硬调波特率。2.2 引脚复用关系F1 的 AFIO 和 F4 的 AF 复用表映射错直接失联串口引脚配置是 F1 和 F4 差异最明显的地方。F1 要把 GPIO 配成复用推挽模式还要额外打开 AFIO 时钟再调用引脚重映射函数F4 则直接通过GPIO_AF配置复用功能查复用映射表选对应的 AF 编号。很多人把 F1 的GPIO_Mode_AF_PP写法搬到 F4编译能过但引脚输出是错的。串口F1/F4 常见 TX 引脚F1/F4 常见 RX 引脚F4 对应的复用编号USART1PA9 或 PB6PA10 或 PB7AF7USART2PA2 或 PD5PA3 或 PD6AF7USART3PB10 或 PD8PB11 或 PD9AF7这里有个隐蔽问题F4 上 USART2 和 USART3 的默认引脚如果不用必须在GPIO_InitStructure.Alternate里填对复用编号否则引脚电平完全不对。配置完成后示波器量 TX 引脚如果没有 3.3V 跳变优先检查复用号而不是代码逻辑。中断服务函数的命名也是坑。标准库和 HAL 库都定义了USART1_IRQHandler这个弱函数如果你的驱动文件里重复定义了同名函数链接时会报错。正确做法是把两个平台的实现分别放在不同的.c文件里通过条件编译只参与其中一个文件的构建。具体组织方式下一章展开。3. 驱动怎么组织一个头文件把标准库和 HAL 库切成两套实现3.1 用宏开关做库适配工程属性里换一个宏整套驱动跟着切换开头先想清楚你的代码是要在同一个工程里同时存在两套库还是为两套库分别建工程我的推荐永远是后者——分别建工程但共享同一套接口头文件和逻辑代码。这样每个工程的编译选项里只需要定义一个宏驱动文件会自动选择底层实现。在uart.h里接口定义和条件编译放在一起/* 编译前必须定义一个平台宏二选一 * #define UART_PLATFORM_HAL 使用 HAL 库 * #define UART_PLATFORM_STD 使用标准库 */ #if defined(UART_PLATFORM_HAL) #include stm32f4xx_hal_uart.h #elif defined(UART_PLATFORM_STD) #include stm32f10x_usart.h #else #error No UART_PLATFORM macro defined! #endif /* 统一对外接口 */ typedef struct { uint32_t baudrate; uint8_t word_length; /* 8 或 9 */ uint8_t stop_bits; /* 1 或 2 */ } uart_config_t; void uart_init(void); void uart_send_blocking(const uint8_t *data, uint16_t len); void uart_rx_start(void); uint16_t uart_rx_bytes_available(void);这里最关键的是#error指令如果两个宏都没定义头文件直接在编译期就报错而不是让你运行到串口初始化才发现问题。uart_config_t结构体的字段在两个库之间语义基本一致只是 HAL 库初始化时还要带HAL_UART_STATE句柄这部分由底层实现去填充接口层不感知。预编译宏在不同 IDE 里设置路径不同但原理一致在工程配置的 C/C 编译选项里加一条UART_PLATFORM_HAL或UART_PLATFORM_STD。切换平台时只改这一行不需要动任何源文件。3.2 接口分层一个接口背后挂两套 port 文件业务层永远不感知底层接口层的实现我倾向于拆成多个文件uart_core.c放环形缓冲、状态机、校验逻辑这些与硬件无关的东西uart_port_hal.c和uart_port_std.c放各自的底层初始化、中断处理、DMA 配置。核心层只通过头文件声明的函数指针或宏调用 port 层。以阻塞发送为例HAL 库和标准库的实现思路完全不同/* uart_port_hal.c */ #if defined(UART_PLATFORM_HAL) #include uart.h static UART_HandleTypeDef huart1; void uart_send_blocking(const uint8_t *data, uint16_t len) { HAL_UART_Transmit(huart1, (uint8_t *)data, len, 1000); } #endif /* uart_port_std.c */ #if defined(UART_PLATFORM_STD) #include uart.h void uart_send_blocking(const uint8_t *data, uint16_t len) { for (uint16_t i 0; i len; i) { while ((USART1-SR USART_SR_TXE) 0) {} /* 等发送数据寄存器空 */ USART1-DR data[i]; } while ((USART1-SR USART_SR_TC) 0) {} /* 等发送完成 */ } #endifHAL 库的HAL_UART_Transmit内部做了超时管理最后一个参数是超时毫秒数标准库则需要手动等待 TXE 和 TC 两个标志位而且没有内置超时。上面的循环写法有个隐患如果串口硬件异常TXE 一直不置位程序会死等。实际项目里我习惯加一个超时计数器比如while循环里计算最大等待次数超过就返回错误。标准库的这个uart_port_std.c同样能用在 F1 上。它的寄存器操作在这种简单的场景下反而比 HAL 库更稳定但如果你同时要处理 DMA、错误中断、9 位数据格式HAL 库的回调机制会更省事。两套 port 文件各管一摊接口层保持稳定这就是分层设计的好处。4. 收发模式的参数落点轮询、中断与 DMA 的配置差异4.1 轮询模式阻塞发送的超时参数不是玄学不设迟早卡死轮询模式最适合短帧、低频交互。HAL 库的HAL_UART_Transmit前三个参数好理解第四个参数 Timeout 的单位是毫秒。它依赖系统 tick 计数如果你在主程序里关闭了全局中断或者当前优先级高于 tick 中断这个超时就不精确了。常见做法是主循环外不用高优先级长关中断保持 tick 正常跳动。标准库没有自带超时动手前先想好等多久算失败。我之前在实际项目里会这样封装bool uart_send_blocking_with_timeout(const uint8_t *data, uint16_t len, uint32_t timeout_ms) { volatile uint32_t tick_start systick_ms(); for (uint16_t i 0; i len; i) { while ((USART1-SR USART_SR_TXE) 0) { if ((systick_ms() - tick_start) timeout_ms) { return false; /* 发送卡死时能主动退出 */ } } USART1-DR data[i]; } return true; }systick_ms()是你在系统初始化时维护的毫秒计数器标准库本身没有现成的。注意两点计数器必须在定时器中断里自增保证systick_ms() - tick_start的差值不会被重入问题破坏timeout_ms按整帧算不要按单字节算否则 9200 波特率下发送一个 32 字节的帧会频繁超时。轮询接收相比之下简单得多读RXNE标志为 1 就从 DR 寄存器取一个字节。但轮询接收有一个天然缺点主循环稍一走神数据就会因为 RXNE 溢出而丢失。所以只要帧长超过几个字节我一般就切到中断接收。4.2 中断接收环形缓冲加状态机把硬件事件变成消息中断接收的思路是硬件每收到一个字节触发一次中断用户在中断服务函数里把字节丢进环形缓冲主循环按自己的节奏取数据。这样主循环的阻塞操作不会丢字节。环形缓冲的核心代码是读写指针的管理#define RX_RING_SIZE 256 typedef struct { uint8_t buffer[RX_RING_SIZE]; volatile uint16_t head; /* 写入位置中断中更新 */ volatile uint16_t tail; /* 读取位置主循环更新 */ } ring_buffer_t; bool ring_write(ring_buffer_t *rb, uint8_t byte) { uint16_t next_head (rb-head 1) % RX_RING_SIZE; if (next_head rb-tail) { return false; /* 缓冲区满丢数据 */ } rb-buffer[rb-head] byte; rb-head next_head; return true; }head和tail都必须加volatile因为它们在中断和主循环两个上下文里被交替访问。判断满的标准是next_head tail这种写法牺牲了一个存储位换来的是读写指针不需要加锁。中断里必须避免任何阻塞操作比如把数据直接通过串口打印出去那会把中断服务函数拖得很长硬件上稍快一点的帧都能触发 ORE 溢出错误。标准库中断里读数据有固定套路先读 SR 再读 DR。如果收到字节的同时产生了溢出错误必须在处理完正常字节后把 ORE 标志清掉否则后续中断可能不再触发。具体清标志方法下一章会说。4.3 空闲中断加 DMA不定长收发一帧收完CPU 全程不干预如果是高频收发或一帧几百字节的数据流轮询和普通中断模式都会大量占用 CPU。实际项目里更常用的组合是DMA 把数据自动搬运到内存串口的空闲中断负责通知「一帧结束了可以处理了」。这里 DMA 用的是正常模式不是循环模式。配置链路分三步先用 DMA 的通道把串口 RX 接到内存缓冲然后使能串口的空闲中断最后在空闲中断里算一下本次收到多少字节。关键代码段如下uint8_t dma_rx_buf[512]; volatile uint16_t dma_rx_len 0; void uart_dma_idle_rx_start(void) { DMA_Cmd(DMA1_Channel5, DISABLE); DMA_ClearFlag(DMA1_FLAG_TC5 | DMA1_FLAG_HT5 | DMA1_FLAG_TE5); DMA_InitStructure.DMA_Mode DMA_Mode_Normal; /* 收满一帧后停止 */ DMA_InitStructure.DMA_PeripheralDataSize DMA_PeripheralDataSize_Byte; DMA_InitStructure.DMA_MemoryDataSize DMA_MemoryDataSize_Byte; DMA_InitStructure.DMA_DIR DMA_DIR_PeripheralSRC; DMA_InitStructure.DMA_MemoryBaseAddr (uint32_t)dma_rx_buf; DMA_InitStructure.DMA_BufferSize sizeof(dma_rx_buf); DMA_Init(DMA1_Channel5, DMA_InitStructure); USART_ITConfig(USART1, USART_IT_IDLE, ENABLE); DMA_Cmd(DMA1_Channel5, ENABLE); USART_DMACmd(USART1, USART_DMAReq_RX, ENABLE); } void USART1_IRQHandler(void) { if (USART_GetITStatus(USART1, USART_IT_IDLE)) { USART_ReceiveData(USART1); /* 读 SR 和 DR 清 IDLE 标志 */ DMA_Cmd(DMA1_Channel5, DISABLE); dma_rx_len sizeof(dma_rx_buf) - DMA_GetCurrDataCounter(DMA1_Channel5); /* 把长度为 dma_rx_len 的数据交给协议层 */ DMA_Cmd(DMA1_Channel5, ENABLE); USART_ITConfig(USART1, USART_IT_IDLE, ENABLE); } }参数选择上注意几点DMA_Mode_Normal适合一帧一处理如果在协议上做流式解析循环模式省去每帧重新使能 DMA 的麻烦但你需要自己计算当前写指针位置很容易算错。BUFFER_SIZE也就是 DMA 的 BufferSize必须大于应用中最大帧长否则 DMA 还没搬完一帧就触发传输完成中断数据被截断。DMA 用的通道号在不同型号上不同F1 的 USART1_RX 在 DMA1_Channel5F4 的 USART1_RX 在 DMA2_Stream2移植时先查数据手册。5. 避坑记录波特率误差、标志位残留与上位机握手协议5.1 波特率误差导致间歇性乱码不是换几根杜邦线能解决的现象115200 以下波特率通信正常把上位机调到 921600 后乱码率明显上升有时候能通、有时候整个一帧都是错的。原因F4 平台在 HAL 库环境下初始化串口时波特率分频用的是UART_InitStructure传入的时钟值这个值来源于 RCC 配置。如果主频改了但 RCC 的结构体没有同步更新或者你直接操作寄存器跳过了 HAL_RCC_ClockConfig库内部计算 BRR 时用了旧时钟实际波特率和预期偏差超过 3%。解决别靠猜打开调试器看huart-Init.BaudRate和实际时钟。对照第 2 章的误差计算脚本优先把 APB1 或 APB2 的实际频率在代码里打印出来。如果误差在 1% 以内仍然乱码排查 USB 转串口小板本身的时钟精度便宜的板子晶振误差能达到 2%两个误差叠加就崩了。5.2 溢出标志 ORE 没清干净中断进了一次就再也不来现象程序启动后第一帧数据能收到第二帧开始串口中断完全静默但上位机明明发送了数据。原因RXNE 标志为 1 即数据寄存器未读时硬件又收到新字节溢出标志 ORE 被置位。标准库的中断服务函数如果只在 RXNE 分支里读 DR没有单独处理 ORE这个标志会一直保持 1后续 RXNE 中断不再触发。HAL 库场景下ORE 会触发HAL_UART_ErrorCallback如果你的回调是空的错误状态一直挂在那里库的gState处于错误态后续收发也会被拒绝。解决中断服务函数里不只处理 RXNE还要单独判断 ORE、FE、NE 这三个错误标志。以标准库为例正确清标志的顺序是先读 SR 再读 DRif (USART_GetFlagStatus(USART1, USART_FLAG_ORE)) { USART_ReceiveData(USART1); /* 读 DR 自动清 ORE */ }如果你用的是 HAL 库在 ErrorCallback 里调用__HAL_UART_CLEAR_OREFLAG(huart1)再调用HAL_UART_AbortReceive复位接收状态。这条踩坑记录基本是每次串口项目调试的必经之路。5.3 中断里调用 HAL_Delay数据一多直接 HardFault现象单帧测试一切正常用串口助手以 50ms 间隔连续发数据跑了十几秒后进 HardFault调试器定位在 HAL_Delay 内部。原因HAL_Delay 是基于 SysTick 的SysTick 优先级默认比较低。如果串口中断优先级高于 SysTick在串口中断里调用 HAL_Delay会让 CPU 在中断上下文里死等 SysTick 中断来更新计数器而 SysTick 本身被当前中断挡住了于是形成死锁。这是 HAL 库中断嵌套里最典型的翻车操作。解决中断服务函数里绝不调用任何阻塞延时函数。收到数据就写环形缓冲、置事件标志、或者交给空闲中断去处理任何需要时间的逻辑都放主循环。如果你的项目确实需要在中断里做短延时用普通的for循环空转或硬件定时器不要依赖操作系统调度层的东西。5.4 DMA 第二次收不到数据因为 TCIF 标志没清现象DMA 空闲中断接收第一帧正常第二帧数据来了但空闲中断没触发事件标志也没有更新。原因DMA 工作在正常模式下传输完成时 TCIF 标志保持置位。如果你在配置下一个 DMA 传输前没有清除这个标志新的 DMA 请求会被挂起或直接不启动。空闲中断的使能顺序也有讲究必须先使能 DMA 再清标志反过来会导致硬件状态异常。解决每次启动 DMA 接收前做一整套复位动作。清 TCIF、HTIF、TEIF 三个标志禁掉 DMA 通道重新配置 BufferSize再使能。上面第 4.3 节给出的代码就是标准做法。顺手检查一下DMA_GetCurrDataCounter的返回时机它要在 DMA 通道还在正常工作时读才是有效值禁掉后可能读到 0。5.5 上位机 DTR/RTS 握手信号把芯片复位了程序正常却看不到输出现象下位机代码确认没问题一打开串口助手芯片直接复位打印信息重新出现但你发出去的控制命令完全没反应。原因很多 USB 转串口模块或开发板把 RTS 或 DTR 接到了芯片的复位脚或 Boot 脚。串口助手打开串口时默认拉低 DTR/RTS等于给芯片来了一次硬复位。在某些芯片上DTR 拉低还会让它进入 Bootloader此时的一切串口交互都会异常。解决在串口助手的连接设置里关掉 DTR/RTS 的自动勾选项或者把开发板上这两个信号和复位脚之间的跳线帽拔掉。调试时确认模块上是否只是 TX、RX、GND 三根线接出来了。这个问题有个典型特征每次都复位但程序依然能运行会让你误以为是代码问题实际改成手动控制 DTR 就恢复了。6. 交付前验证内部回环与帧格式校验把隐患清零前面几章的驱动代码可以解决「能不能收发」但能不能稳定交付是另一回事。我拿到新板子或新芯片都会强制自己走一遍回环验证再进业务层。硬件上把 TX 和 RX 用杜邦线短接或者借助串口测试板的环回功能让 MCU 自己发自己收先验证驱动链路。如果只是验证单字节收发用示波器看波形比看打印更直观。一个 8 位数据字符帧里起始位是一个位宽的低电平接着是 8 位数据位低位在前最后是停止位高电平。以 115200 波特率算一个位宽约 8.68 微秒。示波器上能看到连续的低电平跳变说明 TX 引脚驱动正常如果看到明显的高电平时间被拉长多半是停止位或字长配置问题。压力测试时我习惯用脚本和 MCU 配合发随机数据帧、收回来比对import serial, random, time ser serial.Serial(COMx, 115200, timeout1) ok, fail 0, 0 for _ in range(1000): payload bytes([random.randint(0, 255) for _ in range(32)]) ser.write(payload) recv ser.read(len(payload) 2) if recv[:32] payload: ok 1 else: fail 1 print(fok{ok}, fail{fail}) if fail 0: print(check: parity? stop bits? hw flow control?)这个脚本的随机载荷杜绝了「同一帧数据碰巧通过」的假象1000 帧里只要有一帧不对就说明驱动在边界条件下有问题。测试时保持上位机和下位机同一波特率把流控设为 None。如果失败率集中在某几个特定数据模式上大概率是时钟误差在临界点而不是随机干扰。从那以后我每次接到新板子或新串口外设都会强制先跑一遍这个回环测试再进业务协议联调。这样做最大的好处是出问题时你能确定问题在硬件链路、驱动还是应用协议不用整个系统放大招。希望帮到你。本文还有配套的精品资源点击获取
简介面向STM32嵌入式开发者这份UART通信代码覆盖F1与F4两大主流系列同时兼容标准库与HAL库两种开发方式解决了不同项目在串口通信上的移植与适配难题。压缩包共4个文件包含2个头文件与2个C源文件整体仅33KB结构紧凑便于直接放入工程中引用。代码给出了完整的初始化流程、数据发送接收处理、中断管理及错误处理逻辑源码中带有调试信息与注释方便开发者理解每一步的作用并可根据实际场景进行定制化修改。无论是连接GPS、蓝牙模块还是与PC机通信都能借助这组代码快速打通UART链路。目前已有268人学习下载适合正在学习STM32串口开发或需要快速集成UART功能的初中级工程师也可作为标准库与HAL库编程思路的对照范例。1. 为什么要一份同时兼容 F1/F4、标准库/HAL 库的 UART 代码如果你同时维护过 F1 和 F4 两个平台的串口代码大概率经历过这种尴尬F1 上用得好好的标准库驱动拷到 F4 工程里要么编译不过、要么串口死活不进中断。UART 通信本身不复杂但同样是 STM32 的串口标准和 HAL 两套库的写法差异巨大F1 和 F4 的时钟源、引脚复用方式、中断服务函数又不一样代码基本没法直接复用。这份代码包的核心价值是把「芯片型号差异」和「固件库差异」剥离开底层用条件编译分别实现标准库和 HAL 库的驱动上层统一暴露一套 UART 接口。你只需要在工程里定义一个宏就能在 F1 和 F4 之间来回切换不必再为每种组合单独维护一份串口代码。适合那些手里有一堆老标准库项目、又需要接 F4 新项目的人也适合刚入门想少踩坑的人照着复现。2. 先分清外设差异F1 与 F4 的时钟、引脚和中断号不能混用2.1 时钟树差异APB1 与 APB2 上的串口分布波特率误差从这里来F1 和 F4 的外设时钟挂载点不一样这是很多串口乱码问题的根源。F1 系列的 USART1 挂在 APB2 上USART2 和 USART3 挂在 APB1 上F4 系列除了 USART1 和 USART6 在 APB2USART2、USART3、UART4、UART5 都在 APB1 上。你把 F1 工程里的 RCC 时钟使能代码直接拷到 F4 上使能的总线可能对应了错误的外设。芯片平台挂在 APB1 上的串口挂在 APB2 上的串口F1USART2、USART3USART1F4USART2、USART3、UART4、UART5USART1、USART6这个差异直接影响波特率生成。串口波特率寄存器 BRR 的计算公式是fck / (16 * USARTDIV)其中 fck 是串口所在总线的时钟。以默认主频为例F103 的主频常见配置是 72MHz但 APB1 总线时钟只有 36MHz如果你在 USART2 上误用了 72MHz 去算波特率实际跑出来的速率会偏移近一倍。我一般会在配置波特率之前先用一个脚本把所有候选频率下的误差算一遍确认小数分频寄存器能否整除。clock 36000000 bauds [9600, 19200, 38400, 115200, 921600] for baud in bauds: usart_div clock / (16 * baud) mantissa int(usart_div) fraction int((usart_div - mantissa) * 16 0.5) actual clock / (16 * (mantissa fraction / 16)) error (actual - baud) / baud * 100 print(f{baud:7} - actual {actual:10.2f}, error {error:.3f}%)这段脚本把整数部分和小数部分分别截出来再反算实际波特率。注意小数部分寄存器只保留 4 位*16 0.5是四舍五入误差超过 2% 时通信就会开始不稳定。如果误差大优先改主频配置而不是硬调波特率。2.2 引脚复用关系F1 的 AFIO 和 F4 的 AF 复用表映射错直接失联串口引脚配置是 F1 和 F4 差异最明显的地方。F1 要把 GPIO 配成复用推挽模式还要额外打开 AFIO 时钟再调用引脚重映射函数F4 则直接通过GPIO_AF配置复用功能查复用映射表选对应的 AF 编号。很多人把 F1 的GPIO_Mode_AF_PP写法搬到 F4编译能过但引脚输出是错的。串口F1/F4 常见 TX 引脚F1/F4 常见 RX 引脚F4 对应的复用编号USART1PA9 或 PB6PA10 或 PB7AF7USART2PA2 或 PD5PA3 或 PD6AF7USART3PB10 或 PD8PB11 或 PD9AF7这里有个隐蔽问题F4 上 USART2 和 USART3 的默认引脚如果不用必须在GPIO_InitStructure.Alternate里填对复用编号否则引脚电平完全不对。配置完成后示波器量 TX 引脚如果没有 3.3V 跳变优先检查复用号而不是代码逻辑。中断服务函数的命名也是坑。标准库和 HAL 库都定义了USART1_IRQHandler这个弱函数如果你的驱动文件里重复定义了同名函数链接时会报错。正确做法是把两个平台的实现分别放在不同的.c文件里通过条件编译只参与其中一个文件的构建。具体组织方式下一章展开。3. 驱动怎么组织一个头文件把标准库和 HAL 库切成两套实现3.1 用宏开关做库适配工程属性里换一个宏整套驱动跟着切换开头先想清楚你的代码是要在同一个工程里同时存在两套库还是为两套库分别建工程我的推荐永远是后者——分别建工程但共享同一套接口头文件和逻辑代码。这样每个工程的编译选项里只需要定义一个宏驱动文件会自动选择底层实现。在uart.h里接口定义和条件编译放在一起/* 编译前必须定义一个平台宏二选一 * #define UART_PLATFORM_HAL 使用 HAL 库 * #define UART_PLATFORM_STD 使用标准库 */ #if defined(UART_PLATFORM_HAL) #include stm32f4xx_hal_uart.h #elif defined(UART_PLATFORM_STD) #include stm32f10x_usart.h #else #error No UART_PLATFORM macro defined! #endif /* 统一对外接口 */ typedef struct { uint32_t baudrate; uint8_t word_length; /* 8 或 9 */ uint8_t stop_bits; /* 1 或 2 */ } uart_config_t; void uart_init(void); void uart_send_blocking(const uint8_t *data, uint16_t len); void uart_rx_start(void); uint16_t uart_rx_bytes_available(void);这里最关键的是#error指令如果两个宏都没定义头文件直接在编译期就报错而不是让你运行到串口初始化才发现问题。uart_config_t结构体的字段在两个库之间语义基本一致只是 HAL 库初始化时还要带HAL_UART_STATE句柄这部分由底层实现去填充接口层不感知。预编译宏在不同 IDE 里设置路径不同但原理一致在工程配置的 C/C 编译选项里加一条UART_PLATFORM_HAL或UART_PLATFORM_STD。切换平台时只改这一行不需要动任何源文件。3.2 接口分层一个接口背后挂两套 port 文件业务层永远不感知底层接口层的实现我倾向于拆成多个文件uart_core.c放环形缓冲、状态机、校验逻辑这些与硬件无关的东西uart_port_hal.c和uart_port_std.c放各自的底层初始化、中断处理、DMA 配置。核心层只通过头文件声明的函数指针或宏调用 port 层。以阻塞发送为例HAL 库和标准库的实现思路完全不同/* uart_port_hal.c */ #if defined(UART_PLATFORM_HAL) #include uart.h static UART_HandleTypeDef huart1; void uart_send_blocking(const uint8_t *data, uint16_t len) { HAL_UART_Transmit(huart1, (uint8_t *)data, len, 1000); } #endif /* uart_port_std.c */ #if defined(UART_PLATFORM_STD) #include uart.h void uart_send_blocking(const uint8_t *data, uint16_t len) { for (uint16_t i 0; i len; i) { while ((USART1-SR USART_SR_TXE) 0) {} /* 等发送数据寄存器空 */ USART1-DR data[i]; } while ((USART1-SR USART_SR_TC) 0) {} /* 等发送完成 */ } #endifHAL 库的HAL_UART_Transmit内部做了超时管理最后一个参数是超时毫秒数标准库则需要手动等待 TXE 和 TC 两个标志位而且没有内置超时。上面的循环写法有个隐患如果串口硬件异常TXE 一直不置位程序会死等。实际项目里我习惯加一个超时计数器比如while循环里计算最大等待次数超过就返回错误。标准库的这个uart_port_std.c同样能用在 F1 上。它的寄存器操作在这种简单的场景下反而比 HAL 库更稳定但如果你同时要处理 DMA、错误中断、9 位数据格式HAL 库的回调机制会更省事。两套 port 文件各管一摊接口层保持稳定这就是分层设计的好处。4. 收发模式的参数落点轮询、中断与 DMA 的配置差异4.1 轮询模式阻塞发送的超时参数不是玄学不设迟早卡死轮询模式最适合短帧、低频交互。HAL 库的HAL_UART_Transmit前三个参数好理解第四个参数 Timeout 的单位是毫秒。它依赖系统 tick 计数如果你在主程序里关闭了全局中断或者当前优先级高于 tick 中断这个超时就不精确了。常见做法是主循环外不用高优先级长关中断保持 tick 正常跳动。标准库没有自带超时动手前先想好等多久算失败。我之前在实际项目里会这样封装bool uart_send_blocking_with_timeout(const uint8_t *data, uint16_t len, uint32_t timeout_ms) { volatile uint32_t tick_start systick_ms(); for (uint16_t i 0; i len; i) { while ((USART1-SR USART_SR_TXE) 0) { if ((systick_ms() - tick_start) timeout_ms) { return false; /* 发送卡死时能主动退出 */ } } USART1-DR data[i]; } return true; }systick_ms()是你在系统初始化时维护的毫秒计数器标准库本身没有现成的。注意两点计数器必须在定时器中断里自增保证systick_ms() - tick_start的差值不会被重入问题破坏timeout_ms按整帧算不要按单字节算否则 9200 波特率下发送一个 32 字节的帧会频繁超时。轮询接收相比之下简单得多读RXNE标志为 1 就从 DR 寄存器取一个字节。但轮询接收有一个天然缺点主循环稍一走神数据就会因为 RXNE 溢出而丢失。所以只要帧长超过几个字节我一般就切到中断接收。4.2 中断接收环形缓冲加状态机把硬件事件变成消息中断接收的思路是硬件每收到一个字节触发一次中断用户在中断服务函数里把字节丢进环形缓冲主循环按自己的节奏取数据。这样主循环的阻塞操作不会丢字节。环形缓冲的核心代码是读写指针的管理#define RX_RING_SIZE 256 typedef struct { uint8_t buffer[RX_RING_SIZE]; volatile uint16_t head; /* 写入位置中断中更新 */ volatile uint16_t tail; /* 读取位置主循环更新 */ } ring_buffer_t; bool ring_write(ring_buffer_t *rb, uint8_t byte) { uint16_t next_head (rb-head 1) % RX_RING_SIZE; if (next_head rb-tail) { return false; /* 缓冲区满丢数据 */ } rb-buffer[rb-head] byte; rb-head next_head; return true; }head和tail都必须加volatile因为它们在中断和主循环两个上下文里被交替访问。判断满的标准是next_head tail这种写法牺牲了一个存储位换来的是读写指针不需要加锁。中断里必须避免任何阻塞操作比如把数据直接通过串口打印出去那会把中断服务函数拖得很长硬件上稍快一点的帧都能触发 ORE 溢出错误。标准库中断里读数据有固定套路先读 SR 再读 DR。如果收到字节的同时产生了溢出错误必须在处理完正常字节后把 ORE 标志清掉否则后续中断可能不再触发。具体清标志方法下一章会说。4.3 空闲中断加 DMA不定长收发一帧收完CPU 全程不干预如果是高频收发或一帧几百字节的数据流轮询和普通中断模式都会大量占用 CPU。实际项目里更常用的组合是DMA 把数据自动搬运到内存串口的空闲中断负责通知「一帧结束了可以处理了」。这里 DMA 用的是正常模式不是循环模式。配置链路分三步先用 DMA 的通道把串口 RX 接到内存缓冲然后使能串口的空闲中断最后在空闲中断里算一下本次收到多少字节。关键代码段如下uint8_t dma_rx_buf[512]; volatile uint16_t dma_rx_len 0; void uart_dma_idle_rx_start(void) { DMA_Cmd(DMA1_Channel5, DISABLE); DMA_ClearFlag(DMA1_FLAG_TC5 | DMA1_FLAG_HT5 | DMA1_FLAG_TE5); DMA_InitStructure.DMA_Mode DMA_Mode_Normal; /* 收满一帧后停止 */ DMA_InitStructure.DMA_PeripheralDataSize DMA_PeripheralDataSize_Byte; DMA_InitStructure.DMA_MemoryDataSize DMA_MemoryDataSize_Byte; DMA_InitStructure.DMA_DIR DMA_DIR_PeripheralSRC; DMA_InitStructure.DMA_MemoryBaseAddr (uint32_t)dma_rx_buf; DMA_InitStructure.DMA_BufferSize sizeof(dma_rx_buf); DMA_Init(DMA1_Channel5, DMA_InitStructure); USART_ITConfig(USART1, USART_IT_IDLE, ENABLE); DMA_Cmd(DMA1_Channel5, ENABLE); USART_DMACmd(USART1, USART_DMAReq_RX, ENABLE); } void USART1_IRQHandler(void) { if (USART_GetITStatus(USART1, USART_IT_IDLE)) { USART_ReceiveData(USART1); /* 读 SR 和 DR 清 IDLE 标志 */ DMA_Cmd(DMA1_Channel5, DISABLE); dma_rx_len sizeof(dma_rx_buf) - DMA_GetCurrDataCounter(DMA1_Channel5); /* 把长度为 dma_rx_len 的数据交给协议层 */ DMA_Cmd(DMA1_Channel5, ENABLE); USART_ITConfig(USART1, USART_IT_IDLE, ENABLE); } }参数选择上注意几点DMA_Mode_Normal适合一帧一处理如果在协议上做流式解析循环模式省去每帧重新使能 DMA 的麻烦但你需要自己计算当前写指针位置很容易算错。BUFFER_SIZE也就是 DMA 的 BufferSize必须大于应用中最大帧长否则 DMA 还没搬完一帧就触发传输完成中断数据被截断。DMA 用的通道号在不同型号上不同F1 的 USART1_RX 在 DMA1_Channel5F4 的 USART1_RX 在 DMA2_Stream2移植时先查数据手册。5. 避坑记录波特率误差、标志位残留与上位机握手协议5.1 波特率误差导致间歇性乱码不是换几根杜邦线能解决的现象115200 以下波特率通信正常把上位机调到 921600 后乱码率明显上升有时候能通、有时候整个一帧都是错的。原因F4 平台在 HAL 库环境下初始化串口时波特率分频用的是UART_InitStructure传入的时钟值这个值来源于 RCC 配置。如果主频改了但 RCC 的结构体没有同步更新或者你直接操作寄存器跳过了 HAL_RCC_ClockConfig库内部计算 BRR 时用了旧时钟实际波特率和预期偏差超过 3%。解决别靠猜打开调试器看huart-Init.BaudRate和实际时钟。对照第 2 章的误差计算脚本优先把 APB1 或 APB2 的实际频率在代码里打印出来。如果误差在 1% 以内仍然乱码排查 USB 转串口小板本身的时钟精度便宜的板子晶振误差能达到 2%两个误差叠加就崩了。5.2 溢出标志 ORE 没清干净中断进了一次就再也不来现象程序启动后第一帧数据能收到第二帧开始串口中断完全静默但上位机明明发送了数据。原因RXNE 标志为 1 即数据寄存器未读时硬件又收到新字节溢出标志 ORE 被置位。标准库的中断服务函数如果只在 RXNE 分支里读 DR没有单独处理 ORE这个标志会一直保持 1后续 RXNE 中断不再触发。HAL 库场景下ORE 会触发HAL_UART_ErrorCallback如果你的回调是空的错误状态一直挂在那里库的gState处于错误态后续收发也会被拒绝。解决中断服务函数里不只处理 RXNE还要单独判断 ORE、FE、NE 这三个错误标志。以标准库为例正确清标志的顺序是先读 SR 再读 DRif (USART_GetFlagStatus(USART1, USART_FLAG_ORE)) { USART_ReceiveData(USART1); /* 读 DR 自动清 ORE */ }如果你用的是 HAL 库在 ErrorCallback 里调用__HAL_UART_CLEAR_OREFLAG(huart1)再调用HAL_UART_AbortReceive复位接收状态。这条踩坑记录基本是每次串口项目调试的必经之路。5.3 中断里调用 HAL_Delay数据一多直接 HardFault现象单帧测试一切正常用串口助手以 50ms 间隔连续发数据跑了十几秒后进 HardFault调试器定位在 HAL_Delay 内部。原因HAL_Delay 是基于 SysTick 的SysTick 优先级默认比较低。如果串口中断优先级高于 SysTick在串口中断里调用 HAL_Delay会让 CPU 在中断上下文里死等 SysTick 中断来更新计数器而 SysTick 本身被当前中断挡住了于是形成死锁。这是 HAL 库中断嵌套里最典型的翻车操作。解决中断服务函数里绝不调用任何阻塞延时函数。收到数据就写环形缓冲、置事件标志、或者交给空闲中断去处理任何需要时间的逻辑都放主循环。如果你的项目确实需要在中断里做短延时用普通的for循环空转或硬件定时器不要依赖操作系统调度层的东西。5.4 DMA 第二次收不到数据因为 TCIF 标志没清现象DMA 空闲中断接收第一帧正常第二帧数据来了但空闲中断没触发事件标志也没有更新。原因DMA 工作在正常模式下传输完成时 TCIF 标志保持置位。如果你在配置下一个 DMA 传输前没有清除这个标志新的 DMA 请求会被挂起或直接不启动。空闲中断的使能顺序也有讲究必须先使能 DMA 再清标志反过来会导致硬件状态异常。解决每次启动 DMA 接收前做一整套复位动作。清 TCIF、HTIF、TEIF 三个标志禁掉 DMA 通道重新配置 BufferSize再使能。上面第 4.3 节给出的代码就是标准做法。顺手检查一下DMA_GetCurrDataCounter的返回时机它要在 DMA 通道还在正常工作时读才是有效值禁掉后可能读到 0。5.5 上位机 DTR/RTS 握手信号把芯片复位了程序正常却看不到输出现象下位机代码确认没问题一打开串口助手芯片直接复位打印信息重新出现但你发出去的控制命令完全没反应。原因很多 USB 转串口模块或开发板把 RTS 或 DTR 接到了芯片的复位脚或 Boot 脚。串口助手打开串口时默认拉低 DTR/RTS等于给芯片来了一次硬复位。在某些芯片上DTR 拉低还会让它进入 Bootloader此时的一切串口交互都会异常。解决在串口助手的连接设置里关掉 DTR/RTS 的自动勾选项或者把开发板上这两个信号和复位脚之间的跳线帽拔掉。调试时确认模块上是否只是 TX、RX、GND 三根线接出来了。这个问题有个典型特征每次都复位但程序依然能运行会让你误以为是代码问题实际改成手动控制 DTR 就恢复了。6. 交付前验证内部回环与帧格式校验把隐患清零前面几章的驱动代码可以解决「能不能收发」但能不能稳定交付是另一回事。我拿到新板子或新芯片都会强制自己走一遍回环验证再进业务层。硬件上把 TX 和 RX 用杜邦线短接或者借助串口测试板的环回功能让 MCU 自己发自己收先验证驱动链路。如果只是验证单字节收发用示波器看波形比看打印更直观。一个 8 位数据字符帧里起始位是一个位宽的低电平接着是 8 位数据位低位在前最后是停止位高电平。以 115200 波特率算一个位宽约 8.68 微秒。示波器上能看到连续的低电平跳变说明 TX 引脚驱动正常如果看到明显的高电平时间被拉长多半是停止位或字长配置问题。压力测试时我习惯用脚本和 MCU 配合发随机数据帧、收回来比对import serial, random, time ser serial.Serial(COMx, 115200, timeout1) ok, fail 0, 0 for _ in range(1000): payload bytes([random.randint(0, 255) for _ in range(32)]) ser.write(payload) recv ser.read(len(payload) 2) if recv[:32] payload: ok 1 else: fail 1 print(fok{ok}, fail{fail}) if fail 0: print(check: parity? stop bits? hw flow control?)这个脚本的随机载荷杜绝了「同一帧数据碰巧通过」的假象1000 帧里只要有一帧不对就说明驱动在边界条件下有问题。测试时保持上位机和下位机同一波特率把流控设为 None。如果失败率集中在某几个特定数据模式上大概率是时钟误差在临界点而不是随机干扰。从那以后我每次接到新板子或新串口外设都会强制先跑一遍这个回环测试再进业务协议联调。这样做最大的好处是出问题时你能确定问题在硬件链路、驱动还是应用协议不用整个系统放大招。希望帮到你。本文还有配套的精品资源点击获取
