STM32F1轻量USB复合设备库：HID+MIDI+MSC一体化实现

1. 项目概述USBComposite for STM32F1 是一个面向 STM32F1 系列微控制器基于 ARM Cortex-M3 内核的轻量级、可裁剪式 USB 复合设备固件库。其核心目标是在资源受限的 F1 平台典型 Flash ≤ 64KBSRAM ≤ 20KB上以最小的内存开销和确定性的实时响应同时实现多个 USB 设备类Device Class的功能。该库并非通用 USB 协议栈而是针对 F1 系列 USB 专用外设USB Device Peripheral非 OTG深度优化的专用实现不依赖 HAL 库或 CMSIS-RTOS 抽象层直接操作寄存器与中断向量确保对 USB 时序的绝对控制。与 ST 官方提供的 USB 库如 STM32_USB-FS-Device_Lib相比USBComposite 的设计哲学截然不同它放弃“全功能覆盖”与“高度抽象”转而追求“按需启用”与“零冗余”。开发者无需为未使用的设备类如仅需 HIDMIDI便不链接 Audio 类代码承担任何代码体积或 RAM 开销。所有设备类共享同一套底层 USB 控制传输处理、端点管理、描述符分发与中断服务逻辑通过编译期宏开关#define USB_HID_ENABLED 1决定最终固件镜像中包含哪些功能模块。这种静态链接策略使得最终.bin文件体积可精确控制在 8–15KB 范围内为 F103C8T620KB Flash等小容量型号留出充足的用户应用空间。该库的工程价值在于解决嵌入式音频/人机交互设备开发中的典型矛盾USB 协议复杂性与 MCU 资源稀缺性之间的根本冲突。例如在一款便携式 MIDI 控制器中需要同时提供一个标准 HID 接口用于旋钮/按键状态上报兼容 Windows/macOS/Linux 无需驱动一个标准 USB-MIDI 接口用于发送/接收 MIDI 消息被 DAW 软件识别为专业 MIDI 设备一个只读 Mass Storage 接口用于固件升级或音色库更新模拟 U 盘用户拖放文件即可。若分别集成三个独立的 USB 库Flash 占用将轻易突破 40KB且各库间的中断优先级、端点分配、描述符管理极易产生冲突。USBComposite 则通过统一的复合设备框架将上述三者无缝整合进单个 USB 设备描述符Device Descriptor与配置描述符Configuration Descriptor中并为每个类分配专属的接口Interface、端点Endpoint及描述符子集由同一套底层驱动完成数据收发调度。2. 硬件与软件约束分析2.1 STM32F1 USB 外设特性STM32F1 系列F102/F103/F105/F107集成的是 USB 2.0 全速Full-Speed, 12Mbps设备控制器其硬件架构具有以下关键约束直接决定了 USBComposite 的设计边界特性规格对 USBComposite 的影响端点数量最多 8 个双向端点EP0–EP7每个端点可配置为 IN 或 OUT 方向库必须严格进行端点资源规划。例如EP0强制控制端点、HID INEP1、MIDI INEP2、MIDI OUTEP3、MSC INEP4、MSC OUTEP5、Audio INEP6、Audio OUTEP7。超出 8 个接口将无法物理实现。端点缓冲区每个端点拥有独立的 64 字节双缓冲区仅部分型号支持双缓冲所有类的数据包大小必须 ≤ 64 字节。HID 报告描述符、MIDI SysEx 消息、Audio PCM 帧均需在此限制下分片传输。库内部采用环形缓冲区 DMA若可用或轮询方式管理数据流。中断源单一 USB 中断线USB_LP_IRQn触发事件包括复位、挂起、唤醒、SOAStart of Frame、CTRControl Transfer Complete、PMAOVRPacket Memory Overflow等USBComposite 的USB_LP_IRQHandler必须是高度精简的有限状态机快速判别中断源并分发至对应类的处理函数避免长耗时操作阻塞 USB 实时性。PMAPacket Memory Area512 字节片上 SRAM需手动映射端点缓冲区地址库提供pma_init()函数在初始化阶段根据启用的端点列表静态计算并配置每个端点的 TX/RX 地址与大小此过程不可动态更改。2.2 软件运行时约束USBComposite 运行于裸机环境Bare Metal无 RTOS 依赖其时间模型完全由 USB 协议驱动SOA 中断每 1ms 一次是唯一可靠的系统滴答源。库利用此中断维护毫秒级软定时器用于 HID 报告的轮询间隔bInterval、Audio 同步帧计数、Mass Storage BOTBulk-Only Transport协议超时检测。CTR 中断控制传输完成必须在 100μs 内响应否则主机可能判定设备故障。库将控制传输的 SETUP 包解析、标准请求如GET_DESCRIPTOR处理、状态阶段应答全部置于中断上下文禁用任何可能导致延迟的函数调用如printf、浮点运算。Bulk/Interrupt IN 端点数据由固件主动写入 PMA 并置位TX_VALID标志。库采用“推模式”Push Model即当应用层有新数据如按键按下、MIDI 音符时立即填充 PMA 并触发传输而非等待主机轮询。Bulk OUT 端点数据由主机推送固件需在CTR中断中及时读取 PMA 数据并清空端点否则后续数据包将丢失。库为每个 OUT 端点维护一个固定大小的 FIFO如 128 字节由中断服务程序ISR将数据移入 FIFO由主循环while(1)从中取出处理。这些约束共同定义了 USBComposite 的编程范式一切以 USB 时序为最高优先级牺牲通用性换取确定性。开发者必须接受“在 ISR 中仅做最简数据搬运在主循环中做业务逻辑”的严格分工。3. 核心架构与数据流3.1 分层架构设计USBComposite 采用清晰的三层架构每一层职责单一接口明确----------------------------------- | Application Layer | ← 用户代码HID 报告生成、MIDI 消息构造、 | (User Application Code) | MSC 文件系统访问、Audio PCM 采样 ---------------------------------- ↓ ----------------------------------- | Device Class Abstraction | ← 统一接口class_init(), class_process(), | (Class Driver Layer) | class_handle_out(), class_handle_in() | - hid_class.c / midi_class.c / | | msc_class.c / audio_class.c | ---------------------------------- ↓ ----------------------------------- | USB Core Endpoint Manager | ← 底层驱动USB 初始化、中断处理、 | (USB Core Layer) | PMA 管理、端点使能/禁用、描述符分发 | - usb_core.c / usb_desc.c / | | usb_pma.c / usb_isr.c | -----------------------------------USB Core Layer是整个库的基石。usb_core_init()完成 USB 外设时钟使能、PMA 初始化、中断向量注册、端点 0 的控制传输状态机初始化。usb_isr.c中的USB_LP_IRQHandler是唯一中断入口其核心逻辑为void USB_LP_IRQHandler(void) { uint16_t istr USB-ISTR; // 读取中断状态寄存器 if (istr ISTR_RESET) { usb_reset_handler(); } if (istr ISTR_CTR) { usb_ctr_handler(); } // 处理所有端点的 CTR if (istr ISTR_SOF) { usb_sof_handler(); } // SOF 计数器递增 if (istr ISTR_WKUP) { usb_wakeup_handler(); } USB-ISTR 0; // 清除已处理的中断标志 }此函数执行时间严格控制在 2–3μs 内确保不丢失任何 USB 事件。Class Driver Layer每个设备类HID/MIDI/MSC/Audio实现一套标准回调函数。usb_core在收到特定请求或数据时调用对应类的回调。例如当主机发送SET_INTERFACE请求到 Audio 接口时usb_core解析后调用audio_class_set_interface()当 EP2MIDI IN的CTR中断触发时usb_core调用midi_class_handle_in_complete()通知 MIDI 类“上一包数据已成功发送”。Application Layer开发者在此层编写业务逻辑。库提供一组非阻塞 APIhid_send_report(uint8_t *report, uint16_t len)将 HID 报告放入 EP1 发送队列。midi_send_byte(uint8_t byte)将单字节 MIDI 消息加入 EP2 发送缓冲区。msc_read_sector(uint32_t lba, uint8_t *buffer)从虚拟磁盘读取一个扇区512 字节。audio_get_pcm_buffer(int16_t **left, int16_t **right, uint16_t *len)获取 Audio IN 端点待采集的 PCM 缓冲区指针。3.2 复合设备描述符组织USB 复合设备的核心在于其描述符结构。USBComposite 生成的Configuration Descriptor是一个线性数组按顺序包含Configuration Descriptor9 字节bNumInterfaces 3若启用 HIDMIDIMSC。Interface Association Descriptor (IAD)8 字节可选用于将多个接口逻辑分组如 Audio Control Audio Streaming。Interface Descriptor #0 (HID)9 字节bInterfaceClass 0x03,bInterfaceSubClass 0x01,bInterfaceProtocol 0x02Boot Keyboard。HID Descriptor9 字节指向HID_ReportDescriptor的偏移与长度。Endpoint Descriptor (HID IN)7 字节bEndpointAddress 0x81,bmAttributes 0x03Interrupt。Interface Descriptor #1 (MIDI)9 字节bInterfaceClass 0x01,bInterfaceSubClass 0x03,bInterfaceProtocol 0x00。MIDI Jack Descriptor系列共 26 字节定义嵌入式/外部端口。Endpoint Descriptor (MIDI IN)7 字节bEndpointAddress 0x82,bmAttributes 0x02Bulk。Endpoint Descriptor (MIDI OUT)7 字节bEndpointAddress 0x01,bmAttributes 0x02Bulk。Interface Descriptor #2 (MSC)9 字节bInterfaceClass 0x08,bInterfaceSubClass 0x06,bInterfaceProtocol 0x50Bulk-Only。Endpoint Descriptor (MSC IN)7 字节bEndpointAddress 0x84。Endpoint Descriptor (MSC OUT)7 字节bEndpointAddress 0x05。所有描述符均在编译期由usb_desc.c中的const uint8_t usb_config_descriptor[]数组定义usb_core在收到GET_DESCRIPTOR请求时直接返回该数组对应偏移处的数据零运行时开销。4. 关键设备类实现详解4.1 USB HID 类HIDHuman Interface Device是 USBComposite 中最轻量、最常用的类。其核心在于HID_ReportDescriptor—— 一段由uint8_t数组定义的二进制数据描述设备的输入/输出报告格式。USBComposite 不提供自动生成工具要求开发者手写符合 HID Usage Tables 规范的描述符。一个典型的 8 键2 旋钮的控制器报告描述符简化版如下const uint8_t hid_report_descriptor[] { 0x05, 0x01, // USAGE_PAGE (Generic Desktop) 0x09, 0x06, // USAGE (Keyboard) 0xA1, 0x01, // COLLECTION (Application) 0x05, 0x09, // USAGE_PAGE (Button) 0x19, 0x01, // USAGE_MINIMUM (Button 1) 0x29, 0x08, // USAGE_MAXIMUM (Button 8) 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x25, 0x01, // LOGICAL_MAXIMUM (1) 0x75, 0x01, // REPORT_SIZE (1) 0x95, 0x08, // REPORT_COUNT (8) 0x81, 0x02, // INPUT (Data,Var,Abs) 0x05, 0x01, // USAGE_PAGE (Generic Desktop) 0x09, 0x01, // USAGE (Pointer) 0xA1, 0x00, // COLLECTION (Physical) 0x75, 0x10, // REPORT_SIZE (16) 0x95, 0x02, // REPORT_COUNT (2) 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x26, 0xFF, 0x03, // LOGICAL_MAXIMUM (1023) 0x09, 0x30, // USAGE (X) 0x09, 0x31, // USAGE (Y) 0x81, 0x02, // INPUT (Data,Var,Abs) 0xC0, // END_COLLECTION 0xC0 // END_COLLECTION };hid_send_report()函数将应用层构建的 16 字节报告8 位按钮状态 2×16 位旋钮值通过usb_ep_write()写入 EP1 的 PMA并置位EP1_TX_VALID。Windows 主机加载标准hidclass.sys驱动后即可通过ReadFile()读取原始报告数据或使用HidP_GetButtonCaps()等 API 解析语义。4.2 USB-MIDI 类USB-MIDI 严格遵循 MIDI 1.0 规范RP-007其本质是将传统 31.25kbps 串行 MIDI 流封装进 USB Bulk 端点。USBComposite 的 MIDI 类不处理 MIDI 协议解析仅负责“透明隧道”Transparent Tunneling。MIDI 数据在 USB 上以 4 字节的USB-MIDI Event Packets形式传输Byte 0Byte 1Byte 2Byte 3Cable Number (4b) Code Index Number (4b)MIDI Byte 1MIDI Byte 2MIDI Byte 3例如发送一个 Note On 事件Channel 1, Note 60, Velocity 100Byte 0 0x09Cable 0, Code Index 9 Note OnByte 1 0x90Note On, Ch 1Byte 2 0x3CNote 60Byte 3 0x64Velocity 100midi_send_byte()将单字节追加到 EP2 的发送缓冲区。当缓冲区满或应用层显式调用midi_flush()时库将其打包成完整的 4 字节事件包填入 PMA 并触发传输。对于接收midi_class_handle_out()在 EP1 OUT 端点收到数据后将每个 4 字节包解包提取Byte 1–3并通过回调midi_on_receive(uint8_t b1, uint8_t b2, uint8_t b3)通知应用层。此设计确保了 MIDI 消息的严格时序无任何协议栈开销。4.3 Mass Storage 类BOTUSBComposite 的 MSC 实现遵循 USB Mass Storage Class Bulk-Only Transport (BOT) 规范。它不实现 FAT32 文件系统而是提供一个极简的、基于 LBALogical Block Address的块设备抽象层。开发者需实现两个函数msc_read_sector(uint32_t lba, uint8_t *buffer)将指定 LBA 的 512 字节数据复制到buffer。msc_write_sector(uint32_t lba, const uint8_t *buffer)将buffer的 512 字节写入指定 LBA。库内部维护一个BOT_StateMachine处理标准 SCSI 命令INQUIRY返回设备标识字符串STM32F1 MSC。READ_CAPACITY返回总扇区数与扇区大小512。READ_10/WRITE_10触发msc_read_sector/msc_write_sector。TEST_UNIT_READY检查设备就绪状态。当主机如 Windows枚举到 MSC 接口后会自动加载usbstor.sys驱动并将设备显示为可移动磁盘。用户可直接拖放.bin固件文件到该磁盘应用层在msc_write_sector中检测到特定地址如 LBA 0写入了新固件头即可触发 OTAOver-The-Air升级流程。整个过程无需额外 PC 工具用户体验接近消费级产品。5. 集成与移植指南5.1 最小化工程创建步骤以 STM32F103C8T6Blue Pill为例集成 USBComposite 的完整流程硬件连接将 USB DPA12通过 1.5kΩ 上拉电阻连接到 3.3VD-PA11悬空。此上拉电阻宣告设备为 Full-Speed。时钟配置在system_stm32f10x.c中确保RCC-CFGR | RCC_CFGR_USBPREUSB PLL 使能RCC-CR | RCC_CR_PLL2ON若使用 PLL2 作为 USB 时钟源最终 USBCLK 48MHz。GPIO 初始化RCC-APB2ENR | RCC_APB2ENR_IOPAEN; GPIOA-CRL ~(GPIO_CRL_CNF11 | GPIO_CRL_CNF12 | GPIO_CRL_MODE11 | GPIO_CRL_MODE12); GPIOA-CRL | (GPIO_CRL_CNF11_1 | GPIO_CRL_CNF12_1); // PA11/PA12: Alternate Function Push-PullUSB 外设初始化RCC-APB1ENR | RCC_APB1ENR_USBEN; USB-CNTR 0; // 复位 USB 外设 USB-BTABLE 0; // PMA 基地址 usb_core_init(); // 调用库初始化函数 NVIC_EnableIRQ(USB_LP_IRQn);编译配置在usb_config.h中启用所需类#define USB_HID_ENABLED 1 #define USB_MIDI_ENABLED 1 #define USB_MSC_ENABLED 1 #define USB_AUDIO_ENABLED 0 // 禁用 Audio 以节省空间5.2 与 HAL/LL 库共存注意事项USBComposite 与 ST HAL 库存在根本性冲突严禁在同一工程中同时启用HAL_PCD_MODULE_ENABLED和 USBComposite。二者均尝试独占 USB 外设寄存器、中断向量及 PMA。若项目已使用 HAL 进行其他外设如 UART、SPI开发可采取以下隔离策略HAL 仅用于非 USB 外设保持HAL_UART_Init(),HAL_SPI_Transmit()等调用但绝对禁用HAL_PCD_Init()及所有HAL_PCD_*函数。USB 外设寄存器访问隔离在usb_core.c中所有USB-xxx访问必须使用__IO修饰符如__IO uint16_t *cntr USB-CNTR;防止编译器优化导致的寄存器读写异常。中断向量重定向若 HAL 已接管USB_LP_IRQHandler需在stm32f1xx_it.c中将该函数体替换为 USBComposite 的USB_LP_IRQHandler并确保HAL_NVIC_SetPriority(USB_LP_IRQn, ...)设置的优先级足够高建议 ≤ 1。5.3 性能调优与调试技巧PMA 冲突诊断若设备枚举失败或数据错乱首要检查usb_pma.c中的pma_alloc()分配是否重叠。使用pma_dump()函数打印所有端点的 TX/RX 地址确认无越界。HID 报告速率瓶颈Windows 默认 HID 轮询间隔为 10ms。若需更高频率如游戏手柄需在HID_ReportDescriptor中设置bInterval 11ms并确保usb_sof_handler()中的软定时器精度。MIDI 时序抖动Bulk 传输无严格时序保证。对实时性要求极高的场景如音符触发应在应用层使用硬件定时器TIM2配合midi_send_byte()而非依赖 USB SOF。MSC 写入卡顿Windows 在写入大文件时会发送大量WRITE_10命令。msc_write_sector()必须在 500ms 内完成否则主机超时断开。建议使用外部 SPI Flash 或 SDIO并启用 DMA 传输。6. 典型应用案例便携式合成器控制器一个基于 USBComposite 的实际项目——“PolySynth Ctrl”一款 16 键、8 旋钮、4 推子的硬件合成器控制器其固件结构清晰体现了库的价值HID 接口报告描述符定义 16 个按键0/1、8 个 10 位旋钮0–1023、4 个 10 位推子0–1023、1 个 3 位编码器-1/0/1。Windows 通过 DirectInput API 读取映射到 DAW 的参数。MIDI 接口所有旋钮/推子变化生成 CCControl Change消息按键生成 Note On/Off编码器生成 Pitch Bend。DAW如 Ableton Live将其识别为标准 MIDI 控制器。MSC 接口LBA 0–1023 存储预设文件.syx用户拖放新预设到磁盘设备重启后自动加载。msc_read_sector()从外部 SPI Flash 读取数据msc_write_sector()将新文件写入 Flash。整个固件含所有类编译后占用 Flash 12.3KBSRAM 4.8KB完美适配 F103C8T6。开发者仅需关注main.c中的while(1)循环while(1) { // 读取 ADC 获取旋钮/推子值 for (int i0; i8; i) { uint16_t val adc_read(ADC_CHANNEL_0 i); hid_report.knob[i] val; } // 构建并发送 HID 报告 hid_send_report((uint8_t*)hid_report, sizeof(hid_report)); // 处理 USB 接收的 MIDI 数据 midi_process_rx(); // 处理按键中断 gpio_process_buttons(); }USB 底层细节被完全封装工程师得以聚焦于硬件交互逻辑本身。这正是 USBComposite 的终极使命让嵌入式 USB 开发回归硬件本质而非陷入协议栈泥潭。