极海 APM32F402/F403 USB‑CDC 日志输出开发实操（AN1163 应用笔记 V1.0）

本文基于极海半导体 AN1163 (V1.0) 官方应用笔记，讲解 APM32F402、APM32F403 利用 USB OTG 实现复合设备，同时启用 WinUSB 高速数据通道与 CDC 虚拟串口用于调试日志输出的实现方案。该方案实现单根 USB 线缆完成供电、高速数据交互、调试日志打印，可直接用于数据记录仪、工业采集设备等项目开发参考。文中全部代码、配置逻辑来源于官方文档。

资料获取：AN1163_APM32F402_F403_USB CDC日志输出

1. 项目背景介绍

MCU 项目调试阶段普遍使用硬件 UART 串口输出调试日志。当设备功能趋于复杂，传统 UART 调试会暴露出带宽、接线、硬件资源方面短板。APM32F402/F403 芯片内置 USB OTG 外设，可以配置为USB 复合设备，同时具备 WinUSB 高速数据传输接口、CDC 虚拟串口日志接口。

实现一线三用：同一根 USB 数据线，同时完成设备供电、上位机高速数据交换、MCU 调试日志输出。典型落地案例：数据记录仪设备，设备采集压力、流量、振动传感器数据；维护人员通过 WinUSB 通道高速批量下载历史存储数据；调试人员打开 CDC 虚拟串口，实时读取设备运行状态、告警打印信息，两套逻辑并行运行互不干扰。本文示例均以 APM32F402 作为演示对象，同样适用于 APM32F403。

2. USB‑CDC 替代传统 UART 打印的对比分析

传统 TTL UART 串口调试存在多处工程痛点：

带宽瓶颈：常用 115200bps 波特率，大批量日志输出时传输速度受限；提升波特率对线缆品质要求变高，现场环境容易引入干扰造成乱码。
需要额外配件：TTL 电平串口必须搭配 USB‑TTL 转换模块，增加物料。
接线繁杂：供电电源线、调试串口线、功能信号线数量多，现场调试接线容易混乱。

USB CDC 虚拟串口方案对应的优势：

传输速率更高，性能远高于普通 UART 串口；
物理链路简化，单根 USB 线缆兼顾供电、通信、调试；
支持复合设备模式，CDC 虚拟串口可以和 WinUSB、HID、MSC 等 USB 功能共存，各个逻辑接口互不干扰；
可以一边执行上位机高速大数据交互，一边输出调试打印日志。

3. USB 复合设备工作原理

USB 复合设备指同一个物理 USB 接口，依靠 USB 配置描述符，向外枚举多个独立逻辑功能接口。本方案使用组合：

CDC 接口（虚拟 COM 串口）：专门输出调试日志；
WinUSB 接口（自定义协议）：用于上位机大容量高速数据交互。

硬件资源充足的前提下，复合设备还可以扩展 HID 人机接口、MSC 大容量存储、Audio 音频等其他 USB 功能。

极海 SDK 配套例程OTGD_Composite_CDC_WINUSB，已经完成复合设备描述符、USB 端点分配工作。开发者仅需要少量修改代码，把 printf 输出重定向至 CDC 虚拟串口，原有 WinUSB 高速数据通道功能不受改动影响。

Windows 系统识别完成后设备管理器显示效果：

设备识别说明：标记①位置为 USB 串行设备（CDC 虚拟 COM 口）；标记②位置为APM32 Composite通用串行总线复合设备。两个条目同时出现，代表复合设备枚举成功。

4. 工程落地实现步骤

4.1 基于官方参考例程快速开发

直接使用 SDK 提供OTGD_Composite_CDC_WINUSB工程作为开发基底。该例程已经处理 USB 底层描述符、端点资源分配，无需从零编写复合设备描述符代码，降低开发工作量。

4.2 USB‑CDC 模块初始化

工程需要完整引入 USB 底层驱动文件，包含usb_core、usb_init、usb_cdc等相关驱动源码。在 main 主函数或者系统初始化函数中调用USB_DeviceInit()，完成 USB 设备初始化；该函数完成 USB 设备启动，向 Windows 主机枚举 CDC 与 WinUSB 两组接口。

4.3 printf 重定向实现思路

