企业官网建设流程全解析

这是STM32C5A3R开发笔记的第3篇。拿到板子、把工程模板建好、GPIO点灯跑通之后，我接下来做的事永远是同一个：配置串口打印。串口打印把芯片内部正在跑的状态实时搬到电脑上，printf 一行日志下去，程序走到哪个分支、变量变成什么、中断有没有进，全都一目了然。如果你刚开始上手这颗带 Cortex-M33 内核的新芯片，这篇照着做基本就能把“会说话的固件”跑起来。

1. 先把定位说清楚：这颗 M33 内核芯片与串口打印的关系

1.1 STM32C5A3R 到底是一颗什么样的芯片

STM32C5 系列是 ST 在通用 MCU 产品线上的一次重新梳理，核心换成了 Cortex-M33，支持 TrustZone，主频和片上资源相比老一代 M0+/M4 产品有明显提升。官方给这个系列的定位很直白：在中低功耗场景里提供更强的算力和安全特性。Cortex-M33 可以理解成 Cortex-M4 的换代版本，多了一堆 DSP 指令、可选浮点单元，同时对软件隔离的支持更完整。

这颗芯片对大多数从 STM32F1/F4 迁移过来的开发者来说，开发流程并不陌生。CubeMX 里照样选芯片、配引脚、生成 HAL 工程，代码风格和 STM32 老系列基本一致。真正需要适应的点有三个：时钟树结构变了、部分外设命名规则变了、默认的启动安全配置可能和你想的不一样。串口打印这个功能刚好能把这些变化都暴露出来——时钟有没有配好、引脚复用有没有选对、UART 外设有没有被使能，一跑就露馅。

1.2 为什么开发初期我坚持把串口打印放在最前面

很多刚用 STM32 的开发者会优先折腾调试器断点，觉得既然有在线调试，串口打印就是多余的。我的实际体验恰恰相反：断点解决“当前这一刻发生了什么”，串口打印解决“过去一段时间内发生了什么”。尤其遇到延时相关的时序问题、中断频繁触发的问题，你在断点停下来的时候，现场已经变了，根本抓不住。

串口打印还有一个优点：它在真实运行速度下工作。你在串口助手里看到的是芯片以实际主频运行时输出的信息，不是暂停后的快照。这样定位问题更接近真实场景。再加上后续想接上位机、数据可视化、参数交互面板，串口本身就是现成的物理通道，打印只是它的第一种用法。

所以，无论你是刚拿到 STM32C5A3R 的开发板，还是从其他平台转过来，我都建议先把串口打印当成第一个“正经”外设来配。它代码量不大，但牵涉到的知识点非常密集：时钟、引脚复用、串口协议、标准库重定向，每一块都是嵌入式开发的地基。

2. 硬件接线清单：把串口引脚和USB转串口模块接对

2.1 先对着原理图找到可用串口引脚

给 STM32C5A3R 配置串口打印的第一步，不是打开 CubeMX，而是看开发板原理图。你需要找到板上明确引出的 UART 引脚。STM32C5A3R 的 LQFP 封装上，USART1 一般可以复用到 PA9/PA10，也可能放在 PB6/PB7，具体以你手里的板子为准。开发板厂商通常会把某一路串口直接连到板载调试器的虚拟串口或者排针上，这块信息原理图里一定标得很清楚。

找引脚的时候注意区分一个概念：USART 和 UART。STM32 的 USART 比 UART 多了同步时钟输出功能，但我们在调试打印时只用异步模式，就是把 USART 当 UART 用。此时USARTx_TX和USARTx_RX两根线即可，不需要时钟线。

引脚定下来之后，建议直接在 CubeMX 里输入引脚号看可选的复用功能。如果 CubeMX 里把引脚设为USART1_TX，软件会自动配好 GPIO 的复用模式，不用手动翻数据手册查 AF 编号。这个功能在老手册时代是没有的，现在省了很多事。

2.2 USB转串口模块接线的三个硬性要求

市面上常见的 USB 转串口芯片有 CH340、CP2102、FT232、CH9102 等，用法大同小异。接线原则就三条，缺一个都可能出怪问题：

