STM32+CherryUSB实现UAC双向音频：从描述符到调试全攻略

一直想做一个自己的USB声卡，或者至少把一块STM32开发板变成电脑能直接识别的麦克风加扬声器。以前翻开ST官方的USB音频例程，说实话有点劝退：一堆宏定义、抽象的类结构、繁琐的GetDescriptor处理，想改一个双向音频都得折腾很久。后来换了CherryUSB这套开源的USB协议栈，才发现原来UAC设备也可以写得这么直白——描述符配好、回调里填数据，一个带麦克风+扬声器的USB音频设备就上线了。这篇文章把我完整跑通“STM32 + CherryUSB实现UAC双向音频”的过程、踩坑和调试方法整理出来，适合想从零开始做USB音频设备、但不想被USB底层细节淹没的开发者。

1. 别再硬啃ST官方USB库了：CherryUSB在音频场景的优势

1.1 ST官方USB库在音频开发上的历史包袱

STM32的USB设备库是从早期USB 2.0 Full Speed时代一路改过来的，架构上偏向“通用设备框架”，对HID、CDC这类简单类支持得不错，但到了Audio Class就暴露出不少问题。最常见的是需要自己维护一套复杂的描述符申请回调，还要处理标准请求、类请求、厂商请求的分流，代码一旦写长就很难维护。CubeMX生成的USB中间件虽然能生成代码，但生成的工程默认支持HID/CDC，UAC相关的现成例程分散且版本老旧，拿来做麦克风+扬声器双向音频，等于自己把协议栈的边角料重新拼一遍。

ST的USB库还有一个问题：音频数据的等时传输是很讲究时序的。ST库把SOF事件和端点传输完成事件的回调暴露得不够顺手，在48kHz采样率下，每个SOF帧就要处理一次数据，中断延迟稍微不稳定，爆音和丢数据就来了。不是说ST的库不能用，而是对于想在短期内快速验证UAC方案的开发者，学习成本和排错成本都比较高。

1.2 CherryUSB到底帮你解决了什么

CherryUSB是一套面向嵌入式场景的开源USB协议栈，同时支持Device、Host、OTG，覆盖了STM32F1/F4/H7、ESP32、NXP等大量芯片。它的设计思路很直接：把USB控制器驱动和类驱动剥离开，开发者只需要关注两件事——描述符怎么配、数据回调怎么填。

在UAC场景下，CherryUSB已经内置了usbd_audio类驱动，负责解析Audio Control、Audio Streaming相关的标准请求。用户需要做的，就是提供一个描述符数组，再实现音频数据发送和接收的回调。这种“描述符+回调”的开发模式，比ST库那一大套面向对象的中间层直观很多。

如果是从熟悉Linux ALSA或者其他音频框架转过来的人，理解CherryUSB的audio模型更快：它把USB侧的数据搬运和音频侧的I2S/PDM数据搬运分开，中间用缓冲区衔接。你不需要关心USB协议栈内部怎么组包、怎么解析setup包，只要在回调里把数据放进去、取出来就行。

1.3 和TinyUSB、RT-Thread USB框架的简单对比

很多人在选USB协议栈时也会看TinyUSB。TinyUSB确实很优秀，尤其在跨平台、跨芯片支持上做得很全，文档也还完善，但它的API风格偏精简，很多回调需要自己翻头文件确认；CherryUSB在中文资料、社区讨论、STM32平台适配细节上更贴近国内开发者的使用习惯。

这不是说其他协议栈不行，而是对于一个目标是“快速做出UAC麦克风+扬声器”的项目来说，CherryUSB能让你把精力集中在音频数据处理而不是协议细节上。

2. USB音频的帧传输机制：描述符、等时端点和带宽天花板

2.1 UAC设备描述符链到底长什么样

USB设备能被主机识别为音频设备，靠的是一整套描述符。UAC 1.0设备的描述符链大致是这样：

• 设备描述符：bDeviceClass设为0x00，也就是让每个配置描述符自己去表达设备类型。
• 配置描述符：这里就开始进入音频类了。
• 音频控制接口（AudioControl，AC接口）：bInterfaceClass=0x01，bInterfaceSubClass=0x01。这个接口本身没有数据端点，主要用来描述音量控制、静音控制等实体。
• 音频流接口（AudioStreaming，AS接口）：bInterfaceClass=0x01，bInterfaceSubClass=0x02。这个接口下面挂等时端点，真正传PCM音频数据。

