21ic电子技术开发论坛 › 单片机与嵌入式系统 › ST MCU › 基于STM32F103实现USB Joystick并介绍USB HID协议在STM3 ...
返回列表 发新帖我要提问

[STM32F1] 基于STM32F103实现USB Joystick并介绍USB HID协议在STM32 HAL库中实现

[复制链接]
 楼主| lilijin1995 发表于 2022-11-12 11:47 | 显示全部楼层 |阅读模式
HID, HID协议, JOYSTICK, ST, STM
本帖最后由 lilijin1995 于 2022-11-12 13:41 编辑

#申请原创#
@21小跑堂


基于STM32F103实现USB Joystick并介绍USB HID协议在STM32 HAL库中实现


自序

由于作者水平有限，文档和视频中难免有出错和讲得不好的地方，欢迎各位读者和观众善意地提出意见和建议，谢谢！


第一部分、硬件概述1.1 实物概图

图1.1Gamepad实物概图

1966993-20221015162528917-648827262.jpg


如图1.1所示Gamepad评估板配置了8个6*6轻触按键，一个摇杆（Joystick），搭载一颗WS2812B灯珠，并将UART1串口，编程接口（SWD），外接Joystick接口，microUSB接口引出;  


1.2 Gamepad原理图

Gamepad原理图如图1.2所示，如看不清可打开Doc目录下的PDF文档查阅  

Schematic_Joystick_V2.01_2022-2-12_14-07-01_第1页.png


第二部分、软件工具2.1 软件概述

   在 /Software 目录下是常用的工具软件：

  • Dt2_4：配置USB设备Report描述符的工具；
  • USBHID调试助手/呀呀USB： USB调试工具，相当于串口调试助手功能；
  • BUSHound：总线调试工具；
  • USBlyzer：一款专业的USB协议分析软件
  • MDK:常用编译器；
  • STM32CubeMX：代码生成工具；

第三部分、实战训练3.1 实例Eg1_Joystick

目标是实现 Joystick:枚举成XY轴的平面坐标和8个按键的USB HID。  

3.1.1硬件设计   

图1.3 Joystick原理图

    1966993-20211214224348752-1607121797.png

其中VRX1与VRY1是摇杆的电位器输出的电压信号（ADC检测)；SW1则是按键，右侧H1是外接的Joystick口备用;  


图1.4 KEY原理图  

1966993-20211214224447009-112297073.png

如图1.4是KEY原理图，我们只要配置8个GPIO作为输入去检测按键信号;  

3.1.2 软件设计

USB设备开发需要具备一定的USB设备开发知识；关于Usb的学习，这里推荐两个学习视频和一个学习网站：

  • USB技术应用与开发：
  • CherryUSB设备协议栈教程：
  • USB中文网：
    https://www.usbzh.com/

    我们主要做USB HID开发，一般我们需要了解一些标准请求，还有HID类的请求；其中标准请求主要是主机获取设备描述符、配置描述符、接口描述符、端点描述符、字符串描述符的过程，如果是HID，还有HID描述符的过程 ，以及报表描述符的过程；

    一般的，我们配套的视频都有讲解USB设备枚举过程在代码中的实现，这里主要是基于STM32 HAL库的；

    首先是初始化代码，我们通过STM32cubeMX软件去生成代码，具体配置请打开GamePad.ioc查阅，配套视频也有关键部分的讲解，这里不再赘述;  我们的工程使用的是Keil-MDK编译器，生成的工程目录如图1.5  

    1966993-20211214224618747-792020857.png 图1.5 工程目录其中


    • Application/MDK-ARM 存放的是启动代码；
    • Application/User/Core： main函数，中断Handler，MSP相关代码；
    • Application/User/USB_DEVICE/App：* USB设备应用代码；
    • Application/User/USB_DEVICE/Target： USB设备配置代码；
    • Drivers/STM32F1xx_HAL_Driver： HAL库驱动代码
    • Drivers/CMSIS： CMSIS相关代码        
    • Middlewares/USB_Device_Library/ USB设备库代码，对应cubemx Middleware；
    • Customer： 这是我们自定义的代码；
    • Doc： 存放说明文本文档；

    工程目录这里只做一次介绍，后面的样例目录大同小异。

    以下USB部分内容请大家务必多看几遍代码， 我们打开工程中的main函数可以看到

