STM32F4 USB主机库：轻量级HID与MSC设备支持

1. 项目概述

USBHost-STM32F4 是一个面向 STM32F4 系列微控制器的 USB 主机（USB Host）固件库，其核心目标是为资源受限的嵌入式系统提供轻量、可靠且可移植的 USB 主机协议栈支持。该项目源自 mbed 社区用户 va009039 开发的F401RE-USBHost库，经二次开发后显著扩展了硬件兼容性——不仅完整支持基于 STM32F401RE 的 Nucleo-64 平台，更关键地完成了对Seeed Arch Max（基于 STM32F407VG）和标准 STM32F407VGT6 最小系统板的全功能适配。

在嵌入式系统中，USB 主机模式意味着 MCU 作为“主机”主动枚举、配置并控制 USB 外设（如 U 盘、键盘、鼠标、串口转接器、HID 设备等），而非传统 USB 设备模式（如 MCU 通过 USB 虚拟串口与 PC 通信）。这一能力极大拓展了嵌入式终端的交互维度与数据处理边界：工业 HMI 可直接读取 FAT32 格式 U 盘中的配置文件；医疗设备能通过 USB 键盘输入患者信息；测试仪器可将采集数据实时写入外接存储器。然而，实现 USB 主机协议栈在裸机或 RTOS 环境下极具挑战性——需精确管理 USB 协议层（SOF、Token、Data、Handshake）、事务调度、端点缓冲区、描述符解析、类驱动（Class Driver）以及底层 OTG 控制器寄存器操作。USBHost-STM32F4 正是为此而生：它不依赖 CMSIS-RTOS 或复杂中间件，以 C 语言编写，采用分层架构设计，将硬件抽象层（HAL）、协议栈核心（Core）与设备类驱动（Class Driver）解耦，使开发者能聚焦于应用逻辑而非 USB 协议细节。

该库严格遵循 USB 2.0 规范，支持低速（1.5 Mbps）与全速（12 Mbps）设备，具备完整的错误恢复机制（如 STALL 清除、超时重试、复位恢复），并内置对HID（Human Interface Device）和MSC（Mass Storage Class）两大主流设备类的驱动支持。其代码结构清晰，无动态内存分配（malloc/free），所有缓冲区均静态声明，符合 IEC 61508、ISO 26262 等功能安全标准对确定性内存行为的要求，适用于工业控制、汽车电子等高可靠性场景。

2. 硬件平台与 USB OTG 控制器基础

2.1 支持的硬件平台

USBHost-STM32F4 明确支持以下三类硬件平台，其差异主要体现在引脚定义、时钟配置及 USB PHY 连接方式上：

工程要点：Arch Max 与 F407 最小系统虽同用 STM32F407，但 Arch Max 使用内部 PHY（成本低、布线简单），而标准最小系统常采用外部 ULPI PHY（支持高速模式，但本库未启用）。因此，库中通过宏#define USE_INTERNAL_PHY控制 PHY 初始化路径，避免引脚冲突。

2.2 STM32F4 USB OTG FS 控制器架构

USBHost-STM32F4 驱动的是 STM32F4 系列的USB_OTG_FS（Full Speed）控制器，其核心组件包括：

• Core Layer：处理 USB 协议状态机（Attached, Powered, Default, Address, Configured）、SOF 生成、中断管理（OTG_FS_IRQn）。
• Device Mode / Host Mode 切换：通过OTG_FS_GCCFG.PWRDWN = 0启用 Host 模式，并设置OTG_FS_HCFG.FSLSPCS = 0b00（Full Speed）。
• Host Channel：共 8 个独立通道（CH0–CH7），每个通道可配置为控制、批量、中断或同步传输。库中使用 CH0 处理控制传输（Setup/Status），CH1–CH7 动态分配给数据端点。
• Packet Buffer Memory (PMA)：1.25 KB 片上 SRAM，按 16 字节粒度分区。库中为每个活动通道预分配 512 字节双缓冲区（IN/OUT），确保零拷贝 DMA 传输。

关键寄存器初始化示例（HAL 库风格）：