对于UAC麦克风+扬声器双向设备，配置描述符里会有两个AS接口：一个As接口用IN方向端点（麦克风数据从设备到主机），另一个AS接口用OUT方向端点（扬声器数据从主机到设备）。如果把音量控制也做进去，AC接口里还要有Input Terminal、Output Terminal、Feature Unit这些描述符。

这里有个容易混淆的点：USB Audio的多接口不是靠接口关联描述符（IAD）硬绑定，而是靠接口描述符里的bInterfaceNumber和bAlternateSetting来组织。每个AS接口通常有两个alt setting：alt setting 0表示空接口，不传数据；alt setting 1表示实际打开端点。主机在播放/录音开始时，会先通过SET_INTERFACE请求切换到alt setting 1，否则端点不工作。调试时如果发现设备枚举成功但没声音，先查一下是不是没处理SET_INTERFACE。

2.2 等时端点的带宽预算：Full Speed的1毫秒限制

USB Audio用的是等时传输（Isochronous），这种传输方式没有重传机制，数据丢了就是丢了，好处是带宽有保障、时延低。对于Full Speed设备，主机会以1毫秒为周期发送SOF帧，每个SOF周期内，等时端点最多能传输的字节数是有限制的：全速等时端点单次传输最大1023字节。

这个数字决定了你能承载多高的音频规格。以16bit位宽为例：

从表里看，全速UAC 1.0做96kHz/24bit/双声道也还落在1023字节上限内，但实际工程中还要算上协议开销、总线调度、主机调度策略等因素，建议留足余量。常规稳妥做法是48kHz/16bit/双声道，这个规格下USB侧的压力很小，不管代码还是硬件都更容易稳定。

带宽预算的意义还在于：当你同时跑麦克风IN端点和扬声器OUT端点，两个等时端点共享同一个SOF周期。所以配置描述符里两个端点的wMaxPacketSize之和不能超过合理调度范围，否则主机可能拒绝配置或者出现奇怪的枚举问题。

2.3 同步、自适应和异步：UAC设备如何对上采样节奏

UAC设备的同步方式直接决定数据流是否稳定。Synchronous模式下，设备跟随USB主机的SOF节奏，主机每个帧发多少数据，设备就消耗多少数据，常见于UAC扬声器。Asynchronous模式下，设备有自己的采样时钟，通过反馈端点告诉主机“你应该发快一点还是慢一点”，常见于高端USB DAC。Adaptive模式则是设备根据主机数据速率来调整自己。

对于STM32做UAC设备，我的建议是先用Synchronous模式把功能跑通，也就是主机播多少、设备就放多少；设备采集麦克风时，也按照SOF节奏往里灌数据。虽然这在Hifi玩家眼里不够“讲究”，但工程上简单可靠。等基础功能通了，再考虑用反馈端点做异步模式。UAC 1.0里反馈端点是一个单独的同步端点，UAC 2.0里更是把反馈机制标准化了。CherryUSB的usbd_audio类对这块有预留，但普通项目真的用不上。

3. 硬件链路：MCU、Audio Codec和I2S的时钟同步问题

3.1 主控选型：STM32F4是性价比之选

做UAC设备，主控需要满足两个条件：一是自带USB Full Speed或者High Speed控制器，二是能方便地接音频数据源。STM32F407/F405是我用得最多的选择。原因很简单：F4系列的USB OTG FS不需要外置PHY，D+ D-直接接USB座子就行，而F1系列需要额外的D+上拉控制，稍微麻烦一点。

F4系列的USB控制器要求输入48MHz时钟，一般通过PLL把外部25MHz或者8MHz晶振倍频出来。如果这块时钟不准，USB枚举会直接失败。调试时最先看的就是这个48MHz有没有配好。

音频数据流走向有两种方式：一种是MCU通过I2S/SAI接口接外部Audio Codec，另一种是直接用MCU内置ADC采集模拟麦克风。内置ADC做USB声卡不是不行，但采样时钟精度、噪声性能都比较弱，做演示可以，做产品就算了。我建议用外部Codec，后面也更容易扩展耳机放大、线性输入等功能。

