USB Component  Version 6.0
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
HID: Human Interface Class Functions

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.
 

Description

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).

msc_inline_mscgraph_2

Code Example

The following source code is part of the user code template file. The application specific behaviour may be implemented using this code template.

#include "rl_usbd.h"
#include "usb_hid.h"
// Called during USBD_Initialize to initialize the USB Device class.
void USBD_HIDn_Initialize (void) {
// Add code for initialization
}
// Called during USBD_Uninitialize to de-initialize the USB Device class.
// Add code for de-initialization
}
// \brief Prepare HID Report data to send.
// \param[in] rtype report type:
// - HID_REPORT_INPUT = input report requested
// - HID_REPORT_FEATURE = feature report requested
// \param[in] req request type:
// - USBD_HID_REQ_EP_CTRL = control endpoint request
// - USBD_HID_REQ_PERIOD_UPDATE = idle period expiration request
// - USBD_HID_REQ_EP_INT = previously sent report on interrupt endpoint request
// \param[in] rid report ID (0 if only one report exists).
// \param[out] buf buffer containing report data to send.
// \return number of report data bytes prepared to send or invalid report requested.
// - value >= 0: number of report data bytes prepared to send
// - value = -1: invalid report requested
int32_t USBD_HIDn_GetReport (uint8_t rtype, uint8_t req, uint8_t rid, uint8_t *buf) {
switch (rtype) {
case HID_REPORT_INPUT:
switch (rid) {
case 0:
switch (req) {
case USBD_HID_REQ_EP_CTRL: // Explicit USB Host request via Control OUT Endpoint
case USBD_HID_REQ_PERIOD_UPDATE: // Periodic USB Host request via Interrupt OUT Endpoint
// Update buffer for report data, example:
// buf[0] = 0; // Data Value = 0
// buf[1] = 5; // Data Value = 5
// return (2); // Data Size = 2 bytes
break;
case USBD_HID_REQ_EP_INT: // Called after USBD_HID_GetReportTrigger to signal
// data obtained.
break;
}
break;
}
break;
case HID_REPORT_FEATURE:
break;
}
return (0);
}
// \brief Process received HID Report data.
// \param[in] rtype report type:
// - HID_REPORT_OUTPUT = output report received
// - HID_REPORT_FEATURE = feature report received
// \param[in] req request type:
// - USBD_HID_REQ_EP_CTRL = report received on control endpoint
// - USBD_HID_REQ_EP_INT = report received on interrupt endpoint
// \param[in] rid report ID (0 if only one report exists).
// \param[in] buf buffer that receives report data.
// \param[in] len length of received report data.
// \return true received report data processed.
// \return false received report data not processed or request not supported.
bool USBD_HIDn_SetReport (uint8_t rtype, uint8_t req, uint8_t rid, const uint8_t *buf, int32_t len) {
switch (rtype) {
case HID_REPORT_OUTPUT:
/*
buf: Received Data
len: Received Data Length
*/
break;
case HID_REPORT_FEATURE:
break;
}
return true;
}

Function Documentation

usbStatus USBD_HID_GetReportTrigger ( int8_t  instance,
uint8_t  rid,
const uint8_t *  buf,
int32_t  len 
)

Asynchronously prepare HID Report data to send.

Parameters
[in]instanceinstance of HID class.
[in]ridreport ID.
[out]bufbuffer containing report data to send.
[in]lennumber of report data bytes to send.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

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

