![]() |
USB Component
Version 5.0
MDK-Professional Middleware for USB Device and Host
|
Implement application specific behaviour of a Human Interface Device (HID) Class. More...
Functions | |
void | USBD_HIDn_Initialize (void) |
Called during USBD_Initialize to initialize the USB HID class Device. | |
void | USBD_HIDn_Uninitialize (void) |
Called during USBD_Uninitialize to un-initialize the USB HID class Device. | |
int32_t | USBD_HIDn_GetReport (uint8_t rtype, uint8_t req, uint8_t rid, uint8_t *buf) |
Prepare HID Report data to send. | |
bool | USBD_HIDn_SetReport (uint8_t rtype, uint8_t req, uint8_t rid, const uint8_t *buf, int32_t len) |
Process received HID Report data. | |
usbStatus | USBD_HID_GetReportTrigger (int8_t instance, uint8_t rid, const uint8_t *buf, int32_t len) |
Asynchronously prepare HID Report data to send. | |
Implement application specific behaviour of a Human Interface Device (HID) Class.
The HID class in the USB Component is used for data exchange. It implements a vendor defined HID class with Usage Page ID=0xFF00.
Refer to:
The USB Component allows multiple instances of the HID class. This feature is used to create USB Composite Devices. Each HID class instance has a separate files and interface functions:
This documentation uses n as a placeholder for the instance number 0 - 3. Most applications only require one instance of a HID class. For the first HID class instance the instance number is 0:
To create an USB Device with a HID class:
Configuration File USBD_Config_HID_n.h
The configuration file USBD_Config_HID_n.h defines:
These settings are used to create the Interface Descriptor and Endpoint Descriptor of the related USB Device Class. It is important that the settings match the application specific behaviour in the related C source file USBD_User_HID_n.c.
Software Structure
The handling for the HID class endpoint events is implemented in USBD_HID_Thread which is started by USBD_Initialize. Each instance of a HID class runs an instance of USBD_HID_Thread which calls the data exchange functions USBD_HIDn_GetReport and USBD_HIDn_SetReport.
USBD_HID_GetReportTrigger may be called from any user thread to send asynchronous data reports to the USB Host. USBD_HID_GetReportTrigger cannot be called from interrupt service routines (ISR) as it may wait for previous data to be sent.
The HID class uses a CMSIS-RTOS osTimer set to a 4ms interval to handle polling reports. The polling timing is defined with Endpoint Descriptor. For more information refer to "Set_Idle Request" in HID1_11.pdf which is provided by USB Implementers Forum (USB-IF).
The following source code is part of the user code template file. The application specific behaviour may be implemented using this code template.
usbStatus USBD_HID_GetReportTrigger | ( | int8_t | instance, |
uint8_t | rid, | ||
const uint8_t * | buf, | ||
int32_t | len | ||
) |
Asynchronously prepare HID Report data to send.
[in] | instance | instance of HID class. |
[in] | rid | report ID. |
[out] | buf | buffer containing report data to send. |
[in] | len | number of report data bytes to send. |
The function USBD_HID_GetReportTrigger asynchronously prepares data that will be returned to the USB Host upon request. It enables the USB Device to send HID report data only when the data has changed. Usually, the USB Host sets idle time to infinity upon HID Device enumeration. This means, the USB Host expects data from a device only when it has changed. If idle time is not set to infinity, the USBD_HIDn_GetReport function is called whenever the idle time period is expired.
Use the function only for reports of type HID_REPORT_INPUT and for events that needs to update report data. The function should only be used for reports with the rtype = HID_REPORT_INPUT to signal that an updated HID report is available.
The argument instance specifies the instance of the HID device that is to be used.
The argument rid specifies the report ID and should be 0 if there's only one report in the system.
The argument buf is pointing to the buffer with the data to be sent.
The argument len specifies the number of bytes to be sent.
Code Example
int32_t USBD_HIDn_GetReport | ( | uint8_t | rtype, |
uint8_t | req, | ||
uint8_t | rid, | ||
uint8_t * | buf | ||
) |
Prepare HID Report data to send.
[in] | rtype | report type:
|
[in] | req | request type:
|
[in] | rid | report ID (0 if only one report exists). |
[out] | buf | buffer containing report data to send. |
The function USBD_HIDn_GetReport prepares data that will be returned to the USB Host. You may modify the function to the application's needs. The function is called on any of the following events:
The argument rtype specifies the report type:
Value | Description |
---|---|
HID_REPORT_INPUT | Input report requested |
HID_REPORT_FEATURE | Feature report requested |
The argument req specifies the request type:
Value | Description |
---|---|
USBD_HID_REQ_EP_CTRL | Request came from control endpoint |
USBD_HID_REQ_PERIOD_UPDATE | Request came from idle period expiration |
USBD_HID_REQ_EP_INT | Request came from previously sent report on interrupt endpoint |
The argument rid specifies the report ID and should be 0 if there's only one report in the system.
The argument buf is pointing to the buffer to report data.
Code Example
void USBD_HIDn_Initialize | ( | void | ) |
Called during USBD_Initialize to initialize the USB HID class Device.
The function USBD_HIDn_Initialize is called automatically upon initialization of a Human Interface Device Class Device and needs no invocation in the user code. Modify this function to the application needs to allocate resources and initialize additional peripherals.
Code Example
bool USBD_HIDn_SetReport | ( | uint8_t | rtype, |
uint8_t | req, | ||
uint8_t | rid, | ||
const uint8_t * | buf, | ||
int32_t | len | ||
) |
Process received HID Report data.
[in] | rtype | report type:
|
[in] | req | request type:
|
[in] | rid | report ID (0 if only one report exists). |
[in] | buf | buffer that receives report data. |
[in] | len | length of received report data. |
The function USBD_HIDn_SetReport handles HID report data that is received from the USB Host. The function is called when a HID report was received. You may modify the function to the application's needs.
The argument rtype specifies the report type:
Value | Description |
---|---|
HID_REPORT_OUTPUT | Output report received |
HID_REPORT_FEATURE | Feature report received |
The argument req specifies the request type:
Value | Description |
---|---|
USBD_HID_REQ_EP_CTRL | Request came through control endpoint |
USBD_HID_REQ_EP_INT | Request came through interrupt endpoint |
The argument rid specifies the report ID and should be 0 if there's only one report in the system.
The argument buf is pointing to the buffer to report data.
The argument len specifies the length of the received report data.
Code Example
void USBD_HIDn_Uninitialize | ( | void | ) |
Called during USBD_Uninitialize to un-initialize the USB HID class Device.
The function USBD_HIDn_Uninitialize is called automatically upon un-initialization of a Human Interface Device Class Device and needs no invocation in the user code. If USBD_HIDn_Initialize has been adapted to the application, USBD_HIDn_Uninitialize should release resources and should de-initialize peripherals.
Code Example