复制
  1. int main(void)
    

  2. {
    

  3.   /* Reset of all peripherals, Initializes the Flash interface and the Systick. */
    

  4.   HAL_Init();
    

  5.   /* Configure the system clock */
    

  6.   SystemClock_Config();
    

  7.   /* Initialize all configured peripherals */
    

  8.   MX_GPIO_Init();
    

  9.   MX_DMA_Init();
    

  10.   MX_ADC1_Init();
    

  11.   MX_USB_DEVICE_Init();
    

  12.   MX_USART1_UART_Init();  
    

  13.   Gp_ADC_Start_DMA();//启动ADC DMA并开启中断
    

  14.   while (1)
    

  15.   {
    

  16.         Gp_SendReport();        
    

  17.   }
    

  18. }
其中只有Gp_ADC_Start_DMA和Gp_SendReport是我们自定义的代码；其他均是STM32CUBEMX生成；由于篇幅的原因，我们主要介绍MX_USB_DEVICE_Init；
复制
  1. void MX_USB_DEVICE_Init(void)
    

  2. {
    

  3.   /* Init Device Library, add supported class and start the library. */
    

  4.   if (USBD_Init(&hUsbDeviceFS, &FS_Desc, DEVICE_FS) != USBD_OK)
    

  5.   {
    

  6.     Error_Handler();
    

  7.   }
    

  8.   if (USBD_RegisterClass(&hUsbDeviceFS, &USBD_CUSTOM_HID) != USBD_OK)
    

  9.   {
    

  10.     Error_Handler();
    

  11.   }
    

  12.   if (USBD_CUSTOM_HID_RegisterInterface(&hUsbDeviceFS, &USBD_CustomHID_fops_FS) != USBD_OK)
    

  13.   {
    

  14.     Error_Handler();
    

  15.   }
    

  16.   if (USBD_Start(&hUsbDeviceFS) != USBD_OK)
    

  17.   {
    

  18.     Error_Handler();
    

  19.   }
    

  20. }
其中USBD_Init函数中的FS_Desc数据结构里面是获取UBS设备描述符USBD_FS_DeviceDescriptor，语言ID字符串描述符USBD_FS_LangIDStrDescriptor，厂商字符串描述符USBD_FS_ManufacturerStrDescriptor，产品字符串描述符USBD_FS_ProductStrDescriptor，序列号字符串描述符USBD_FS_SerialStrDescriptor，配置字符串描述符USBD_FS_ConfigStrDescriptor，接口描述符USBD_FS_InterfaceStrDescriptor的函数指针；
上述描述符中，UBS设备描述符是必需的，其他都是字符串描述符，可选的；我们不妨打开usb描述符获取函数与usb描述符报表。
 14603636f2c12ee986.png



关于USB设备描述符的介绍，注释已经非常清楚；不了解的地方可以学习一下前面的推荐两个学习视频和一个学习网站；

设备描述符找到了，我们还需要的配置描述符，接口描述符，HID描述符（如果是HID设备），端点描述符；

我们继续回到MX_USB_DEVICE_Init，可以看到USBD_RegisterClass中的USBD_CUSTOM_HID，其中USBD_CUSTOM_HID_Setup是处理USB主机的一些请求过程，包括标准请求等；而USBD_CUSTOM_HID_GetHSCfgDesc（高速）和USBD_CUSTOM_HID_GetFSCfgDesc（全速）都是配置描述符；


