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

Functions
void	USBH_HID_Initialize (uint8_t instance)
	Callback function called when Human Interface Device was enumerated and is ready.

void	USBH_HID_Uninitialize (uint8_t instance)
	Callback function called when Human Interface Device was disconnected.

uint8_t	USBH_HID_GetDevice (uint8_t instance)
	Get Device instance of Human Interface Device.

usbStatus	USBH_HID_GetStatus (uint8_t instance)
	Get status of Human Interface Device.

int32_t	USBH_HID_Read (uint8_t instance, uint8_t *buf, int32_t len)
	Read data received from Human Interface Device.

int32_t	USBH_HID_Write (uint8_t instance, const uint8_t *buf, int32_t len)
	Write data to Human Interface Device.

int	USBH_HID_GetKeyboardKey (uint8_t instance)
	Retrieve first pending pressed keyboard key on HID Keyboard.

usbStatus	USBH_HID_GetMouseState (uint8_t instance, usbHID_MouseState *state)
	Retrieve state change since last call of this function.

void	USBH_HID_ParseReportDescriptor (uint8_t instance, const uint8_t *ptr_hid_report_desc, uint32_t len)
	Callback function called for parsing of the Human Interface Device report descriptor.

void	USBH_HID_DataReceived (uint8_t instance, uint32_t len)
	Callback function called when data is received from the Human Interface Device.

Description

User API reference of the Human Interface Device Class.

Function Documentation

◆ USBH_HID_DataReceived()

void USBH_HID_DataReceived	(	uint8_t	instance,
		uint32_t	len
	)

Callback function called when data is received from the Human Interface Device.

Parameters

[in]	instance	instance index.
[in]	len	length of received data.

The USBH_HID_DataReceived function enables programmers to analyze received data coming from an USB HID device. Implementing this function in user code overrides the USB Component function that handles boot protocol device data reception. This is useful if the default HID functionality needs to be changed to support special HID devices.

◆ USBH_HID_GetDevice()

uint8_t USBH_HID_GetDevice ( uint8_t instance )

Get Device instance of Human Interface Device.

Parameters

[in] instance instance of HID Device.

Returns

instance of Device or non-existing Device instance :

value <= 127 : instance of Device
value 255 : non-existing Device instance

The function USBH_HID_GetDevice is used to retrieve device instance that is used to handle human interface device instance.

The argument instance specifies the HID device instance.

◆ USBH_HID_GetKeyboardKey()

int32_t USBH_HID_GetKeyboardKey ( uint8_t instance )

Retrieve first pending pressed keyboard key on HID Keyboard.

Parameters

[in] instance instance of HID Device.

Returns

code of first pressed unread key or no key was pressed :

value >= 0 : code of first pressed unread key
value -1 : indicates no key was pressed since last time this function was called

The function USBH_HID_GetKeyboardKey enables programmers to handle signals from a USB keyboard.

The argument instance specifies the HID device instance.

The function returns an integer value of the first pending keystroke. Characters that are directly mapped into ASCII are the HID codes starting from 4 (representing 'a') up to to 57 (representing '/'). All other HID codes are passed by this function using bit 16. set to '1' to notify the application about extended non-ASCII mapped HID codes. Modifier keys are encoded in bits 8..15 with following encoding:

Bit	Modifier Key
8	Left Control
9	Left Shift
10	Left Alt
11	Left GUI
12	Right Control
13	Right Shift
14	Right Alt
15	Right GUI

Consult the USB-IF's online documentation for information on HID Usage Tables relevant usage page for this function is Keyboard/Keypad Page 0x07.

Code Example

#include "rl_usb.h"
 
