单片机与物联网 / 系统课时
串口日志与故障定位
串口日志与故障定位
串口通信异常常被笼统描述为“收不到”或“有乱码”,但不同现象对应完全不同的原因。本课建立可检索的日志格式,并按信号、配置、缓冲和协议四个层次定位接线错误、波特率不匹配与丢包问题。
学习目标
- 能够设计包含时间、级别、模块和关键参数的串口日志
- 能够按固定顺序区分硬件接线、通信参数和软件缓冲问题
- 能够利用错误计数与最小测试程序验证修复结果
日志应记录什么
有效日志要回答“何时、哪里、发生了什么、关键参数是多少”。推荐格式为 [时间][级别][模块] 事件: key=value。时间用于还原先后关系,级别用于过滤,模块用于定位代码区域,键值参数用于比较期望状态与实际状态。
日志级别通常分为 DEBUG、INFO、WARN 和 ERROR。发布版本可以关闭高频 DEBUG,但应保留初始化参数、错误计数、缓冲区高水位和协议异常。不要在中断中直接执行阻塞式 printf;更稳妥的方法是把短日志记录写入环形缓冲区,再由主循环或 DMA 异步发送。
固定的定位顺序
排查串口时应从物理层向软件层推进,避免在代码里反复试错。先确认引脚是否有电平跳变,再核对 TX 与 RX 是否交叉、是否共地、双方是否使用兼容的 TTL 电平。RS-232 的正负电压不能直接接入 MCU UART 引脚。