3.2 外部Codec怎么选：WM8960、ES8388这类常见芯片

Codec芯片市场上可选的很多。WM8960是经典款，支持I2S接口，内置立体声DAC和ADC，信噪比够用，48kHz/16bit条件下表现稳定。ES8388也是国产化方案里常见的，双声道ADC/DAC，价格有优势，文档也还可以。SGTL5000在一些开发板上也能见到，性能和驱动支持都行。

我自己的板子用WM8960比较多，主要原因是它能同时提供DAC和ADC两条路径，正好对应扬声器和麦克风两条USB数据流。如果板子上已经集成了数字MEMS麦克风（I2S/PDM接口），那主控可以直接从I2S收数据，少一颗Codec芯片，但扬声器播放还是得靠DAC输出，所以完整方案下Codec基本省不掉。

3.3 双向I2S接线：一个容易翻车的地方

STM32F4系列的标准SPI/I2S外设，默认是半双工的，一个I2S实例只能管一路数据，要么是接收（连Codec ADC的DOUT），要么是发送（连Codec DAC的DIN）。要在同一块板子上同时跑麦克风和扬声器，就需要两个I2S实例配合，一个负责发送，一个负责接收，并且它们要共用BCLK和LRCK时钟线。

连线逻辑大概是：

• Codec的MCLK、BCLK、LRCK接主控，并由主控或外部有源晶振提供时钟。
• DAC数据线DIN接主控的一个I2S发送引脚。
• ADC数据线DOUT接主控的另一个I2S接收引脚。
• 如果两颗I2S外设都能配置为master，注意它们的BCLK和LRCK频率必须完全一致，否则左右声道和解码会出问题。

这里有一个更稳的方案：选择带SAI接口的STM32型号，比如F746、H743。SAI接口天然支持全双工，一条SAI既可以接收也可以发送，接线和配置都简单不少。如果手头只有F407这类芯片，用两个I2S外设也能做，但初始化的时钟配置要格外小心，而且I2S外设作为master时的BCLK/LRCK不会自动和其他I2S实例同步，需要硬件上把两边的BCLK/LRCK短接到同一个Codec时钟线，或者干脆让Codec输出MCLK作为参考。

3.4 时钟精度和音调漂移的关系

USB音频对采样时钟的要求不是“差不多就行”，而是“尽量准”。I2S的LRCK就是采样率时钟，它来自MCU或Codec的主时钟。如果LRCK比标准48kHz偏差超过几十ppm，人耳不一定立刻听出来，但长时间播放会感觉到音调整体偏高或偏低，专业一点来说就是“音调漂移”。

我实测过用STM32内部PLL直接生成48kHz，如果外部晶振是普通精度（20ppm以内），不接Codec外部晶振时，USB播放还能凑合；但一旦同时录音和播放，主机作为同步基准，设备端采样时钟如果偏差大，缓冲区会周期性出现欠载或溢出，爆音的频率会明显上升。所以我的建议是：给音频Codec配一个独立的有源晶振或者高精度无源晶振，确保MCLK稳定。

4. 工程改造：从CherryUSB audio例程改出双向UAC的完整路径

4.1 先把CherryUSB拉进工程

CherryUSB的仓库地址在GitHub上直接搜 CherryUSB 就能找到，仓库的docs目录下有中文文档。源码组织很清晰，core目录是协议栈核心，class目录里有audio、cdc、hid等现成类，port目录下是针对各MCU的控制器驱动。

把CherryUSB集成进STM32工程，可以手动复制文件到Keil/IAR工程，也可以用RT-Thread Studio的软件包直接拉取。如果你是裸机开发，用不上RT-Thread，直接复制下面这些关键文件就行：

• core/usb_os.c、usb_config.c、usb_dc.c、usb_hcd.c（按需）
• class/audio/usbd_audio.c、usbd_audio.h
• port/stm32/stm32f4xx/下的USB控制器驱动

项目里需要一个配置文件usb_config.h，里面要打开对应的宏，至少包括USB_DEVICE_CONFIG_AUDIO等开关。每个芯片的配置宏略有差异，我建议先编译一遍仓库里自带的device/audio示例，确认环境没问题，再往自己的板子上移植。

4.2 描述符怎么配：一份简化的UAC描述符片段