• 共地：开发板的 GND 必须和 USB 转串口模块的 GND 连在一起。两边系统各自独立供电时，参考地不一样，电平判断就会出错。
• 交叉连接：开发板的 TX 接模块的 RX，开发板的 RX 接模块的 TX。这两根线接反是最常见的“无打印”原因。
• 电平匹配：STM32C5A3R 是 3.3V IO，模块要选 3.3V 电平的版本，不要把 5V TTL 电平直接怼进去。大部分常见模块在设计时已经默认按 3.3V 工作，但有些老模块出厂是 5V，需要确认。

我在实际项目里还会格外注意 RTS/DTR 这两个信号。很多低价 USB 转串口模块会把 DTR/RTS 引出来做成自动下载电路，插上电脑或者打开串口助手的瞬间，模块会给开发板一个复位脉冲。如果你在跑一个正在打印的固件，这个脉冲会导致芯片重启，看起来就像“打印到一半突然重来”。“我只接 TX、RX、GND 三根线，把 DTR/RTS 悬空”，这个习惯帮我避开了大量诡异问题。

2.3 上电前用万用表做的 30 秒自检

接好线、上电前，我通常会拿万用表量一下开发板 TX 引脚的静态电平。串口初始化之后，空闲状态 TX 引脚应该是高电平，接近 3.3V。如果量出来是 0V，很可能引脚没配置成功，或者芯片根本没跑起来；如果是 1.6V 左右这种半高电平，往往是引脚悬空或者被测点选错了。

这个判断在固件还没烧进去的时候也适用：芯片默认状态下大部分引脚是高阻，量出来的电压不稳定；烧入正确的串口初始化代码后，TX 引脚应该稳定在 3.3V 附近。如果你手头有示波器，可以观察发送 printf 的瞬间，TX 引脚上会出现一串矩形波。没有示波器也没关系，几百块钱的逻辑分析仪也能干这件事，至少比蒙着眼睛调要快得多。

3. CubeMX 工程配置逐项解释：每个选项都不是白设的

3.1 新建工程的时钟、调试接口和串口外设分配

在 CubeMX 里新建工程，输入 STM32C5A3R 这个型号后，第一件事是配置 RCC。如果板上有 8MHz 外部晶振，直接把 HSE 设为 Crystal/Ceramic Resonator，用外部晶振能给串口提供更准的波特率基准。如果板上没有外部晶振，就保持 HSI 作为时钟源，注意 HSI 的精度或温度漂移没有晶振好，但这不影响 115200 这种常规波特率。

然后配置调试接口。STM32 的调试接口不默认占用引脚，需要到 SYS 里打开 Serial Wire，否则烧录器连不上也进不了调试。这一步很多人会忘，等你做完所有配置生成工程后才发现 SWD 不可用，就得退回重新设置。

接着到 Connectivity 里选 USART1，Mode 选 Asynchronous（异步模式），这会把 USART1 的 TX、RX 引脚自动分配到 CubeMX 认为可用的物理引脚上。在此页往下看，Parameter Settings里默认的 115200-8-N-1 对调试打印来说完全够用，一般不需要改。

3.2 HAL_UART_Init 里每个参数到底在影响什么

生成代码后，CubeMX 会在MX_USART1_UART_Init函数里填好一串初始化参数。我平时调试时很少改这串配置，但每个参数的作用必须清楚：

huart1.Instance = USART1; huart1.Init.BaudRate = 115200; huart1.Init.WordLength = UART_WORDLENGTH_8B; huart1.Init.StopBits = UART_STOPBITS_1; huart1.Init.Parity = UART_PARITY_NONE; huart1.Init.Mode = UART_MODE_TX_RX; huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE; huart1.Init.OverSampling = UART_OVERSAMPLING_16; if (HAL_UART_Init(&huart1) != HAL_OK) { Error_Handler(); }