int main (void) {
  usbStatus usb_status;                 // USB status
  int       status;                     // Generic status
  int       ch;                         // Character
  uint8_t   con = 0U;                   // Connection status of keyboard
 
  SystemCoreClockUpdate();              // Update system clock
 
  status = stdout_init ();              // Initialize retargeted stdout
  if (status != 0) {
    for (;;) {}                         // Handle stdout init failure
  }
 
  usb_status = USBH_Initialize (0U);    // Initialize USB Host 0
  if (usb_status != usbOK) {
    for (;;) {}                         // Handle USB Host 0 init failure
  }
 
  for (;;) {
    usb_status= USBH_HID_GetStatus(0U); // Get HID device status
    if (usb_status == usbOK) {
      if (con == 0U) {                  // If keyboard was not connected previously
        con = 1U;                       // Keyboard got connected
        printf ("Connect!\n");
      }
    } else {
      if (con == 1U) {                  // If keyboard was connected previously
        con = 0U;                       // Keyboard got disconnected
        printf ("\nDisconnect!\n");
      }
    }
    if (con != 0U) {                    // If keyboard is active
      ch = USBH_HID_GetKeyboardKey (0U);// Get pressed key
      if (ch != -1) {                   // If valid key value
        if ((ch & 0x10000) != 0) {      // Handle non-ASCII translated keys (Keypad 0 .. 9)
                                        // Bit  16:    non-ASCII bit (0 = ASCII, 1 = not ASCII)
                                        // Bits 15..8: modifiers (SHIFT, ALT, CTRL, GUI)
                                        // Bits  7..0: ASCII or HID key Usage ID if not ASCII
          ch &= 0xFF;                   // Remove non-ASCII bit and modifiers
          if ((ch>=0x59)&&(ch<=0x61)) { // Keypad 1 .. 9 key convert to
            ch = (ch - 0x59) + '1';     // ASCII  1 .. 9
          } else if (ch == 0x62) {      // Keypad 0 key convert to
            ch = '0';                   // ASCII  0
          } else {                      // If not Keypad 0 .. 9
            ch = -1;                    // invalidate the key
          }
        }
        if ((ch > 0) && (ch < 128)) {   // Output ASCII 0 .. 127 range
          putchar(ch);
          fflush(stdout);
        }
      }
    }
    osDelay(10U);
  }
}

◆ USBH_HID_GetMouseState()

bool USBH_HID_GetMouseState	(	uint8_t	instance,
		usbHID_MouseState *	state
	)

Retrieve state change since last call of this function.

Parameters

[in]	instance	instance of HID Device.
[out]	state	pointer to mouse state usbHID_MouseState structure.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_HID_GetMouseState enables programmers to handle signals from an USB mouse.

The argument instance specifies the HID device instance.

The argument state is a pointer to the mouse state structure (usbHID_MouseState).

Code Example

#include "rl_usb.h"
 
void getmouse (void)  {
  ..
  if (USBH_HID_GetMouseState (0, &MouseState)) { // If mouse move
    ..
  }
)

◆ USBH_HID_GetStatus()

usbStatus USBH_HID_GetStatus ( uint8_t instance )

Get status of Human Interface Device.

Parameters

[in] instance instance of HID Device.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_HID_GetStatus checks whether the human interface device is connected and initialized.

The argument instance specifies the HID device instance.

Code Example

#include "rl_usb.h"
 
int main (void) {
  usbStatus usb_status;                 // USB status
 
  usb_status = USBH_Initialize (0U);    // Initialize USB Host 0
  if (usb_status != usbOK) {
    for (;;) {}                         // Handle USB Host 0 init failure
  }
 
  while (1) {
    usb_status= USBH_HID_GetStatus(0U); // Get HID device status
    if (usb_status == usbOK) {
      //do something
    }
  }
}

◆ USBH_HID_Initialize()

void USBH_HID_Initialize ( uint8_t instance )

Callback function called when Human Interface Device was enumerated and is ready.

Parameters

[in] instance instance of HID Device.

The function USBH_HID_Initialize is called when a human interface device was connected and successfully enumerated and is ready for communication.

The argument instance specifies the HID device instance.

◆ USBH_HID_ParseReportDescriptor()