// 1. 使能 USB_OTG_FS 时钟与 GPIO 时钟 __HAL_RCC_USB_OTG_FS_CLK_ENABLE(); __HAL_RCC_GPIOA_CLK_ENABLE(); // 2. 配置 PA11/PA12 为复用推挽（内部 PHY） GPIO_InitStruct.Pin = GPIO_PIN_11 | GPIO_PIN_12; GPIO_InitStruct.Mode = GPIO_MODE_AF_PP; GPIO_InitStruct.Pull = GPIO_NOPULL; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_VERY_HIGH; GPIO_InitStruct.Alternate = GPIO_AF10_OTG_FS; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); // 3. 复位 USB_OTG_FS Core __HAL_RCC_USB_OTG_FS_FORCE_RESET(); __HAL_RCC_USB_OTG_FS_RELEASE_RESET(); // 4. 配置为 Host 模式（关键！） USB_OTG_FS->GUSBCFG |= USB_OTG_GUSBCFG_FHMOD; // Force Host Mode USB_OTG_FS->GUSBCFG &= ~USB_OTG_GUSBCFG_FDMOD; // Clear Device Mode

3. 软件架构与核心模块解析

3.1 分层架构设计

USBHost-STM32F4 采用经典的三层架构，各层职责明确，接口清晰：

+---------------------+ | Application Layer | ← 用户应用：U盘文件读写、HID按键解析 +---------------------+ | Class Driver | ← HID Driver, MSC Driver (fatfs集成) +---------------------+ | Core Stack | ← USB Host Core: Enumeration, Transfer, Error Handling +---------------------+ | Hardware Abstraction| ← OTG Register Access, IRQ Handler, PHY Control +---------------------+

• Hardware Abstraction Layer (HAL)：封装所有寄存器读写、中断服务程序（ISR）、PHY 电源管理。usbh_hal.c中的USBH_LL_Init()完成控制器初始化，USBH_LL_PortReset()执行物理复位。
• Core Stack：位于usbh_core.c，是协议栈中枢。核心函数包括：
  • USBH_Process()：主状态机循环，处理连接检测、复位、地址分配、描述符获取、配置选择。
  • USBH_InterruptHandler()：在 OTG_FS_IRQHandler 中被调用，解析通道中断（CHx_XFER_COMPLETE, CHx_STALL, CHx_NAK）。
  • USBH_LL_SubmitURB()：提交 USB 请求块（URB），触发 DMA 传输。
• Class Driver：usbh_hid.c与usbh_msc.c实现具体设备类逻辑。例如USBH_MSC_Handle()在USBH_Process()中被周期调用，轮询 U 盘就绪状态并执行 SCSI 命令。

3.2 设备枚举（Enumeration）流程详解

枚举是 USB 主机识别设备的必经过程，USBHost-STM32F4 严格遵循 USB 2.0 规范的 7 步流程，其状态机定义在usbh_core.h中：

typedef enum { HOST_IDLE = 0, HOST_WAIT_FOR_DEVICE, HOST_ENUMERATION, HOST_ADDRESS_DEFAULT, HOST_GET_DESCRIPTOR, HOST_SET_CONFIGURATION, HOST_CLASS_REQUEST, HOST_USER_INPUT, HOST_CHECK_CLASS, } USBH_StateTypeDef;

关键步骤与工程实现细节：

1. Wait for Device：轮询OTG_FS_HPRT.PRTCONNSTS检测 DP/DM 线电平变化，确认设备插入。
2. Reset & Address Assignment：发送复位信号（10ms），随后发送SET_ADDRESS控制传输，将设备地址从默认 0 改为 1–127 范围内唯一值。库中使用USBH_CtlReq()封装此过程。
3. Get Device Descriptor (First 8 bytes)：因初始地址为 0，仅请求前 8 字节以获知设备最大包长（bMaxPacketSize0），用于后续传输缓冲区配置。
4. Set Address：使用新地址重新建立连接。
5. Get Full Device Descriptor：再次请求完整 18 字节描述符，解析bDeviceClass、idVendor、idProduct。
6. Get Configuration Descriptor：请求全部配置描述符（含接口、端点），库中USBH_ParseConfDesc()解析出端点数量、类型、方向及最大包长。
7. Set Configuration：发送SET_CONFIGURATION，设备进入可操作状态。

调试提示：若枚举失败，优先检查USBH_ErrLog()输出的错误码（如USBH_NOT_SUPPORTED表示设备类不支持，USBH_BUSY表示通道忙）。常见原因包括 VBUS 检测电路故障（导致HOST_WAIT_FOR_DEVICE卡死）或时序偏差（需校准OTG_FS_GUSBCFG.TOCAL）。

3.3 数据传输机制

