STM32+ CherryUSB实现UAC音频设备：麦克风与扬声器完整开发实战

USB音频设备开发这几年越来越热尤其直播声卡、USB耳机、会议麦克风阵列这类产品本质上都是UACUSB Audio Class设备的变体。我自己在做了几个基于STM32的USB项目之后最大的体会是协议栈选对了开发效率能翻好几倍。CherryUSB这套开源协议栈配合STM32内置的USB外设确实把UAC音频设备的门槛拉低了不少。这篇文章就完整记录一下我如何从零搭建一个同时支持麦克风和扬声器功能的USB音频设备把其中的关键思路、协议细节、代码实现和踩坑经历都摊开来讲清楚给正在做相关项目的朋友一个可直接参考的路线。1. 项目整体设计与方案选型1.1 为什么选择CherryUSB作为协议栈做过USB开发的朋友都知道USB协议栈这件事选型往往比写代码本身更影响项目走向。STM32官方有USB设备库ST提供的USB Device Library用起来中规中矩但对UAC这类音频类设备支持不算友好描述符结构复杂、回调机制繁琐调试起来非常痛苦。创业团队或独立开发者长期依赖ST官方库做定制音频方案很容易被版本兼容问题绊住脚。CherryUSB是国产开源的一套USB主机与设备协议栈核心优势在于它对USB协议层的抽象非常干净设备描述符通过结构体配置端点回调直接绑定处理函数代码可读性远好于官方库的宏定义堆叠。我最初是被它的UAC示例吸引过来的因为CherryUSB官方仓库里带了UAC Speaker和UAC Microphone的参考实现基于这套示例改造成麦克风和扬声器同时存在的复合设备工作量小很多。最关键的一点是CherryUSB对STM32的适配已经非常成熟无论是F1、F4系列的标准USB外设还是H7系列内置的OTG控制器都有现成的驱动接入层我们只需要关注应用层音频数据的搬运逻辑不需要把时间花在USB底层时序上。对于做产品的团队来说这点太实用了。1.2 主控选型STM32在UAC方案中的定位STM32家族里能做USB音频设备的型号非常多但选型时核心考量点在于USB外设类型、RAM大小、音频数据通路性能。我目前用的STM32F407配合CherryUSB因为F407内置了USB OTG FS控制器支持全速Full SpeedUSB 12Mbps同时主频168MHz做音频数据的实时搬运绰绰有余。全速USB对音频设备的限制是带宽一个全速USB帧是1ms可用的等时传输Isochronous Transfer带宽大约是1023字节每帧。如果只做麦克风或只做扬声器标准配置采样率48kHz、16bit、单声道每帧需要传输48000/1000 48个采样点乘以2字节就是96字节加上协议头开销带宽占用很小。但如果要做48kHz、双声道、24bit的高品质音频流每帧数据量会明显增大全速USB勉强够用但留给其他端点的带宽余地就比较紧张了。如果项目对音频质量有更高要求比如96kHz采样率、多通道输入输出那就得考虑STM32H7系列它内置的OTG HS高速控制器可以达到480Mbps不过需要注意高速模式需要外接USB PHY芯片比如USB3300这会增加硬件成本和布线复杂度。我自己在做第一阶段原型验证时果断选择了F407全速方案先把功能跑通后续再考虑升级。选型的时候还有一点容易忽略音频数据的搬运需要足够的RAM做缓冲。F407有192KB RAM做UAC设备系统开销大约需要20~30KB协议栈、端点缓冲剩余做音频DMA环形缓冲完全够用。如果选小RAM型号如STM32F103代码和缓冲的规划就要精细很多。1.3 UAC方案如何同时承载麦克风与扬声器这里的核心问题在于USB协议里如何描述一个既具备输入功能麦克风又具备输出功能扬声器的音频设备。UAC规范定义了音频设备由音频控制接口Audio Control Interface和若干个音频流接口Audio Streaming Interface组成。The architecture:一个UAC复合音频设备内部包含三个接口一个音频控制接口AC Interface负责音量、静音、采样率等控制。一个音频流输入接口AS Interface输出方向Out方向主机-设备对应扬声器功能。一个音频流输出接口AS Interface输入方向In方向设备-主机对应麦克风功能。所以从USB枚举的角度看这个设备有3个接口Interface接口0为AC接口1为AS输出接口2为AS输入每个接口都会在配置描述符Configuration Descriptor中体现。CherryUSB的示例代码里UAC Speaker和UAC Microphone是分开的两个工程我们需要把两个示例的设备描述符合并到一个工程中并处理好端点分配。合并的过程中最重要的一点是确保每个设备的端点地址不冲突。USB的端点地址由设备端点号与方向组成比如0x01代表端点1的IN方向设备到主机0x02代表端点1的OUT方向主机到设备不对标准USB端点地址中方向位在bit70x81表示端点1 IN0x01表示端点1 OUT仔细看。我们在设计时采用端点1做麦克风数据上传IN端点2做扬声器数据下行OUT这样两个方向的音频数据流互不干扰也不存在方向共用同一端点号的带宽竞争。2. UAC协议核心细节与实操要点2.1 从枚举过程理解USB描述符的层次关系在写UAC代码前必须把USB描述符的层次关系理清楚。USB设备连接主机后主机会发起总线枚举请求设备描述符Device Descriptor、配置描述符Configuration Descriptor、字符串描述符String Descriptor等。对音频设备来说配置描述符里会在标准配置描述符后依次附加音频控制接口描述符、音频流接口描述符以及对应的端点描述符和环境描述符。描述符的顺序是不能乱来的这在UAC协议中尤其严格。UAC设备中AC接口描述符之后必须紧跟着它的输入终端描述符Input Terminal和输出终端描述符Output Terminal用于描述设备端的音频拓扑。比如麦克风功能拓扑是USB端点 - 输出终端 - 输入终端 - I2S接口实际采集物理音频。主机通过解析这些终端描述符来理解设备的能力比如是否支持音量调节、支持哪些采样率、声道数等。如果描述符定义有误主机的表现各异Windows可能显示“设备无法启动”Linux下dmesg会打印详细的USB解析错误信息比如usb 1-1: config 0 descriptor?或者cannot submit urb等这个是我们调试时重要的定位手段。所以描述符这部分我建议不要凭记忆手写而是基于CherryUSB的参考代码修改改完用USB分析仪或Wireshark抓包核对每一层的字节布局。2.2 音频端点与带宽计算的关键参数等时端点Isochronous Endpoint是UAC音频数据的主要通道。等时传输的特点是带宽有保证、无重传、时延低非常适合实时音频。全速USB的等时传输每1ms帧里最多可以安排多次事务每次事务传输的数据大小由端点描述符的wMaxPacketSize字段定义。我们这里的麦克风和扬声器都采用48kHz、16bit、单声道配置每帧1ms音频数据量 48000 / 1000 48 采样点每采样点大小 2 字节16bit每帧数据量 48 * 2 96 字节所以等时端点的wMaxPacketSize应按96字节设置也可以设置118字节预留一些余量给协议层更稳妥但这个会略微增加带宽占用。设备端在描述符中声明了这个值主机端才会按这个大小来调度总线的时隙。如果应用程序里实际发送的数据量超过wMaxPacketSize等时传输就会溢出主机声音会变成明显的爆音杂音。对于扬声器方向主机以每1ms一帧的节奏向设备的OUT端点发送音频数据对于麦克风方向设备需要在每1ms内准备好一帧96字节48个采样点数据等待主机发起IN令牌后返回给主机。如果你的音频采集通路中断出问题导致某个帧没有数据可发USB控制器通常会发空包主机端就会出现一段静音或噪声。所以音频数据缓冲设计必须保证端点在主机请求时总有数据可取这是UAC麦克风稳定工作的核心难点。2.3 采样率同步与反馈问题UAC音频有一个其他USB类不常见的问题时钟同步。计算机声卡本地时钟和USB主机时钟、设备端音频时钟不完全一致长时间运行时如果设备端音频采样时钟和主机期望的采样率偏差过大语音就会逐渐变调或者出现缓冲区溢出/欠载。对于扬声器功能设备从主机收数据主机节奏由主机的音频堆栈控制设备端只需要按自己的采样率播放即可短时间运行没有问题。但如果设备端实际采样率和主机期望的48kHz有偏差比如实际是48.1kHz那么运行几分钟后设备端的DAC缓冲会逐渐被填满或掏空表现为声音断续或越来越快/越来越慢解决这个问题的两种常规方案一种是PLL锁相环锁定主机的SOFStart of Frame信号来调整设备端时钟硬件上需要支持另一种是软件层面做重采样用异步采样率转换ASRC把数据率匹配到本地时钟。F407内部没有可调时钟专门锁USB的SOF所以我做原型时采用的是简单控制策略定时检查DMA缓冲水位如果水位持续偏高则丢弃一个采样点如果持续偏低则补一个采样点。这种做法的音频效果对普通音质要求够用但如果你做专业音频设备必须在硬件设计阶段就考虑时钟方案选型。3. 实操过程与核心环节实现3.1 硬件准备最小系统与音频编解码芯片在开始写代码之前先明确一下硬件清单。我这次的实验板是自制的STM32F407最小系统板USB接口通过F407的PA11D-、PA12D连接到USB座子D上接1.5kΩ上拉电阻用于全速设备识别F407内置OTG控制器实际上上拉由软件控制但如果是传统USB设备模式还是需要外部上拉。OTG FS的VBUS检测引脚PA9上分压电路用于检测USB插入/拔出。音频编解码器我选用的是内置I2S接口的ES8388或者也可以用CS4272、WM8960等它同时具备ADC麦克风采集和DAC扬声器播放这样一块芯片就能覆盖麦克风和扬声器两条音频通路。ES8388的I2S接口与STM32的SPI2/I2S2外设连接STM32 I2S_SCK位时钟- ES8388 MCLK/BCLKSTM32 I2S_SD数据- ES8388 DIN/DOUTSTM32 I2S_WS左右声道选择- ES8388 LRCK另外还需要I2C接口SCL/SDA用于配置ES8388的寄存器比如设置采样率、ADC/DAC增益、工作模式。硬件上容易出问题的点ES8388的MCLK主时钟一般需要系统时钟如果直接用I2S的BCLK做MCLK采样率一高就容易失真。我采用的是STM32的MCO主时钟输出引脚输出PLL分频后的时钟给ES8388做MCLK这样MCLK 256*Fs对48kHz采样率就是12.288MHzES8388工作稳定。3.2 CubeMX工程初始化与时钟树配置用STM32CubeMX初始化工程可以省掉很多底层的寄存器配置时间。关键配置项RCCHSE外部晶振8MHzPLL倍频到168MHz系统时钟。USB需要48MHz时钟在时钟树中配置USB预分频器把PLLQ输出设为48MHz。USB OTG FS选择Device_Only模式使能VBUS Sensing其实F407全速设备可以关闭VBUS检测以简化但建议保留这样能正确响应USB插入/拔出。I2S2配置为Master Transmit主发送模式16bit数据宽度、48kHz采样率。注意I2S这里还有一个半双工的问题F407的I2S外设不能同时收发所以麦克风采集和扬声器播放要么用两个不同的I2S外设要么用时分复用。我在原型中直接采用两个I2S通道I2S2做扬声器输出DACI2S3做麦克风输入ADC逻辑清晰避免数据竞争。SPI1配置为I2C模式模拟的I2C也可以但用硬件I2C或SPI模拟I2C会更稳用于控制ES8388寄存器。DMAI2S2的TX和I2S3的RX分别配置DMA数据以环形缓冲方式传输。时钟树上还有个细节USB的48MHz时钟如果由PLLQ输出必须确保PLL输入频率经过合理倍频分频后能精确得到48MHz。8MHz HSE、PLLM8、PLLN336、PLLP2、PLLQ7这样PLLQ输出是48MHz同时系统时钟是168MHz这是F407非常标准的一套配置。3.3 CherryUSB的UAC设备描述符与接口注册CubeMX生成工程后把CherryUSB的源码包放在工程目录下开始配置协议栈。CherryUSB中设备描述符通过usbd_desc结构体配置音频接口描述符则由UAC类驱动的源码提供。我们不做UAC类驱动本身的修改而是在usb_dc_init之前调用usbd_initialize注册接口并挂载我们自己的端点回调处理函数。先看设备描述符的核心结构struct usbd_descriptor { uint8_t *device_descriptor; uint8_t *config_descriptor; uint8_t *string_descriptor_null; uint8_t *string_descriptor_manufacturer; uint8_t *string_descriptor_product; uint8_t *string_descriptor_serial; uint8_t *string_descriptor_interface; };对于复合UAC设备config_descriptor是一个大块内存需要依次排列标准配置描述符、接口0AC及其相关描述符、接口1AS输出及其端点描述符、接口2AS输入及其端点描述符。CherryUSB参考示例中通常只包含一个音频流接口所以我们需要自己拼接这个config_descriptor。拼接描述符其实不难但很繁琐。我建议在工程中单独写一个usbd_uac_desc.c文件把所有描述符定义放在一起用宏定义统一管理端点地址和wMaxPacketSize。这样可以避免多个文件修改时的遗漏。3.4 麦克风和扬声器的音频数据通路实现设备枚举成功后音频数据通路就开始工作了。这个过程分为两个方向也是整个项目最核心的实时逻辑。麦克风方向设备到主机音频流是ES8388的ADC采集到的PCM数据通过I2S3的DMA传输到STM32的RAM缓冲区当USB主机发起IN令牌时协议栈从RAM缓冲区取出一帧音频数据96字节放到USB端点FIFO由USB硬件发送给主机。这段逻辑在CherryUSB中通过等时IN端点回调触发。我们可以注册一个uac_mic_in_callback函数在该回调中从音频采集缓冲区读取数据并填入端点缓冲区。注意等时传输没有重传机制所以回调执行必须足够快如果音频采集DMA数据还没有准备好宁可直接发静音数据全零也不要让主机端读到非法数据否则会出现明显噪音。扬声器方向主机到设备主机以1ms周期通过OUT端点发送音频数据设备收到后会触发uac_spk_out_callback回调我们需要在该回调中把数据从USB端点缓冲区拷贝到I2S DAC的DMA发送缓冲区。由于I2S的DMA是周期性从缓冲区取数据的相当于一个消费者USB回调是数据生产者两者之间用环形缓冲来衔接。环形缓冲区的大小至少要能容纳几十毫秒的音频数据这样即使USB和I2S时钟有微小偏差也不会立刻导致缓冲上溢或下溢。我来写一个简化的示意代码展示等时IN端点的数据发送逻辑void uac_mic_in_callback(uint8_t *buf, uint32_t len) { // 从MIC_DMA_RX_BUF中读取一帧PCM数据48个采样点16bit memcpy(buf, mic_dma_ringbuf_get_frame(), len); } void uac_spk_out_callback(uint8_t *buf, uint32_t len) { // 把主机下发的PCM数据写入DAC环形缓冲 spk_dma_ringbuf_write(buf, len); if (spk_dma_ringbuf_count() SPK_BUF_MAX) { // 缓冲快满时丢弃最旧的数据防止整体延迟越来越大 spk_dma_ringbuf_skip(spk_dma_ringbuf_count() - SPK_BUF_TARGET); } }代码很简单但真正调试时这里的细节非常多。比如mic_dma_ringbuf_get_frame必须保证I2S DMA已经写完一帧完整数据而数据是以16bit对齐的如果指针处理不当会出现左右声道交换、数据位移、沙沙声等问题。另一个问题是memcpy在回调中执行如果此时CPU正被高优先级中断占用可能导致回调超时所以整个回调函数体不能做重活拷贝必须用DMA或memcpy这种快速操作完成。3.5 音频参数与主机端对齐UAC设备在主机上能以“USB音频设备”的名称出现在声音设置里。Windows和Linux主机通常会在音频会话开始时向设备发送采样率设置请求Set Sample Rate ControlUAC协议里通过控制传输实现设备要回应该请求并记录当前采样率。CherryUSB的UAC驱动已经处理了对采样率控制的标准响应你只要保证描述符中声明的采样率集合和实际音频硬件的采样率一致即可。我在描述符中只声明了48kHz单一采样率这样主机的音频栈就不会尝试切换其他采样率简化了处理逻辑。如果后续要做44.1kHz/48kHz自动切换就需要在处理Set Sample Rate请求时动态调整I2S外设和ES8388的分频系数工作量会大不少。4. 常见问题与排查技巧实录4.1 枚举失败设备插入后无反应这是USB开发最常遇到的情况。设备插上后Windows没有任何提示或者显示“未知USB设备设备描述符请求失败”。先排查硬件层面用USB分析仪或示波器看D和D-两条线上的电平。全速设备在插入后设备端会把D拉高主机检测到D电平变化后会发起复位和枚举。如果看不到D拉高问题出在硬件上常见原因有USB D上拉电阻没有接、USB座子引脚虚焊、F407的VDD35/VUSB供电没接对。如果电平正常但仍然枚举失败大概率是描述符问题。我踩过一次坑是config_descriptor缓冲区定义太小拼接描述符时越界写坏了相邻内存导致枚举后段崩溃。建议在定义描述符缓冲区时预留足够空间并在拼接后打印或导出描述符的hex数据用USB抓包工具比如Wireshark配合USBPcap逐字节核对。还有一个容易被忽略的问题F407的OTG全速设备需要用3.3V供电但有些开发板的USB口会通过5V供电如果板上没有电压转换USB收发器可能工作异常。我试验过一次表现为设备偶发无法识别最后发现是供电噪声导致加一颗去耦电容后稳定了。4.2 主机能识别但无声音频数据流未打通枚举成功后设备出现在设备管理器中“声音、视频和游戏控制器”下但没有声音输出或麦克风没有信号这时说明USB枚举没问题问题出在音频数据通路上。先说扬声器无声的情况。用示波器或逻辑分析仪看I2S的BCLK和WS信号如果I2S有波形但扬声器没声音检查ES8388的DAC输出是否被静音、增益寄存器是否配置正确。进一步看USB端数据是否进入DMA缓冲可以在uac_spk_out_callback里加一个计数变量用调试串口或Debugger输出计数值变化如果回调没触发说明主机根本没有向OUT端点发送音频确认主机音频输出设备确实选择了这个USB音频设备。麦克风无声的排查类似先用逻辑分析仪看ES8388的ADC是否有数据输出到I2S3的SD线再确认DMA是否有搬运数据最后看uac_mic_in_callback是否被触发。如果回调触发但主机收到的是一段静音大概率是DMA数据没有正确写入端点缓冲区或者音频数据位宽/对齐方式和描述符声明不一致。4.3 声音断续、卡顿与爆音音频断续和爆音是所有UAC设备调试中最磨人的问题。爆音的来源通常是等时端点数据包忽大忽小或者端点FIFO过小导致数据溢出。判断方法用调试工具周期性统计USB端点在1s内成功发送或接收的音频数据字节数。如果平均值接近480002 96000字节/秒说明数据量没问题但如果波动剧烈说明缓冲设计有缺陷。我经历过一次典型的坑I2S DMA环形缓冲区只有296字节I2S外设每读走一个缓冲区就会触发中断如果中断和USB回调用同一个优先级可能互相阻塞导致某一帧数据没有被及时消费声音出现卡顿。后来我把DMA环形缓冲区扩大到了16帧1536字节并且把I2S DMA中断优先级调低、USB等时传输回调优先级调高卡顿问题明显改善。还有就是很多工程师容易忽略的事在UAC设备播发扬声器方向主机的音频堆栈会以一定的周期批量发送多个音频帧比如每次批量发4帧。如果你的DAC环形缓冲太浅接纳不了这批数据就需要丢弃数据表现为周期性爆音。建议缓冲区至少覆盖10ms的音频数据也就是480字节以上我最后配置的是20ms1920字节稳定了不少。4.4 抓包工具与USB分析调试经验做USB音频开发一定要学会用USB抓包分析数据。Wireshark搭配USBPcap或USBTrace可以在PC端抓取主机与设备之间的USB总线数据包括枚举阶段的描述符传输、控制请求以及等时传输的数据包。抓包最常用的场景是查看枚举过程的控制传输序列是否符合UAC规范。比如主机发送GET DESCRIPTOR请求后设备返回的配置描述符是不是完整UAC类特定描述符Class-specific AC Interface Descriptor、Input Terminal Descriptor、Output Terminal Descriptor的字节是否和规范一致这些都是枚举失败的高发区域。另外抓包还能直观看到等时传输包的实际负载大小。如果发现每次IN传输返回的数据量不是96字节而是忽大忽小说明设备端缓冲区管理出了问题主机接收端必然会出现音频异常。关于具体抓包操作建议在设备枚举完成后先主动播放一段音频或录音观察等时传输包是否连续、是否有空包。根据我个人的经验空包ZLP偶尔出现一次问题不大但如果连续多次出现说明设备端数据生产跟不上需要从DMA/中断/缓冲三个环节同时找原因。4.5 与USB转串口等调试通道的共存调试UAC设备时我通常还会保留一路USB转串口比如通过FT232R或CP2102来输出实时日志但有一个问题要提前预防如果UAC设备和USB转串口同时占用USB总线等时传输会挤压批量传输的带宽。调试过程中最好把串口日志量控制到每秒不超过几十条否则可能导致USB转串口数据丢包反而干扰UAC问题的判断。更稳妥的方式是使用MCU的另一个物理串口用TTL转接板接到电脑的独立COM口这样UAC设备和调试串口走不同的USB总线一个走主板USB口另一个走USB Hub调试体验会好很多。5. 项目管理与工程化建议5.1 源码结构组织与版本管理这个项目的源码文件数量会比较多有CherryUSB协议栈源码、STM32的HAL库、CubeMX生成的初始化代码、UAC应用层代码描述符拼接、音频回调、ES8388驱动、还有调试用的串口日志模块。建议按功能模块分目录管理先让协议栈保持只读状态把每次改动集中在自己的应用目录中所有修改用Git管理并用commit信息说明改了什么。协议栈升级时只需要替换协议栈目录即可应用层代码能最大限度保持兼容。5.2 音频性能验证的实用方法功能跑通后建议做几个标准测试来验证设备性能电缆传输测试使用长距离USB线检查音频是否稳定双向同时播放和录音测试检验缓存行为是否OK长时间播放稳定性测试至少连续播放1小时音频文件观察是否出现卡顿、爆音、时钟偏移导致音频逐渐失真针对时钟漂移一个简单的手段是录一段1kHz的正弦波用Audacity等软件录制USB麦克风播放该正弦波回看录制的波形频率偏移。如果偏差在±0.1Hz以上说明时钟同步策略有风险建议从时钟硬件或软件重采样方案入手优化。5.3 后续功能扩展音量控制与多通道支持UAC设备做完麦克风扬声器的基本形态后可以继续扩展的功能包括在AC接口中实现音量控制和静音控制通过Feature Unit Descriptor描述音量调节范围配合控制传输处理主机端的SET_CUR请求就能在Windows音量滑块中动态调节设备端的ADC/DAC增益。增加多声道支持比如USB麦克风阵列2个及以上通道这要求修改描述符中的声道数并且将I2S的DMA数据以多声道交织的方式打包发送。增加采样率动态切换比如44.1kHz/48kHz/96kHz自适应这需要I2S硬件支持生成不同采样率的位时钟配合重采样算法实现。扩展的时候还是要注意UAC协议的版本选择。UAC 2.0比UAC 1.0在等时传输机制、控制请求上有较大差异Windows对UAC 2.0的原生支持虽然已经改善但兼容性测试还是要覆盖Win10/Win11/macOS/Linux多平台。如果面向广泛用户1.0版本兼容性更稳如果面向专业音频应用2.0能支持更高采样率、更大位深和更好的时钟治理机制。6. 写在最后的经验总结项目做完后我最大的感触是UAC设备开发的核心难点不在USB协议本身而在音频数据流的时钟同步与缓冲策略。USB协议栈帮你解决了描述符、枚举、传输机制这些繁琐问题但音频数据什么时候该填充、缓冲满时该丢还是该等、I2S和USB时钟不同源怎么办这些问题只能靠应用层来处理。CherryUSB的示例代码给了一个很好的起点但真正做成一个稳定的产品级设备还需要针对具体硬件、具体使用场景做大量的调优和测试。我也调试了很久才找到适合自己硬件平台的缓冲参数麦克风DMA缓冲用32帧扬声器DMA缓冲用16帧USB等时端点的FIFO根据数据量自动调整。参数上没有绝对正确的答案不同主控、不同音频编解码器、不同主机系统最合适的值都可能不同。先按前面说的规模设一个初值然后通过压力测试不断微调直到在播放和录音双开情况下不出现卡顿、爆音这就算调通了。建议手头常备一个逻辑分析仪调音频的时候看波形永远比猜代码直观。如果后续有朋友想深入了解UAC 2.0或者有关于USB音频设备开发的疑问欢迎在评论区交流我尽量把踩坑细节和经验都分享出来。