void USBH_HID_ParseReportDescriptor	(	uint8_t	instance,
		const uint8_t *	ptr_hid_report_desc,
		uint32_t	len
	)

Callback function called for parsing of the Human Interface Device report descriptor.

Parameters

[in]	instance	instance index.
[in]	ptr_hid_report_desc	pointer to HID report descriptor.
[in]	len	length of HID report descriptor.

The USBH_HID_ParseReportDescriptor function enables programmers to parse report descriptors of an USB HID device. This is useful if the default HID functionality needs to be changed to support special HID devices.

◆ USBH_HID_Read()

int32_t USBH_HID_Read	(	uint8_t	instance,
		uint8_t *	buf,
		int32_t	len
	)

Read data received from Human Interface Device.

Parameters

[in]	instance	instance of HID Device.
[out]	buf	buffer that receives data.
[in]	len	maximum number of bytes to read.

Returns

number of bytes read or execution status :

value >= 0 : number of bytes read
value < 0 : error occurred, -value is execution status as defined with usbStatus

The function USBH_HID_Read retrieves the data sent by an USB HID device and stores it in a buffer.

The argument instance specifies the HID device instance.

The argument buf is pointing to the location where the data will be returned (stored). It is recommended that buffer is 4-byte aligned as some drivers might not support 1-byte alignment if DMA is used.

The argument len specifies the number of bytes to be read (must be multiple of HID device Interrupt In endpoint maximum packet size).

Code Example

#include "rl_usb.h"
 
void HID_start_data_reception (void)  {
  U8 data[16];
  ..
  if (USBH_HID_Read (0, &data, 2)) {  // If data received from HID device
    ..
  }
)

◆ USBH_HID_Uninitialize()

void USBH_HID_Uninitialize ( uint8_t instance )

Callback function called when Human Interface Device was disconnected.

Parameters

[in] instance instance of HID Device.

The function USBH_HID_Unitialize is called when a human interface device was disconnected form the USB Bus.

The argument instance specifies the HID device instance.

◆ USBH_HID_Write()

int32_t USBH_HID_Write	(	uint8_t	instance,
		const uint8_t *	buf,
		int32_t	len
	)

Write data to Human Interface Device.

Parameters

[in]	instance	instance of HID Device.
[in]	buf	data buffer containing data to write.
[in]	len	number of data bytes to write.

Returns

number of bytes accepted for writing or execution status :

value >= 0 : number of bytes accepted for writing
value < 0 : error occurred, -value is execution status as defined with usbStatus

The function USBH_HID_Write writes data from a buffer to an USB HID device.

The argument instance specifies the HID device instance.

The argument buf is pointing to the location where the data will be written. It is recommended that buffer is 4-byte aligned as some drivers might not support 1-byte alignment if DMA is used.

The argument len specifies the number of data bytes to be written.

Code Example

#include "rl_usb.h"
 
int main (void) {
  usbStatus usb_status;                 // USB status
  uint8_t   out;
 
  usb_status = USBH_Initialize (0U);    // Initialize USB Host 0
  if (usb_status != usbOK) {
    for (;;) {}                         // Handle USB Host 0 init failure
  }
 
  while (1) {
    usb_status= USBH_HID_GetStatus(0U); // Get HID device status
    if (usb_status == usbOK) {
      USBH_HID_Write (0,(uint8_t *)&out,1);     // Turn on NUM LED
      :
    }
    osDelay(100);
  }
}

Functions

Description

Function Documentation

◆ USBH_HID_DataReceived()

◆ USBH_HID_GetDevice()

◆ USBH_HID_GetKeyboardKey()

◆ USBH_HID_GetMouseState()

◆ USBH_HID_GetStatus()

◆ USBH_HID_Initialize()

◆ USBH_HID_ParseReportDescriptor()

◆ USBH_HID_Read()

◆ USBH_HID_Uninitialize()

◆ USBH_HID_Write()