USBHost-STM32F4 支持四种传输类型，其实现均基于Host Channel与DMA：

Bulk 传输示例（U盘读扇区）：

// 在 MSC Class Driver 中调用 uint8_t USBH_MSC_Read(uint8_t lun, uint8_t *buf, uint32_t sector, uint32_t cnt) { uint8_t status = USBH_OK; uint32_t len = cnt * 512; // 512字节/扇区 // 1. 发送 READ_10 SCSI 命令（Control Transfer） status = USBH_MSC_SCSI_SendCommand(phost, lun, SCSI_READ_10, ...); // 2. 执行 Bulk IN 传输（从端点 0x81 读数据） status = USBH_Bulk_Transfer(phost, MSC_EPIN_ADDR, // 0x81 buf, len, 5000); // 5秒超时 return status; }

底层USBH_Bulk_Transfer()会：

• 查找空闲 Host Channel（CH1–CH7）
• 配置HCCHAR寄存器：EPNUM,EPTYP=2(Bulk),LSDEV=0(FS),ODDFRM=0
• 设置HCTSIZ：PKTCNT=cnt,XFRSIZ=len,DPID=2(DATA1)
• 启动通道：HCCHAR.CHENA=1
• 进入阻塞等待，直至USBH_InterruptHandler()检测到CHx_XFER_COMPLETE中断并更新phost->hc[chan].state

4. 设备类驱动深度解析

4.1 MSC（大容量存储）驱动

MSC 驱动是 USBHost-STM32F4 的核心价值所在，它实现了完整的BOT（Bulk-Only Transport）协议，并桥接至 FatFs 文件系统。其工作流程如下：

1. LUN（Logical Unit Number）探测：发送INQUIRY命令，解析响应中的Peripheral Device Type（0x00=Direct Access, 0x08=USB Flash）。
2. READ CAPACITY：获取 LUN 总扇区数与扇区大小（通常 512 字节）。
3. TEST UNIT READY：轮询设备就绪状态，为读写做准备。
4. FatFs 集成：通过diskio.c中的disk_read()调用USBH_MSC_Read()，disk_write()调用USBH_MSC_Write()，使f_open(),f_read()等 FatFs API 可直接操作 U 盘。

关键配置参数（usbh_msc.h）：

实战经验：某些廉价 U 盘对READ_CAPACITY响应异常（返回 0 扇区）。此时需在USBH_MSC_Process()中添加容错逻辑：若READ_CAPACITY失败，则尝试READ_FORMAT_CAPACITIES或强制设为 1GB（2M 扇区）进行试探性挂载。

4.2 HID（人机接口）驱动

HID 驱动支持键盘、鼠标、游戏手柄等设备，其核心在于解析HID Report Descriptor并映射为标准事件。USBHost-STM32F4 提供两种模式：

• Raw Report 模式：直接传递原始报告数据（USBH_HID_GetReport()），适用于自定义设备。
• Parsed Report 模式：内置简易解析器，提取键盘按键（hid->keys[0]–hid->keys[5]）、鼠标 X/Y 位移（hid->x,hid->y）、滚轮（hid->wheel）及按键状态（hid->buttons）。

HID 描述符解析关键点：

• USBH_HID_ParseHIDReport()遍历 Report Descriptor，识别Usage Page（0x01=Generic Desktop, 0x07=Keyboard/Keypad）、Usage Minimum/Maximum（定义按键范围）、Logical Minimum/Maximum（数值范围）。
• 键盘报告格式固定为 8 字节：[Modifier][Reserved][Key1..6]，库中USBH_HID_EventCallback()将其转换为HID_KEYBD_Info_TypeDef结构体。

中断传输配置（usbh_hid.c）：

// 配置 HID 中断端点（通常为 EP1 IN） if (pinterface->ep_in != 0) { hid->poll_interval = pinterface->ep_in_poll; // 通常为 10ms USBH_INT_Open(&phost->dev, pinterface->ep_in, hid->poll_interval, hid->buffer, HID_BUFFER_SIZE); }

5. 移植指南与关键配置

5.1 移植到新平台（以 STM32F411CEU6 为例）

1. 硬件适配：

   • 修改usbh_conf.h：定义USBH_MAX_NUM_INTERFACES=2,USBH_MAX_NUM_ENDPOINTS=4（根据设备需求调整）。
   • 更新 GPIO 初始化：F411CEU6 的 USB 引脚为 PA11/PA12，与 F401RE 一致，无需修改。
   • 校准时钟：F411CEU6 的 USB 时钟需由 PLLQ 分频得到 48MHz，确保RCC_PLLCFGR.PLLQ=6。

