单片机与物联网 / 系统课时

串口日志与故障定位

串口日志与故障定位

串口通信异常常被笼统描述为“收不到”或“有乱码”,但不同现象对应完全不同的原因。本课建立可检索的日志格式,并按信号、配置、缓冲和协议四个层次定位接线错误、波特率不匹配与丢包问题。

学习目标

  • 能够设计包含时间、级别、模块和关键参数的串口日志
  • 能够按固定顺序区分硬件接线、通信参数和软件缓冲问题
  • 能够利用错误计数与最小测试程序验证修复结果

日志应记录什么

有效日志要回答“何时、哪里、发生了什么、关键参数是多少”。推荐格式为 [时间][级别][模块] 事件: key=value。时间用于还原先后关系,级别用于过滤,模块用于定位代码区域,键值参数用于比较期望状态与实际状态。

日志级别通常分为 DEBUG、INFO、WARN 和 ERROR。发布版本可以关闭高频 DEBUG,但应保留初始化参数、错误计数、缓冲区高水位和协议异常。不要在中断中直接执行阻塞式 printf;更稳妥的方法是把短日志记录写入环形缓冲区,再由主循环或 DMA 异步发送。

固定的定位顺序

排查串口时应从物理层向软件层推进,避免在代码里反复试错。先确认引脚是否有电平跳变,再核对 TX 与 RX 是否交叉、是否共地、双方是否使用兼容的 TTL 电平。RS-232 的正负电压不能直接接入 MCU UART 引脚。

串口日志与故障定位流程

如果引脚有跳变但字符乱码,优先核对波特率、数据位、校验位和停止位,并检查系统时钟配置。若大部分数据正确但高负载时丢包,应读取 UART 的帧错误、噪声错误和溢出错误标志,同时观察环形缓冲区是否写满。只有硬件和参数均正常后,才继续检查帧头、长度、校验与超时逻辑。

完整可运行示例

下面的 C11 程序演示统一日志格式,并根据一组 UART 状态快照给出优先排查方向。主机程序不会访问真实寄存器,但诊断输入与嵌入式系统中的错误计数器一一对应。

c
#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 编译并运行:

bash
gcc -std=c11 -Wall -Wextra -Wpedantic uart_log_demo.c -o uart_log_demo
./uart_log_demo

预期输出

text
[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 接收与多任务通信。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

串口日志与故障定位

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通