背景STM32 的 USB 开发为什么劝退USB 协议栈是嵌入式领域学习曲线最陡的技术之一而 STM32 的 USB 开发又把这层难度放大了ST HAL 库把协议栈藏在层层回调后面USB 复位、枚举、描述符交换全是黑盒改一个字段可能牵动六个地方出错时又不知道从哪里查——USB 分析仪一台几千块多数人只能靠 printf 盲调。TinyUSB 走的是反方向把描述符从黑盒里拿出来变成你亲手写的字节数组。本文给出在 STM32 上实现一个 USB HID 键盘设备的完整流程。环境STM32F4 / F7 / H7 / L4 / G4TinyUSB 已内置移植层CubeMX 配时钟编译链 arm-none-eabi-gcc。一、一个宏定下设备类型// tusb_config.h —— 三行宏USB 设备类型就定下来了#defineCFG_TUD_HID1#defineCFG_TUD_CDC0#defineCFG_TUD_MSC0插上 USB 线STM32 就是一台标准 HID 设备Windows / Linux / macOS 自带驱动。先建立直觉USB 本质是一套问答游戏主机问「你是什么设备」设备答「我是键盘」主机问「数据格式」设备答「8 字节1 字节修饰键 6 字节按键码」。这套问答的标准答案模板就是描述符。对比两种写法的差别// HAL 的方式描述符藏在结构体赋值里pdev-DevDesc.bDeviceClass0x00;// TinyUSB 的方式描述符就是手写的字节数组你写什么总线上就是什么uint8_tconstdesc_hid_report[]{TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(RID_KEYBOARD))};从数据到总线的映射是透明的——出了 bug 把数组 dump 出来跟 USB 规范对照即可。二、HID 描述符三份身份材料USB 枚举的本质是设备向主机递交三份材料1. 设备描述符我是谁tusb_desc_device_tconstdesc_device{.bLengthsizeof(tusb_desc_device_t),.bDescriptorTypeTUSB_DESC_DEVICE,.bcdUSB0x0200,.idVendor0xCafe,// 你的 VID.idProduct0x4001,// 你的 PID.bNumConfigurations1,};VID/PID 建议自己玩用 0xCAFE / 0xBEEF 这类测试 ID正式产品向 USB-IF 申请或从芯片厂商获取子授权。别用 STM32 官方 VID0x0483否则 Linux 上可能把设备认成 ST-Link。2. 配置描述符我能干什么HID 通常只用一种配置。3. HID 报告描述符我的数据长什么样HID 设备的灵魂。TUD_HID_REPORT_DESC_KEYBOARD宏展开约 60 字节定义修饰键 1 字节、保留 1 字节、按键码 6 字节。三、五步从编译到枚举Step 1CubeMX 配时钟。USB 外设要 48MHz 精准时钟用 HSI48 CRS时钟恢复最省事无需外部晶振。勾上 USB 外设不要勾 ST 的 USB Device 中间件。Step 2拉源码。git clone https://github.com/hathach/tinyusb.git把src/拷到项目Middlewares/下移植tusb_config.h和芯片移植层STM32F4 已内置。Step 3写描述符。建usb_descriptors.c定义四种描述符实现回调uint8_tconst*tud_descriptor_device_cb(void){return(uint8_tconst*)desc_device;}Step 4实现 HID 回调。uint16_ttud_hid_get_report_cb(uint8_tinstance,uint8_treport_id,hid_report_type_treport_type,uint8_t*buffer,uint16_treqlen){return0;// 主机读报告枚举完读一次}voidtud_hid_set_report_cb(uint8_tinstance,uint8_treport_id,hid_report_type_treport_type,uint8_tconst*buffer,uint16_tbufsize){// 主机发报告键盘 LED 状态}Step 5主循环发数据。voidhid_task(void){if(!tud_hid_ready())return;// 还没枚举完跳过uint8_treport[8]{0};report[2]HID_KEY_A;tud_hid_report(0,report,sizeof(report));// 发送 Amemset(report,0,sizeof(report));tud_hid_report(0,report,sizeof(report));// 发空报告释放按键}连上 USB 线lsusb或设备管理器里就能看到CAFE:4001的新设备。四、局限不是所有 STM32 系列都有移植层官方支持 F4 / F7 / H7 / L4 / G4较新的 H5 / H7RS / U5带 USB 3.0 PHY移植还在开发选型前到 TinyUSB 的 supported MCU 列表确认。多实例 HID 有限制可同时做键盘鼠标但端点配置在 DCD 层复用资源池不同实例要不同轮询间隔需改移植层。Isochronous 传输不成熟HID 用的中断传输没问题但 USB 麦克风/摄像头这类 Isochronous 端点只在部分 MCU如 ESP32-S2/S3稳定。调试难度依然在代码比 HAL 透明但协议本身没变简单。无分析仪时把CFG_TUD_LOG_LEVEL开到 3 看描述符请求和枚举过程是可行的替代。五、总结TinyUSB 把描述符从 HAL 黑盒里拿出来变成你直接可控的字节数组——出了问题能追、改了能懂。想要更省事可用 Adafruit 的 TinyUSB Arduino 库枚举全自动灵活度打折想理解协议、要灵活控制就用 TinyUSB。剩下的事找根 USB 线、烧程序、看dmesg里弹出新设备的那一刻。 背景STM32 的 USB 开发为什么劝退USB 协议栈是嵌入式领域学习曲线最陡的技术之一而 STM32 的 USB 开发又把这层难度放大了ST HAL 库把协议栈藏在层层回调后面USB 复位、枚举、描述符交换全是黑盒改一个字段可能牵动六个地方出错时又不知道从哪里查——USB 分析仪一台几千块多数人只能靠 printf 盲调。TinyUSB 走的是反方向把描述符从黑盒里拿出来变成你亲手写的字节数组。本文给出在 STM32 上实现一个 USB HID 键盘设备的完整流程。环境STM32F4 / F7 / H7 / L4 / G4TinyUSB 已内置移植层CubeMX 配时钟编译链 arm-none-eabi-gcc。一、一个宏定下设备类型// tusb_config.h —— 三行宏USB 设备类型就定下来了#defineCFG_TUD_HID1#defineCFG_TUD_CDC0#defineCFG_TUD_MSC0插上 USB 线STM32 就是一台标准 HID 设备Windows / Linux / macOS 自带驱动。先建立直觉USB 本质是一套问答游戏主机问「你是什么设备」设备答「我是键盘」主机问「数据格式」设备答「8 字节1 字节修饰键 6 字节按键码」。这套问答的标准答案模板就是描述符。对比两种写法的差别// HAL 的方式描述符藏在结构体赋值里pdev-DevDesc.bDeviceClass0x00;// TinyUSB 的方式描述符就是手写的字节数组你写什么总线上就是什么uint8_tconstdesc_hid_report[]{TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(RID_KEYBOARD))};从数据到总线的映射是透明的——出了 bug 把数组 dump 出来跟 USB 规范对照即可。二、HID 描述符三份身份材料USB 枚举的本质是设备向主机递交三份材料1. 设备描述符我是谁tusb_desc_device_tconstdesc_device{.bLengthsizeof(tusb_desc_device_t),.bDescriptorTypeTUSB_DESC_DEVICE,.bcdUSB0x0200,.idVendor0xCafe,// 你的 VID.idProduct0x4001,// 你的 PID.bNumConfigurations1,};VID/PID 建议自己玩用 0xCAFE / 0xBEEF 这类测试 ID正式产品向 USB-IF 申请或从芯片厂商获取子授权。别用 STM32 官方 VID0x0483否则 Linux 上可能把设备认成 ST-Link。2. 配置描述符我能干什么HID 通常只用一种配置。3. HID 报告描述符我的数据长什么样HID 设备的灵魂。TUD_HID_REPORT_DESC_KEYBOARD宏展开约 60 字节定义修饰键 1 字节、保留 1 字节、按键码 6 字节。三、五步从编译到枚举Step 1CubeMX 配时钟。USB 外设要 48MHz 精准时钟用 HSI48 CRS时钟恢复最省事无需外部晶振。勾上 USB 外设不要勾 ST 的 USB Device 中间件。Step 2拉源码。git clone https://github.com/hathach/tinyusb.git把src/拷到项目Middlewares/下移植tusb_config.h和芯片移植层STM32F4 已内置。Step 3写描述符。建usb_descriptors.c定义四种描述符实现回调uint8_tconst*tud_descriptor_device_cb(void){return(uint8_tconst*)desc_device;}Step 4实现 HID 回调。uint16_ttud_hid_get_report_cb(uint8_tinstance,uint8_treport_id,hid_report_type_treport_type,uint8_t*buffer,uint16_treqlen){return0;// 主机读报告枚举完读一次}voidtud_hid_set_report_cb(uint8_tinstance,uint8_treport_id,hid_report_type_treport_type,uint8_tconst*buffer,uint16_tbufsize){// 主机发报告键盘 LED 状态}Step 5主循环发数据。voidhid_task(void){if(!tud_hid_ready())return;// 还没枚举完跳过uint8_treport[8]{0};report[2]HID_KEY_A;tud_hid_report(0,report,sizeof(report));// 发送 Amemset(report,0,sizeof(report));tud_hid_report(0,report,sizeof(report));// 发空报告释放按键}连上 USB 线lsusb或设备管理器里就能看到CAFE:4001的新设备。四、局限不是所有 STM32 系列都有移植层官方支持 F4 / F7 / H7 / L4 / G4较新的 H5 / H7RS / U5带 USB 3.0 PHY移植还在开发选型前到 TinyUSB 的 supported MCU 列表确认。多实例 HID 有限制可同时做键盘鼠标但端点配置在 DCD 层复用资源池不同实例要不同轮询间隔需改移植层。Isochronous 传输不成熟HID 用的中断传输没问题但 USB 麦克风/摄像头这类 Isochronous 端点只在部分 MCU如 ESP32-S2/S3稳定。调试难度依然在代码比 HAL 透明但协议本身没变简单。无分析仪时把CFG_TUD_LOG_LEVEL开到 3 看描述符请求和枚举过程是可行的替代。五、总结TinyUSB 把描述符从 HAL 黑盒里拿出来变成你直接可控的字节数组——出了问题能追、改了能懂。想要更省事可用 Adafruit 的 TinyUSB Arduino 库枚举全自动灵活度打折想理解协议、要灵活控制就用 TinyUSB。剩下的事找根 USB 线、烧程序、看dmesg里弹出新设备的那一刻。 
![洛谷 P7912：[CSP-J 2021 T4] 小熊的果篮 ← 双向链表](http://pic.xiahunao.cn/yaotu/洛谷 P7912：[CSP-J 2021 T4] 小熊的果篮 ← 双向链表)