复制
  1. USBD_ClassTypeDef  USBD_CUSTOM_HID =
    

  2. {
    

  3.   USBD_CUSTOM_HID_Init,
    

  4.   USBD_CUSTOM_HID_DeInit,
    

  5.   USBD_CUSTOM_HID_Setup,
    

  6.   NULL, /*EP0_TxSent*/
    

  7.   USBD_CUSTOM_HID_EP0_RxReady, /*EP0_RxReady*/ /* STATUS STAGE IN */
    

  8.   USBD_CUSTOM_HID_DataIn, /*DataIn*/
    

  9.   USBD_CUSTOM_HID_DataOut,
    

  10.   NULL, /*SOF */
    

  11.   NULL,
    

  12.   NULL,
    

  13.   USBD_CUSTOM_HID_GetHSCfgDesc,
    

  14.   USBD_CUSTOM_HID_GetFSCfgDesc,
    

  15.   USBD_CUSTOM_HID_GetOtherSpeedCfgDesc,
    

  16.   USBD_CUSTOM_HID_GetDeviceQualifierDesc,
    

  17. };
由于我们的MCU是支持全速的，所以这里应该是USBD_CUSTOM_HID_GetFSCfgDesc，
复制
  1. /* USB CUSTOM_HID device FS Configuration Descriptor */
    

  2. __ALIGN_BEGIN static uint8_t USBD_CUSTOM_HID_CfgFSDesc[USB_CUSTOM_HID_CONFIG_DESC_SIZ] __ALIGN_END =
    

  3. {
    

  4.   0x09, /* bLength: Configuration Descriptor size */
    

  5.   USB_DESC_TYPE_CONFIGURATION, /* bDescriptorType: Configuration */
    

  6.   USB_CUSTOM_HID_CONFIG_DESC_SIZ,
    

  7.   /* wTotalLength: Bytes returned */
    

  8.   0x00,
    

  9.   0x01,         /*bNumInterfaces: 1 interface*/
    

  10.   0x01,         /*bConfigurationValue: Configuration value*/
    

  11.   0x00,         /*iConfiguration: Index of string descriptor describing
    

  12.   the configuration*/
    

  13.   0xC0,         /*bmAttributes: bus powered */
    

  14.   0x32,         /*MaxPower 100 mA: this current is used for detecting Vbus*/
    


  15. 

  16.   /************** Descriptor of CUSTOM HID interface ****************/
    

  17.   /* 09 */
    

  18.   0x09,         /*bLength: Interface Descriptor size*/
    

  19.   USB_DESC_TYPE_INTERFACE,/*bDescriptorType: Interface descriptor type*/
    

  20.   0x00,         /*bInterfaceNumber: Number of Interface*/
    

  21.   0x00,         /*bAlternateSetting: Alternate setting*/
    

  22.   0x02,         /*bNumEndpoints*/
    

  23.   0x03,         /*bInterfaceClass: CUSTOM_HID*/
    

  24.   0x00,         /*bInterfaceSubClass : 1=BOOT, 0=no boot*/
    

  25.   0x00,         /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
    

  26.   0,            /*iInterface: Index of string descriptor*/
    

  27.   /******************** Descriptor of CUSTOM_HID *************************/
    

  28.   /* 18 */
    

  29.   0x09,         /*bLength: CUSTOM_HID Descriptor size*/
    

  30.   CUSTOM_HID_DESCRIPTOR_TYPE, /*bDescriptorType: CUSTOM_HID*/
    

  31.   0x11,         /*bCUSTOM_HIDUSTOM_HID: CUSTOM_HID Class Spec release number*/
    

  32.   0x01,
    

  33.   0x00,         /*bCountryCode: Hardware target country*/
    

  34.   0x01,         /*bNumDescriptors: Number of CUSTOM_HID class descriptors to follow*/
    

  35.   0x22,         /*bDescriptorType*/
    

  36.   USBD_CUSTOM_HID_REPORT_DESC_SIZE,/*wItemLength: Total length of Report descriptor*/
    

  37.   0x00,
    

  38.   /******************** Descriptor of Custom HID endpoints ********************/
    

  39.   /* 27 */
    

  40.   0x07,          /*bLength: Endpoint Descriptor size*/
    

  41.   USB_DESC_TYPE_ENDPOINT, /*bDescriptorType:*/
    


  42. 

  43.   CUSTOM_HID_EPIN_ADDR,     /*bEndpointAddress: Endpoint Address (IN)*/
    

  44.   0x03,          /*bmAttributes: Interrupt endpoint*/
    

  45.   CUSTOM_HID_EPIN_SIZE, /*wMaxPacketSize: 2 Byte max */
    

  46.   0x00,
    

  47.   CUSTOM_HID_FS_BINTERVAL,          /*bInterval: Polling Interval */
    

  48.   /* 34 */
    


  49. 

  50.   0x07,          /* bLength: Endpoint Descriptor size */
    

  51.   USB_DESC_TYPE_ENDPOINT, /* bDescriptorType: */
    

  52.   CUSTOM_HID_EPOUT_ADDR,  /*bEndpointAddress: Endpoint Address (OUT)*/
    

  53.   0x03, /* bmAttributes: Interrupt endpoint */
    

  54.   CUSTOM_HID_EPOUT_SIZE,  /* wMaxPacketSize: 2 Bytes max  */
    

  55.   0x00,
    

  56.   CUSTOM_HID_FS_BINTERVAL,  /* bInterval: Polling Interval */
    

  57.   /* 41 */
    

  58. };
    

  59. static uint8_t  *USBD_CUSTOM_HID_GetFSCfgDesc(uint16_t *length)
    

  60. {
    

  61.   *length = sizeof(USBD_CUSTOM_HID_CfgFSDesc);
    

  62.   return USBD_CUSTOM_HID_CfgFSDesc;
    

  63. }