CherryUSB的audio示例里，描述符是放在一个uint8_t数组里的。下面是一段示意结构，对应UAC 1.0的扬声器+麦克风配置，实际用的时候需要按芯片和端点分配情况调整端点号：

#define AUDIO_IN_EP 0x81 #define AUDIO_OUT_EP 0x01 static uint8_t audio_descriptor[] = { /* Configuration Descriptor */ USB_DESCRIPTOR_LENGTH_CONFIG, // bLength USB_DESCRIPTOR_TYPE_CONFIGURATION, // bDescriptorType 0x00, 0x00, // wTotalLength，编译时由计算宏填 0x03, // bNumInterfaces: AC + AS(In) + AS(Out) 0x01, // bConfigurationValue 0x00, // iConfiguration 0xC0, // bmAttributes 0x32, // bMaxPower: 100mA /* Audio Control Interface */ USB_DESCRIPTOR_LENGTH_INTERFACE, USB_DESCRIPTOR_TYPE_INTERFACE, 0x00, // bInterfaceNumber 0x00, // bAlternateSetting 0x00, // bNumEndpoints 0x01, // bInterfaceClass: Audio 0x01, // bInterfaceSubClass: AudioControl 0x00, // bInterfaceProtocol /* Audio Streaming Interface - Microphone IN */ USB_DESCRIPTOR_LENGTH_INTERFACE, USB_DESCRIPTOR_TYPE_INTERFACE, 0x01, // bInterfaceNumber 0x00, // bAlternateSetting(零带宽) 0x00, // bNumEndpoints 0x01, // bInterfaceClass: Audio 0x02, // bInterfaceSubClass: AudioStreaming 0x00, // bInterfaceProtocol /* 另一个alt setting打开端点，这里省略长度，示意结构 */ AUDIO_OUT_EP, // bEndpointAddress: OUT USB_ENDPOINT_TYPE_ISOCHRONOUS, // bmAttributes 0xC0, 0x00, // wMaxPacketSize: 192字节/帧 0x01, // bInterval /* Audio Streaming Interface - Speaker OUT（按如上规则展开） */ ... };

如果你只是想把例程跑起来，建议直接用CherryUSB仓库里已经写好的描述符模板，不要去手工改那个wTotalLength和校验收的字节数，很容易算错。在描述符数组后面，CherryUSB通过usbd_audio_descriptor_callback把数组地址和长度注册给协议栈，剩下的枚举流程由协议栈自己处理。

4.3 主程序初始化流程

在main函数里，初始化USB控制器，注册audio类，然后进入while循环或让RTOS调度。一个典型的初始化流程如下：

extern void usbd_audio_add_interface(usbd_class_t *devclass); extern void usbd_audio_class_init(usbd_class_t *devclass); int main(void) { /* 时钟配置、GPIO配置、I2S配置、Codec配置... */ /* 初始化协议栈 */ usb_dc_init(); /* 注册audio类 */ usbd_audio_class_init(&usbd_audio_class); /* 连接USB */ usbd_initialize(); while (1) { /* 裸机模式下需要周期调用协议栈处理，或使用中断驱动 */ delay_ms(1); } }

裸机模式下，USB协议栈的中断处理和音频数据回调都是基于中断的，所以while循环里没有太多事可干。如果用了RT-Thread，可以直接把协议栈挂到设备框架下，把USB设备注册为sound设备，用标准audio框架去读写，这样更贴近Linux风格，但纯裸机也完全够用。

4.4 双向数据处理回路：核心回调怎么写

CherryUSB的usbd_audio定义了四个核心回调：start、stop、parse_data、send_data。分别对应主机开始播放/录音、停止播放/录音、收到USB发来的扬声器数据、需要向主机发送麦克风数据。

下面这段示意代码展示了双向音频数据的搬运逻辑：

static usbd_audio_callback_t audio_cb = { .start = audio_start, .stop = audio_stop, .parse_data = audio_parse_data, .send_data = audio_send_data, }; /* 主机发来扬声器数据，USB OUT -> I2S TX */ void audio_parse_data(uint8_t *buf, uint32_t len) { /* 将USB数据拷贝到I2S发送DMA的缓冲区 */ i2s_tx_dma_write(buf, len); } /* 主机读取麦克风数据，I2S RX -> USB IN */ void audio_send_data(uint8_t *buf, uint32_t len) { /* 从I2S接收DMA的缓冲区拷贝数据到USB端点缓冲区 */ i2s_rx_dma_read(buf, len); }