#include "cmsis_os.h"
#include "rl_usb.h"
#include "Keyboard.h"
int main (void) {
uint8_t but;
uint8_t buf[2];
Keyboard_Initialize();
USBD_Initialize (0); /* USB Device 0 Initialization */
USBD_Connect (0); /* USB Device 0 Connect */
USBD_Initialize (1); /* USB Device 1 Initialization */
USBD_Connect (1); /* USB Device 1 Connect */
while (1) { /* Loop forever */
but = (uint8_t)(Keyboard_GetKeys ());
if (((but ) ^ buf[0]) & 1) {
buf[0] = (but ) & 1;
USBD_HID_GetReportTrigger(0, 0, &buf[0], 1);
}
if (((but >> 1) ^ buf[1]) & 3) {
buf[1] = (but >> 1) & 3;
USBD_HID_GetReportTrigger(1, 0, &buf[1], 1);
}
osDelay(100); /* 100 ms delay for sampling buttons */
}
}
int32_t USBD_HIDn_GetReport ( uint8_t  rtype,
uint8_t  req,
uint8_t  rid,
uint8_t *  buf 
)

Prepare HID Report data to send.

Parameters
[in]rtypereport type:
  • HID_REPORT_INPUT = input report requested
  • HID_REPORT_FEATURE = feature report requested
[in]reqrequest type:
  • USBD_HID_REQ_EP_CTRL = control endpoint request
  • USBD_HID_REQ_PERIOD_UPDATE = idle period expiration request
  • USBD_HID_REQ_EP_INT = previously sent report on interrupt endpoint request
[in]ridreport ID (0 if only one report exists).
[out]bufbuffer containing report data to send.
Returns
number of report data bytes prepared to send or invalid report requested.
  • value >= 0: number of report data bytes prepared to send
  • value = -1: invalid report requested

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:

  • after a USBD_HID_GetReportTrigger was sent to the USB Host,
  • if HID report was requested by the USB Host through the control endpoint.

The argument rtype specifies the report type:

Value Description
HID_REPORT_INPUT Input report requested
HID_REPORT_FEATUREFeature 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_UPDATERequest 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

#include "rl_usbd.h"
#include "usb_hid.h"
int32_t USBD_HIDn_GetReport (uint8_t rtype, uint8_t req, uint8_t rid, uint8_t *buf) {
switch (rtype) {
case HID_REPORT_INPUT:
switch (rid) {
case 0:
switch (req) {
break;
}
break;
}
break;
case HID_REPORT_FEATURE:
break;
}
return (0);
}
void USBD_HIDn_Initialize ( void  )

Called during USBD_Initialize to initialize the USB HID class Device.

Returns
none.

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

#include "rl_usb.h"
#include "rl_usbd.h"
#include "usb_hid.h"
int main (void) {
..
USBD_Initialize (0); // USB Device 0 Initialization calls USBD_HIDn_Initialize() automatically
USBD_Connect (0); // USB Device 0 Connect
..
}
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.

Parameters
[in]rtypereport type:
  • HID_REPORT_OUTPUT = output report received
  • HID_REPORT_FEATURE = feature report received
[in]reqrequest type:
  • USBD_HID_REQ_EP_CTRL = report received on control endpoint
  • USBD_HID_REQ_EP_INT = report received on interrupt endpoint
[in]ridreport ID (0 if only one report exists).
[in]bufbuffer that receives report data.
[in]lenlength of received report data.
Returns
true received report data processed.
false received report data not processed or request not supported.

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_FEATUREFeature 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

#include "rl_usbd.h"
#include "usb_hid.h"
bool USBD_HIDn_SetReport (uint8_t rtype, uint8_t req, uint8_t rid, const uint8_t *buf, int32_t len) {
uint8_t i;
switch (rtype) {
case HID_REPORT_OUTPUT:
for (i = 0; i < 4; i++) {
if (*buf & (1 << i))
LED_On (i);
else
LED_Off (i);
}
break;
case HID_REPORT_FEATURE:
break;
}
return true;
}
void USBD_HIDn_Uninitialize ( void  )

Called during USBD_Uninitialize to un-initialize the USB HID class Device.

Returns
none.

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

#include "rl_usb.h"
#include "rl_usbd.h"
#include "usb_hid.h"
int main (void) {
..
USBD_Initialize (0); // USB Device 0 Initialization
...
USBD_Uninitialize (0); // USB Device 0 Un-Initialization
..
}