通过STM32CubeMX生成HID双向通讯工程之示例

[下面内容转载于STM32单片机微信公众号]

前言

客户在做USB通讯的时候，基本的需求就是发送某些数据到USB host端，同时接收一些数据从USB Host端，那么如何快速的建立一个工程并验证数据是否正确呢？下边我们就结合STM32F072的评估板（其他的STM32xx系列的实现方式都是类似的）来快速实现一个简单的数据收发实验。

下面是具体操作和一些基本的解说。

USBHost软件 的准备

PC端软件使用ST免费提供的Usb Hid Demonstrator。这个软件可以在ST官网上免费下载到。连接地址：STSW-STM32084，此软件调用的是windows标准的HID类驱动，所以无需安装任何驱动程序及可运行。

下载安装完这个软件之后，我们就可以开始开发STM32的USB 从机程序了。

首先，打开STM32CubeMX，新建工程，选择STM32F072B-DISCOVERY开发板。

其次，在Pinout选项中，开打USB的device功能。

并在Middleware中选择开启classfor IP中的 custom Human Interface Device（HID）

点击“保存”后直接生成工程。我们这里以生成IAR工程为例，项目名叫做HID。

这样我们的工程就基本成功了，但是还缺少最最关键的一步，就是USB主机和从机的通讯“协议”，这个协议在那里实现呢？因为我们Host端软件已经是Usb Hid Demonstrator，那么这边的协议就已经固定了（其实在实际的开发中大多是主机端和从机相互沟通后，软件自行修改的），从机只需要对应这套协议即可。

将如下代码复制，替换掉usbd_custom_hid_if.c文件中的同名数组。

1. __ALIGN_BEGIN static uint8_tCUSTOM_HID_ReportDesc_FS [USBD_CUSTOM_HID_REPORT_DESC_SIZE] __ALIGN_END =
   ; _8 A; J4 N- M3 g
2. {
   ! u$ Q% @8 t4 {6 J8 Y9 z3 V% S
3. 0x06, 0xFF, 0x00, /* USAGE_PAGE(Vendor Page: 0xFF00) */
   - m4 `: V/ W% Y; o- r" |4 W
4. 0x09, 0x01, /* USAGE (Demo Kit) */
   . r9 \/ X( ~# B
5. 0xa1, 0x01, /* COLLECTION(Application) */
   2 A- Q+ Q- N$ l" N8 y2 K8 \
6. /* 6 */
   
7. /* LED1 */
   ; U5 v' o/ m$ R" f. A$ v" i6 l
8. 0x85, LED1_REPORT_ID, /* REPORT_ID(1) */
   % l8 Y) \( H3 G. M6 y2 R
9. 0x09, 0x01, /* USAGE (LED 1) */
   ; E: D2 I7 l# r* j
10. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    
11. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    
12. 0x75, 0x08, /* REPORT_SIZE (8) */
    
13. 0x95, LED1_REPORT_COUNT, /*REPORT_COUNT (1) */
    
14. 0xB1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    - S5 s5 Y) j$ s( d2 {! J) Z, t
15. 0x85, LED1_REPORT_ID, /* REPORT_ID(1) */
    * C' b8 k; E: U. f( ~7 e
16. 0x09, 0x01, /* USAGE (LED 1) */
    0 r) O) ~6 f) s9 K. [% ~
17. 0x91, 0x82, /* OUTPUT(Data,Var,Abs,Vol) */
    
18. /* 26 */
    
19. /* LED2 */
    
20. 0x85, LED2_REPORT_ID, /* REPORT_ID 2*/
    ! L! i8 x  Y% U! {# ]$ C
21. 0x09, 0x02, /* USAGE (LED 2) */
    
22. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    
23. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    8 O6 L; P) X8 H) V1 p- e
24. 0x75, 0x08, /* REPORT_SIZE (8) */
    % {9 i& ~1 u# A- X- j$ v. S
25. 0x95, LED2_REPORT_COUNT, /*REPORT_COUNT (1) */
    
26. 0xB1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    2 R, K8 P. t1 n& `$ b, {
27. 0x85, LED2_REPORT_ID, /* REPORT_ID(2) */
    
28. 0x09, 0x02, /* USAGE (LED 2) */
    
29. 0x91, 0x82, /* OUTPUT(Data,Var,Abs,Vol) */
    2 \4 b6 x$ V) C4 g5 |9 L8 k, u) ~# w% O
30. /* 46 */
    / |7 U  ]' H/ w. @- ]' P& n9 j