看起来很简单，但真正要注意的是缓冲区深度和DMA搬运的同步。如果I2S RX的DMA数据还没就绪，USB的IN端点就拷数据，麦克风数据就会出现大量重复或丢帧；如果USB OUT数据来了，I2S TX的DMA还没消费完，旧的缓冲可能被覆盖，扬声器就会爆音。解决办法一般是做环形缓冲区，或者用双缓冲机制，在中断回调里安全地切换buffer。

我在实板上用的策略是：I2S DMA配置成循环模式，每次半传输和全传输都产生中断，中断里把半缓冲/全缓冲的数据搬运到USB端点的发送buffer。反过来，USB OUT端点的数据也先进入一个环形缓冲，I2S TX DMA从环形缓冲取数。这样USB侧的等时传输节奏和I2S侧DMA节奏解耦，爆音概率大幅下降。

4.5 别忘了配置端点带宽和FIFO

STM32F4的USB OTG控制器为每个端点单独分配FIFO，如果FIFO配小了，等时传输的wMaxPacketSize又比较大，会出现“端点数据装不下”的报错或数据丢弃。以F407为例，建议把IN和OUT端点的FIFO都调整到足够容纳最大包加上一定余量。比如192字节/包的话，FIFO至少配256字节。

同时，USB中断优先级要高于普通任务，但不要高过系统节拍，避免长时间阻塞。遇到爆音时，很多人第一反应去调I2S采样率，实际上先检查一下USB端点FIFO和DMA优先级，往往立竿见影。

5. 调试实录：枚举失败、爆音、音调漂移的完整排查

5.1 枚举失败：从D+上拉到48MHz时钟

UAC设备插上电脑后，如果设备管理器里完全没有反应或者出现黄色感叹号，我的排查顺序一般是这样的。

先查D+上拉。STM32F4的USB OTG FS内部已经做了D+上拉控制，但这取决于软件是否正确配置了内部上拉电阻。有的开发板还额外外挂了1.5k上拉，两者冲突可能导致枚举异常。确认硬件上没有多余上拉后，再看软件是否调用了USB连接使能函数。

再查48MHz时钟。F4系列USB OTG FS必须使用48MHz的PLL48CK。配置错的话，USB控制器状态会因为时钟频率不对而无法稳定。用示波器或逻辑分析仪直接测D+引脚在插入瞬间是否有电平跳变，能快速判断枚举启动是否开始。

如果这两个都没问题，就上抓包工具。Windows下可以用Wireshark搭配USBPcap，或者用Bus Hound看设备的Setup包交互。设备回包超时、返回错误长度描述符，都是常见枚举失败原因。多数时候是描述符的bLength或wTotalLength算错，导致主机解析中断。

5.2 有声音但爆音/杂音：重点查缓冲区和中断优先级

爆音是个很磨人的问题，因为它不是每次必现，经常是播放个几秒钟才出现一次。我遇到过最典型的情况有两种。

第一种是缓冲区溢出或欠载。USB OUT方向数据进来太快，I2S TX DMA还没消费完，缓冲区被覆盖；或者I2S TX太慢，DMA空了，Codec拿到空数据。解决方法是把I2S DMA的接收和发送都做成双缓冲或环形缓冲，并定期统计缓冲区水位，打印出来看看是不是临界值太紧。

第二种是中断优先级配置不当。等时传输要求每个SOF周期内完成数据搬运，如果USB中断被其他低优先级中断长时间打断，数据就可能晚到。我给USB中断设置了较高优先级，同时确保不能在USB中断里做耗时操作，只做数据搬运和标志位设置，真正的信号处理或算法放到主循环或低优先级任务里。

另外，还有一个容易被忽略的点：Codec的I2S位深和USB描述符里声明的位置必须一致。Windows默认输出可能是16bit，如果USB描述符写了24bit，而I2S只配置成16bit，数据宽度不一致，也会表现为杂音或音量异常。

5.3 音调漂移和采样率不一致：先电平测量，再查描述符

