做嵌入式这几年跟设备打交道最多的就是串口。调试日志、AT指令、固件升级哪一样都离不开UART。但老式串口方案要么占一个USART外设要么外挂一颗CH340或者CP2102费钱费板子面积。后来我在STM32F407上试了一把USB CDC直接把USB口虚拟成一个串口主机侧看到的就是一个COM口不需要额外芯片一根USB线搞定整个调试链路清爽了很多。这篇文章就从零开始把STM32F407 USB CDC虚拟串口的完整实现过程捋一遍。包括CubeMX的配置细节、中间件代码怎么改、上位机联调怎么做、以及我在实际项目里踩过的坑。适合正在做设备调试工具、数据采集、固件升级通道或者想省掉一颗USB转串口芯片的同学参考。1. USB CDC与虚拟串口为什么值得自己搭一套1.1 虚拟串口到底怎么实现的USB CDCCommunications Device Class通信设备类是USB组织定义的一种标准设备类用于实现网络、电话、串口等通信功能。我们常说的虚拟串口用的是其中的ACM子类Abstract Control Model抽象控制模型。简单说设备通过USB描述符向主机声明“我是CDC ACM设备”Windows、Linux、macOS识别后就会把它虚拟成一个串口设备。以前我们做USB转串口往往是接一颗CH340、CP2102、FT232这类专用桥接芯片芯片一端接USB一端接MCU的UART。现在用STM32F407事情就变简单了F407内部带了USB OTG FS控制器只要在PA11、PA12上直接引出USB数据线把固件里的USB中间件配置成CDC类再写一段驱动代码MCU本身就能充当USB转串口设备。主机侧看到的是COM口下位机侧收发的是USB端点数据外设层面的UART完全绕开了。这么做的本质是把“物理串口”替换成“端点管道”。PC发的串口数据会变成USB批量传输包通过端点发送到MCUMCU想上报的数据也通过端点发送给主机。对外表现和普通串口几乎一样但底层机制完全不同这也是后面理解各种“异常现象”的关键。1.2 相比外部UART转USB芯片CDC方案的优势和代价先说优势。第一省掉一颗芯片BOM成本降低PCB面积也省下来。第二虚拟串口是USB全速设备批量传输模式下实际吞吐量比传统UART转USB芯片跑大波特率时高得多。第三不需要用掉USART外设对引脚资源紧张的板子非常友好。第四STM32F407的USB控制器支持多个接口组合同一个USB口可以同时做CDC和MSCU盘这对做“带日志导出和参数升级的数据采集器”非常实用。有优势就有代价。首先是驱动复杂度上来了USB协议栈的初始化、枚举、端点管理中间件代码比你调UART寄存器要复杂。其次USB调试不方便一旦枚举失败查看问题的手段比串口少需要逻辑分析仪或者USB分析仪才能看清描述符交互过程。第三虚拟串口虽然叫“串口”但它不是字节流管道而是包管道每次接收是一个USB包接收回调处理逻辑和串口中断不太一样。1.3 这套方案适合谁我觉得下面几类场景特别适合用F407的USB CDC虚拟串口产品调试口。一个USB口既能供电又能输出日志、输入指令调试阶段很省事。数据采集设备。比如传感器数据采集上位机通过虚拟串口每隔几十毫秒拉一次数据。固件升级通道。很多设备没有网口用USB虚拟串口做Bootloader的下载通道很常见。教学演示和二次开发。F407开发板基本都引出了USB口跑通一个CDC代码对理解USB协议栈很有帮助。如果你只是想在串口助手里收发几个字节这个方案可能有点“重”。但只要涉及批量传输、自动升级、高速采集USB CDC的优势立刻就体现出来了。2. 硬件与工程配置CubeMX里把地基打好2.1 硬件准备和接线检查我用的板子是自己画的F407核心板不过市面上的正点原子、野火、ST官方Discovery板基本都适用。硬件上只要确认USB_OTG_FS相关的几个引脚没接错就行。STM32F407有两个USB控制器USB_OTG_FS和USB_OTG_HS。其中USB_OTG_FS内部已经集成了PHY直接用PA11DM、PA12DP两个引脚就能工作USB_OTG_HS内部没有PHY需要外接USB3300这类ULPI PHY一般项目用不上。做虚拟串口优先用USB_OTG_FS。接线检查三个地方PA11、PA12是否接到了USB座的D-、DPA9是否连接到USB座的VBUSPCB上DP、DM走线是否等长尽量短。PA9这个脚容易被忽略它对应USB_OTG_FS的VBUS检测。如果你没有把PA9接到5V的VBUS上设备可能无法被主机识别。很多开发板已经默认接好但自己画板子的话这个最容易漏。另外要看USB座子有没有把ID引脚处理掉。做Device模式时ID脚一般悬空或者接地都行关键还是DP/DM/VBUS三根线。2.2 时钟配置为什么USB非要48MHzUSB全速设备的位速率是12Mbps但这个速度不是直接分频出来的USB控制器内部需要以48MHz作为参考时钟。STM32F407的USB OTG FS和HS都要求输入48MHz时钟而且必须由PLL的Q输出提供。时钟树配置里外部晶振我用了8MHz系统主频跑到168MHz。PLL的N、P、Q参数比较关键CubeMX里40MHz到48MHz等参数都可以自动计算。你只要在Clock Configuration界面里把USB OTG FS clock那一栏点成48MHz就行。这里有个隐藏的坑有人用25MHz外部晶振如果PLLQ分频选错USB时钟可能变成45MHz或者50MHz设备一样能枚举成功但数据收发极不稳定偶发丢包、枚举概率性失败。所以每次怀疑USB问题先查系统时钟是不是168MHzUSB时钟是不是48MHz。CubeMX里这两个颜色都变成绿色才算安全。2.3 USB_OTG_FS与CDC中间件配置在CubeMX里配置流程不复杂步骤我列一下。第一步配置RCC。HSE选择Crystal/Ceramic Resonator使用外部高速晶振。第二步配置时钟树。按上面说的主频168MHzUSB时钟48MHz。第三步选择USB_OTG_FS。在Connectivity里找到USB_OTG_FS把Mode选成Device_Only。第四步使能USB Device中间件。在Middleware里找到USB_DEVICEClass for FS IP改成Communication Device ClassVirtual Port Com这就是CDC虚拟串口。USB_DEVICE的参数页里有VID、PID、Manufacturer String、Product String默认是ST的VID 0x0483、PID 0x5740建议改成自己产品的VID和PID避免和ST官方的VCP驱动冲突。第五步配置NVIC。在System Core的NVIC设置里勾选OTG_FS_IRQHandler。中断优先级建议默认就行但不要设成0因为USB中断里要做的事情不少优先级太高容易卡住其他关键任务。第六步生成代码。生成之前再看一眼Project Manager确保Toolchain选对了我一般用MDK-ARM V5。生成之后工程里会出现USB_DEVICE文件夹里面有usbd_cdc.c、usbd_cdc_if.c、usbd_desc.c、usbd_conf.c这些文件后面代码改造主要就动usbd_cdc_if.c。2.4 生成工程后先改的3个地方CubeMX帮你把大部分工作做完了但有三个地方我建议改一下不然后面调试会难受。第一个usbd_cdc_if.c里的接收和发送缓冲区大小。默认的APP_RX_DATA_SIZE和APP_TX_DATA_SIZE都是2048一般够用。如果需要更大的吞吐或者要缓存长数据帧可以加大但要注意内存开销。第二个设备描述符里的字符串。usbd_desc.c里用的是默认的STMicroelectronics字符串建议改成你自己的产品名。USB描述符里的厂商名、产品名、序列号主机端通过注册表缓存如果频繁插拔不同设备容易认错设备改成自己的描述符能避免不少混淆。第三个设备默认打印日志。CubeMX生成的main.c里会有一个printf重定向的日志示例如果你没有接UART这个可以先屏蔽不然板子跑起来会有多余输出干扰串口调试。我通常把USB对应的UserRxBufferFS、UserTxBufferFS当成调试数据的最终载体而不是再走一条外部串口。改这三处不影响USB基本流程但属于“事后再想改就晚”的配置。生成代码之后再回来改描述符要重新生成工程很容易忘了覆盖掉。3. 代码改造把虚拟串口真正跑起来3.1 理解中间件的收发骨架USB CDC中间件的代码结构比较清晰我把几个核心函数列出来大家看代码时知道往哪里改。CDC_Init_FS()设备初始化时调用主要做收发缓冲区的绑定。CDC_DeInit_FS()反初始化一般不用动。CDC_Control_FS()处理CDC控制请求比如设置波特率、设置控制线状态后面做“检测串口打开”会用到。CDC_Receive_FS()接收回调主机发过来的USB包会通过这个回调送上来。CDC_Transmit_FS()发送接口MCU要往主机发数据时调用。CDC_TransmitCplt_FS()发送完成回调一个数据包从端点发送完成后触发。CubeMX默认生成的CDC_Receive_FS是这样的static int8_t CDC_Receive_FS(uint8_t *Buf, uint32_t *Len) { USBD_CDC_SetRxBuffer(hUsbDeviceFS, UserRxBufferFS[0]); USBD_CDC_ReceivePacket(hUsbDeviceFS); return (USBD_OK); }这段代码只是把接收缓冲区和端点重新绑定然后等待下一个USB包但并没有保存数据。如果你什么都不改数据来了就被丢弃。所以第一步就是在这里把数据拷贝到自己的缓冲区里。发送接口的CDC_Transmit_FS也有一个坑如果上一次发送还没完成函数会返回USBD_BUSY。用的时候不能简单地调用完就不管要处理错误返回。3.2 接收回调别丢包的关键写法我的做法是维护一个环形缓冲区USB接收回调把数据往里面塞主循环再取出来处理。这样做的好处是接收回调的耗时非常短USB端点很快就能继续接收下一包不容易因为处理慢导致丢包。环形缓冲区的数据结构我直接用结构体定义#define RING_BUFFER_SIZE 2048 typedef struct { uint8_t buffer[RING_BUFFER_SIZE]; volatile uint16_t head; volatile uint16_t tail; } ring_buffer_t; ring_buffer_t g_rx_ring;写入函数很简单注意头部和尾部指针走到末尾时要回绕uint16_t ring_buffer_write(ring_buffer_t *rb, uint8_t *data, uint16_t len) { uint16_t i; for (i 0; i len; i) { uint16_t next (rb-head 1) % RING_BUFFER_SIZE; if (next rb-tail) { break; } rb-buffer[rb-head] data[i]; rb-head next; } return i; }然后在CDC接收回调里调用static int8_t CDC_Receive_FS(uint8_t *Buf, uint32_t *Len) { ring_buffer_write(g_rx_ring, Buf, *Len); USBD_CDC_SetRxBuffer(hUsbDeviceFS, UserRxBufferFS[0]); USBD_CDC_ReceivePacket(hUsbDeviceFS); return (USBD_OK); }这里有一个非常重要的操作收到数据后必须马上重新调用USBD_CDC_ReceivePacket否则端点只接收一次数据之后主机的数据就进不来了。CubeMX默认生成的代码里已经带了这一步你只要保证从Buf里取数据足够快就行。接收回调是在USB中断上下文里执行的尽量不要在里面做耗时操作比如解析协议、写Flash、打印日志这些全部丢到主循环里去处理。3.3 发送接口主动上报数据的正确姿势向PC发送数据用的是CDC_Transmit_FS。它的原型是uint8_t CDC_Transmit_FS(uint8_t *Buf, uint16_t Len);返回USBD_OK表示发送成功返回USBD_BUSY表示上一次发送还没完成。我最初没管这个返回值日志一多数据就莫名其妙丢了后来才发现是发送状态没用对。正确的写法是封装一层uint8_t vcp_send_data(uint8_t *data, uint16_t len) { uint32_t timeout 100000; while (CDC_Transmit_FS(data, len) USBD_BUSY) { if (--timeout 0) { return 1; } } return 0; }这里轮询一下发送状态等USB发送完成回调把状态清掉再往外发下一包。如果数据量大建议在发送完成回调里加一个标志volatile uint8_t g_tx_complete 1; static int8_t CDC_TransmitCplt_FS(uint8_t *Buf, uint32_t *Len, uint8_t epnum) { g_tx_complete 1; return (USBD_OK); }发送前清标志发送完成后置位主循环里判断标志再继续。这种方式比死等外设状态要自然也不会阻塞主循环。还要注意一点CDC_Transmit_FS传入的Buf指针在发送完成前不能被改写。如果你要发送的数据在临时数组里函数返回后立刻修改临时数组下一个内容可能把还没发出去的数据改掉。稳妥起见要么等待发送完成要么用双缓冲轮流切换。3.4 一个简单的回环测试程序刚把工程生成出来我习惯先做一个回环测试验证USB基础链路通不通。回环测试没有任何协议上位机发什么单片机原样返回什么逻辑最简单。主循环代码int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USB_DEVICE_Init(); while (1) { uint8_t buf[64]; uint16_t n ring_buffer_read(g_rx_ring, buf, sizeof(buf)); if (n 0) { vcp_send_data(buf, n); } } }环形缓冲区读出来多少就发多少。如果上位机发一串“hello”收到的回显也是“hello”说明USB枚举、端点收发、中断回调全部正常。这一步跑通之后再往里面加自己的协议比如帧头帧尾校验、AT指令解析、日志分级输出会从容很多。4. 上位机联调从枚举到数据互通的完整路径4.1 驱动与设备识别把烧录好固件的F407插到电脑USB口正常情况下设备管理器里会多出一个“COM和LPT”分类里面出现一个COM口名字可能是“STMicroelectronics Virtual COM Port”或者你自定义的Product String。Windows 10和Windows 11系统自带CDC ACM驱动插上就能识别基本不用手动装。Windows 7未必自带可能要装ST官方发布的VCP驱动也可以下载STM32Cube包里的驱动目录。Linux下更简单插上之后会出现/dev/ttyACM0这样的设备节点直接用串口工具访问即可。macOS也是类似设备节点通常是/dev/tty.usbmodemXXXX。如果设备管理器里显示的是“Unknown Device”说明枚举过程失败和驱动没关系先回硬件和时钟那一步查。4.2 串口助手与Python验证回环测试用串口助手就行。打开串口助手选择对应的COM口波特率随便设置因为CDC虚拟串口不走物理UART波特率参数在中间件里默认不生效。发送“hello”看到同样的“hello”回来链路就通了。这里有个迷惑点有人担心波特率设置不对会影响通信实际上USB CDC虚拟串口的波特率只是一个“控制参数”主机把它下发给设备设备想用就用不想用可以忽略。默认固件不处理所以任意波特率都能收发。如果做自动化测试我用Python的pyserial库比较多。回环测试脚本可以这样写import serial ser serial.Serial(COM12, 115200, timeout1) payload bhello usb cdc\r\n ser.write(payload) for _ in range(10): data ser.read(64) if data: print(data) break如果单片机能回显Python这边能打印出同样的内容。做压力测试时可以连续写几千帧数据再统计回显数量判断丢包情况。4.3 上下位机通信的注意点虚拟串口虽然使用体验和串口一致但它本质是USB批量传输和物理UART有几点差异容易踩坑。第一个要注意的是包边界。UART串口是字节流驱动层会把多个字节拼起来发出去接收端看到的是连续字节。USB CDC是包传输一次发送可能被拆成一个或多个USB包一次接收回调拿到的数据长度也未必等于发送长度。所以上位机和下位机通信一定要有协议边界比如帧头帧尾、长度字段不能简单依赖“每次都收完整的一帧”。第二个是时序。USB枚举和驱动加载需要时间单片机刚上电就立刻往上位机发数据可能此时虚拟串口还没建立好数据就丢了。调试阶段可以让设备等待主机打开串口再发数据后面会提到怎么检测串口打开事件。第三个是打开关闭状态。上位机关闭串口后USB CDC设备端点仍然存在但上位机不会再读数据。如果下位机一直往上发数据会堆积在USB驱动缓冲区甚至导致发送超时。很多调试工具会做成“串口打开后设备才开始上报”。我在做项目时一般把上位机、下位机、协议三者的关系理清楚后再写正式业务逻辑。虚拟串口只是一个透明的通道通道两端怎么解析还是靠应用层约定。5. 踩坑复盘常见问题与排查经验5.1 枚举失败、Unknown Device、无COM口我把自己在调试中遇到的典型问题整理成了一张表方便排查时对照。现象可能原因排查方向插上USB后无任何反应PA11/PA12接反或没接好检查DP/DM接线设备管理器出现Unknown DeviceVBUS检测有问题检查PA9是否接VBUSUnknown Device且设备反复枚举断开USB供电不足换USB口、换线、用独立供电枚举成功但无COM口系统驱动缺失手动安装CDC ACM驱动枚举成功但收发完全不正常USB时钟不是48MHz检查PLLQ分频参数VBUS检测这个坑我印象太深了。最开始自己画的板子插上电脑就是“Unknown Device”一点反应都没有。后来仔细查了电路发现PA9悬空没有接VBUS。HAL库里的vbus_sensing_enable默认是ENABLE控制器会检测VBUS电压。把PA9接到USB座的5V之后设备立马就被识别了。如果你不想接PA9也可以在usbd_conf.c里把这段初始化改掉hpcd.Init.vbus_sensing_enable DISABLE;改掉之后控制器不再检测VBUS只要USB插入内部就认为有效连接。这个做法在正式产品里我没直接用开发调试阶段倒是能救命。注意重新生成工程时这个文件会被覆盖要记得备份或者记录修改点。USB线也要注意。有些线只支持充电没有数据线芯插上设备自然识别不了。我调试遇到过好几次换了根数据线就好了这种问题花费时间最多却和固件一点关系都没有。5.2 收发异常和丢包设备枚举成功、串口也能打开但数据收发不稳定一般有几种原因。第一没有重新调用USBD_CDC_ReceivePacket导致只收一包后就再也不接收。这是新手最容易犯的错误在CDC_Receive_FS里处理完数据后必须再次调用。第二接收回调里处理耗时太长。USB中断优先级下回调处理时间过长会影响后续数据接收和主机通信。解决方法是把数据快速拷到环形缓冲区放到主循环处理。第三发送缓冲区处理不当。CDC_Transmit_FS传入的Buf必须保持有效直到发送完成。我看到有人用一个全局数组每次发送前往里面填数据但发送还没完成就填下一个数据最后发出去的内容是乱的。第四上位机读取不及时。当数据量较大上位机串口工具读数据不够快时操作系统USB驱动缓冲区会溢出造成数据丢失。这个问题不能只靠下位机重发上位机侧也要提高读取频率或者用批量读取的线程。丢包压力测试时我常用的方式是把上位机发送缓存调到最大然后循环发10万帧统计回显丢失率。正常情况下TCP/IP都不保证不丢虚拟串口本地USB通信的丢包率应该很低。如果丢包率超过千分之一优先怀疑上述四点。5.3 中断优先级、堆栈和性能优化USB中间件对中断优先级比较敏感。CubeMX默认把OTG_FS_IRQHandler中断优先级设成5或6这通常没问题。但如果你用FreeRTOS就要注意中断优先级不能高于FreeRTOS配置的LIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY否则在中断里调用USB相关函数会触发断言。堆栈大小也是容易踩的坑。USB中间件使用了不少局部变量如果任务栈开太小跑着跑着就会进HardFault。使用FreeRTOS时创建USB处理任务建议给到512字2048字节以上如果用到printf这类会膨胀栈的函数还要再加大。性能方面USB CDC全速设备理论带宽约1MB/s左右实测稳定吞吐一般在几十KB/s到几百KB/s。如果需要更高吞吐可以考虑把F407的HS控制器配合外接ULPI PHY跑但电路复杂度会上来不少。我已经把F407的USB OTG FS跑到了稳定300KB/s左右这对大部分调试、日志传输、固件升级场景足够了。还有一个优化点如果你只是用CDC传输日志不需要上位机发送数据可以在接收回调里只重新挂载接收不去处理外部数据。这样能减少主循环负担也能让USB吞吐更稳定。5.4 给后续项目的一些扩展思路USB CDC虚拟串口跑通之后能做的东西就很多了。我建议下一步做“串口打开检测”。CDC控制请求里有一个SET_CONTROL_LINE_STATE命令上位机打开串口时会把DTR信号置位。在CDC_Control_FS里拦截这个请求设备就知道“上位机已经打开串口了”可以开始上报数据上位机关闭串口时设备也能感知自动停止上报。这个功能对做低功耗设备特别重要。再往后可以做USB转网口的简化版CDC里有ECM/NCM子类F407在STM32CubeMX里也可以配置。不过要对USB协议栈有更深的理解建议先把CDC ACM玩透。如果你想把这个虚拟串口做成一个真正的产品级调试口我建议设计一个简单的帧协议比如用0xAA 0x55开头加2字节长度和CRC32校验上位机用Python脚本解析。有了这个基础后面接4G模组、OTA升级、上位机GUI都能顺理成章复用。最后分享一个我实际调试中养成的习惯先开一个简单的回环测试用例每次验证USB改动都用它做“回归测试”。不管后面加了多少功能这个最小用例永远保留拔插一次USB口发一段数据看是否原样返回。只要它能过USB底层链路就是健康的排查问题的时候能过滤掉一大半干扰项。