单片机与物联网 / 系统课时
串口日志调试
串口日志调试
本课完成一套适用于 STM32 HAL 工程的最小串口日志方案:将 printf 输出重定向到 UART,增加日志级别和模块标签,并分析阻塞发送对实时任务的影响。完成后,你可以用终端连续观察程序状态,同时知道何时应升级为中断或 DMA 日志。
学习目标
- 将标准输出重定向到 STM32 串口
- 设计可筛选的分级日志格式
- 识别并降低日志阻塞、丢失和干扰时序的风险
建立最小日志通道
示例假设 STM32CubeMX 已生成 USART2,句柄名称为 huart2,编译器使用 GCC/Newlib,串口终端参数与 CubeMX 保持一致。下面代码可放入 main.c 的用户代码区,它依赖 HAL 工程,不能脱离具体芯片独立运行。
#include "main.h"
#include <stdarg.h>
#include <stdio.h>
extern UART_HandleTypeDef huart2;
typedef enum {
LOG_LEVEL_ERROR = 0,
LOG_LEVEL_WARN,
LOG_LEVEL_INFO,
LOG_LEVEL_DEBUG
} LogLevel;
static LogLevel current_level = LOG_LEVEL_INFO;
int _write(int file, char *ptr, int len)
{
(void)file;
// 阻塞发送适合低频调试,超时用于避免永久卡死
HAL_StatusTypeDef status = HAL_UART_Transmit(
&huart2,
(uint8_t *)ptr,
(uint16_t)len,
100
);
return status == HAL_OK ? len : -1;
}
static const char *level_name(LogLevel level)
{
static const char *names[] = {"ERROR", "WARN", "INFO", "DEBUG"};
return names[level];
}
void log_print(LogLevel level, const char *module, const char *format, ...)
{
if (level > current_level) {
return;
}
char message[128];
va_list args;
va_start(args, format);
vsnprintf(message, sizeof(message), format, args);
va_end(args);
printf("[%lu][%s][%s] %s\r\n",
(unsigned long)HAL_GetTick(),
level_name(level),
module,
message);
}
void log_demo(void)
{
log_print(LOG_LEVEL_INFO, "APP", "system started");
log_print(LOG_LEVEL_DEBUG, "ADC", "raw=%u", 2048U);
log_print(LOG_LEVEL_ERROR, "SENSOR", "read timeout");
}预期输出
[<TIME>][INFO][APP] system started
[<TIME>][ERROR][SENSOR] read timeout在 main() 完成外设初始化后调用 log_demo()。<TIME> 是 HAL_GetTick() 返回的毫秒计数,实际值会不同。当前级别为 INFO,因此 DEBUG 日志被过滤。
设计格式并控制输出开销
一条实用日志至少应包含时间、级别、模块和事件。错误日志记录导致功能失败的信息;警告日志记录可恢复但值得关注的异常;信息日志记录启动、连接和状态切换;调试日志记录内部数据。发布版本通常关闭 DEBUG,以减少带宽和格式化计算。
日志文本应包含对象、动作、结果和关键参数。sensor read failed, status=3 比单独输出“失败”更容易检索,也能直接支持根因判断。固定字段顺序还能让终端脚本或日志工具稳定解析。
串口常用的 8N1 格式每个字符需要 10 位。一条 100 字节日志在 115200 bit/s 下,理论发送时间约为:
如果控制任务每 1 ms 执行一次,直接调用阻塞式 printf 会明显破坏调度。浮点格式化还会增加 CPU 开销和固件体积,因此嵌入式日志应限制长度、频率和数据类型。

避免阻塞并验证可靠性
中断服务函数中不应调用阻塞式 printf。发送可能持续数毫秒,还可能依赖中断推进,造成优先级反转、嵌套延迟甚至死锁。更安全的做法是在中断中只记录事件码或写入环形缓冲区,由主循环或低优先级任务统一发送。
高频日志应采用“生产者写缓冲区,UART 中断或 DMA 消费”的结构。缓冲区满时必须明确选择丢弃最新日志、覆盖最旧日志或累计丢弃计数,不能让关键任务无限等待。多个 RTOS 任务同时写日志时,可用互斥锁保护格式化与入队,但中断中不得获取普通互斥锁。
验证时先把级别设为 DEBUG,确认三条日志都出现;再改回 INFO,确认 DEBUG 被过滤。随后连续输出多条短日志,检查乱码、缺行和卡顿。乱码通常来自波特率、时钟或帧格式不一致,缺行常见于缓冲区溢出,卡顿则多由阻塞发送引起。
还应暂时关闭终端或断开接收端,确认 HAL_UART_Transmit() 超时后程序仍能继续。若日志失败会阻断核心业务,应改为忽略单次发送错误并累计故障计数。