细心的同学可以发现，其实这个函数是获取了配置描述符，接口描述符，HID描述符，端点描述符；不过一般的，主机一般都是先请求配置描述符，然后通过配置描述符就知道了整个描述符集合的大小USB_CUSTOM_HID_CONFIG_DESC_SIZ；

现在配置描述符，接口描述符，HID描述符，端点描述符都有了，因为我们是HID设备，故而还需要报表描述符；还是回到MX_USB_DEVICE_Init，在USBD_CUSTOM_HID_RegisterInterface这个函数中的USBD_CustomHID_fops_FS结构体中的第一个成员，真是众里寻他千百度,蓦然回首,那报表描述符却在灯火阑珊处。

复制
  1. /** Usb HID report descriptor. */
    

  2. __ALIGN_BEGIN static uint8_t CUSTOM_HID_ReportDesc_FS[USBD_CUSTOM_HID_REPORT_DESC_SIZE] __ALIGN_END =
    

  3. {
    

  4.     0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    

  5.     0x09, 0x04,                    // USAGE (Joystick)
    

  6.     0xa1, 0x01,                    // COLLECTION (Application)
    

  7.     0xa1, 0x02,                    //     COLLECTION (Logical)
    

  8.     0x09, 0x30,                    //     USAGE (X)
    

  9.     0x09, 0x31,                    //     USAGE (Y)
    

  10.     0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    

  11.     0x26, 0xff, 0x00,              //     LOGICAL_MAXIMUM (255)
    

  12.     0x35, 0x00,                    //     PHYSICAL_MINIMUM (0)
    

  13.     0x46, 0xff, 0x00,              //     PHYSICAL_MAXIMUM (255)
    

  14.     0x75, 0x08,                    //     REPORT_SIZE (8)
    

  15.     0x95, 0x02,                    //     REPORT_COUNT (2)
    

  16.     0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    

  17.     0x05, 0x09,                    //     USAGE_PAGE (Button)
    

  18.     0x19, 0x01,                    //     USAGE_MINIMUM (Button 1)
    

  19.     0x29, 0x08,                    //     USAGE_MAXIMUM (Button 8)
    

  20.     0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    

  21.     0x25, 0x01,                    //     LOGICAL_MAXIMUM (1)
    

  22.     0x95, 0x08,                    //     REPORT_COUNT (8)
    

  23.     0x75, 0x01,                    //     REPORT_SIZE (1)
    

  24.     0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    

  25.     0xc0,                          //     END_COLLECTION
    

  26.     0xC0                                               //END_COLLECTION                     */
    

  27. };
    

  28. USBD_CUSTOM_HID_ItfTypeDef USBD_CustomHID_fops_FS =
    

  29. {
    

  30.   CUSTOM_HID_ReportDesc_FS,
    

  31.   CUSTOM_HID_Init_FS,
    

  32.   CUSTOM_HID_DeInit_FS,
    

  33.   CUSTOM_HID_OutEvent_FS
    

  34. };