MDK、IAR 编译环境中，标准 C 库 printf 输出底层依靠fputc或者_write函数。重写底层输出函数，将输出目标从硬件 UART 替换为 CDC 发送接口，即可实现 printf 打印输出到 USB 虚拟串口。

直接逐字符调用 USB 发送接口会造成频繁 USB 报文交互，传输效率低下。工程实现建议增加静态缓冲区：字符先存入内存缓冲区；当缓冲区存满，或者检测换行符\n，一次性调用 CDC 发送接口批量上传数据。

4.4 带缓冲的 fputc 核心代码示例

#define CDC_TX_BUF_SIZE (128)
/*!
* @brief Redirect C Library function printf to serial port.
After Redirection, you can use printf function.
* @param ch: The characters that need to be send.
* @param *f: pointer to a FILE that can recording all information
needed to control a stream
* @retval The characters that need to be send.
* @note
*/
int fputc(int ch, FILE* f)
{
/* 原始的UART 发送代码可以注释或移除*/
// USART_TxData(DEBUG_USART, (uint8_t)ch);
// while (USART_ReadStatusFlag(DEBUG_USART, USART_FLAG_TXBE) == RESET);

/* 定义静态发送缓冲区和计数器*/
static uint8_t s_cdcTxBuf[CDC_TX_BUF_SIZE];
static uint16_t s_cdcTxCount = 0;

/* 可选:根据需要将'\n' 转换为Windows 习惯的"\r\n" */
if (ch == '\n')
{
// 在添加'\r' 前,检查缓冲区是否会溢出
if (s_cdcTxCount >= CDC_TX_BUF_SIZE)
{
USBD_FS_CDC_ItfSend(s_cdcTxBuf, s_cdcTxCount);
s_cdcTxCount = 0;
}
// s_cdcTxBuf[s_cdcTxCount++] = '\r'; // 如果需要,取消此行注释
}

/* 将当前字符存入缓冲区*/
s_cdcTxBuf[s_cdcTxCount++] = (uint8_t)ch;

/* 当缓冲区满或遇到换行符\n 时,立即发送数据*/
if (s_cdcTxCount >= CDC_TX_BUF_SIZE || ch == '\n')
{
USBD_FS_CDC_ItfSend(s_cdcTxBuf, s_cdcTxCount);
s_cdcTxCount = 0; // 发送后清空计数器
}
return (ch);
}

代码关键说明：

s_cdcTxBuf[]静态缓冲区，用于缓存打印字符，减少频繁调用USBD_FS_CDC_ItfSend()；
s_cdcTxCount统计缓冲区内有效字节数量；
触发发送条件：缓冲区填满，或者收到换行符\n，调用 CDC 发送接口批量输出。

4.5 编译、下载与整机测试流程

将重写完成的fputc函数添加至项目工程；
编译工程，固件下载至 APM32F402/F403 开发板；
使用 USB 线缆连接 PC 与开发板 USB OTG 接口；
打开 Windows 设备管理器，确认同时识别虚拟 COM 端口以及 APM32 Composite 复合设备；
使用 PuTTY、Tera Term 等串口工具打开 CDC 对应的 COM 口；USB‑CDC 不受传统波特率参数约束，波特率配置不影响实际通信，传输速率由 USB 总线决定；
完成配置后，程序内 printf 输出日志就会在串口终端输出显示。

串口终端接收日志效果如下图：

5. 方案业务价值与适用场景

基于官方例程少量修改即可完成 CDC 日志输出，这套复合设备方案带来几点工程收益：

硬件连接简化：单 USB 线缆兼顾供电、下载调试、日志打印；
释放硬件 UART 外设：把硬件串口资源释放出来，外接需要硬件流控、特殊波特率的外部串口外设；
双通道并行工作：WinUSB 执行大数据高速传输，CDC 独立输出调试日志，两套通道互不干扰。

适合工业采集设备、数据记录仪、消费电子设备。文档同时提示，开发者还可以在此基础做二次拓展，例如引入 DMA 传输、RTOS 环境搭建发送队列，实现更复杂业务需求（拓展仅为文档提及的可能性，不属于强制实现内容）。

声明：本文全部内容转录自极海官方 AN1163 V1.0 应用笔记，产品实际开发需要结合原厂 SDK、芯片数据手册完成整机验证。