31. /* LED3 */
    7 h  i9 u9 u6 s( `* Z  o
32. 0x85, LED3_REPORT_ID, /* REPORT_ID(3) */
    0 t5 @# A) F$ d9 |( k/ C" P9 T
33. 0x09, 0x03, /* USAGE (LED 3) */
    " g( g* a- r. @* S
34. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    
35. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    6 r/ g* P( b6 @- k- c( w
36. 0x75, 0x08, /* REPORT_SIZE (8) */
    
37. 0x95, LED3_REPORT_COUNT, /*REPORT_COUNT (1) */
    
38. 0xB1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    
39. 0x85, LED3_REPORT_ID, /* REPORT_ID(3) */
    
40. 0x09, 0x03, /* USAGE (LED 3) */
    
41. 0x91, 0x82, /* OUTPUT (Data,Var,Abs,Vol) */
    ( |. o8 j9 m) X) f9 A/ e8 y0 Y
42. /* 66 */
    
43. /* LED4 */
    ! q. ]5 d1 u2 U5 s" T7 r$ n' `2 z( J, Q
44. 0x85, LED4_REPORT_ID, /* REPORT_ID4) */
    
45. 0x09, 0x04, /* USAGE (LED 4) */
    
46. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    : D+ n" E) d& b6 C6 y8 B( k
47. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    
48. 0x75, 0x08, /* REPORT_SIZE (8) */
    
49. 0x95, LED4_REPORT_COUNT, /*REPORT_COUNT (1) */
    
50. 0xB1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    
51. 0x85, LED4_REPORT_ID, /* REPORT_ID(4) */
    
52. 0x09, 0x04, /* USAGE (LED 4) */
    
53. 0x91, 0x82, /* OUTPUT(Data,Var,Abs,Vol) */
    
54. /* 86 */
    
55. /* key Push Button */
    1 x8 k) {) R3 x8 @% Z. @! n
56. 0x85, KEY_REPORT_ID, /* REPORT_ID(5) */
    
57. 0x09, 0x05, /* USAGE (Push Button)*/
    
58. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    
59. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    
60. 0x75, 0x01, /* REPORT_SIZE (1) */
    $ N* N" r1 e& a" C, R
61. 0x81, 0x82, /* INPUT(Data,Var,Abs,Vol) */
    
62. 0x09, 0x05, /* USAGE (Push Button)*/
    : v7 i5 B/ d# M1 K$ w/ i
63. 0x75, 0x01, /* REPORT_SIZE (1) */
    
64. 0xb1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    
65. 0x75, 0x07, /* REPORT_SIZE (7) */
    
66. 0x81, 0x83, /* INPUT(Cnst,Var,Abs,Vol) */
    ! c7 V3 N+ W5 o4 {9 X% a) z
67. 0x85, KEY_REPORT_ID, /* REPORT_ID(2) */
    " p; j2 s( A! k7 {3 I1 T+ Z4 K
68. 0x75, 0x07, /* REPORT_SIZE (7) */
    
69. 0xb1, 0x83, /* FEATURE (Cnst,Var,Abs,Vol)*/
    * x) |& K# m9 _
70. /* 114 */
    
71. /* Tamper Push Button */
    $ c2 X9 D2 S: I& w
72. 0x85, TAMPER_REPORT_ID,/* REPORT_ID(6) */
    
73. 0x09, 0x06, /* USAGE (Tamper PushButton) */
    
74. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    + J) S/ y4 P- F1 W% b
75. 0x25, 0x01, /* LOGICAL_MAXIMUM (1)*/
    . j- L# Y: C  z5 J8 t
