USB Component  Version 6.13.6
MDK Middleware for USB Device and Host Communication
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages

User API reference of the Human Interface Device Class. More...

Functions

void USBD_HIDn_Initialize (void)
 Callback function called during USBD_Initialize to initialize the USB HID class instance. More...
 
void USBD_HIDn_Uninitialize (void)
 Callback function called during USBD_Uninitialize to de-initialize the USB HID class instance. More...
 
int32_t USBD_HIDn_GetReport (uint8_t rtype, uint8_t req, uint8_t rid, uint8_t *buf)
 Callback function called to prepare HID Report data to send. More...
 
bool USBD_HIDn_SetReport (uint8_t rtype, uint8_t req, uint8_t rid, const uint8_t *buf, int32_t len)
 Callback function called to process received HID Report data. More...
 
usbStatus USBD_HID_GetReportTrigger (uint8_t instance, uint8_t rid, const uint8_t *buf, uint32_t len)
 Asynchronously prepare HID Report data to send. More...
 

Description

User API reference of the Human Interface Device Class.

Function Documentation

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

Asynchronously prepare HID Report data to send.

Parameters
[in]instanceinstance of HID class.
[in]ridreport ID.
[in]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 "rl_usb.h"
__NO_RETURN void app_main (void *arg) {
uint8_t joy, joy_last;
(void)arg;
Joystick_Initialize(); // Joystick Initialization
USBD_Initialize(0U); // USB Device 0 Initialization
USBD_Connect (0U); // USB Device 0 Connect
joy = joy_last = 0U;
for (;;) { // Loop forever
joy = (uint8_t)(Joystick_GetState ());
if ((joy ^ joy_last) & 0x1FU) {
joy_last = joy & 0x1FU;
if (USBD_Configured (0)) { USBD_HID_GetReportTrigger(0U, 0U, &joy, 1U); }
}
osDelay(100U); // 100 ms delay for sampling buttons
}
}
int32_t USBD_HIDn_GetReport ( uint8_t  rtype,
uint8_t  req,
uint8_t  rid,
uint8_t *  buf 
)

Callback function called to 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:

  • if USB Host has requested new data by request on Control Endpoint 0,
  • if USB Host set idle period different than infinite, at each idle period expiration,
  • if data was sent to USB Host.

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  )

Callback function called during USBD_Initialize to initialize the USB HID class instance.

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 
)

Callback function called to 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
received report data processed status :
  • value true : processed
  • value false : not processed

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, uint32_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  )

Callback function called during USBD_Uninitialize to de-initialize the USB HID class instance.

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