最近做固件升级工具遇到一个硬需求：设备通过USB连电脑后，既要枚举出一个虚拟串口用来输出运行日志，又要枚举出一个U盘，用户把升级包拖进去就自动开始烧录。最初我想的是直接上两颗USB芯片，后来冷静下来一算，STM32自带的USB口本身就支持把多个功能组合成复合设备。配合Azure RTOS里面的USBX设备栈，我在一颗STM32F407上实现了CDC虚拟串口加MSC大容量存储的composite class，一个USB物理端口同时承担调试和升级两件事，电脑端看到的是一台复合设备，下面挂着两个功能节点。
这篇文章把从协议原理、CubeMX配置到代码调试的完整过程整理出来，供所有打算做同类USB复合设备的工程朋友参考。如果你已经在裸机上调过USB鼠标键盘，或者用HAL库调过虚拟串口，读起来会非常顺；如果完全没接触过USB协议，我也尽量把概念讲浅，重点放在“为什么这么改”和“踩到坑怎么查”上。
1. 复合类到底是什么：一个USB设备如何“分裂”成两个外设
1.1 从USB协议视角看设备、配置、接口、端点
实现之前，我建议先把这个概念在脑子里摆正。USB设备端的逻辑层次从高到低是：设备、配置、接口、端点。一个物理USB设备只有一个设备描述符，它说明厂商ID、产品ID、设备版本等信息。设备描述符下面可以有多个配置描述符，但大多数设备只实现一个配置。每个配置里包含若干个接口描述符，接口才是主机端类驱动真正识别的单位。接口下面有端点，端点是实际收发数据的通道。
普通单功能设备，比如一个简单的CDC虚拟串口，配置里只包含和串口功能相关的两个接口：一个通信接口和一个数据接口。这两个接口在逻辑上是一套，主机驱动通过接口关联把它们组合成一个串口节点。复合设备则不同，它会在同一个配置描述符里同时塞入多个独立功能的接口集合。主机端枚举时先读到设备描述符，再读配置描述符，当发现配置里有多个不同功能的接口时，就会把整体识别为“USB composite device”，随后把每个功能分离成对应的子设备。
这个逻辑层级是最重要的地基。后面改描述符遇到的所有问题，几乎都能归到三件事：接口数量不对、接口顺序不对、端点地址冲突。
1.2 复合设备与普通多接口设备的区别
很多人会把“一个配置里有很多接口”和“复合设备”直接画等号，实际上要分情况。有些设备一个配置里确实有多个接口，但这些接口属于同一个功能。CDC就是典型，它必须用两个接口才能模拟出完整串口，这叫接口关联，不是复合。
真正的复合设备，组合的是两个或更多互相独立的类功能，每个功能都能被主机端识别成独立设备。常见组合有哪些？我用一个表格梳理：
| 功能组合 | 典型应用场景 | 注意事项 |
|---|---|---|
| CDC + MSC | 调试日志加拖拽升级，量产工装，仪器仪表 | 两个功能都需要占用批量端点，带宽要估算 |
| CDC + HID | 串口配置加键盘鼠标模拟，HID免驱交互 | HID占用中断端点，需要预留调度 |
| MSC + HID | 数据存储加多媒体控制，消费电子外设 | 对设备端驱动能力要求不高，但主机端行为要测透 |
| CDC + MSC + HID | 三合一复杂设备，适合演示和验证极限 | 内存占用和描述符复杂度明显上升，不建议作为起点 |
我实现的是CDC+MSC组合，因为升级工具最需要的就是一个串口交互命令，一个U盘接收固件文件。两个功能在逻辑上完全独立，互相干扰最小，也最适合作为第一次接触复合设备的练手项目。
1.3 为什么偏偏选Azure RTOS里的USBX
裸机写USB Device栈不是不行，但想同时维护多类驱动的枚举状态、端点调度和类回调，工作量会爆表。尤其USB协议里每个类都有独立的请求和状态机，特别是MSC的Bulk-Only传输有CBW、CSW、命令状态三个阶段，写错一个字节就可能在Windows里弹出“此驱动器存在问题”。
Azure RTOS里的USBX设备栈把类驱动做成了可注册的模块。每个类是一个独立实例，有统一的读写接口和IOCTL请求接口。它本身和ThreadX深度绑定，天然支持多线程访问，可以把CDC接收线程和MSC读写线程分开，避免一个功能卡住拖死另一个。再加上STM32CubeMX对Azure RTOS中间件有现成集成，工程生成后初始化框架和描述符文件已经搭好，我们要做的是在框架里补全复合设备逻辑，而不是从零写协议栈。
不过这里要泼一盆冷水：CubeMX能生成“多类”的框架，不等于生成的描述符天生就是正确的复合设备。尤其当你手动增加类、调整端点时，必须打开生成的文件亲手核对字节。后面第三节会详细说。
2. 动手前的先决条件：硬件和中间件的一次“体检”
2.1 选型：哪种STM32适合跑USB复合类
不是所有STM32都带USB外设，带USB外设的型号实现方式也不同。F1/F3系列通常内置USB FS Device，电路上需要外部上拉电阻和精确的48MHz时钟，设计时要多留几个检查点。F4、L4、H7这类带OTG外设的型号更灵活，可以配置成Device Only、Host、OTG等模式，内部有独立的上拉控制，硬件上少一些麻烦。
我用的是STM32F407，外设是OTG_FS，配置为Device Only模式。为什么选它？RAM足够大，跑ThreadX加USBX缓冲绰绰有余；主频高，MSC做固件升级时不会因为CPU处理慢拖累USB吞吐。如果你手头是F1，也不是不能做，但建议把一部分精力放在时钟精度和外部上下拉上，先让裸枚举通过再谈多类。
选型时还要看USB外设和引脚冲突。F4的OTG_FS是PA11作为DM，PA12作为DP。CubeMX里把USB_OTG_FS选成Device_Only之后，引脚会自动复用。如果你在其他功能里占用了PA11/PA12，后面会有严重冲突，必须提前规划。
2.2 时钟、引脚和电源的常见隐患
USB FS要求48MHz时钟，精度不够会导致枚举时断时续。CubeMX在Clock Configuration里会尝试自动配置，但你要亲自确认PLL的USB输出是否为48MHz。比如F407主频168MHz时，PLLQ经常是48MHz，没问题；但如果为了省电把主频调低，USB时钟可能跟着变，这是最容易被忽略的坑。
电源方面，F4系列带USB功能的芯片通常有独立的VDDUSB引脚，有些开发板没有接，或者没有按手册要求接地，会造成设备端完全无法进入枚举。经验是拿到一块新板子，第一件事查VDDUSB和VDDA，确认供电正常，再去看USB信号线上的ESD保护和串联电阻。DM和DP走线要短，尽量等长，串联电阻常用22欧姆，靠近MCU侧放置。
这些看起来低级的硬件条件，恰恰是复合设备调试时最大的隐性风险。软件写得再对，如果硬件在临界状态，枚举可能时好时坏，非常难查。我的建议是在写任何类驱动代码之前，先让USBX不带任何类，裸枚举一次，确认主机能读到厂商ID和产品ID，再继续往下加功能。
2.3 CubeMX里的Azure RTOS中间件版本与配置入口
现在Azure RTOS以Eclipse ThreadX的名义开源，在CubeMX的Software Packs组件管理里可以直接下载。不同CubeMX版本生成的结构略有差异，但核心API名字基本稳定。
进入CubeMX后，在Middleware and Software Packs一栏勾选Azure RTOS，先启用ThreadX，然后启用USBX。USBX的配置界面里有Device和Host两个方向，必须选Device。选择后，可以进一步勾选需要的类，比如CDC ACM、MSC、HID等。这里能多选，说明USBX设计上就是支持多类共存的。
我建议在项目开始前先确认中间件版本。旧版USBX可能缺少一些针对复合设备的修复，如果项目允许，尽量升级到较新的包。另外要提前检查编译选项里是否定义了UX_DEVICE_CLASS_CDC_ACM和UX_DEVICE_CLASS_MSC这类宏，不然即使你在CubeMX勾选了类，预处理阶段也会把相关源码编译掉，回调函数根本进不了工程。
3. CubeMX生成多类USBX工程：从勾选到描述符微调
3.1 开ThreadX和USBX Device，并同时勾选CDC、MSC
具体操作路径是：CubeMX -> Middleware and Software Packs -> Azure RTOS -> ThreadX，启用它；再进入USBX，启用Device。在USBX Device配置页里勾选CDC_ACM和MSC两个类。许多版本的CubeMX在勾选之后还会要求你给每个类设置接口号和属性，保持默认也是一种稳妥选择，但最好理解这些字段的意义。
ThreadX配置里有一个关键参数是内存池大小。USBX依赖ThreadX的内存分配能力，常见做法是在ThreadX配置中预留一个较大的字节池，再把这个池的地址和大小传给USBX。我习惯在tx_user.h或app_threadx.h里定义一个APP_MEM_POOL_SIZE，Windows端至少给16KB以上，如果加入MSC大块读写，建议给到32KB。内存池不够，最典型的现象是两个类同时工作时，某个类突然卡死或设备从总线断开。
完成配置后生成代码。生成的目录里会有一个usbx_device文件夹，里面包含ux_device_descriptors.c、ux_device_initialize.c等文件。先不要急着改，先看一眼初始化函数，确认它调用了USBX的标准初始化步骤，再往下走。
3.2 描述符文件里到底发生了什么
打开ux_device_descriptors.c，你会看到一堆UCHAR device_framework_full_speed[]之类的大数组。USBX不是通过结构体直接操作描述符，而是把描述符作为原始字节数组传给设备栈，因此你必须清楚每个字节的含义。
先做一道加法题：CDC占两个接口，MSC占一个接口，所以配置描述符里的bNumInterfaces必须是3。bNumInterfaces在配置描述符的第5字节（从0开始算第4个字节）位置。如果你打开数组发现这个值仍然是1，说明CubeMX生成的只是单类工程，需要手动修改。
再看接口描述符块。每个接口描述符以0x09开头，表示长度9字节。CDC会依次出现两个接口描述符，第一个是通信接口，类代码bInterfaceClass是0x02，子类0x02，协议0x01；第二个是数据接口，类代码是0x0A。MSC则是一个接口描述符，类代码是0x08，子类0x06，协议0x50。你需要在配置描述符数组里依次找到这三个块，并确认它们按顺序排列。
我遇到过一次非常诡异的问题：接口描述符顺序是CDC通信接口、MSC接口、CDC数据接口。Windows枚举时把MSC独立识别了，CDC却变成未知设备，因为主机找不到配对的通信接口和数据接口。所以描述符里接口顺序和类注册顺序必须一致，最好保持CDC两个接口连续，MSC跟在后面。
3.3 端点冲突和接口编号的修复
复合设备最常见的崩溃级问题就是端点地址重复。USB FS设备单个端点有编号限制，F4的OTG_FS支持多个IN端点和OUT端点，但每个端点地址必须唯一。CDC通常需要一对批量端点和可能的中断端点，MSC也需要一对批量端点。如果CubeMX生成的端点分配有重叠，设备虽然能枚举成功，但传输时会出现STALL或busy。
修改端点前，建议先画一张端点分配表。CDC用端点1做批量IN，端点2做批量OUT，MSC用端点3做批量IN，端点4做批量OUT。这样相对清晰。如果使用中断端点，也要确保地址唯一。在描述符数组里找到对应的bEndpointAddress字节，改成自己想要的地址，同时还要改对应端点描述符里的wMaxPacketSize和bInterval等字段。
为了后续好维护，我把描述符里的长数组拆开来定义：设备描述符一个数组，字符串描述符一个数组，配置描述符用若干个小数组拼接，比如cdc_interface_descriptor[]、msc_interface_descriptor[]、ep_descriptor_in[]等，然后在配置描述符数组里用memcpy组装。代码会多几十行，但出问题排查时能少掉不少头发。
4. 初始化流程和两个类驱动的协同逻辑
4.1 mx_usbx_device_init里发生了什么
CubeMX生成的初始化入口一般是MX_USBX_Device_Init()，它内部通常由几个重要步骤组成：调用ux_system_initialize初始化整个USBX系统，调用ux_device_stack_initialize初始化设备栈，然后逐个注册类。
ux_system_initialize会传入USBX自己的内存池。这一步直接决定复合设备能跑到什么程度。我用的配置是系统池给到24KB，每个类再单独分配缓冲。MSC的传输缓冲至少要能容纳一个或几个扇区，常用512字节*2或者4KB；CDC的环形缓冲给4KB。算下来内存约30KB左右，对F407来说完全够用。如果芯片RAM本来就小，就要仔细权衡两个类的缓冲，宁可把MSC缓冲缩到2KB，也不要让系统池告急。
注册类时，USBX需要传入类初始化函数和类实例。比如CDC注册时用ux_device_class_cdc_acm_initialize，MSC注册时用ux_device_class_storage_initialize。这些函数在CubeMX生成代码里已经自动接好，但你要去看一眼传入的参数有没有问题，比如UX_SLAVE_CLASS_CDC_ACM_PARAMETER里的端点地址是否和描述符一致。
4.2 CDC虚拟串口和MSC存储介质的回调实现要点
CDC这套东西看着简单，实际用起来有几个细节。发送数据前必须确认主机端已经打开了串口，并且DTR/RTS信号有效。否则调用ux_device_class_cdc_acm_write会把数据积压，直到主机端打开端口才发送。我在应用层做了一个环形队列，日志先写进队列，等CDC状态变成ready后再取出发送，这样就不会因为主机状态导致业务线程被阻塞。
接收方向类似。USBX会把主机发来的数据通过类回调送上来，回调里不要做耗时处理。我一般只做数据拷贝，然后丢给一个专门的解析线程做AT指令或协议解析。在回调里直接调用阻塞的写函数是最容易犯的错误，USBX很多接口要求从ThreadX线程上下文调用，而不是中断上下文。
MSC部分的核心是存储介质回调。USBX存储类驱动会调用你实现的读写接口，完成CBW命令解析和CSW状态回复。为了不把Flash底层的磨损均衡逻辑一开始就卷进来，我建议先用一个大数组作为RAM盘测试。把扇区大小设为512字节，容量设为1MB，回调函数里对应的是memcpy操作。RAM盘能正常挂载FAT32，再切换到真实Flash或SD卡驱动，问题定位范围会小很多。
4.3 两个类共享一条USB总线时的缓冲和任务调度
复合设备虽然在主机端拆成了两个节点，但物理上仍然共享同一条USB总线和同一个控制器。MSC做连续大块读写时，会占掉大量批量传输带宽，如果CDC也在往外吐数据，两个类之间就会出现资源竞争。
我的解决办法是给两个类分配不同的传输任务优先级。CDC日志任务优先级高于MSC读写任务，当有串口数据要发时，MSC任务可以让出CPU和总线，保证交互反馈不卡顿。MSC传输的缓冲可以给大一点，例如64KB，让它在一个调度周期里连续搬移更多数据，减少线程切换和总线重协调频率。
还要控制单次发送的尺寸。CDC单次发送不要超过4KB，否则容易挤占MSC带宽；MSC读写不要一次提交一个超大缓冲区，除非你确认USBX的内存池和端点缓冲能接受。实测下来，CDC单包2KB、MSC单次16KB的组合，在我这个项目里非常稳定。
5. 插上电脑之后：枚举验证和避坑记录
5.1 怎么判断复合设备是否真正枚举成功
把设备插到Windows电脑上，打开设备管理器，如果成功，会先看到“USB composite device”，展开之后下面会挂“USB串行设备”和“USB大容量存储设备”。这说明复合设备已经正确拆分成两个子设备。
如果只看到一个未知设备，或者只有一个类被识别，基本可以断定是描述符问题。这时候用USB Device Tree Viewer这类工具抓完整描述符，重点检查配置描述符里的bNumInterfaces和每个接口描述符的类代码。Windows对复合设备的拆分依赖这些字段，任何一处字节错位都会导致无法识别。
我遇到过一种情况：设备管理器显示复合设备，但CDC子设备有黄色感叹号，MSC正常。后来发现是CDC数据接口的类代码写成了0x02，正确值应该是0x0A。主机把数据接口当成通信接口处理，驱动加载失败。这类问题靠肉眼看描述符数组很难发现，必须对着协议规范逐字节比对。
5.2 CDC回环和MSC读写压测：一次完整的验证流程
CDC部分最基础的验证是回环测试。PC端用串口助手发送一段字符，STM32收到后原样返回。回环通了，再测双向大流量：PC端持续以115200甚至更高波特率发送数据，设备端接收后返回固定长度的包，看是否有丢失。
MSC部分先用RAM盘验证。在PC上把设备格式化FAT32，拷入一个文件，再从U盘读回，用哈希校验文件一致性。如果一致，说明MSC的CBW、CSW和数据传输链路没问题。然后换真实Flash驱动，重复同样操作。
两个类单独通过后，才做联合压测。写一个脚本同时打开串口和拷贝文件，一边用串口持续发日志，一边往MSC写入几十MB数据。如果过程中出现串口丢包、U盘读写中断，甚至系统提示“设备无法识别”，就把问题记录到排查表里。
5.3 高频问题排查表
| 现象 | 可能原因 | 解决建议 |
|---|---|---|
| 枚举成功但CDC设备不出现 | CDC接口描述符缺失，或DTR/线路编码未处理 | 检查接口数，确认应用处理SET_CONTROL_LINE_STATE和SET_LINE_CODING |
| MSC能枚举但显示0字节 | 扇区大小或介质容量回调参数错误 | 用RAM盘排除介质驱动问题，检查容量与扇区大小返回值 |
| 两个类同时工作必死 | 内存池耗尽，端点缓冲区冲突 | 加大USBX内存池，检查端点地址是否重复 |
| 设备能识别但Windows提示无法启动 | 字符串描述符索引越界或配置描述符长度错误 | 用协议抓包工具比对所有长度字段 |
| 拔插后第一次正常第二次蓝屏 | 类实例释放未清理 | 检查总线复位后的重新初始化逻辑，确保资源重复创建不冲突 |
| 有MSC读写时CDC丢包 | 总线带宽争用，CDC发送无背压 | 降低单次发送尺寸，提高CDC任务优先级 |
这些坑我基本都踩过。尤其是“MSC能枚举但显示0字节”，真正原因往往是read回调里读的扇区数和你设置的逻辑块大小不一致，和Flash驱动关系不大。
6. 调试顺序和两个容易被忽略的描述符参数
6.1 从单类到复合：先让每个功能独立跑通
我可以很负责地说，复合设备最忌讳一上来就同时调两个类。正确顺序是先只注册CDC，跑通虚拟串口；然后把CDC注释掉，只注册MSC，跑通U盘枚举和读写；最后再把两个类同时打开。每次只引入一个变量，出问题时不用猜。
这个顺序看着保守，实际上能省下大量时间。因为复合设备的故障往往隐藏在两个类互相影响的过程中，如果单个类就没跑通，那复合阶段的排查会变成叠buff，很难定位。我在第三次做类似项目时，已经把这个顺序当成纪律来执行。
6.2 bcdUSB和wMaxPacketSize两个参数不能随手抄
描述符里有几个参数非常容易被忽略。第一个是bcdUSB，它表示设备支持的USB规范版本。如果你写的是0x0200，但实际USB外设跑在FS模式，最大包长度是64字节；如果写0x0300则表示USB3.0，但你根本没有SuperSpeed PHY，主机可能会按错误方式协商。复合设备尤其要把这个参数对齐到硬件真实能力。
第二个是wMaxPacketSize。FS模式下批量端点最大包长64字节，HS模式最大512字节。如果配置描述符里写的是512，但你的外设实际没有启用HS，Windows会按HS包长度去调度，导致设备端收到的数据被截断。老实按FS的64字节写，宁可速度低一点，稳定性最优先。
这两个参数在生成代码里不一定正确，特别是当CubeMX版本或芯片封装模板有差异时。调试时不要想当然，用USBLyzer或USB Device Tree Viewer读一遍实际枚举结果，再和意图对比。
6.3 什么情况下不要硬上复合设备
复合设备确实强大，但它不是银弹。第一个限制是总线带宽。USB FS总带宽只有12Mbps，CDC和MSC同时大量传输时，带宽会被迅速耗尽。如果你的应用需要长时间满速跑MSC，又要求CDC实时性，复合设备可能扛不住，建议评估Host和Device是否都用HS，或者把交互通道改成HID减少开销。
第二个限制是端点数。多一个类就多占用端点资源，FS模式下端点资源有限。如果你计划组合三个及以上功能，必须提前画端点分配表，确认每个类都能分到唯一的IN/OUT端点对。如果端点不够，就要砍功能，或者改用外部USB Hub加多芯片方案。
最后是复杂度风险。复合设备对描述符的正确性要求极高，一点错位就可能导致某个子设备驱动加载失败。产品项目如果时间紧，功能又不需要共享同一个USB口，选择两颗独立USB芯片反而更可靠。做技术选型时不要被“复合设备很酷”绑架，要回到真实需求去权衡。
最后再分享一个我保留了很久的调试习惯：在工程里挂一个USB状态回调，把总线复位、设置配置、类请求这些关键事件用调试串口打出来。这个习惯帮我少走了很多弯路，尤其是复合设备这种多状态叠加的场景，看到事件日志和枚举现象一一对应，心里才有底。