如果引脚有跳变但字符乱码,优先核对波特率、数据位、校验位和停止位,并检查系统时钟配置。若大部分数据正确但高负载时丢包,应读取 UART 的帧错误、噪声错误和溢出错误标志,同时观察环形缓冲区是否写满。只有硬件和参数均正常后,才继续检查帧头、长度、校验与超时逻辑。
完整可运行示例
下面的 C11 程序演示统一日志格式,并根据一组 UART 状态快照给出优先排查方向。主机程序不会访问真实寄存器,但诊断输入与嵌入式系统中的错误计数器一一对应。
#include <stdbool.h>
#include <stdarg.h>
#include <stdint.h>
#include <stdio.h>
typedef enum {
LOG_DEBUG,
LOG_INFO,
LOG_WARN,
LOG_ERROR
} LogLevel;
typedef struct {
bool rx_pin_has_edges;
uint32_t received_bytes;
uint32_t expected_bytes;
uint32_t frame_errors;
uint32_t overrun_errors;
} UartSnapshot;
static const char *level_name(LogLevel level) {
static const char *names[] = {"DEBUG", "INFO", "WARN", "ERROR"};
return names[level];
}
static void log_message(uint32_t time_ms,
LogLevel level,
const char *module,
const char *format,
...) {
va_list arguments;
printf("[%06lu][%s][%s] ",
(unsigned long)time_ms,
level_name(level),
module);
va_start(arguments, format);
vprintf(format, arguments);
va_end(arguments);
putchar('\n');
}
static void diagnose_uart(const char *case_name,
uint32_t time_ms,
const UartSnapshot *snapshot) {
log_message(time_ms,
LOG_INFO,
"DIAG",
"%s: rx=%lu/%lu, frame=%lu, overrun=%lu",
case_name,
(unsigned long)snapshot->received_bytes,
(unsigned long)snapshot->expected_bytes,
(unsigned long)snapshot->frame_errors,
(unsigned long)snapshot->overrun_errors);
if (!snapshot->rx_pin_has_edges) {
log_message(time_ms + 1,
LOG_ERROR,
"DIAG",
"RX no edges: check TX/RX crossover, common GND, and voltage standard");
} else if (snapshot->frame_errors > 0) {
log_message(time_ms + 1,
LOG_WARN,
"DIAG",
"Frame errors: verify baud rate, data bits, parity, and stop bits");
} else if (snapshot->overrun_errors > 0) {
log_message(time_ms + 1,
LOG_WARN,
"DIAG",
"Overrun detected: shorten ISR work, read faster, or use DMA/ring buffer");
} else if (snapshot->received_bytes < snapshot->expected_bytes) {
log_message(time_ms + 1,
LOG_WARN,
"DIAG",
"Missing bytes without hardware errors: inspect buffering and protocol framing");
} else {
log_message(time_ms + 1,
LOG_INFO,
"DIAG",
"Link healthy: byte count and error counters match expectations");
}
}
int main(void) {
const UartSnapshot wiring = {false, 0, 8, 0, 0};
const UartSnapshot baud = {true, 8, 8, 7, 0};
const UartSnapshot overrun = {true, 80, 100, 0, 3};
const UartSnapshot healthy = {true, 100, 100, 0, 0};
log_message(100, LOG_INFO, "UART", "initialized: baud=115200, format=8N1");
diagnose_uart("case-wiring", 110, &wiring);
diagnose_uart("case-baud", 120, &baud);
diagnose_uart("case-overrun", 130, &overrun);
diagnose_uart("case-healthy", 140, &healthy);
return 0;
}将代码保存为 uart_log_demo.c,使用 GCC 编译并运行:
gcc -std=c11 -Wall -Wextra -Wpedantic uart_log_demo.c -o uart_log_demo
./uart_log_demo预期输出
[000100][INFO][UART] initialized: baud=115200, format=8N1
[000110][INFO][DIAG] case-wiring: rx=0/8, frame=0, overrun=0
[000111][ERROR][DIAG] RX no edges: check TX/RX crossover, common GND, and voltage standard
[000120][INFO][DIAG] case-baud: rx=8/8, frame=7, overrun=0
[000121][WARN][DIAG] Frame errors: verify baud rate, data bits, parity, and stop bits
[000130][INFO][DIAG] case-overrun: rx=80/100, frame=0, overrun=3
[000131][WARN][DIAG] Overrun detected: shorten ISR work, read faster, or use DMA/ring buffer
[000140][INFO][DIAG] case-healthy: rx=100/100, frame=0, overrun=0
[000141][INFO][DIAG] Link healthy: byte count and error counters match expectations移植到 STM32 时,可从 USART 状态寄存器或 HAL 错误回调累计帧错误与溢出错误,并用系统毫秒计数替换示例时间。动态时间值会随实际运行变化,但字段顺序应保持稳定,便于终端过滤和脚本解析。
常见故障与验证
| 现象 | 优先原因 | 修复动作 | 验证方法 |
|---|---|---|---|
| 完全无数据 | TX/RX 未交叉、未共地、引脚复用错误 | 检查连线与 GPIO 复用配置 | 观察 RX 引脚跳变并执行回环测试 |
| 持续乱码 | 波特率或帧格式不一致 | 双方统一波特率和 8N1 等参数 | 发送固定字节序列并逐字节比对 |
| 高负载时丢包 | 接收溢出、阻塞日志、缓冲区过小 | 缩短中断、扩大环形缓冲区或启用 DMA | 错误计数归零且接收字节数一致 |
| 偶发校验失败 | 干扰、帧超时或协议重新同步不足 | 改善布线并增加超时和强校验 | 连续传输多轮后无错误帧 |
| 开启日志后故障加重 | 日志发送阻塞改变时序 | 降低日志级别并改为异步发送 | 关闭与开启日志时业务结果一致 |
修复后不要只观察“看起来正常”。应清零计数器,连续发送已知数量的固定帧,核对发送数、接收数、校验失败数和溢出数。条件允许时,再用逻辑分析仪确认实际位宽与设定波特率一致。
本课练习
练习一:为示例增加 noise_errors 和 buffer_high_watermark 字段。当噪声错误大于 0 时输出布线与电源检查建议;当缓冲区高水位超过容量的 80% 时输出性能告警。验收时,不同快照应进入互斥且合理的诊断分支。
练习二:设计一次 1000 帧回环测试。每帧包含递增序号,接收端记录缺失序号、重复序号、校验失败数和最大接收间隔。验收条件是报告字段完整,并能区分链路丢帧与应用层重复处理。
本课总结
- 可定位的日志必须包含时间、级别、模块、事件和关键参数
- 串口故障应按物理连接、通信参数、缓冲处理和协议解析的顺序排查
- 修复结果要用错误计数、固定数据和连续回环测试量化验证
下一课预告
完成 UART 基础后,下一阶段可以把串口协议、环形缓冲区和日志系统组合进完整外设工程,并进一步学习 DMA 接收与多任务通信。