User API

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

USBD_HIDn_Initialize()

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

USBD_HIDn_Uninitialize()

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

USBD_HIDn_GetReport()

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]	rtype	report type : HID_REPORT_INPUT = input report requested HID_REPORT_FEATURE = feature report requested
[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
[in]	rid	report ID (0 if only one report exists).
[out]	buf	buffer 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_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

#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) {
            case USBD_HID_REQ_EP_CTRL:
            case USBD_HID_REQ_PERIOD_UPDATE:
            case USBD_HID_REQ_EP_INT:
              break;
          }
          break;
      }
      break;
    case HID_REPORT_FEATURE:
      break;
  }
  return (0);
}

USBD_HIDn_SetReport()

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]	rtype	report type : HID_REPORT_OUTPUT = output report received HID_REPORT_FEATURE = feature report received
[in]	req	request type : USBD_HID_REQ_EP_CTRL = report received on control endpoint USBD_HID_REQ_EP_INT = report received on interrupt endpoint
[in]	rid	report ID (0 if only one report exists).
[in]	buf	buffer that receives report data.
[in]	len	length 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_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

#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;
}

USBD_HID_GetReportTrigger()

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]	instance	instance of HID class.
[in]	rid	report ID.
[in]	buf	buffer containing report data to send.
[in]	len	number 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
  }
}