音调整体偏高或偏低，一般是LRCK时钟频率不准；音调忽高忽低伴随爆音，则很可能是主机的播放采样率和设备描述符声明的不一致。Windows上有些应用默认播放格式是“16位，48000Hz”，如果设备只在描述符里声明了44100Hz，Windows可能进行重采样或者协商失败，表现就是播放速度异常。

用频率计或逻辑分析仪量一下LRCK的频率，如果实际频率和预期值有偏差，那问题在MCU/I2S时钟配置。如果LRCK频率准确，那问题大概率在USB侧枚举或采样率协商。可以把Codec配置成从机模式，由MCU提供MCLK/BCLK/LRCK，这样调试时更容易对照确认。

还有一个常见原因：主机播放格式和录音格式不一致。Windows的默认通信采样率有48kHz和16kHz两套策略，如果设备在麦克风接口和扬声器接口声明了不同的采样频率，系统可能会在切换时把音频流的采样率改来改去，导致回放和录音互相干扰。尽量让两个AS接口的采样率保持一致，等基础稳定后再去适配多采样率。

5.4 调试工具怎么搭配最高效

• 逻辑分析仪：这是定位时钟问题的主力。采样率不需要太高，能看到BCLK、LRCK、MCLK的周期即可。测试点我一般直接放在Codec引脚附近，方便观察实际信号。
• Wireshark + USBPcap：抓USB总线包，能看到枚举过程的所有Setup包、Get Descriptor响应、SET_INTERFACE请求。音频跑起来之后，还能看到每个SOF帧的端点数据包大小。
• Bus Hound：更轻量，对端点传输情况有统计，适合看等时端点的数据包数量、丢包、NAK情况。
• 串口printf：在回调函数里加统计计数器，比如每秒打印一次“USB IN包数量、I2S RX DMA已搬运字节数”，两端一对比就知道是谁跟不上谁。

调试这类设备，我的原则是：一次只改一个变量。不要同时调采样率、缓冲区大小和中断优先级，否则问题定位会变得很模糊。改完一个参数，播放一首固定的测试音，或者录音一段固定频率的音频，再对比前后差异。

6. 进阶方向：音量控制、采样率切换和类驱动二次开发

双向UAC跑通之后，项目其实只完成了“能出声、能录音”的基础版本。再往前走，有几个方向很常见。

第一个是音量控制和静音控制。UAC的AudioControl接口里有Input Terminal、Output Terminal、Feature Unit这些结构，主机通过GET_CUR/SET_CUR请求来读取和设置音量。CherryUSB的usbd_audio类预留了控制请求的分发入口，你需要在对应的控制回调里处理音量值，转化成Codec的寄存器配置。这个功能并不难，但要仔细解析UAC 1.0的控制请求格式，尤其是主音量是双通道共用还是一个通道一监听，容易搞混。

第二个是多采样率支持。如果把描述符里的采样率改成192kHz/24bit，对应的等时带宽和I2S配置也要跟着变。CherryUSB在SET_INTERFACE和sample frequency request的处理上给了扩展点，你可以在类驱动回调里重新配置I2S的时钟分频和DMA缓冲区大小。这个改动比音量控制更考验对音频链路的理解，建议先加一套48kHz，再加44.1kHz，把不同格式之间的切换状态机理清楚。

第三个方向是把UAC设备扩展成复合设备，比如同时支持UAC和HID，做一个带音量旋钮的USB声卡。CherryUSB支持多个类同时注册，只要描述符里定义多个接口，协议栈的调度会帮你把不同类的setup包分发到对应驱动。复合设备的调试难度会增加，尤其是Windows对UAC和其他类的复合设备的兼容性有一些特殊策略，但作为个人项目，可玩性非常高。

从零把一块STM32变成能被电脑识别的麦克风加扬声器，整个链路里最耗时间的其实不是USB协议本身，而是对音频数据流的理解和对排查方法论的把握。我自己在测试双I2S时钟同步那个环节卡了快一整晚，后来用逻辑分析仪量出两个I2S外设的BCLK起始相位不一致，才真正理解为什么资料里反复强调“共享时钟线”这件事。做这类项目，硬件上的坑通常比软件更多，但只要确保每一个时钟信号都有明确来源，每一条数据通路都有缓冲区兜底，剩下的事情就只是按部就班调参数了。