• BaudRate：每秒传输的比特数，串口两端必须一致。115200 是调试场景的黄金速率。
• WordLength：8 位数据位是默认值，和 9 位数据位相比，适用于绝大多数文本打印。
• StopBits：停止位是 1 位，足够。
• Parity：无校验。打印调试信息不需要校验，多一位校验反而降低有效数据速度。
• Mode：如果后续只想发送不接收，可以只选UART_MODE_TX。但为了以后调试方便，一般直接开着收发。
• HwFlowCtl：硬件流控，需要 RTS/CTS 引脚配合。日常调试不开，否则还需要多接两根线。

OverSampling 默认是 16 倍过采样，也就是每个数据位被采样 16 次，抗干扰能力强。8 倍过采样能提高最高波特率，但噪声环境下的误码率会略高。做串口打印完全没必要改。

3.3 时钟树里的一个隐蔽红线：波特率误差

USART 的波特率不是想设多少就多少，它由外设时钟PCLK和波特率寄存器BRR共同决定。芯片里能分频出来的频率和理想波特率之间，总会存在一点偏差。CubeMX 打开时钟树 Clock Configuration，把 APB 总线和串口时钟源一路点下来，能看到当前配置下波特率的实际偏差。

以 115200 为例，如果恰好算出来是个循环小数，取整后偏差一般在 0.2% 以内，串口通信完全能容忍。但如果你把 APB 分频设置得很极端，比如分频到 12.5MHz，这时 115200 的误差会跳到无法容忍的地步。老工程师常说的“串口乱码查时钟”，指的就是这种情况。

所以配置时不要只看串口设置的波特率，还要在时钟树里确认一下实际分频结果。CubeMX 的界面上通常会直接显示出误差百分比，或者用颜色提示异常。即使看不到提示，只要外设时钟是整数倍的常见分频组合，115200 几乎没有问题。

4. printf 重定向的三种写法：Keil、GCC 和一个万能兜底

4.1 Keil 的微库重定向写法

CubeMX 生成的 HAL 库提供了HAL_UART_Transmit函数来发送字节，但 C 标准库的printf并不知道这个函数存在。printf最终会调用一个底层字符输出函数，在 PC 平台上它往终端写，在嵌入式平台我们把它改写到串口。Keil 环境里如果勾选了 MicroLIB（微库），实现起来很简洁：

#include "stdio.h" #include "stm32c5xx_hal.h" extern UART_HandleTypeDef huart1; int fputc(int ch, FILE *f) { uint8_t b = (uint8_t)ch; if (HAL_UART_Transmit(&huart1, &b, 1, 100) != HAL_OK) { return EOF; } return ch; }

这个函数里100是超时时间，单位毫秒。我特意不用HAL_MAX_DELAY，因为如果串口硬件出错，无限等待会让程序永远卡死在打印这里。100ms 足够一次常规命令发送，出错时还能返回到调用处，方便定位。

勾选 MicroLIB 的原因是为了省资源。微库编译出来的 printf 相关代码体积更小，而且默认行为更贴近嵌入式需求。如果你的程序里不是必须用 C99 标准库的某些高级特性，开着微库没坏处。

4.2 GCC 工具链下的 _write 实现

用 STM32CubeIDE、CLion 加 arm-none-eabi 工具链时，重定向函数不一样。GCC 的 newlib 库使用_write作为底层字符输出入口，需要实现这个函数而不是fputc：

#include <stdio.h> #include <unistd.h> #include "stm32c5xx_hal.h" extern UART_HandleTypeDef huart1; int _write(int fd, char *ptr, int len) { if (fd == STDOUT_FILENO || fd == STDERR_FILENO) { if (HAL_UART_Transmit(&huart1, (uint8_t *)ptr, len, 100) != HAL_OK) { return -1; } } return len; }

注意 newlib 有一个坑：printf默认是全缓冲模式，也就是说不等缓冲区满或者程序正常退出，打印内容不会真正发出去。这在嵌入式死循环程序里可能导致你看不到想看的日志。解决办法是在main初始化后调用一句：

setvbuf(stdout, NULL, _IONBF, 0);

这句话把 stdout 设为无缓冲，printf直接调用_write，日志实时输出。对于调试阶段这种近乎裸奔的用法，比纠结缓冲策略高效得多。

4.3 不依赖标准库的字符串发送兜底方案