另外需要注意USBD_CUSTOM_HID_REPORT_DESC_SIZE,  这个宏是报告描述符实际数组大小，大小不对会导致枚举失败;  

"#define USBD_CUSTOM_HID_REPORT_DESC_SIZE     46"

以上报表描述符通过生成工具Dt2_4配置生成报告描述符，可以看出X,Y轴定义成无符号8位数，XY的描述占用2个字；按键一共有8个，每个大小描述是bit，8个bit即1个byte；因此XY坐标+8个按键=3个byte；我们需要上报3个byte的数据给主机（HOST）。

最后是应用程序的编写，在main函数中调用Gp_ADC_Start_DMA和Gp_SendReport，其中Gp_ADC_Start_DMA是启动ADC DMA 中断完成采样的，而Gp_SendReport则是解析ADC采样后的数据并上报；

我们是通过Gp_ADC_Start_DMA调用HAL_ADC_Start_DMA启动ADC DMA模式采样，需要传入hadc1句柄，AD_DATA数据缓存，AD_DATA_SIZE缓存大小，其中偶数索引是ADC通道0的采样数据，如AD_DATA[0],AD_DATA[2]，反之则是通道2的数据；HAL_ADC_Start_IT是启动ADC1的全局中断，HAL_ADC_ConvCpltCallback是采样完成的中断回调函数，在stm32f1xx_it.c的ADC1_2_IRQHandler里面可遍历找到。

复制
  1. //启动ADC DMA
    

  2. void Gp_ADC_Start_DMA(void)
    

  3. {
    

  4.     HAL_ADC_Start_DMA(&hadc1, (uint32_t*)&AD_DATA, AD_DATA_SIZE);
    

  5.     HAL_ADC_Start_IT(&hadc1);
    

  6. }
    

  7. /**        ADC ISR
    

  8. *                Handles the values from ADC after the conversion finished
    

  9. */
    

  10. void HAL_ADC_ConvCpltCallback(ADC_HandleTypeDef* hadc) {
    


  11. 

  12.     if( adcValueReady == 0 ) {
    

  13.         for(i=0; i<AD_DATA_SIZE;)
    

  14.         {
    

  15.             AdXSum += AD_DATA[i];
    

  16.             i++;
    

  17.             AdYSum += AD_DATA[i];
    

  18.             i++;
    

  19.         }
    

  20.         adcValueReady = 1;
    

  21.     }
    


  22. 

  23. }

再来看我们的数据处理上报函数