2. 中断向量表：

   • 在startup_stm32f411xe.s中，将OTG_FS_IRQHandler指向USBH_IRQHandler（库中已定义）。

3. 内存优化：

   • 若 RAM 紧张，减小USBH_MAX_DATA_BUFFER（默认 512）至 256，但需确保大于最大包长（HID 报告通常 8 字节，U盘 512 字节）。

5.2 FreeRTOS 集成方案

USBHost-STM32F4 原生支持裸机轮询，但与 FreeRTOS 协同可提升实时性。推荐方案：

• 创建 USB Host 任务：

  void USBH_Task(void const * argument) { USBH_HandleTypeDef *phost = (USBH_HandleTypeDef*)argument; for(;;) { USBH_Process(phost); // 主状态机 osDelay(10); // 10ms 轮询间隔 } }

• 事件通知：在USBH_UserProcess()回调中，使用xQueueSend()向应用任务发送USBH_USER_CONNECTION或USBH_USER_DISCONNECTION事件。
• DMA 缓冲区保护：若使用 DMA，需在USBH_LL_SubmitURB()前调用taskENTER_CRITICAL()，传输完成 ISR 中调用taskEXIT_CRITICAL()，防止缓冲区被覆盖。

5.3 关键编译选项

usbh_conf.h中的核心宏定义：

6. 故障排查与性能调优

6.1 常见故障现象与根因

6.2 性能调优实践

• 降低枚举延迟：在USBH_LL_Init()中，将OTG_FS_GUSBCFG.TOCAL从默认 0x00 改为0x03（校准值），可减少 SOF 时序误差。
• 提升 Bulk 传输吞吐量：
  • 启用 DMA：在USBH_LL_BulkTransmit()中调用HAL_USBH_BulkTransfer_DMA()替代轮询。
  • 增加缓冲区：将USBH_MAX_DATA_BUFFER设为 2048，一次读取 4 个扇区，减少 SCSI 命令开销。
• 内存占用优化：若仅用 HID，注释掉usbh_msc.c并在usbh_core.c中移除MSC_CLASS注册，可节省 8KB Flash。

7. 实际项目应用案例

7.1 工业数据记录仪（STM32F407 + USBHost-STM32F4 + FatFs）

• 需求：每 5 秒采集 16 路 ADC 数据，写入 U 盘 CSV 文件。
• 实现：

  // 主循环中 if (usb_status == USBH_MSC_READY) { f_open(&fil, "DATA.CSV", FA_OPEN_ALWAYS | FA_WRITE); f_lseek(&fil, f_size(&fil)); // 追加模式 sprintf(buf, "%lu,%d,%d,...\r\n", HAL_GetTick(), adc_val[0], adc_val[1]); f_write(&fil, buf, strlen(buf), &bw); f_close(&fil); }

• 关键点：使用f_sync()确保数据落盘；U盘拔出前调用USBH_MSC_DeInit()避免文件系统损坏。

7.2 智能家居中控（Arch Max + USBHost-STM32F4 + HID）

• 需求：接收 USB 键盘输入，控制 LED 灯组（RGB）。
• 实现：

  void USBH_HID_EventCallback(USBH_HandleTypeDef *phost) { HID_HandleTypeDef *hid = phost->pActiveClass->pData; if (hid->keys[0] == KEY_A) { // 'A'键点亮红灯 HAL_GPIO_WritePin(LED_R_GPIO_Port, LED_R_Pin, GPIO_PIN_RESET); } }

• 优势：无需额外蓝牙/WiFi 模块，键盘即插即用，成本降低 40%。

USBHost-STM32F4 的价值，在于它将 USB 主机这一复杂功能，压缩进不到 32KB Flash 的固件中，让工程师得以在 STM32F4 上构建真正自主的 USB 外设交互系统。其代码中每一处while(!flag)的轮询、每一个HAL_Delay()的超时、每一条USBH_ErrLog()的日志，都凝结着对 USB 协议时序的敬畏与对嵌入式资源边界的精准拿捏。当 U 盘指示灯在 Arch Max 板上稳定闪烁，当键盘按键在 FreeRTOS 任务中实时触发 GPIO 翻转，那便是底层代码与物理世界最坚实的握手。