USB‑CDC 虚拟串口完整移植实施方案

1. 故障现象复现步骤

1. 获取 HAL 示例工程device_cdc_acm_uart_freertos，原生适配 NUCLEO‑C562RE；
2. IAR 工程中将目标 MCU 器件修改为 STM32C5A3ZG；不改动任何时钟相关代码；
3. 编译生成 hex 固件，下载至 NUCLEO‑C5A3ZG（MB2310）开发板；
4. Type‑C 线缆连接开发板 USB 接口与 PC；
5. PC 端弹出 “无法识别的 USB 设备”，设备管理器无新增 COM 虚拟串口。

资料获取：实战经验 | LAT1720 从NUCLEO-C562RE向NUCLEO-C5A3ZG移植USB示例

2. 分步移植修改操作

注意：两处修改必须全部完成，只改一处无法解决问题。

步骤 1：修改 RCC 初始化函数 mx_rcc_init ()，更新 PSI 参考时钟 定位mx_rcc_init()RCC 初始化函数： 原始 C562RE 代码：

config_psi.psi_source = HAL_RCC_PSI_SRC_HSE;
config_psi.psi_ref = HAL_RCC_PSI_REF_24MHZ;
config_psi.psi_out = HAL_RCC_PSI_OUT_144MHZ;

修改适配 C5A3ZG：

config_psi.psi_source = HAL_RCC_PSI_SRC_HSE;
config_psi.psi_ref = HAL_RCC_PSI_REF_48MHZ;
config_psi.psi_out = HAL_RCC_PSI_OUT_144MHZ;

核心变更：psi_ref由HAL_RCC_PSI_REF_24MHZ修改为HAL_RCC_PSI_REF_48MHZ，PSI 输出目标频率保持 144MHz 不变。

步骤 2：修改 stm32_external_env.h 头文件 HSE_VALUE 宏 打开stm32_external_env.h头文件，找到 HSE_VALUE 定义片段。 原始定义（C562RE）

#if !defined(HSE_VALUE)
#define HSE_VALUE 24000000UL /*!< Value of the External oscillator in Hz*/
#endif /* HSE_VALUE*/

修改为适配 NUCLEO‑C5A3ZG：

#if !defined(HSE_VALUE)
#define HSE_VALUE 48000000UL /*!< Value of the External oscillator in Hz*/
#endif /* HSE_VALUE*/

替代方案：不在头文件修改，在 IAR 编译器预处理器选项，增加全局宏定义HSE_VALUE=48000000UL，可以规避头文件被覆盖风险。
步骤 3：确认工程 MCU 器件选型 IAR 工程选项，确认芯片型号选择为 STM32C5A3ZG，完成编译。

3. 固件验证测试流程

1. 将编译完成固件下载至 NUCLEO‑C5A3ZG 开发板；
2. 使用 USB Type‑C 线缆连接开发板 USB 接口和 PC；
3. PC 设备管理器观察，正常识别出新的 CDC‑ACM 虚拟 COM 端口；
4. 打开 Tera Term 工具，分别打开 USB 虚拟串口与板载 ST‑Link 虚拟串口；
5. 在任意一个串口输入字符，字符回显至另外一路串口，双向收发数据正常，代表 USB 虚拟串口移植成功。

4. 工程落地检查清单

• 确认硬件板卡实际 HSE 晶振频率，NUCLEO‑C5A3ZG 硬件为 48MHz；
• mx_rcc_init()函数 PSI 的psi_ref枚举参数与硬件晶振匹配；
• stm32_external_env.h中HSE_VALUE数值和硬件晶振匹配；
• 检查编译器预处理器是否已经全局定义 HSE_VALUE，防止头文件修改不生效；
• 工程器件选型已经切换为目标 MCU；
• 下载后 PC 识别 COM 口，双向收发数据测试通过；
• 如果使用 STM32CubeMX 生成工程，需要在 MX 配置界面设置 HSE 晶振，避免代码生成覆盖手动修改。