做嵌入式开发的人十有八九都被串口调试折腾过。前阵子调一块STM32F407板子需要和PC上位机联调手边偏偏没有USB转TTL翻了半天抽屉只找到一根Type-C数据线。正犯愁的时候突然想起来F407自带USB OTG外设完全可以用USB CDC类把它变成一个虚拟串口PC端直接识别成一个COM口连外部转换芯片都省了。这个方案在STM32F407上非常实用尤其是做日志输出、参数配置、上位机通信这类场景。本文把从CubeMX配置时钟树到代码层面实现收发、再到典型坑位排查的完整过程记录下来按这个思路走你也能在半小时内让F407和电脑说上话。1. 为什么非用USB CDC不可虚拟串口相对传统USART的优点很多人在F407上做通信第一反应永远是USART加一颗USB转TTL芯片比如CH340或者CP2102。这个方案确实成熟但在实际项目中会遇到不少让人头疼的情况。1.1 传统USART方案的三个痛点首先是波特率误差问题。USART通信时收发双方的波特率必须一致。如果外部晶振精度不够或者固件里算错了分频系数波特率一高就会出现乱码。16MHz和8MHz晶振的系统我都遇到过有些板子为了省成本用的晶振误差达到±0.5%115200波特率下偶尔就会蹦出一个错字节。其次是硬件接线问题。USB转TTL模块的TXD要接板子的RXD模块的RXD接板子的TXD再加上共地。很多新手在这里翻车TXD和RXD接反的比比皆是。更麻烦的是有些模块是3.3V电平有些是5V电平接错直接烧引脚。第三个痛点是驱动问题。CH340在Windows 10以下版本还得手动装驱动CP2102也有类似问题。到了Linux或者Mac环境驱动兼容性更是随缘。如果换一台电脑就要重新装一次驱动现场调试的体验相当糟糕。1.2 USB CDC虚拟串口的实际体验用USB CDC方案后上面的这些问题基本都消失了。USB CDC在PC端呈现为一个标准串口设备Windows 10以及更新的系统直接免驱动插上就能在设备管理器里看到一个新的COM口。Linux下则显示为/dev/ttyACM0。不需要关心波特率因为虚拟串口的波特率只是个记录值物理层不参与上位机设置多少都不会影响数据传输的准确性。从带宽角度看F407的USB OTG FS全速模式理论速率12Mbps虽然比不上USB HS的480Mbps但实际有效吞吐跑到1MB/s左右没有问题。这个数字是普通USART完全无法比的就算用USART的最快分频通常也就几Mbps而且高速USART布线要求也高。1.3 先泼一盆冷水F407的USB控制器速度等级这里要先说清楚一个容易被标题党带偏的点。STM32F407一共有两个USB控制器一个是USB OTG FS一个是USB OTG HS。FS模式内置PHY直接用PA11和PA12两根引脚就能工作速度是12Mbps全速。HS模式虽然标称480Mbps但STM32F407内部没有集成高速PHY必须外接USB3300或者USB3320这类ULPI接口的高速PHY芯片这就增加了硬件成本和布线复杂度。所以绝大多数开发板上实现USB虚拟串口用的都是USB OTG FS全速模式。千万不要以为看到芯片型号带个F407就能跑到480Mbps实际项目中把FS跑满已经够用。2. 硬件准备与CubeMX配置时钟树和USB外设的每一个细节从零开始构建虚拟串口第一步是在STM32CubeMX里把工程配置好。这个过程看着简单但里面的细节能卡住不少人。2.1 硬件基础板载USB口和引脚F407的USB OTG FS使用PA11作为DM负信号PA12作为DP正信号。这里的DM和DP就是USB协议中的差分数据线电脑主板上的USB座子也要对应的D-和D。全速USB设备需要在DP线上接一个1.5kΩ上拉电阻让主机识别出这是一台全速设备。这个上拉电阻在F407内置PHY中已经集成在芯片内部不需要外部额外添加。不过实际画板时还是需要注意PA11和PA12这两根线的布线要尽量短做等长差分走线减少信号反射。我之前用过一块核心板厂家把USB座子放在了板边走线很短通信非常稳定另一块转接板走线绕了一大圈设备偶尔就会枚举失败。USB的电源也很关键。如果板子完全由USB口供电要确保整个系统的电流消耗不超过500mA。F407全速运行加外设的时候电流可能到200-300mA通常没有问题。但如果板上还带着电机、大功率LED这些负载就建议用外部电源供电否则USB口电压跌落会导致设备反复掉线。2.2 CubeMX时钟树配置USB必须吃精确的48MHz这是整个配置过程中最容易出错的地方。USB OTG FS的PHY需要48MHz的时钟这个48MHz必须精确允许的误差范围通常在±0.25%以内。时钟频率不对最典型的症状就是设备管理器里反复提示无法识别的USB设备。在CubeMX中的RCC配置里把HSE外部高速晶振选为Crystal/Ceramic Resonator。假设板载晶振是8MHz可以通过下面的参数配出系统时钟168MHz和USB时钟48MHzHSE8MHzPLL M48MHz ÷ 4 2MHzPLL N1682MHz × 168 336MHzPLL P2336MHz ÷ 2 168MHz系统主频PLL Q7336MHz ÷ 7 48MHzUSB时钟注意PLL Q就是专门给USB和SDIO这些外设用的输出。CubeMX的Clock Configuration页面里能看到一个USB的时钟树分支必须保证这个分支最终显示为48.0MHz。如果改成别的值比如PLL M8、N336、P2、Q7虽然也是168MHz主频但USB时钟会变成96MHz超出了USB PHY允许的范围。这里分享一下我个人踩过的一次坑。当时手里有一块板子用的12MHz晶振我按习惯配了一套参数主频倒是正常到了168MHz但忘了检查USB时钟树结果插上电脑后设备一直无法识别。后来重新配成M6、N168、P2、Q7终于看到12MHz ÷ 6 2MHz2MHz × 168 336MHz336MHz ÷ 7 48MHzUSB设备才正常出现。所以每次配置完时钟树一定要回头确认USB Clock下面的数值是48MHz而不是看主频正常就觉得万事大吉。2.3 CubeMX的USB外设配置Device Only与Virtual Port Com在左侧Categories里找到Connectivity然后选择USB_OTG_FS。首先要确认Mode选项这里选Device Only。另外一个选项是Host Only用于U盘、键盘这类外设做虚拟串口不需要。还有一个HNP支持之类的高级选项用默认值就行。接着在Middleware里选中USB_DEVICE这一项在左侧的Middleware and Software Packs分类下面。在Class for FS IP下拉菜单中选择Communication Device Class (Virtual Port Com)也就是CDC虚拟串口。CubeMX实际上把CDC大类里的抽象控制模型ACM虚拟串口子类直接封装成了一个选项选它就行。USB_DEVICE配置界面里面还有一个USB_Device库版本选项其实是HAL库的版本选择不用管。还有一个重要的参数是VDDA电压这个只在特定情况下需要关注一般设3.3V即可。到这里CubeMX配置就算完成了。点击GENERATE CODE生成代码前还可以去Project Manager设置一下工具链和堆栈大小。建议把最小堆栈大小增加到0x400以上因为USB库和CDC缓冲区都要占用不少栈空间默认值偏小的话调试时容易出现莫名的HardFault。2.4 生成代码后的关键文件结构生成之后的工程里有几个文件需要重点认识usbd_cdc_if.cCDC类的用户接口文件最需要经常改的就是这个usbd_cdc.cCDC类核心驱动一般不用动usbd_conf.cUSB设备底层配置包括缓冲区内存管理usb_device.cUSB设备初始化的总入口usbd_desc.cUSB描述符定义包含VID、PID、字符串描述符上面这些文件构成了完整的USB协议栈。CubeMX生成的是ST官方的USB Device库代码结构成熟稳定性有保障。作为应用开发者我们主要跟usbd_cdc_if.c打交道这个文件里的函数分别是数据收发的回调接口和发送接口后面的代码实战也是围绕它展开。3. USB枚举与CDC描述符PC是怎么把单片机认成串口的第一次插上F407组成的USB设备时电脑设备管理器里可能先是闪一下正在安装设备驱动程序然后出现一个COM端口节点下的新串口。这个过程背后是USB协议栈里一套完整的枚举流程理解了枚举过程后面排查各种识别不了的问题会轻松很多。3.1 枚举流程中发生了什么USB主机对设备的识别并不是设备插上就自动完成的而是经过一个标准的问答过程设备插入后主机检测到DP引脚被拉高判断有全速设备连接主机向地址0发送获取设备描述符请求设备返回自己的基本信息主机会为设备分配一个唯一的地址主机重新获取设备描述符和配置描述符主机发送设置配置请求设备开始正常工作在枚举过程中主机访问设备是分步骤进行的。每一步都在USB总线上产生实际的数据交换可以用USBLyzer或者Wireshark这类USB抓包工具看到完整过程。如果设备在枚举中间阶段没有正确返回数据主机就会显示无法识别的USB设备。3.2 CDC类的双接口结构与端点分配USB CDC设备在描述符层面的设计和HID或者Mass Storage类设备不太一样。一个CDC虚拟串口设备实际上由两个接口组成接口0通信控制接口Communication Interface负责管理和控制例如设置波特率、控制RTS/DTR信号接口1数据接口Data Interface负责实际的数据收发这种结构叫接口关联描述符IAD让主机明白这两个接口属于同一个设备功能。实际操作中我们不需要手动在CubeMX里搭建这些描述符ST的USB设备库已经预先定义好了。F407的USB OTG FS控制器为CDC设备分配了默认的端点结构端点方向用途传输类型EP0双向控制传输枚举和类请求控制传输EP1 IN设备到主机数据发送批量传输EP1 OUT主机到设备数据接收批量传输EP2 IN设备到主机通知消息如串口状态变化中断传输EP0是所有USB设备必备的枚举阶段的交互全靠它。EP1 IN和EP1 OUT是数据通道用于用户数据的传输通常大块的数据流都走这里。EP2 IN是一个额外的通知端点用来发送UART状态变化这类信息比如DCD信号变化、break信号等实际项目中不太常用。3.3 打开串口时发生了哪些主机请求当PC端串口助手打开这个虚拟串口时主机会发送一系列CDC类请求这些请求在USB规范里是标准命令SET_LINE_CODING设置波特率、停止位、数据位和校验位SET_CONTROL_LINE_STATE设置RTS和DTR信号线的状态特别要强调的是SET_LINE_CODING里的波特率参数对USB CDC虚拟串口来说只是一个记录值。设备端的MCU可以读取这个值但是不会像硬件USART那样真正用这个波特率去收发数据。USB CDC的数据传输底层是USB批量传输跟波特率没有半毛钱关系全速USB的速率是固定的12Mbps。所以无论串口助手里设置的是9600还是921600虚拟串口的实际传输能力都一样这个波特率更多是为了兼容老的串口应用程序。4. 从生成代码到第一次收发回环例程与缓冲设计CubeMX生成的工程默认只能被PC识别为串口设备但还没有任何实际的数据收发功能。要让设备真正能通信需要用户自己在usbd_cdc_if.c里补充收发逻辑。4.1 认识CDC_Transmit_FS和CDC_Receive_FSusbd_cdc_if.c中有两个核心函数一个是数据发送函数CDC_Transmit_FS另一个是数据接收回调函数CDC_Receive_FS。发送函数原型如下uint8_t CDC_Transmit_FS(uint8_t* Buf, uint16_t Len)调用这个函数设备就会把Buf里的Len个字节通过EP1 IN端点发送给PC端。注意这个函数只是把数据交给USB外设发送并不代表PC端已经收到了数据。USB库会管理端点缓冲区数据进入缓冲区后就可以继续做别的事情。接收回调函数原型如下static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len)这个函数是当PC发数据给设备时由USB中断自动调用的。参数Buf指向USB接收缓冲区Len是收到的字节数。这个回调函数运行在USB中断上下文里所以里面的处理逻辑要尽量轻量千万不要在这个函数里做耗时操作更不能调用HAL_Delay这类阻塞函数。4.2 最小可用的回环逻辑直接改usbd_cdc_if.c文件在接收回调里把收到的数据原样送回去就能实现一个最简单的回声功能static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len) { // 把收到的数据原样发送回PC CDC_Transmit_FS(Buf, *Len); // 重新启动下一次接收 USBD_CDC_SetRxBuffer(hUsbDeviceFS, Buf); USBD_CDC_ReceivePacket(hUsbDeviceFS); return (USBD_OK); }上面代码的最后两行特别关键第一次写这个程序的人很容易漏掉。USB设备的接收缓冲区是一次性的接收到一次数据后如果不重新调用USBD_CDC_SetRxBuffer和USBD_CDC_ReceivePacket那么下一次PC发来的数据就不会再触发这个回调了。表现就是第一次通信正常后面就再无响应。4.3 一个稍微实用一点的收发缓冲设计直接回环对实际项目价值不大更多场景是PC发指令给设备设备解析后执行操作再返回状态。这时候需要设计一个接收缓冲队列。在usbd_cdc_if.c中定义两个数组形成双缓冲static uint8_t UserRxBufferFS[2048]; static uint8_t UserRxBuffer2FS[2048]; static volatile uint8_t currentRxBuffer 0; static volatile uint16_t rxDataLen 0;在初始化和接收回调中交替使用两个缓冲区void cdc_init(void) { USBD_CDC_SetRxBuffer(hUsbDeviceFS, UserRxBufferFS); USBD_CDC_ReceivePacket(hUsbDeviceFS); } static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len) { if (Buf UserRxBufferFS) { currentRxBuffer 0; } else if (Buf UserRxBuffer2FS) { currentRxBuffer 1; } rxDataLen *Len; // 切换到另一个缓冲区并重新启动接收 uint8_t* nextBuf (Buf UserRxBufferFS) ? UserRxBuffer2FS : UserRxBufferFS; USBD_CDC_SetRxBuffer(hUsbDeviceFS, nextBuf); USBD_CDC_ReceivePacket(hUsbDeviceFS); // 设置标志位通知主循环处理数据 dataReady 1; return (USBD_OK); }然后在主循环中检查dataReady标志位从对应的缓冲区解析数据。这种双缓冲的好处是在中断回调里只做指针切换把实际的数据解析工作放到主循环里避免中断处理时间过长导致的USB数据丢失。4.4 一个完整的收发测试流程在main.c主循环中可以做一个简单的交互测试。当收到PC发来的字符串LED_ON时点亮板载LED并回复LED已打开当收到LED_OFF时熄灭LED并回复LED已关闭。先定义一个函数从接收缓冲区解析命令行void process_command(uint8_t* buf, uint32_t len) { if (len 6 memcmp(buf, LED_ON, 6) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); CDC_Transmit_FS((uint8_t*)LED ON\r\n, 9); } else if (len 7 memcmp(buf, LED_OFF, 7) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); CDC_Transmit_FS((uint8_t*)LED OFF\r\n, 10); } }主循环里查询数据就绪标志while (1) { if (dataReady) { process_command(currentBuf, rxDataLen); dataReady 0; } }到这里一个基本的虚拟串口通信系统就已经能跑起来了。用电脑端的串口助手打开对应的COM口发送LED_ON命令板载LED会点亮同时返回文本信息。5. 实战踩坑记录设备无法识别、驱动报错、收发异常的排查链路这一节的内容全部来自真实调试中踩过的坑按排查链路写下来以后遇到类似问题可以直接对照着查。5.1 PC端无法识别USB设备的排查链路设备插上后没有任何反应或者设备管理器里反复出现无法识别的USB设备设备描述符请求失败这是最常见的故障。我建议按下面的顺序排查第一步检查USB时钟。用示波器测量板上晶振引脚确认晶振起振且频率正确。然后再通过一个GPIO输出一个已知频率的方波验证主频是否正常或者直接在调试器里查看System Clock的值是否等于168MHz。重点检查CubeMX时钟树页面里的USB Clock分支是否精确为48MHz。第二步检查USB外设是否使能。在初始化代码中确认MX_USB_DEVICE_Init函数被正确调用。这个函数内部执行USBD_Init、USBD_RegisterClass、USBD_CDC_RegisterInterface和USBD_Start任何一个环节异常都会导致枚举失败。第三步检查供电。用万用表测USB口的VBUS电压应该稳定在5V左右。同时测DPA12引脚当设备连接电脑后D上应该被上拉到约3.3V。如果D电压只有0V说明设备没有正常宣告自己是全速设备问题大概率出在PHY或者时钟。第四步用USB抓包工具看枚举过程。USBLyzer这种工具可以捕获主机和设备之间的全部USB总线数据。如果能看到主机发GET_DESCRIPTOR请求但设备没有响应基本可以确定是设备端的问题如果连请求都发不出去那问题在主机USB端口或者线缆上。这里分享一个具体案例。我曾经用过一根只有充电功能、没有数据线的USB线设备插上后完全没反应一开始还以为是硬件问题排查了好半天。换了一根标准数据线后设备立刻被识别。USB线材质量对全速设备的影响很大劣质线材会衰减差分信号导致枚举失败。5.2 设备识别了但驱动安装失败的排查链路如果设备管理器里看到的是一个带黄色感叹号的未知设备说明枚举成功但主机不知道该用哪个驱动来加载它。Windows 10和Windows 11系统通常自带usbser.sys驱动能够识别CDC类设备并自动创建COM口。如果提示驱动安装失败可以尝试手动指定驱动。打开设备管理器右键点击带感叹号的设备选择更新驱动程序→浏览我的电脑以查找驱动程序→让我从计算机上的可用驱动程序列表中选取然后在设备类别列表中选择端口COM和LPT。Windows会列出可用驱动选USB 串行设备即可。还有一种情况是之前安装过别的虚拟串口驱动留下了缓存冲突。这时候需要先在设备管理器中彻底卸载设备勾选删除此设备的驱动程序软件然后重新插拔USB线让系统重新枚举。5.3 数据只能收一次或者彻底收不到这个问题的根源九成是出在CDC_Receive_FS回调函数里忘记重新启动接收。ST的USB库设计是接收回调触发一次后USB外设就处于等待状态不会再自动接收新数据必须由软件再次调用USBD_CDC_ReceivePacket。另一个常见原因是接收回调里处理时间过长。USB全速模式下每帧时间是1ms端点缓冲区只有64字节。如果回调里做了太耗时的事情比如调用printf输出到硬件USART、执行HAL_Delay就会导致数据来不及取走缓冲区被覆盖表现出来就是收到的数据是乱码或者丢字节。正确的姿势是在接收回调里只做缓冲区切换和数据就绪标志置位数据处理全部放到主循环。如果数据量大考虑用前面介绍的双缓冲甚至环形缓冲结构。另外注意USBD_CDC_SetRxBuffer传入的缓冲区地址在USB外设传输期间不能被其他代码修改。如果使用了双缓冲两个缓冲区在交替使用时要确保主循环不会同时访问正在被USB写入的那个缓冲区。这需要配合标志位和适当的临界区保护。5.4 串口助手能打开但收发乱码虚拟串口的物理链路是USB不存在波特率不匹配的问题。如果出现乱码通常是发送和接收的缓冲区管理出了问题。一种情况是发送函数返回了USBD_BUSY说明上一次发送还没完成又有新数据要发送。因为EP1 IN只有一个缓冲区上一包数据没发完就调用CDC_Transmit_FS函数会直接返回失败数据丢失。解决方法是增加一个发送队列或者在发送之前检查返回值。发送数据量比较大时拆分成小块等上一包发送完成后再发下一包。这里可以简单使用HAL库提供的外设状态机制在应用层维护一个发送忙标志。还有一种情况是接收缓冲区的长度和实际数据长度不匹配。USB接收回调的Len参数是本次接收的实际字节数如果代码里硬编码了某个固定长度去解析就会解析错位。建议以Len为解析依据。6. 提升虚拟串口的传输效率带宽上限与批量传输优化CDC虚拟串口跑通之后很多人会开始关注它的传输极限。能不能直接拿它传固件能不能做实时波形传输这些问题都需要先弄清楚USB全速模式下的带宽限制。6.1 USB全速模式的带宽墙在哪USB全速模式把时间分成1ms一帧每一帧内可以安排多个事务传输。对于批量传输端点每帧最多可以安排19个批量事务每个全速批量事务最大64字节。于是理论上限是19个事务 × 64字节 × 1000帧/秒 1,216,000字节/秒换算下来约为1.2MB/s。这个数值就是F407内置USB PHY在CDC数据传输中能达到的理论上限。实际测试中加上协议开销、帧间隔和控制传输的占用稳定跑到800KB/s到1MB/s已经算不错了。如果是USB高速模式理论上限会高得多。但正如前面说的F407的HS必须外接高速PHY芯片成本增加不少一般情况下用不到。6.2 大批量数据发送的策略传输大量数据时如果直接把整个数据块一次性交给CDC_Transmit_FS函数会因为端点缓冲区容量有限而返回失败。推荐的策略是分块发送。块大小可以选择64字节的整数倍比如512字节或者1024字节。在发送循环中调用CDC_Transmit_FS检查返回值如果返回USBD_BUSY就稍等片刻再重发。这个逻辑可以封装成void cdc_send_buffer(uint8_t* data, uint32_t len) { uint32_t offset 0; while (offset len) { uint32_t chunk (len - offset 512) ? 512 : (len - offset); uint8_t ret CDC_Transmit_FS(data offset, chunk); if (ret USBD_OK) { offset chunk; } // 返回USBD_BUSY时自动重试等待端点释放 } }需要注意的是这个发送循环会在发送大量数据时阻塞主循环。如果系统还要响应其他任务最好把发送放到一个带超时机制的队列里而不是在主循环里死等。接收方向也是如此。数据到达时会触发回调如果数据量很大USB库的缓冲区会很快写满。双缓冲设计在这里能有效降低丢包概率但仍然有上限。真正要求不丢数据的场景建议在PC端和MCU端都做协议层的确认重传机制。6.3 常用调试工具与流程调试USB CDC虚拟串口工具用对了能省一半时间。首先是串口调试助手推荐用支持十六进制收发和文本同时显示的软件方便观察ASCII指令和二进制数据。打开串口时选择正确的COM口号波特率随便设置因为虚拟串口不关心波特率。其次建议准备一个USB抓包工具比如USBLyzer它可以显示完整的USB枚举过程和数据传输。设备无法识别时抓包能准确告诉你设备卡在了枚举的哪一步是设备描述符没响应还是配置描述符出错。Windows下还可以用Wireshark配合USBPcap驱动来抓USB流量。硬件方面有条件的话备一个USB电流监测器也很有用。每次设备掉线时看一眼电流曲线就能判断是不是供电不足导致的问题。一个实际操作中非常管用的技巧是在代码里暴露一个调试用端点。比如定义一个测试指令当PC发来VER时设备返回固件版本号和USB状态信息包括当前端点缓冲区使用情况、接收计数、发送失败计数等。这样通过串口助手就能快速掌握设备内部状态不用每次都接调试器。7. 从虚拟串口到实际项目我的一些选型建议最后分享一些个人在实际项目里积累的经验算不上什么高深理论但很实用。第一个建议是在F407项目里默认把USB CDC作为调试日志通道。相比硬件USART接USB转TTLUSB CDC省去了外部芯片、省去了波特率配置、还省了一个UART外设。库里的printf重定向到CDC_Transmit_FS后日志输出速度飞快哪怕每毫秒打一条都不会拖慢系统。第二个建议是应用层协议尽量设计成小包多次。USB批量传输最小单位是事务每个事务最多64字节所以一个包在63字节以内是最高效的。如果协议设计成大包底层会自动分包处理但应用层等待和组包逻辑会增加复杂度也会牺牲一部分实时性。第三个建议是把接收数据放到专用的Ring Buffer里。USB尾数中断回调里只做写入主循环做消费两端通过读写指针配合这样既不需要在中断里做耗时解析也不用担心双缓冲切换时的临界区问题。STM32F407的USB CDC虚拟串口做下来除了功能本身更重要的是理解了USB枚举、端点和批量传输这套机制。这些东西在后续做USB HID、USB Mass Storage、USB复合设备时都是通用的底子。以F407的USB库为基础扩展出自定义USB设备也没有想象中那么难。希望这篇整理对你有所帮助。