复制
  1. //按键扫描
    

  2. u8 key_scan(void)
    

  3. {
    

  4.     key=0;
    

  5.     if((UPKEY)==0)
    

  6.     {
    

  7.         key|=BIT0;
    

  8.     }else{
    

  9.                 key&=(~BIT0);
    

  10.         }
    

  11.     if((LFKEY)==0)
    

  12.     {
    

  13.         key|=BIT1;
    

  14.     }else{
    

  15.                 key&=(~BIT1);
    

  16.         }
    

  17.     if((RGKEY)==0)
    

  18.     {
    

  19.         key|=BIT2;
    

  20.     }else{
    

  21.                 key&=(~BIT2);
    

  22.         }
    

  23.     if((DNKEY)==0)
    

  24.     {
    

  25.         key|=BIT3;
    

  26.     }else{
    

  27.                 key&=(~BIT3);
    

  28.         }
    

  29.     if((TBKEY)==0)
    

  30.     {
    

  31.         key|=BIT4;
    

  32.     }else{
    

  33.                 key&=(~BIT4);
    

  34.         }
    

  35.     if((BKKEY)==0)
    

  36.     {
    

  37.         key|=BIT5;
    

  38.     }else{
    

  39.                 key&=(~BIT5);
    

  40.         }
    

  41.     if((MDKEY)==0)
    

  42.     {
    

  43.         key|=BIT6;
    

  44.     }else{
    

  45.                 key&=(~BIT6);
    

  46.         }
    

  47.     if((STKEY)==0)
    

  48.     {
    

  49.         key|=BIT7;
    

  50.     }else{
    

  51.                 key&=(~BIT7);
    

  52.         }
    

  53.     return key;
    


  54. 

  55. }
    


  56. 


  57. 

  58. /*        Re-maps a number from one range to another
    

  59. *
    

  60. */
    

  61. int32_t map(int32_t x, int32_t in_min, int32_t in_max, int32_t out_min, int32_t out_max){
    

  62.   return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
    

  63. }
    


  64. 


  65. 

  66. //处理并上报数据
    

  67. void Gp_SendReport(void)
    

  68. {
    

  69.         u8 X=0,Y=0,Ktemp=0;
    

  70.         if( adcValueReady == 1 )
    

  71.         {
    

  72.                 Xtemp=AdXSum/10;
    

  73.                 AdXSum=0;
    

  74.                 Ytemp=AdYSum/10;
    

  75.                 AdYSum=0;
    

  76.                 if(Xtemp>Xmax)
    

  77.                         Xtemp=Xmax;
    

  78.                 if(Xtemp<Xmin)
    

  79.                         Xtemp=Xmin;
    


  80. 

  81.                 if(Ytemp>Ymax)
    

  82.                         Ytemp=Ymax;
    

  83.                 if(Ytemp<Ymin)
    

  84.                         Ytemp=Ymin;                
    

  85.                 adcValueReady=0;
    

  86.         }
    


  87. 

  88.     X=(uint8_t)map( Xtemp, Xmin, Xmax, 0, UINT8_MAX );
    

  89.     Y=(uint8_t)map( Ytemp, Ymin, Ymax, 0, UINT8_MAX );
    

  90.         Ktemp=key_scan();
    

  91.         Joystick_Report[0]=Y;
    

  92.         Joystick_Report[1]=X;
    

  93.         Joystick_Report[2]=Ktemp;
    

  94.         USBD_CUSTOM_HID_SendReport(&hUsbDeviceFS,(u8*)&Joystick_Report, 3);        
    

  95.                                         
    

  96.         HAL_Delay(5);
    

  97.         
    

  98. }

key_scan是扫描按键，map是转换数据的范围，因为我们的ADC采样是12bit，取值0~4095，需要转成8bit，0~255；

最后通过USBD_CUSTOM_HID_SendReport上报数据给主机。


3.1.3 下载验证

我们把固件程序下载进去可以，打开“设备与打印机”可以看到USB设备枚举成了一个Gamepad，如下图。

   1966993-20211214231513890-445089246.png   

图1.5 Gamepad设备  右键打开游戏控制器后，点击属性得到下图所示界面

1966993-20211214231614778-314243803.png

图1.6 游戏控制器  

我们可以摇Joystick和按按键可以发现上图游戏控制器界面也跟着响应。

3.1.4 入门视频

本期的入门视频如下：

回复 赏

举报

相关帖子
返回列表 发新帖
高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 注册

本版积分规则

lilijin1995

56

主题

165

帖子

8

粉丝
快速回复 在线客服 返回列表 返回顶部