不排除一种情况：项目禁用了标准库、内存小到放不下 printf 的格式化逻辑，或者链接时怎么都报fputc重复定义的错。这种时候不要死磕标准库，直接用串口发送接口写一个轻量打印函数，一样能干活：

#include "stm32c5xx_hal.h" #include <stdarg.h> #include <stdio.h> extern UART_HandleTypeDef huart1; void dbg_printf(const char *fmt, ...) { char buf[128]; va_list args; va_start(args, fmt); vsnprintf(buf, sizeof(buf), fmt, args); va_end(args); HAL_UART_Transmit(&huart1, (uint8_t *)buf, strlen(buf), 100); }

这个方案绕开了 stdout 的重定向，直接走格式化加发送，代码逻辑一目了然。缺点是场景固定：单线程、轮询发送、格式串长度受限。但对早期调试来说完全够用。等以后项目需要稳定日志框架时，再把输出管道切到 DMA 或者直接接 RTT，这里的接口可以保持不动，只改内部实现。

5. 打开串口助手后的排查表：乱码、没反应、丢首字符

5.1 现象一：全是乱码

串口助手收到的内容呈现乱码，第一怀疑对象永远是波特率不一致。你拿着板子的 115200 去对比助手的 9600，解析出来肯定是一堆无法辨认的字符。这时候先确认助手里选的波特率、数据位、停止位、校验位是否和 CubeMX 中完全一致。

如果参数一致还是乱码，就要怀疑发送端波形时序不对。常见原因是时钟配置改过之后，串口实际波特率和预期偏差过大。用示波器量 TX 引脚，数一数 1 秒内能收到多少帧起始位，基本就能算出真实波特率。对于 115200 这种目标，实测偏离只要在 1% 左右，一般不会出现肉眼可見的乱码；一旦乱到看不清字符，多半是分频数设错了。

5.2 现象二：完全无输出

无输出的排查顺序比乱码更讲究，我就是按下面的顺序来的：

1. 量一下 TX 引脚静态电平，确认引脚有没有被配置成复用功能。
2. 确认串口模块的 RX 接到开发板 TX，模块 TX 接到开发板 RX，接反了不会有任何输出。
3. 确认 GND 已经共地，模块和板子各自工作但参考电位不同，也会静默。
4. 看 main 函数有没有执行到 printf 所在位置。可能程序卡在系统时钟初始化、Flash 等待周期配置，或者中断里死循环。

还有一个特别容易忽略的地方：板载串口芯片用作 USB 转串口时，需要安装对应驱动。没有驱动时，设备管理器里显示的是未知设备或感叹号，串口助手自然打不开正确串口号。

5.3 现象三：打印中途卡死

打印到中间突然完全不动的，常见原因有四个：

• HAL_UART_Transmit 超时设成了HAL_MAX_DELAY，发送期间硬件产生错误，函数永远等下去。
• 串口模块断连或者 USB 接触不良，上位机这边一直没收到后续数据。
• 程序本身死机了，比如某个中断没有清标志导致 CPU 一直停在中断里。
• printf 格式化参数和实际参数不匹配，例如用%d打印一个float，newlib 在某些配置下会直接跑飞。

第五种情况特别阴险，因为编译期不会报错，运行时的行为又不可预测。我吃过这个亏之后，在所有 printf 之前都会把浮点格式串检查一遍，或者在 CubeMX 工程设置里显式开启use float with printf。

5.4 现象四：一开始的前几行不见了

如果程序上电就 printf ，但串口助手是在芯片跑起来之后才打开的，那前几行日志已经发过去了，你打开窗口前数据就丢了。解决办法有几种：

• 在最开始的 printf 前面加一个HAL_Delay(100)，给上位机一个打开窗口的时间窗口。
• 让串口助手带 DTR 复位功能，在打开串口的同时让芯片复位重新打印一轮。
• 在 UART 初始化后立刻设置一个状态查询协议，上位机主动请求，芯片收到命令后再输出历史日志。

这个现象不会影响调试功能，但它会让你误判“程序没跑到这里”，实际上程序早就跑过了。如果实在需要完整日志，建议用下节说的 RTT 或者记录到 Flash，彻底绕开 PC 串口打开时机的问题。