76. 0x75, 0x01, /* REPORT_SIZE (1) */
    ) l( q* a1 W! ~% a9 D6 C% k2 I4 a
77. 0x81, 0x82, /* INPUT(Data,Var,Abs,Vol) */
    
78. 0x09, 0x06, /* USAGE (Tamper PushButton) */
    8 c2 V1 A8 {8 I1 h2 ]! K* m
79. 0x75, 0x01, /* REPORT_SIZE (1) */
    
80. 0xb1, 0x82, /* FEATURE(Data,Var,Abs,Vol) */
    
81. 0x75, 0x07, /* REPORT_SIZE (7) */
    ' s' d8 \4 h, ~/ g+ ?/ f, }
82. 0x81, 0x83, /* INPUT (Cnst,Var,Abs,Vol)*/
    
83. 0x85, TAMPER_REPORT_ID,/* REPORT_ID(6) */
    + W, }2 u' U" I+ `
84. 0x75, 0x07, /* REPORT_SIZE (7) */
    
85. 0xb1, 0x83, /* FEATURE(Cnst,Var,Abs,Vol) */
    & @* E! Z, a0 H* r/ v4 e2 q
86. /* 142 */
    7 A9 H; }' c( J
87. /* ADC IN */
    
88. 0x85, ADC_REPORT_ID, /* REPORT_ID */
    0 }/ `) g- V" w+ M
89. 0x09, 0x07, /* USAGE (ADC IN) */
    9 i( I9 n9 W. u9 s- L
90. 0x15, 0x00, /* LOGICAL_MINIMUM (0)*/
    ) X& H% d- J9 m
91. 0x26, 0xff, 0x00, /* LOGICAL_MAXIMUM(255) */
    
92. 0x75, 0x08, /* REPORT_SIZE (8) */
    + {' B0 h: V* k) _
93. 0x81, 0x82, /* INPUT(Data,Var,Abs,Vol) */
    
94. 0x85, ADC_REPORT_ID, /* REPORT_ID(7) */
    
95. 0x09, 0x07, /* USAGE (ADC in) */
    : M7 J( ^1 D1 o2 ^7 ]- T; t
96. 0xb1, 0x82, /* FEATURE (Data,Var,Abs,Vol)*/
    , I! L3 m/ ?- Z& {1 L
97. /* 161 */
    
98. 0xc0 /* END_COLLECTION */
    
99. };

复制代码

注意：这里一定要覆盖“同名”数组，千万不要覆盖错了。

之后将如下代码复制到usbd_custom_hid_if_if.h中。

1. #define LED1_REPORT_ID 0x01
   
2. #define LED1_REPORT_COUNT 0x01
   
3. #define LED2_REPORT_ID 0x02
   ; Q3 h! z3 f+ p1 w$ K: _
4. #define LED2_REPORT_COUNT 0x01
   ( @0 K/ d: Y2 k* R2 Y8 Q# |: K
5. #define LED3_REPORT_ID 0x03
     k0 B0 @& A5 f& S' D1 S6 h2 v
6. #define LED3_REPORT_COUNT 0x01
   2 a# n: C, y. E) m# c1 d2 c! R" e' J! F
7. #define LED4_REPORT_ID 0x04
   ( i4 c$ t2 @6 |' Y  O
8. #define LED4_REPORT_COUNT 0x01
   & ^( V& h/ h7 U& Z
9. #define KEY_REPORT_ID 0x05
   
10. #define TAMPER_REPORT_ID 0x06
    ; ~8 L% C! G* M$ d
11. #define ADC_REPORT_ID 0x07

复制代码

" _8 c- {/ s% H  {* n  w

最后在usbd_conf.h文件中将USBD_CUSTOM_HID_REPORT_DESC_SIZE的定义值修改

为163（默认值是2）

1. #defineUSBD_CUSTOM_HID_REPORT_DESC_SIZE 163 //2

复制代码

: R( @$ p& c2 l5 D9 E& U

为什么这样修改呢? 简单说一下其中关键值的含义。

这个HID 的报文描述符其实定义了8个部分（条目）的功能定义，分为LED1，LED2，LED3，

LED4，按键输入，篡改按键输入和ADC输入。每部分的基本格式都是固定的。以LED1为例（其他条目可自行对照文档解析）：

0x85, LED1_REPORT_ID， 含义是这个功能的ID号是LED1_REPORT_ID（宏定义为0x01）

这个ID号是每次报文发送的时候最先被发送出去的（USB都是LSB）字节，之后跟着的才是我们实际有效的数据/指令，到底是数据还是指令，就看你的应用程序如何去解析这个数据了。

0x09, 0x01, 这个功能序号为1，后边的序号依次递加。

0x15, 0x00, 这个是规定逻辑最小值为0 。

0x25, 0x01, 这个是规定逻辑最大值为1 。

上边的这两条语句规定了跟在报文ID后边的数据范围，最大值是1，最小值是0.（因为我们的LED也就只有灭和亮两种状态）

0x75, 0x08, 这个是报文的大小为8，只要别写错就行了。

0x95, LED1_REPORT_COUNT， 这个是说下边有LED1_REPORT_COUNT （宏定义为1）个项目会被添加，即这个功能的数量是1个 。

0xB1, 0x82, 这个是规定能够发送给从机设备的数据信息。

0x91, 0x82, 这个规定了该功能的数据方向是输出（传输方向以主机为参照）。

总结一下，通过这个报文描述符，我们就告诉了主机，在HID中有一个功能ID为1的功能，其方向是从主机到从机，每次发送1个有效数据（前边的ID是都要含有的），这个数据可以是0或者是1.

关于HID 报文描述符的详细信息，您可以在下边的网址下载一篇叫做《Device Class Definitionfor HID》的文档来参考。

http://www.usb.org/developers/hidpage

这样基本的程序框架就已经成功了。此时我们可以先编译一下，看看是否有任何遗漏的或者笔误。如果编译是正确的，那么我们就可以先下载到硬件开发板上，连接到PC端，看看是否可以枚举出设备。如果您前边的修改都是正确的，那么在PC的设备管理器中会看到如下图所示的内容。

注意：开发板上有两个一模一样的Mini USB接口，一个是USB USER，另 一个是USB ST-link，下载代码的时候用USB ST-Link，连接电脑运行程序的时候要用USB USER。

此时我们的USB枚举就完成了，这个是USB通讯的关键步骤，之后的应用通讯内容都是通过这个枚举工程来进行“规划”的。

数据发送

就类似串口通讯，我们首先做一个数据的发送工作。

在Main.c文件中，我们在while(1)的主循环中增加我们的发送函数，主要就是调用发送报文的API：USBD_CUSTOM_HID_SendReport（）

1. /* USER CODE BEGIN 2 */
   9 I- o( `1 c% i; ~
