STM32 Custom HID免驱开发实战：双向通信与报告描述符

1. 为什么是Custom HID免驱不是唯一理由做嵌入式USB设备的开发者大概率都经历过这样一个过程先玩一阵子CDC虚拟串口用串口助手调数据等产品要交付了才发现——用户电脑上插上设备没反应原因是没装串口驱动或者系统给设备分配的COM口对不上。然后你开始研究怎么免驱搜了一圈发现HID类设备是最稳的选择于是走进Custom HID这条路。我最初接触Custom HID也是因为一个实际需求做一个自定义按键面板十几个按键加一个旋钮要从PC上位机下发背光亮度、按键映射还需要把旋钮的增量值实时上报。用串口方案其实能做但客户环境是几百台办公电脑IT部门不允许装驱动串口方案直接被毙了。评估了几类USB类后选了Custom HID。这里顺手做个对比帮助还没入坑的朋友理解路线差异对比项CDC虚拟串口标准HID键盘/鼠标Custom HID驱动依赖多数系统自带但部分环境受限系统级免驱系统级免驱传输方式批量传输吞吐量大中断传输包小中断传输包小双向通信原生支持一般只做单向输入原生支持实时性一般高高开发门槛低简单但约束多中等卡点在描述符扩展性一般受HID用法页限制自定义能力最强Custom HID的核心价值不光是免驱。它走的是中断传输时延低且带宽有保证非常适合小数据量、高实时性的交互场景。键盘、鼠标这类标准HID设备虽然也免驱但报告格式和用法被协议死死框住——你没法随便往报告里塞自己定义的字段除非做一些“借用”操作而且这种借用很容易产生兼容性问题。Custom HID用自己的Usage Page描述数据格式主机只需要把它当HID设备加载如何解释数据由你定。所以这个方案的定位很明确上位机由自己开发、通信数据量不大、要求低时延、需要系统级免驱的产品交互场景。工控面板、宏键盘、采集卡控制、医疗设备操作终端之类都是典型适用场景。2. CubeMX阶段最容易配错的三处地方很多人觉得CubeMX图形化配置就是点点鼠标的事结果卡了很久问题往往不在代码而在前期的工程配置。我以STM32F103系列为例把容易踩的点一个一个讲清楚。2.1 时钟树48MHz USB时钟不是自动配好的STM32的USB全速外设要求48MHz时钟。F103的USB时钟来自PLL的Q分频输出很多人生成工程后直接烧录设备插上PC一点反应都没有查了半天发现USB时钟源没配。CubeMX里默认时钟树很可能是系统主频72MHz、USB关闭。正确的操作路径是在RCC设置里把HSE打开设为Crystal/Ceramic Resonator。进入Clock Configuration页面配置PLL使系统时钟跑到72MHz。在页面下方找到USB那一栏把PLLQ或对应分频值配成48MHz。F103的USB时钟必须严格是48MHz偏差太大会导致枚举失败。有一种很隐蔽的情况是工程里开了LSE/RTC相关功能时钟树优先级变化USB时钟被连带改掉这时候要回头检查USB时钟源是否还是48MHz。2.2 USB设备库与类选择进入Connectivity选项卡打开USB_OTG_FS或USB Peripherals里的Device模式然后去Middleware and Software Packs选择USB_DEVICE。这个环节有一个很关键的选项Class for FS IP里面有HID、CDC、Custom HID等选项必须选Custom HID Class而不是HID。两个选项的区别在于标准HID类生成的是固定报告描述符一般是一个键盘或鼠标的报表结构Custom HID类生成的是用户自定义的报表结构端点配置也允许双向。选错的话后面改代码的工程量会翻倍不如在这里就选对。还有一个小细节不同版本的CubeMX/F1固件包里Custom HID选项的位置可能有差异老版本可能在USB_DEVICE中间件配置页面里叫“Custom HID Class”新版本统一归到Class for FS IP下拉菜单。如果找不到检查一下固件包有没有装全。2.3 描述符长度和端点的联动关系CubeMX生成Custom HID工程时默认的报告描述符会被编译器通过链接脚本嵌入到USB配置描述符里。默认报告描述符长度是34字节左右端点配置里IN端点的最大包长默认是16字节Buffer数组也是16字节。如果你要改成64字节双向通信需要动三个地方而且必须同步改报告描述符里的Report Count要改成64。USBD_CUSTOM_HID_ReportDesc数组要改成你自定义的描述符字节序列。usbd_custom_hid_if.c里的USBD_CUSTOM_HID_OutReport_Buffer数组和USBD_CUSTOM_HID_OutBufferSize以及端点描述符里的wMaxPacketSize都要改成64。端点和Buffer之间的联动关系是排查问题时最容易忽视的。曾经我同事A接手一个项目改大了描述符但忘了改Buffer长度数据上报正常接收命令总是截断。排查了一下午最后发现是Out Buffer还停留在16字节。这个坑在后面第4章详细说。3. 报告描述符逐行拆解设备与主机之间的“说明书”HID报告描述符是Custom HID开发中最容易卡住的地方。它的本质是一份用USB HID协议语法写的数据说明书告诉操作系统“这个设备会发什么格式的数据、能接收什么格式的数据、数据的取值范围是多少”。主机不需要理解你的业务逻辑只要按这个说明书把数据包正确地送进驱动框架就行。3.1 一个可用的双向64字节描述符这里给一份我常用的双向64字节描述符可以直接放到工程里const uint8_t USBD_CUSTOM_HID_ReportDesc[] { 0x06, 0x00, 0xFF, // Usage Page (Vendor Defined Page 1) 0x09, 0x01, // Usage (Vendor Usage 1) 0xA1, 0x01, // Collection (Application) 0x85, 0x01, // Report ID (1) 0x09, 0x01, // Usage (Vendor Usage 1) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8 bits) 0x95, 0x40, // Report Count (64) 0x81, 0x02, // Input (Data, Var, Abs) 0x09, 0x01, // Usage (Vendor Usage 1) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8 bits) 0x95, 0x40, // Report Count (64) 0x91, 0x02, // Output (Data, Var, Abs) 0xC0 // End Collection };这份描述符的含义拆开看就几条Usage Page选Vendor Defined Page 1意思是数据格式是厂商自定义的操作系统不做协议层解释。Collection Application表示这是应用集合里面可以定义多个报告。Report ID设为1让主机用这个ID来区分是哪个报告。先用Report Size 8把64个字节定义成64个8位字段Input表示设备到主机Output表示主机到设备。两份报告一份Input一份Output各64字节正好对应双向通信的需求。3.2 为什么推荐Vendor Defined页这里有个值得啰嗦的点。你完全可以在描述符里复用Generic Desktop页甚至把每个字节定义为坐标轴、按钮等但这种做法存在两个隐患一是语义被系统解释成标准控件可能出现系统层面的额外处理比如某些平台会把你的数据当鼠标位移二是当你想扩字段时标准用法页很难定义“这个字节代表背光亮度”这种业务含义。用Vendor Defined页的好处是把语义完全留给自己。上位机通过hidapi或Windows的HidD接口读取的是原始字节怎么解释是应用层的事。这种方式最纯粹也最不容易被系统“好心办坏事”。3.3 描述符改错会有什么表现描述符里一个数值写错在现象上往往非常隐晦Report Count与Buffer长度不匹配主机收到的数据包长度对不上出现截断、多余字节或读取失败。Logical Maximum设置过小比如设成127而不是255那你发0x80以上的字节时系统上报的值可能被符号扩展成负数收到的数据完全错乱。Input/Output顺序颠倒主机端可能找不到输出报告或者写入操作报参数错误。遗漏End Collection设备枚举阶段会直接失败设备管理器报“描述符请求失败”。如果你改完描述符出现这些现象不要急着查业务代码先把描述符逐字节对着协议说明走一遍90%的问题都在这里。4. HAL库数据通路发送与接收的完整链路描述符搞定设备能被电脑识别接下来就要把业务数据跑通了。HAL库把USB数据通路封装得比较友好但封装带来的问题是什么都看不清楚一旦出问题很难定位到具体环节。4.1 上报数据USBD_CUSTOM_HID_SendReport设备主动往主机发数据调用的是这个函数。它的原型大致是uint8_t USBD_CUSTOM_HID_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, uint16_t len);调用时机要看你业务。我做的按键面板是在检测到按键状态变化时上报同时还有个定时器每20毫秒上报一次旋钮增量值。这里要记住中断传输是有报告间隔限制的枚举时配置的bInterval决定主机轮询间隔F103的USB全速设备最小间隔是1毫秒。也就是说你想要更高的上报频率也做不到协议层面就限死了。上报函数的调用要注意两个问题。第一len不是随便填的不能超过描述符里定义的Report Count否则USB控制器可能出现溢出或数据被丢弃。第二如果上一次上报还没完成HAL状态还停在BUSY你又调了一次这次会返回失败需要做重发或缓存机制。4.2 接收命令HID_Itf_DataOut回调主机下发数据给设备数据到达后HAL库会通过回调通知应用层。在usbd_custom_hid_if.c里需要实现这个函数static int8_t HID_Itf_DataOut(USBD_HandleTypeDef *pdev, uint8_t *pbuf, uint32_t *length) { // pbuf 指向接收缓冲区length 是收到的数据长度 // 在这里做数据解析、命令分发 return 0; }这个回调运行在USB中断上下文里处理逻辑要快。我见过有人直接在回调里做字符串处理、查表、往EEPROM写配置结果就是USB枚举不稳定、系统卡顿。正确做法是将数据拷贝到自己的接收队列然后通过标志位或消息邮箱让主循环去处理。另一个值得注意的点HAL库的OutReport Buffer是一个环形或覆盖式的缓冲区如果上一包数据还没被应用层取走下一包又到了新数据会把旧数据覆盖掉。所以回调里至少要把数据搬走哪怕只是搬到应用层缓冲区。4.3 Buffer尺寸不匹配的隐形炸弹前面提到CubeMX默认Out Buffer是16字节现在把这个坑展开讲。现象是这样的上位机下发一包64字节的数据设备端收到的长度始终只有16字节或者前16字节正确、后面的数据丢失。很多人的第一反应是改上位机代码或者怀疑通信协议有问题折腾很久。实际上问题就出在usbd_custom_hid_if.c这个文件的几个数组上#define USBD_CUSTOM_HID_OUTREPORT_BUF_SIZE 64 static uint8_t USBD_CUSTOM_HID_OutReport_Buffer[USBD_CUSTOM_HID_OUTREPORT_BUF_SIZE];如果这里还是16即使描述符、端点和上位机都改成64字节设备端也只会接收前16字节。这个参数有个更阴险的地方CubeMX在生成代码时会把数组和宏放在不同文件里宏定义在usbd_custom_hid.h数组在usbd_custom_hid_if.c改漏任何一个都可能出错。**建议做法是先把所有的Buffer尺寸宏全部改成目标值再从描述符到端点描述符全部过一遍最后用Bus Hound或USB抓包工具确认实际传输长度。**不要靠肉眼代码审查长度不对的Bug肉眼很难看出来。5. 实测排查设备识别失败与数据错位的完整链路代码写完上电实测这是开发者最兴奋也最容易受挫的环节。归纳一下我在实际项目中遇到的几类问题从现象到根因帮你梳理一遍。5.1 设备管理器里的“未知设备”怎么查插上设备PC没有弹任何提示设备管理器里出现一个带黄色感叹号的“未知USB设备设备描述符请求失败”。这种问题基本集中在枚举层面可能原因优先级从高到低分别是USB时钟不对先回去确认48MHz。D上拉电阻问题。F103的USB D上拉是内部集成的但如果CubeMX里没把USB的D上拉配置打开或者上拉电路异常枚举会失败。固件里中断优先级配置不当USB中断被其他高优先级中断饿死。供电不足尤其是从USB口取电但板子上还带了显示屏、传感器等外设。排查手法有个笨办法但非常有效换一台不同年代的电脑试。某一台机器枚举失败、另一台正常基本可以确认是时序问题而不是设备彻底坏了。此时可以用逻辑分析仪或USB分析仪抓取枚举阶段的数据包确认设备有没有响应Set Address请求。5.2 数据全0、丢包、首字节错位怎么查设备能被识别说明枚举阶段OK问题就集中在应用层。最常见的情况是设备上报数据但上位机读到的全是0或者读到的首字节丢失或者是数据对不上。先说全0。排查顺序确认上报函数有没有真正执行加个IO口翻转或用调试器打断点确认上报长度参数是否正确最后用USB分析仪看原始包。有次我的项目里全0的原因是描述符里Report ID写了1但SendReport时传入的数组第一个字节是0xFF主机端按Report ID1来解析就丢掉了第一个字节后面的数据就错位了。HID设备在带Report ID时每个报告的第一个字节固定是Report ID这个字节不会出现在你业务数据里。所以你的有效数据要么从Data[1]开始存要么在应用层用一个偏移量规避。再看数据对不上。要确认主机收到的真的是你发的那包数据可以用一个简单的自测流程设备端固定发一串0x00到0x3F的递增序列上位机收到后检查序列值哪一段断了错位了就能反推是发送端问题还是接收端问题。5.3 用Python脚本快速验证双向通路上位机调试不一定非得先写完整的业务程序推荐用Python加上hidapi库做最小验证。一个可用的测试脚本如下import hid # 这里填你设备枚举出来的VID和PID VENDOR_ID 0x1234 PRODUCT_ID 0x5678 device hid.device() device.open(VENDOR_ID, PRODUCT_ID) device.set_nonblocking(1) # 发送一包给设备注意首字节是Report ID out_data [0x01, 0xAA, 0xBB, 0xCC] [0x00] * 60 device.write(out_data) # 读取设备上报的数据 try: in_data device.read(64, timeout_ms2000) print(freceived {len(in_data)} bytes: {list(in_data)}) except Exception as e: print(fread failed: {e}) device.close()这个脚本跑通后再去写正式的上位机逻辑能省很多时间。另外一个建议是准备一个USB抓包工具。Windows上可以用Bus HoundLinux上用Wireshark加一个USB抓包模块或者买一个USB分析仪。抓包工具能看到最底层的数据流判断“设备到底有没有发出那包数据”几乎是唯一的权威手段。最后说几句HAL库的Custom HID开发走到这里基本完整了工程配置、描述符编写、数据通路、问题排查。我的切身体会是这类项目真正花时间的不是代码本身而是对USB枚举和HID协议的理解。建议入门时用小步快跑的方式先实现最小枚举设备能被识别再跑通一包双向数据然后才去扩展业务功能。最后再分享一个小技巧设计产品时最好在项目早期就把Custom HID的数据帧格式和协议定下来因为一旦设备交付、装有上位机的用户多了描述符和Report ID就不能轻易改动否则会造成一批无法识别设备的“砖头”。协议扩展时优先考虑在Payload里做版本号兼容而不是改动描述符。祝各位一次点亮。