6. 上点强度：DMA 打印、RTT 和结构化日志怎么接

6.1 从轮询打印到中断/DMA 打印

HAL 库的HAL_UART_Transmit是阻塞轮询发送，它会占用 CPU 直到最后一个字节从移位寄存器发出去。115200 波特率下，一个字节大约 87 微秒，如果你每秒打印几千个字节，CPU 时间被吃掉不少。更麻烦的是，如果你在中断服务函数里调用阻塞打印，整个中断被拖慢，实时性直接遭殃。

进阶做法是用 DMA：

HAL_UART_Transmit_DMA(&huart1, (uint8_t *)buf, len);

但 DMA 方式有个关键问题：printf 返回时数据可能还在 DMA 搬运中，你紧接着发第二次 printf，老缓冲区被新内容覆盖，输出就乱了。如果只是简单地在 fputc 里改成 DMA，大概率会得到一堆支离破碎的日志。正确的设计是建一个发送环形缓冲区，将要发送的数据先搬进缓冲区，把“业务逻辑”和“硬件发送”解耦。数据进入缓冲区后被逐段交给 DMA，DMA 完成中断再把下一个段送到串口。

这样改完之后，printf 的耗时不再取决于波特率，而取决于拷贝到环形缓冲区的时间。对很多需要高速日志输出的场景，这是质的提升。

6.2 换条调试通道：SWO 和 RTT 什么时候值得用

串口打印毕竟要占一个外设和两根引脚。如果项目对引脚资源敏感，或者对时序要求很高，可以考虑另一条调试通道：

• SWO 引脚输出：Cortex-M33 的 ITM 模块可以把调试信息从 SWO 引脚发出去，只需要一根线。配合调试器的 Trace 功能，不占用 UART 引脚。缺点是各厂商调试器的 SWO 支持程度不一样，而且这个方案没法让普通上位机直接读取，必须有一套配套软件。
• RTT：SEGGER J-Link 调试器的 RTT 模式通过调试接口进行双向数据通道，速度远快于串口，而且不需要额外的 IO。但 RTT 要求必须有 SEGGER J-Link 或兼容调试器，有的 IDE 或低端烧录器不一定支持。

如果你手头同时有 J-Link 和 USB 转串口，我的建议是：开发初期用串口打印，省事且普适；当你开始调实时性要求高的算法，比如电机控制、音频处理，再把日志切到 RTT。RTT 的缺点是看着不直观，需要开一个调试器上位机窗口，但它不会因为多打几行日志就把时序拖垮。

6.3 让日志带上等级和时间戳

项目代码量上来后，裸的“我在哪”“变量是多少”已经不够用了。需要打印系统当前时间，定位一段日志发生的先后顺序；需要打印日志等级，方便过滤错误和调试信息。实现方式很简单：用一个全局 tick 作为时间戳，在打印函数前面拼接好再输出。

我习惯定义一个简单的日志宏：

#define LOG_ERROR(fmt, ...) do { \ printf("[ERR][%lu] " fmt "\r\n", (unsigned long)get_tick(), ##__VA_ARGS__); \ } while(0)

这样一个宏的好处是：想彻底关闭某级日志时，直接把这个宏的 printf 改成空操作即可，不影响调用代码逻辑。在调试串口偶尔会成为性能瓶颈时，这个开关非常实用，不需要删代码，只改一个宏定义。

6.4 最后再说一句实在话

如果你刚开始入门 STM32C5A3R，别急着把打印通道做得花里胡哨。先把最朴素的轮询串口跑通，把 printf 重定向搞定，能看到日志就是胜利。之后遇到性能问题、功能需求，再逐步把打印通道升级成 DMA、RTT、日志模块。好用的调试系统不是一次设计出来的，是跟着项目需求生长出来的。

串口打印这个功能看似基础，但它连接了芯片内外两个世界。通过它你能同时验证时钟配置、外设初始化、标准库行为，以及上位机工具链是否就绪。这一层跑通了，后面无论是搞电机控制、传感器驱动还是协议栈，都有一条可以随时拉通的观测通道，开发效率和问题定位速度都会明显上一个台阶。