2. uint8_t i=0;
   6 N; M# v# l' }$ H1 X
3. sendbuffer[0]=0x07; //这个是report ID，每次发送报文都需要以这个为开始，这样主机才能正确//解析后边的数据含义
   
4. sendbuffer[1]=0x01; //这个是实际发送的数据，可以自由定义，只要不超过报文描述符的限制
   & Q6 w. C0 ~6 b
5. /* USER CODE END 2 */
   % u% ^" W1 F; H: v4 `9 E6 Q8 t
6. /* Infinite loop */
   
7. /* USER CODE BEGIN WHILE */
   ' A2 e3 y8 s0 d. f! e
8. while (1)
   
9. {
   1 W9 R) r- {, g; Z
10. HAL_Delay(100); //延迟100ms
    1 J( X4 G9 d: O0 f; i
11. sendbuffer[1]++; //每次发送都将变量自加1
    
12. USBD_CUSTOM_HID_SendReport(&hUsbDeviceFS,sendbuffer,2);//发送报文
    
13. /* USER CODE END WHILE */
    
14. /* USER CODE BEGIN 3 */
    9 T+ p6 t  L. I) L9 r
15. }
    
16. /* USER CODE END 3 */

复制代码

: C! y* w8 @/ Y7 x7 ]$ V) y

