1. 项目缘起为什么嵌入式开发者需要关注USB协议栈如果你做过嵌入式项目尤其是需要和PC、手机或者其他智能设备打交道的大概率绕不开USB。从最简单的USB转串口调试到U盘、鼠标键盘再到现在的USB音频、USB网络共享这个接口几乎无处不在。但很多开发者包括我自己早期对USB的态度是“能用就行”——找个现成的芯片比如CH340、CP2102装上驱动调通串口收发项目就告一段落。至于USB协议本身总觉得那是芯片原厂或者驱动工程师该操心的事深不可测。直到你遇到这样的场景产品需要一个自定义的USB设备类型比如做一个专用的数据采集器通过USB高速传输数据到上位机或者你想在单片机上实现一个复合设备同时模拟键盘和U盘又或者你发现市面上的USB转串口芯片在特定波特率下不稳定想自己用MCU的USB外设实现一个更可靠的版本。这时候你才会发现没有对USB协议栈的理解你连调试的方向都找不到。你面对的是一堆晦涩的USB描述符、端点配置、标准请求还有令人头疼的枚举过程。这就是我接触并深入研究CherryUSB的起点。它不是一个简单的库而是一个结构清晰、可移植性强的开源USB协议栈实现。它把USB协议中那些复杂、固定的流程封装起来让你能更专注于自己的设备功能逻辑。这篇文章我就结合自己从“避之不及”到“主动拥抱”USB开发的经历拆解CherryUSB的原理并分享一套从零开始基于它进行嵌入式USB设备开发的实践指南。无论你是想彻底搞懂USB设备端开发还是手头有项目急需一个可靠的USB解决方案希望这篇长文能给你带来实实在在的帮助。2. USB设备开发的核心挑战与协议栈的价值在深入CherryUSB之前我们必须先搞清楚自己实现一个USB设备到底难在哪里。这有助于理解一个协议栈究竟为我们承担了什么。2.1 硬件层不止是两根线很多人以为USB就是D和D-两根差分数据线。没错物理连接很简单但协议极其复杂。USB通信是基于“事务”的由主机Host通常是PC绝对主导。设备Device我们的嵌入式系统永远处于被动响应状态。主机以1ms全速/高速或125us高速为周期发出帧Frame或微帧Microframe所有通信都包裹在这些时间片里。对于设备端的MCU你需要正确配置USB外设的物理层PHY设置正确的速度低速1.5Mbps、全速12Mbps、高速480Mbps并管理好多个“端点”Endpoint。端点可以理解为硬件上的数据缓冲区每个端点有独立的地址和传输类型控制、中断、批量、同步。光是配置这些硬件寄存器就足以让新手望而却步。2.2 协议层繁琐的“握手”与描述符USB设备的生命始于“枚举”。当设备插入主机主机会发起一系列标准请求设备必须一一正确回复。这个过程完全由协议规定不能出错。核心是以下几类描述符设备描述符告诉主机“我是谁”包括厂商ID、产品ID、设备类、协议版本等。配置描述符描述设备的一种工作模式供电模式、接口数量等。接口描述符定义一个功能接口比如一个HID人机接口设备接口或一个CDC通信设备类接口。端点描述符描述某个端点的类型、方向、最大包大小等。字符串描述符提供可读的厂商名、产品名等。这些描述符是一个层层嵌套的树状结构需要你在代码里以严格的格式定义好。枚举过程中主机会像查户口一样通过控制传输端点0依次索要这些描述符。任何一个描述符格式错误或响应超时枚举就会失败在设备管理器里你大概率会看到一个“未知USB设备”或者带感叹号的设备。2.3 驱动层免驱的幻觉与INF文件的现实我们常听说“免驱USB设备”其实这是个不完全准确的说法。所谓的“免驱”是指操作系统已经内置了该设备类的通用驱动程序。例如你做一个HID键盘Windows和Linux系统内核里已经有hidclass.sys等驱动能自动识别并加载无需用户额外安装。但这背后是你的设备必须严格遵循HID类的规范正确报告描述符。如果你的设备是一个自定义的、操作系统没有内置驱动的类型那么你必须为用户提供一个INF文件。这个文件告诉操作系统“这个设备的厂商ID和产品ID是多少请加载我提供的这个.sys或.dll驱动文件”。编写和签名INF文件、开发Windows内核驱动WDM/WDF或用户态驱动WinUSB, libusb又是另一个庞大的领域。2.4 CherryUSB协议栈的价值所在面对以上三层挑战CherryUSB这样的协议栈的价值就凸显出来了硬件抽象层它封装了不同MCU平台如STM32, GD32, NXP, 乐鑫ESP32-S3等的USB外设寄存器操作。你只需要实现几个底层的回调函数如端点读写、中断处理就能适配新的硬件平台。协议引擎它实现了完整的USB设备枚举状态机。你只需要按照它的格式定义好你的描述符树协议栈会自动处理主机发来的所有标准请求如GET_DESCRIPTOR,SET_CONFIGURATION你几乎不用关心枚举过程。类驱动框架它内置了常见设备类如HID, CDC, MSC, AUDIO, DFU的框架。你只需要填充类特定的回调函数例如MSC类需要实现读/写扇区的回调HID类需要实现获取报告的回调就能快速构建一个符合标准类的设备实现“免驱”。资源管理它统一管理各个端点的缓冲区、处理数据传输的完整性如拆分长包、处理NAK未就绪响应等琐碎但易错的事务。简单说CherryUSB把USB开发从“手搓汇编”级别提升到了“框架编程”级别。你不再需要直接面对原始字节流和硬件寄存器而是关注“我的设备有什么功能”这个业务逻辑。3. CherryUSB协议栈架构深度解析理解了为什么需要协议栈我们再打开CherryUSB的“引擎盖”看看它是如何工作的。它的代码结构非常清晰主要分为核心层、端口层和类层。3.1 核心层协议栈的大脑与脊柱核心层是协议栈最独立、最核心的部分与具体MCU硬件无关。它主要包含以下几个模块USB核心维护设备的全局状态未上电、上电、默认、地址已分配、已配置、挂起等处理来自主机的标准设备请求。这是协议栈的“大脑”。端点管理抽象出端点的概念提供统一的接口供上层类驱动进行数据收发。它负责管理端点的状态、缓冲区并处理传输完成、错误等事件。描述符管理提供一套描述符构造和解析的辅助工具。虽然描述符最终需要开发者定义但核心层提供了标准的描述符结构体并负责在枚举时按需返回正确的描述符数据块。DCD接口这是核心层与硬件连接的桥梁。DCD全称是Device Controller Driver。核心层通过一组定义良好的函数指针如dcd_init,dcd_ep_write,dcd_ep_read来调用底层硬件操作。这是你需要为你的MCU平台适配的主要部分。3.2 端口层硬件适配的关键端口层就是DCD接口的具体实现。CherryUSB已经为许多流行的MCU提供了现成的端口实现例如dcd_stm32.c针对STM32F0/F1/F4等系列的USB外设。dcd_rp2040.c针对树莓派Pico的RP2040芯片。dcd_esp32_sx.c针对乐鑫ESP32-S2/S3的USB-OTG外设。如果你使用的MCU不在支持列表里就需要自己实现一个端口层。这通常是移植CherryUSB最具技术挑战的一步但也是有固定模式的实现USB外设的初始化时钟、引脚、中断。实现端点配置函数根据核心层的请求配置硬件端点的类型、大小和地址。实现端点数据发送函数将数据写入硬件FIFO并启动传输。实现端点数据接收准备函数配置硬件以接收数据。实现USB全局中断服务程序并在其中处理诸如“复位”、“挂起”、“唤醒”、“传输完成”等事件然后调用核心层提供的回调函数如dcd_event_handler来通知上层。实操心得移植端口层时最需要参考的就是原厂提供的USB库例程和参考手册。CherryUSB的端口层代码本质上是将原厂库的“过程式”调用封装成符合DCD接口的“模块化”函数。重点关注中断处理流程和端点缓冲区的管理这两处最容易出问题。3.3 类层实现具体功能的积木类层建立在核心层之上实现了各种USB设备类的规范。这是开发者打交道最多的部分。CherryUSB提供的类驱动像一个个积木CDC ACM实现USB转串口功能。这是最常用的类之一可以让你设备在电脑上显示为一个COM口。HID实现键盘、鼠标、游戏手柄等。数据传输速率不高但实时性好且绝对“免驱”。MSC实现U盘功能。你需要提供存储介质的读/写/擦除接口。AUDIO实现USB麦克风、扬声器。涉及同步端点对时序要求高。DFU实现设备固件升级。可以通过USB直接更新设备程序非常实用。每个类驱动都提供了一套标准化的接口。以HID为例你需要定义一个符合HID规范的报告描述符描述按键、鼠标移动等数据结构。实现set_report和get_report的回调函数。在应用层当你需要发送一个按键事件时调用hid_report_send函数并填充好报告数据即可。类驱动会处理好剩下的传输事务。3.4 数据流一次发送是如何完成的让我们以设备通过CDC类虚拟串口向上位机发送数据“Hello”为例串联起整个协议栈的工作流程应用层你的应用程序调用cdc_acm_write(“Hello”)。类层CDC ACM类驱动收到数据检查当前使用的批量输出端点是否空闲。如果空闲它调用核心层的端点管理接口usbd_ep_write(ep_addr, “Hello”, len)。核心层核心层找到对应端点的结构体将数据放入该端点的软件缓冲区然后调用DCD接口的函数指针dcd_ep_write(ep_addr, buffer, len)。端口层dcd_ep_write的具体实现会将数据拷贝到MCU USB外设对应端点的硬件FIFO中并启动传输。硬件层USB外设根据USB协议在主机下一次轮询到这个端点时将数据包通过差分线发送出去。中断回调传输完成后USB硬件产生中断。端口层的中断服务程序捕获该事件调用核心层的传输完成回调usbd_event_handler(USB_EVENT_XFER_COMPLETE, ep_addr)。核心层 - 类层核心层通过事件机制通知CDC ACM类驱动“某端点传输完成”。类驱动可以据此释放缓冲区或准备下一次发送。整个过程对应用层几乎是透明的你只需要关心“发数据”和“收数据”这两个动作。4. 从零构建一个USB-CDC设备实战指南理论讲得再多不如动手做一遍。我们以最常见的STM32F103C8T6蓝色药丸板为例使用CherryUSB实现一个USB虚拟串口CDC ACM设备。这个设备插入电脑后会识别为一个COM口我们可以用串口助手与之通信。4.1 环境准备与工程搭建首先你需要一个基本的开发环境。我使用的是STM32CubeIDE但任何支持ARM GCC的工具链如Keil, IAR, VSCodePlatformIO都可以。获取CherryUSB源码从GitHub仓库克隆或下载CherryUSB最新版本。创建工程在STM32CubeIDE中创建一个基于STM32F103C8的空白工程。使用CubeMX配置时钟外部晶振8MHzPLL到72MHz并启用USB外设。关键配置如下USB模式Device OnlySpeedFull-speedUSB_DP引脚PA12 USB_DM引脚PA11这是固定的在Project Manager-Code Generator中选择“Copy only necessary library files”以减少代码体积。集成CherryUSB文件将CherryUSB的core/port/class/目录拷贝到你的工程目录下。重点关注core/所有核心文件。port/dcd_stm32.cSTM32的端口层实现。class/cdcCDC类驱动。common/usb_util.c等辅助文件。添加头文件路径在IDE的工程属性中添加CherryUSB各模块的包含路径。处理冲突STM32CubeMX生成的代码会包含一个usbd_conf.c和usbd_desc.c以及HAL库的USB设备库。CherryUSB不需要这些。我们需要做的是在main.c中不调用MX_USB_DEVICE_Init()。删除或排除掉usbd_conf.c和usbd_desc.c文件。确保链接了HAL库中USB外设的底层驱动如stm32f1xx_hal_pcd.c因为CherryUSB的dcd_stm32.c底层会调用HAL库的函数。4.2 描述符定义设备的“身份证”这是最关键的一步。我们在usbd_cdc.c可以自己新建中定义描述符。一个CDC设备至少需要两个接口一个通信接口用于发送AT命令和一个数据接口用于传输实际数据。// 设备描述符 const uint8_t cdc_descriptor[] { // 1. 设备描述符 USB_DEVICE_DESCRIPTOR_INIT(USB_2_0, 0xEF, 0x02, 0x01, 0x2000, 0x1234, 0x5678, 0x0100, 1, 2, 3, 1), // 2. 配置描述符总长度需要计算 USB_CONFIG_DESCRIPTOR_INIT(0x43, 0x02, 0x01, USB_CONFIG_BUS_POWERED, 100), // 2.1 通信接口 USB_INTERFACE_DESCRIPTOR_INIT(0x00, 0x00, 0x01, USB_DEVICE_CLASS_CDC, CDC_COMM_SUBCLASS_ACM, CDC_COMM_PROTOCOL_ATCOMMAND, 0x00), // 通信接口的类特定描述符功能描述符 CDC_ACM_HEADER_DESCRIPTOR_INIT(0x0110), CDC_ACM_CALL_MANAGEMENT_DESCRIPTOR_INIT(0x01, 0x01), CDC_ACM_ABSTRACT_CONTROL_MANAGEMENT_DESCRIPTOR_INIT(0x02), CDC_ACM_UNION_DESCRIPTOR_INIT(0x00, 0x01), // 通信接口的端点通知端点中断传输 USB_ENDPOINT_DESCRIPTOR_INIT(0x81, USB_ENDPOINT_TYPE_INTERRUPT, 0x08, 0x0A), // 2.2 数据接口 USB_INTERFACE_DESCRIPTOR_INIT(0x01, 0x00, 0x02, USB_DEVICE_CLASS_CDC_DATA, 0x00, 0x00, 0x00), // 数据接口的端点批量输出PC - 设备 USB_ENDPOINT_DESCRIPTOR_INIT(0x02, USB_ENDPOINT_TYPE_BULK, 0x40, 0x00), // 数据接口的端点批量输入设备 - PC USB_ENDPOINT_DESCRIPTOR_INIT(0x82, USB_ENDPOINT_TYPE_BULK, 0x40, 0x00), // 3. 字符串描述符可选但建议有 USB_LANGID_INIT(USBD_LANGID_STRING), USB_STRING_DESCRIPTOR_INIT(1, ‘C‘), // 厂商字符串索引1 USB_STRING_DESCRIPTOR_INIT(2, ‘C‘), // 产品字符串索引2 USB_STRING_DESCRIPTOR_INIT(3, ‘1‘), // 序列号字符串索引3 };注意上面的描述符是一个简化示例总长度0x43需要根据你实际的定义精确计算。CherryUSB的usb_util.h中提供了很多宏来简化描述符构造务必仔细阅读其注释。4.3 初始化与主循环让设备“活”起来在main.c中我们需要初始化CherryUSB协议栈并实现应用逻辑。#include “cherryusb.h“ #include “cdc_acm.h“ // 定义USB设备实例和CDC类实例 static struct usbd_device *usbd_dev; static struct cdc_acm_dev acm_dev; // CDC ACM类的回调函数 static void cdc_acm_data_received(uint8_t ep, uint32_t len) { uint8_t buf[64]; // 从端点缓冲区读取数据 usbd_ep_read(ep, buf, len); // 这里可以处理接收到的数据例如回显 cdc_acm_write(acm_dev, buf, len); } int main(void) { HAL_Init(); SystemClock_Config(); // 系统时钟配置必须保证USB时钟为48MHz // 1. 初始化USB设备核心 usbd_dev usbd_device_create(); // 2. 添加描述符 usbd_device_add_descriptor(usbd_dev, cdc_descriptor, sizeof(cdc_descriptor)); // 3. 添加CDC ACM类驱动 cdc_acm_init(acm_dev, usbd_dev, cdc_acm_data_received); // 4. 启动USB设备 usbd_device_init(usbd_dev); while (1) { // USB事务处理在中断中完成主循环可以处理其他任务 // 也可以在这里调用 cdc_acm_write 主动发送数据 HAL_Delay(1000); cdc_acm_write(acm_dev, (uint8_t*)Tick\r\n, 6); } }4.4 调试与排错当设备无法识别时第一次尝试设备很可能无法被电脑识别。别慌这是USB开发的常态。按照以下步骤排查检查硬件连接确保DPPA12和DMPA11线连接正确且USB端口供电稳定。STM32F103的USB需要从USB总线取电或者通过VBUS引脚PA9检测到5V电压。检查时钟USB模块需要精确的48MHz时钟。对于STM32F103需要将72MHz的系统时钟通过分频提供给USB。在SystemClock_Config()中确保RCC_PLLMul设置为x98MHz * 9 72MHz并且RCC_USBCLKSource设置为RCC_USBCLKSource_PLLCLK_1Div572MHz / 1.5 48MHz。这是最常出错的地方使用USB分析仪如果条件允许使用诸如Beagle USB、Ellisys之类的USB协议分析仪是终极武器。它能抓取总线上的每一个数据包让你看到主机到底发了什么请求设备又回复了什么。没有分析仪时我们只能靠“盲调”。利用CherryUSB的日志在usbd_core.c等文件中有很多USB_LOG宏。确保在usb_config.h中打开调试日志如#define CONFIG_USB_DBG_LEVEL USB_DBG_INFO并通过串口非USB打印出来。观察枚举过程在哪一步卡住了。描述符验证使用USBlyzer或Wireshark需要USBPcap驱动等软件在电脑端抓取USB枚举流量。虽然不如硬件分析仪精确但有时能看到主机请求和设备的回复对比你的描述符数据是否正确。枚举失败常见原因设备描述符请求失败通常是设备没有及时响应GET_DESCRIPTOR(Device)请求。检查USB中断是否使能端点0的收发处理函数是否正确。未知USB设备设备描述符回复了但后续请求如配置描述符出错。检查描述符的总长度、层次结构是否正确特别是配置描述符集合的wTotalLength字段。代码10错误设备无法启动。通常是配置描述符中声明的接口或端点在硬件上没有正确初始化。检查dcd_ep_open等端口层函数是否被成功调用。5. 进阶应用与性能优化当你的第一个USB设备跑通后可以尝试更复杂的应用并思考如何优化。5.1 实现复合设备一芯多能复合设备是指一个物理USB设备在主机看来是多个独立功能的集合。例如一个设备同时是键盘和U盘。在CherryUSB中实现复合设备非常直观描述符合并将多个设备类如HID和MSC的描述符按顺序放在同一个配置描述符集合中。每个类占用独立的接口Interface。例如接口0为HID键盘接口1为MSC大容量存储。初始化多个类驱动在main函数中依次调用hid_init()和msc_init()并传入同一个usbd_device实例。处理类事件每个类驱动会注册自己的回调。核心层会根据主机请求的接口号将请求分发到对应的类驱动进行处理。关键在于在配置描述符中你需要为每个接口分配不同的接口编号并在USB_INTERFACE_DESCRIPTOR_INIT宏中正确设置。5.2 高速传输与缓冲区管理对于需要高速传输数据的应用如虚拟网卡、摄像头使用批量传输端点并优化缓冲区管理至关重要。双缓冲/多缓冲CherryUSB的端口层和核心层支持端点的双缓冲机制。当硬件正在发送一个缓冲区数据时软件可以填充下一个缓冲区从而实现“乒乓操作”几乎消除总线空闲时间极大提升吞吐量。在实现dcd_ep_write时需要检查并利用硬件是否支持此特性。合理设置包大小USB全速批量端点的最大包大小是64字节高速是512字节。在端点描述符中应设置为允许的最大值。对于大数据量传输协议栈和主机驱动会自动进行分包和重组。零长度包当数据长度恰好是包大小的整数倍时必须发送一个零长度包来告知主机传输结束。CherryUSB的核心层通常会帮你处理这个细节但了解这个机制有助于调试。5.3 低功耗与唤醒对于电池供电的设备USB挂起和唤醒功能是必须的。挂起当总线空闲超过3ms主机发送挂起信号。USB外设会产生挂起中断。在端口层的中断服务程序中需要检测此事件并调用usbd_event_handler(USB_EVENT_SUSPEND, 0)。此时你可以让MCU进入低功耗模式如Stop模式。唤醒主机通过发送恢复信号恢复K状态或设备远程唤醒设备驱动D线来唤醒总线。端口层需要检测唤醒事件并调用usbd_event_handler(USB_EVENT_RESUME, 0)。协议栈会恢复内部状态。CherryUSB的支持协议栈核心层处理了挂起和唤醒的状态切换。你只需要在端口层正确上报事件并在应用层根据USB_EVENT_SUSPEND和USB_EVENT_RESUME事件执行进入和退出低功耗模式的代码即可。6. 踩坑实录那些协议栈不会告诉你的细节最后分享几个我在实际项目中踩过的坑这些在官方文档或代码注释里往往不会写明。坑一端点地址的方向位混淆USB端点地址是一个8位值最高位表示方向1IN设备到主机0OUT主机到设备。例如0x81是一个IN端点0x02是一个OUT端点。在配置描述符和代码中这个地址必须与硬件端点的实际配置完全匹配。我曾经因为将0x82错写成0x02导致数据发送不出去调试了半天。记住描述符里的端点地址必须和你在dcd_ep_open函数中打开的硬件端点地址一致。坑二字符串描述符的索引字符串描述符是可选的但一旦使用索引号就不能出错。设备描述符中的iManufacturer,iProduct,iSerialNumber字段指向的是字符串描述符的索引。这个索引是从1开始的0保留给语言ID。如果你定义了三个字符串索引分别是123但在设备描述符里把iProduct写成了4电脑可能显示不出产品名或者直接枚举失败。坑三控制传输的状态阶段控制传输分为建立阶段、数据阶段和状态阶段。对于没有数据阶段的控制请求如SET_CONFIGURATION设备在状态阶段需要返回一个ACK。CherryUSB的核心层已经处理了绝大多数情况。但如果你需要自己处理一些厂商自定义的请求必须注意在请求处理函数的最后不要忘记调用usbd_ep_write(EP0_IN, NULL, 0)或usbd_ep_read(EP0_OUT, NULL, 0)来主动完成状态阶段。否则主机会一直等待导致超时。坑四中断的优先级与延迟USB中断对实时性要求很高。特别是全速USB的帧周期是1ms主机每1ms就会查询一次中断端点。如果你的USB中断被其他更高优先级的中断长时间阻塞可能会导致数据传输丢失或枚举失败。务必在系统设计时给USB中断分配一个足够高的优先级。坑五内存对齐与结构体打包USB描述符是“打包”的数据结构编译器默认可能会在结构体成员之间插入填充字节以满足对齐要求这会导致描述符长度和内容错误。在定义描述符结构体时必须使用编译器指令如GCC的__attribute__((packed))或IAR的#pragma pack(1)来确保单字节对齐。CherryUSB提供的描述符宏已经处理了这个问题但如果你自己定义复杂的类特定描述符一定要留意。 
长河君 · 2026/8/8 2:32:19 · 阅读 1.2k 嵌入式USB设备开发实战：从协议栈原理到CherryUSB应用指南
1. 项目缘起为什么嵌入式开发者需要关注USB协议栈如果你做过嵌入式项目尤其是需要和PC、手机或者其他智能设备打交道的大概率绕不开USB。从最简单的USB转串口调试到U盘、鼠标键盘再到现在的USB音频、USB网络共享这个接口几乎无处不在。但很多开发者包括我自己早期对USB的态度是“能用就行”——找个现成的芯片比如CH340、CP2102装上驱动调通串口收发项目就告一段落。至于USB协议本身总觉得那是芯片原厂或者驱动工程师该操心的事深不可测。直到你遇到这样的场景产品需要一个自定义的USB设备类型比如做一个专用的数据采集器通过USB高速传输数据到上位机或者你想在单片机上实现一个复合设备同时模拟键盘和U盘又或者你发现市面上的USB转串口芯片在特定波特率下不稳定想自己用MCU的USB外设实现一个更可靠的版本。这时候你才会发现没有对USB协议栈的理解你连调试的方向都找不到。你面对的是一堆晦涩的USB描述符、端点配置、标准请求还有令人头疼的枚举过程。这就是我接触并深入研究CherryUSB的起点。它不是一个简单的库而是一个结构清晰、可移植性强的开源USB协议栈实现。它把USB协议中那些复杂、固定的流程封装起来让你能更专注于自己的设备功能逻辑。这篇文章我就结合自己从“避之不及”到“主动拥抱”USB开发的经历拆解CherryUSB的原理并分享一套从零开始基于它进行嵌入式USB设备开发的实践指南。无论你是想彻底搞懂USB设备端开发还是手头有项目急需一个可靠的USB解决方案希望这篇长文能给你带来实实在在的帮助。2. USB设备开发的核心挑战与协议栈的价值在深入CherryUSB之前我们必须先搞清楚自己实现一个USB设备到底难在哪里。这有助于理解一个协议栈究竟为我们承担了什么。2.1 硬件层不止是两根线很多人以为USB就是D和D-两根差分数据线。没错物理连接很简单但协议极其复杂。USB通信是基于“事务”的由主机Host通常是PC绝对主导。设备Device我们的嵌入式系统永远处于被动响应状态。主机以1ms全速/高速或125us高速为周期发出帧Frame或微帧Microframe所有通信都包裹在这些时间片里。对于设备端的MCU你需要正确配置USB外设的物理层PHY设置正确的速度低速1.5Mbps、全速12Mbps、高速480Mbps并管理好多个“端点”Endpoint。端点可以理解为硬件上的数据缓冲区每个端点有独立的地址和传输类型控制、中断、批量、同步。光是配置这些硬件寄存器就足以让新手望而却步。2.2 协议层繁琐的“握手”与描述符USB设备的生命始于“枚举”。当设备插入主机主机会发起一系列标准请求设备必须一一正确回复。这个过程完全由协议规定不能出错。核心是以下几类描述符设备描述符告诉主机“我是谁”包括厂商ID、产品ID、设备类、协议版本等。配置描述符描述设备的一种工作模式供电模式、接口数量等。接口描述符定义一个功能接口比如一个HID人机接口设备接口或一个CDC通信设备类接口。端点描述符描述某个端点的类型、方向、最大包大小等。字符串描述符提供可读的厂商名、产品名等。这些描述符是一个层层嵌套的树状结构需要你在代码里以严格的格式定义好。枚举过程中主机会像查户口一样通过控制传输端点0依次索要这些描述符。任何一个描述符格式错误或响应超时枚举就会失败在设备管理器里你大概率会看到一个“未知USB设备”或者带感叹号的设备。2.3 驱动层免驱的幻觉与INF文件的现实我们常听说“免驱USB设备”其实这是个不完全准确的说法。所谓的“免驱”是指操作系统已经内置了该设备类的通用驱动程序。例如你做一个HID键盘Windows和Linux系统内核里已经有hidclass.sys等驱动能自动识别并加载无需用户额外安装。但这背后是你的设备必须严格遵循HID类的规范正确报告描述符。如果你的设备是一个自定义的、操作系统没有内置驱动的类型那么你必须为用户提供一个INF文件。这个文件告诉操作系统“这个设备的厂商ID和产品ID是多少请加载我提供的这个.sys或.dll驱动文件”。编写和签名INF文件、开发Windows内核驱动WDM/WDF或用户态驱动WinUSB, libusb又是另一个庞大的领域。2.4 CherryUSB协议栈的价值所在面对以上三层挑战CherryUSB这样的协议栈的价值就凸显出来了硬件抽象层它封装了不同MCU平台如STM32, GD32, NXP, 乐鑫ESP32-S3等的USB外设寄存器操作。你只需要实现几个底层的回调函数如端点读写、中断处理就能适配新的硬件平台。协议引擎它实现了完整的USB设备枚举状态机。你只需要按照它的格式定义好你的描述符树协议栈会自动处理主机发来的所有标准请求如GET_DESCRIPTOR,SET_CONFIGURATION你几乎不用关心枚举过程。类驱动框架它内置了常见设备类如HID, CDC, MSC, AUDIO, DFU的框架。你只需要填充类特定的回调函数例如MSC类需要实现读/写扇区的回调HID类需要实现获取报告的回调就能快速构建一个符合标准类的设备实现“免驱”。资源管理它统一管理各个端点的缓冲区、处理数据传输的完整性如拆分长包、处理NAK未就绪响应等琐碎但易错的事务。简单说CherryUSB把USB开发从“手搓汇编”级别提升到了“框架编程”级别。你不再需要直接面对原始字节流和硬件寄存器而是关注“我的设备有什么功能”这个业务逻辑。3. CherryUSB协议栈架构深度解析理解了为什么需要协议栈我们再打开CherryUSB的“引擎盖”看看它是如何工作的。它的代码结构非常清晰主要分为核心层、端口层和类层。3.1 核心层协议栈的大脑与脊柱核心层是协议栈最独立、最核心的部分与具体MCU硬件无关。它主要包含以下几个模块USB核心维护设备的全局状态未上电、上电、默认、地址已分配、已配置、挂起等处理来自主机的标准设备请求。这是协议栈的“大脑”。端点管理抽象出端点的概念提供统一的接口供上层类驱动进行数据收发。它负责管理端点的状态、缓冲区并处理传输完成、错误等事件。描述符管理提供一套描述符构造和解析的辅助工具。虽然描述符最终需要开发者定义但核心层提供了标准的描述符结构体并负责在枚举时按需返回正确的描述符数据块。DCD接口这是核心层与硬件连接的桥梁。DCD全称是Device Controller Driver。核心层通过一组定义良好的函数指针如dcd_init,dcd_ep_write,dcd_ep_read来调用底层硬件操作。这是你需要为你的MCU平台适配的主要部分。3.2 端口层硬件适配的关键端口层就是DCD接口的具体实现。CherryUSB已经为许多流行的MCU提供了现成的端口实现例如dcd_stm32.c针对STM32F0/F1/F4等系列的USB外设。dcd_rp2040.c针对树莓派Pico的RP2040芯片。dcd_esp32_sx.c针对乐鑫ESP32-S2/S3的USB-OTG外设。如果你使用的MCU不在支持列表里就需要自己实现一个端口层。这通常是移植CherryUSB最具技术挑战的一步但也是有固定模式的实现USB外设的初始化时钟、引脚、中断。实现端点配置函数根据核心层的请求配置硬件端点的类型、大小和地址。实现端点数据发送函数将数据写入硬件FIFO并启动传输。实现端点数据接收准备函数配置硬件以接收数据。实现USB全局中断服务程序并在其中处理诸如“复位”、“挂起”、“唤醒”、“传输完成”等事件然后调用核心层提供的回调函数如dcd_event_handler来通知上层。实操心得移植端口层时最需要参考的就是原厂提供的USB库例程和参考手册。CherryUSB的端口层代码本质上是将原厂库的“过程式”调用封装成符合DCD接口的“模块化”函数。重点关注中断处理流程和端点缓冲区的管理这两处最容易出问题。3.3 类层实现具体功能的积木类层建立在核心层之上实现了各种USB设备类的规范。这是开发者打交道最多的部分。CherryUSB提供的类驱动像一个个积木CDC ACM实现USB转串口功能。这是最常用的类之一可以让你设备在电脑上显示为一个COM口。HID实现键盘、鼠标、游戏手柄等。数据传输速率不高但实时性好且绝对“免驱”。MSC实现U盘功能。你需要提供存储介质的读/写/擦除接口。AUDIO实现USB麦克风、扬声器。涉及同步端点对时序要求高。DFU实现设备固件升级。可以通过USB直接更新设备程序非常实用。每个类驱动都提供了一套标准化的接口。以HID为例你需要定义一个符合HID规范的报告描述符描述按键、鼠标移动等数据结构。实现set_report和get_report的回调函数。在应用层当你需要发送一个按键事件时调用hid_report_send函数并填充好报告数据即可。类驱动会处理好剩下的传输事务。3.4 数据流一次发送是如何完成的让我们以设备通过CDC类虚拟串口向上位机发送数据“Hello”为例串联起整个协议栈的工作流程应用层你的应用程序调用cdc_acm_write(“Hello”)。类层CDC ACM类驱动收到数据检查当前使用的批量输出端点是否空闲。如果空闲它调用核心层的端点管理接口usbd_ep_write(ep_addr, “Hello”, len)。核心层核心层找到对应端点的结构体将数据放入该端点的软件缓冲区然后调用DCD接口的函数指针dcd_ep_write(ep_addr, buffer, len)。端口层dcd_ep_write的具体实现会将数据拷贝到MCU USB外设对应端点的硬件FIFO中并启动传输。硬件层USB外设根据USB协议在主机下一次轮询到这个端点时将数据包通过差分线发送出去。中断回调传输完成后USB硬件产生中断。端口层的中断服务程序捕获该事件调用核心层的传输完成回调usbd_event_handler(USB_EVENT_XFER_COMPLETE, ep_addr)。核心层 - 类层核心层通过事件机制通知CDC ACM类驱动“某端点传输完成”。类驱动可以据此释放缓冲区或准备下一次发送。整个过程对应用层几乎是透明的你只需要关心“发数据”和“收数据”这两个动作。4. 从零构建一个USB-CDC设备实战指南理论讲得再多不如动手做一遍。我们以最常见的STM32F103C8T6蓝色药丸板为例使用CherryUSB实现一个USB虚拟串口CDC ACM设备。这个设备插入电脑后会识别为一个COM口我们可以用串口助手与之通信。4.1 环境准备与工程搭建首先你需要一个基本的开发环境。我使用的是STM32CubeIDE但任何支持ARM GCC的工具链如Keil, IAR, VSCodePlatformIO都可以。获取CherryUSB源码从GitHub仓库克隆或下载CherryUSB最新版本。创建工程在STM32CubeIDE中创建一个基于STM32F103C8的空白工程。使用CubeMX配置时钟外部晶振8MHzPLL到72MHz并启用USB外设。关键配置如下USB模式Device OnlySpeedFull-speedUSB_DP引脚PA12 USB_DM引脚PA11这是固定的在Project Manager-Code Generator中选择“Copy only necessary library files”以减少代码体积。集成CherryUSB文件将CherryUSB的core/port/class/目录拷贝到你的工程目录下。重点关注core/所有核心文件。port/dcd_stm32.cSTM32的端口层实现。class/cdcCDC类驱动。common/usb_util.c等辅助文件。添加头文件路径在IDE的工程属性中添加CherryUSB各模块的包含路径。处理冲突STM32CubeMX生成的代码会包含一个usbd_conf.c和usbd_desc.c以及HAL库的USB设备库。CherryUSB不需要这些。我们需要做的是在main.c中不调用MX_USB_DEVICE_Init()。删除或排除掉usbd_conf.c和usbd_desc.c文件。确保链接了HAL库中USB外设的底层驱动如stm32f1xx_hal_pcd.c因为CherryUSB的dcd_stm32.c底层会调用HAL库的函数。4.2 描述符定义设备的“身份证”这是最关键的一步。我们在usbd_cdc.c可以自己新建中定义描述符。一个CDC设备至少需要两个接口一个通信接口用于发送AT命令和一个数据接口用于传输实际数据。// 设备描述符 const uint8_t cdc_descriptor[] { // 1. 设备描述符 USB_DEVICE_DESCRIPTOR_INIT(USB_2_0, 0xEF, 0x02, 0x01, 0x2000, 0x1234, 0x5678, 0x0100, 1, 2, 3, 1), // 2. 配置描述符总长度需要计算 USB_CONFIG_DESCRIPTOR_INIT(0x43, 0x02, 0x01, USB_CONFIG_BUS_POWERED, 100), // 2.1 通信接口 USB_INTERFACE_DESCRIPTOR_INIT(0x00, 0x00, 0x01, USB_DEVICE_CLASS_CDC, CDC_COMM_SUBCLASS_ACM, CDC_COMM_PROTOCOL_ATCOMMAND, 0x00), // 通信接口的类特定描述符功能描述符 CDC_ACM_HEADER_DESCRIPTOR_INIT(0x0110), CDC_ACM_CALL_MANAGEMENT_DESCRIPTOR_INIT(0x01, 0x01), CDC_ACM_ABSTRACT_CONTROL_MANAGEMENT_DESCRIPTOR_INIT(0x02), CDC_ACM_UNION_DESCRIPTOR_INIT(0x00, 0x01), // 通信接口的端点通知端点中断传输 USB_ENDPOINT_DESCRIPTOR_INIT(0x81, USB_ENDPOINT_TYPE_INTERRUPT, 0x08, 0x0A), // 2.2 数据接口 USB_INTERFACE_DESCRIPTOR_INIT(0x01, 0x00, 0x02, USB_DEVICE_CLASS_CDC_DATA, 0x00, 0x00, 0x00), // 数据接口的端点批量输出PC - 设备 USB_ENDPOINT_DESCRIPTOR_INIT(0x02, USB_ENDPOINT_TYPE_BULK, 0x40, 0x00), // 数据接口的端点批量输入设备 - PC USB_ENDPOINT_DESCRIPTOR_INIT(0x82, USB_ENDPOINT_TYPE_BULK, 0x40, 0x00), // 3. 字符串描述符可选但建议有 USB_LANGID_INIT(USBD_LANGID_STRING), USB_STRING_DESCRIPTOR_INIT(1, ‘C‘), // 厂商字符串索引1 USB_STRING_DESCRIPTOR_INIT(2, ‘C‘), // 产品字符串索引2 USB_STRING_DESCRIPTOR_INIT(3, ‘1‘), // 序列号字符串索引3 };注意上面的描述符是一个简化示例总长度0x43需要根据你实际的定义精确计算。CherryUSB的usb_util.h中提供了很多宏来简化描述符构造务必仔细阅读其注释。4.3 初始化与主循环让设备“活”起来在main.c中我们需要初始化CherryUSB协议栈并实现应用逻辑。#include “cherryusb.h“ #include “cdc_acm.h“ // 定义USB设备实例和CDC类实例 static struct usbd_device *usbd_dev; static struct cdc_acm_dev acm_dev; // CDC ACM类的回调函数 static void cdc_acm_data_received(uint8_t ep, uint32_t len) { uint8_t buf[64]; // 从端点缓冲区读取数据 usbd_ep_read(ep, buf, len); // 这里可以处理接收到的数据例如回显 cdc_acm_write(acm_dev, buf, len); } int main(void) { HAL_Init(); SystemClock_Config(); // 系统时钟配置必须保证USB时钟为48MHz // 1. 初始化USB设备核心 usbd_dev usbd_device_create(); // 2. 添加描述符 usbd_device_add_descriptor(usbd_dev, cdc_descriptor, sizeof(cdc_descriptor)); // 3. 添加CDC ACM类驱动 cdc_acm_init(acm_dev, usbd_dev, cdc_acm_data_received); // 4. 启动USB设备 usbd_device_init(usbd_dev); while (1) { // USB事务处理在中断中完成主循环可以处理其他任务 // 也可以在这里调用 cdc_acm_write 主动发送数据 HAL_Delay(1000); cdc_acm_write(acm_dev, (uint8_t*)Tick\r\n, 6); } }4.4 调试与排错当设备无法识别时第一次尝试设备很可能无法被电脑识别。别慌这是USB开发的常态。按照以下步骤排查检查硬件连接确保DPPA12和DMPA11线连接正确且USB端口供电稳定。STM32F103的USB需要从USB总线取电或者通过VBUS引脚PA9检测到5V电压。检查时钟USB模块需要精确的48MHz时钟。对于STM32F103需要将72MHz的系统时钟通过分频提供给USB。在SystemClock_Config()中确保RCC_PLLMul设置为x98MHz * 9 72MHz并且RCC_USBCLKSource设置为RCC_USBCLKSource_PLLCLK_1Div572MHz / 1.5 48MHz。这是最常出错的地方使用USB分析仪如果条件允许使用诸如Beagle USB、Ellisys之类的USB协议分析仪是终极武器。它能抓取总线上的每一个数据包让你看到主机到底发了什么请求设备又回复了什么。没有分析仪时我们只能靠“盲调”。利用CherryUSB的日志在usbd_core.c等文件中有很多USB_LOG宏。确保在usb_config.h中打开调试日志如#define CONFIG_USB_DBG_LEVEL USB_DBG_INFO并通过串口非USB打印出来。观察枚举过程在哪一步卡住了。描述符验证使用USBlyzer或Wireshark需要USBPcap驱动等软件在电脑端抓取USB枚举流量。虽然不如硬件分析仪精确但有时能看到主机请求和设备的回复对比你的描述符数据是否正确。枚举失败常见原因设备描述符请求失败通常是设备没有及时响应GET_DESCRIPTOR(Device)请求。检查USB中断是否使能端点0的收发处理函数是否正确。未知USB设备设备描述符回复了但后续请求如配置描述符出错。检查描述符的总长度、层次结构是否正确特别是配置描述符集合的wTotalLength字段。代码10错误设备无法启动。通常是配置描述符中声明的接口或端点在硬件上没有正确初始化。检查dcd_ep_open等端口层函数是否被成功调用。5. 进阶应用与性能优化当你的第一个USB设备跑通后可以尝试更复杂的应用并思考如何优化。5.1 实现复合设备一芯多能复合设备是指一个物理USB设备在主机看来是多个独立功能的集合。例如一个设备同时是键盘和U盘。在CherryUSB中实现复合设备非常直观描述符合并将多个设备类如HID和MSC的描述符按顺序放在同一个配置描述符集合中。每个类占用独立的接口Interface。例如接口0为HID键盘接口1为MSC大容量存储。初始化多个类驱动在main函数中依次调用hid_init()和msc_init()并传入同一个usbd_device实例。处理类事件每个类驱动会注册自己的回调。核心层会根据主机请求的接口号将请求分发到对应的类驱动进行处理。关键在于在配置描述符中你需要为每个接口分配不同的接口编号并在USB_INTERFACE_DESCRIPTOR_INIT宏中正确设置。5.2 高速传输与缓冲区管理对于需要高速传输数据的应用如虚拟网卡、摄像头使用批量传输端点并优化缓冲区管理至关重要。双缓冲/多缓冲CherryUSB的端口层和核心层支持端点的双缓冲机制。当硬件正在发送一个缓冲区数据时软件可以填充下一个缓冲区从而实现“乒乓操作”几乎消除总线空闲时间极大提升吞吐量。在实现dcd_ep_write时需要检查并利用硬件是否支持此特性。合理设置包大小USB全速批量端点的最大包大小是64字节高速是512字节。在端点描述符中应设置为允许的最大值。对于大数据量传输协议栈和主机驱动会自动进行分包和重组。零长度包当数据长度恰好是包大小的整数倍时必须发送一个零长度包来告知主机传输结束。CherryUSB的核心层通常会帮你处理这个细节但了解这个机制有助于调试。5.3 低功耗与唤醒对于电池供电的设备USB挂起和唤醒功能是必须的。挂起当总线空闲超过3ms主机发送挂起信号。USB外设会产生挂起中断。在端口层的中断服务程序中需要检测此事件并调用usbd_event_handler(USB_EVENT_SUSPEND, 0)。此时你可以让MCU进入低功耗模式如Stop模式。唤醒主机通过发送恢复信号恢复K状态或设备远程唤醒设备驱动D线来唤醒总线。端口层需要检测唤醒事件并调用usbd_event_handler(USB_EVENT_RESUME, 0)。协议栈会恢复内部状态。CherryUSB的支持协议栈核心层处理了挂起和唤醒的状态切换。你只需要在端口层正确上报事件并在应用层根据USB_EVENT_SUSPEND和USB_EVENT_RESUME事件执行进入和退出低功耗模式的代码即可。6. 踩坑实录那些协议栈不会告诉你的细节最后分享几个我在实际项目中踩过的坑这些在官方文档或代码注释里往往不会写明。坑一端点地址的方向位混淆USB端点地址是一个8位值最高位表示方向1IN设备到主机0OUT主机到设备。例如0x81是一个IN端点0x02是一个OUT端点。在配置描述符和代码中这个地址必须与硬件端点的实际配置完全匹配。我曾经因为将0x82错写成0x02导致数据发送不出去调试了半天。记住描述符里的端点地址必须和你在dcd_ep_open函数中打开的硬件端点地址一致。坑二字符串描述符的索引字符串描述符是可选的但一旦使用索引号就不能出错。设备描述符中的iManufacturer,iProduct,iSerialNumber字段指向的是字符串描述符的索引。这个索引是从1开始的0保留给语言ID。如果你定义了三个字符串索引分别是123但在设备描述符里把iProduct写成了4电脑可能显示不出产品名或者直接枚举失败。坑三控制传输的状态阶段控制传输分为建立阶段、数据阶段和状态阶段。对于没有数据阶段的控制请求如SET_CONFIGURATION设备在状态阶段需要返回一个ACK。CherryUSB的核心层已经处理了绝大多数情况。但如果你需要自己处理一些厂商自定义的请求必须注意在请求处理函数的最后不要忘记调用usbd_ep_write(EP0_IN, NULL, 0)或usbd_ep_read(EP0_OUT, NULL, 0)来主动完成状态阶段。否则主机会一直等待导致超时。坑四中断的优先级与延迟USB中断对实时性要求很高。特别是全速USB的帧周期是1ms主机每1ms就会查询一次中断端点。如果你的USB中断被其他更高优先级的中断长时间阻塞可能会导致数据传输丢失或枚举失败。务必在系统设计时给USB中断分配一个足够高的优先级。坑五内存对齐与结构体打包USB描述符是“打包”的数据结构编译器默认可能会在结构体成员之间插入填充字节以满足对齐要求这会导致描述符长度和内容错误。在定义描述符结构体时必须使用编译器指令如GCC的__attribute__((packed))或IAR的#pragma pack(1)来确保单字节对齐。CherryUSB提供的描述符宏已经处理了这个问题但如果你自己定义复杂的类特定描述符一定要留意。