编译后下载到MCU内，连接上位机软件即可看到如下所示的进度条在不断的增长。

这个就是我们上传到的数据在上位机的图形显示，你也可以看Input/outputtransfer里的数据变化。

这样看起来是不是更像是串口调试助手了？嘿嘿本来机制就差不多的。

数据接收

MCU的USB数据是如何接收的呢？是不是调用一个类似于串口接收的API呢？

不是的！USB的数据接收都是在中断中完成的，在新建的工程中，我们在函数CUSTOM_HID_OutEvent_FS内增加如下代码。

1. static int8_t CUSTOM_HID_OutEvent_FS(uint8_t event_idx, uint8_t state)
   + ^6 s, t4 `/ m
2. {
   / M! L, e# D0 E: ^! W
3. /* USER CODE BEGIN 6 */switch(event_idx)
   ' z0 a. ^0 B) ]! Y4 K
4. {
   
5. case 1: /* LED3 */
   2 F$ q2 T  O& o4 a
6. (state == 1) ?HAL_GPIO_WritePin(LD3_GPIO_Port,LD3_Pin,GPIO_PIN_SET) :
   * q8 h% S7 S, \, y7 g4 ?
7. HAL_GPIO_WritePin(LD3_GPIO_Port,LD3_Pin,GPIO_PIN_RESET);
   
8. break;
   6 a7 u2 g& {8 U, q0 r
9. case 2: /* LED4 */
   3 l# z" R3 |( H* U- F
10. (state == 1) ?HAL_GPIO_WritePin(LD4_GPIO_Port,LD4_Pin,GPIO_PIN_SET) :
    1 {3 E3 l% O' V9 h8 h
11. HAL_GPIO_WritePin(LD4_GPIO_Port,LD4_Pin,GPIO_PIN_RESET);
    
12. break;
    
13. case 3: /* LED5 */
    % C+ V, ?1 |( F* L  R3 _
14. (state == 1) ?HAL_GPIO_WritePin(LD5_GPIO_Port,LD5_Pin,GPIO_PIN_SET) :
    3 u" g% F# p. X7 H+ m' T/ b7 P* ]
15. HAL_GPIO_WritePin(LD5_GPIO_Port,LD5_Pin,GPIO_PIN_RESET);
    
16. break;
    
17. case 4: /* LED6 */
    ; q  z7 N' v. z" N
18. (state == 1) ?HAL_GPIO_WritePin(LD6_GPIO_Port,LD6_Pin,GPIO_PIN_SET) :
    
19. HAL_GPIO_WritePin(LD6_GPIO_Port,LD6_Pin,GPIO_PIN_RESET);
    
20. break;
    
21. default:
    
22. break;
    
23. }
    
24. return (0);
    + D0 B2 o2 W/ i2 e
25. /* USER CODE END 6 */
    3 p( z- ?$ m' }- R3 K! b. Z
26. }

复制代码

编译之后下载到MCU内，通过USBUSER连接到PC端，打开UsbHidDemonstrator，我们可以通过勾选右下角的图形界面来实现控制开发板上的LED电量或者关闭。

当然，这个是通过图像化的界面来进行控制，你也可以通过Input/outputtransfer中的写入对话框来完成这个操作。注意，写入的第一个字节是ID，表示你想控制的是哪个LED；第二个字节是0或者是1，表示你想让这个LDE的状态变成灭还是亮。

总结：

本范例程序是为了快速实现USB 从机设备与主句设备双向通讯目的，其初始化代码是用STM32CubeMX来生成的，大大降低了工程师开发USB设备的难度（尤其是是入门阶段的难度）。从这个工程的基础上，工程师可以比较方便的建立好框架工程并，对其中的代码进行研究，进而移植或增加自己的应用代码。

- ]$ A5 B- U/ x& V( ~

文章出处： 茶话MCU

; p3 i; V5 R) V) r+ g