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 USBH_HID_Initialize (uint8_t instance)
 Callback function called when Human Interface Device was enumerated and is ready. More...
 
void USBH_HID_Uninitialize (uint8_t instance)
 Callback function called when Human Interface Device was disconnected. More...
 
uint8_t USBH_HID_GetDevice (uint8_t instance)
 Get Device instance of Human Interface Device. More...
 
usbStatus USBH_HID_GetStatus (uint8_t instance)
 Get status of Human Interface Device. More...
 
int32_t USBH_HID_Read (uint8_t instance, uint8_t *buf, int32_t len)
 Read data received from Human Interface Device. More...
 
int32_t USBH_HID_Write (uint8_t instance, const uint8_t *buf, int32_t len)
 Write data to Human Interface Device. More...
 
int USBH_HID_GetKeyboardKey (uint8_t instance)
 Retrieve first pending pressed keyboard key on HID Keyboard. More...
 
usbStatus USBH_HID_GetMouseState (uint8_t instance, usbHID_MouseState *state)
 Retrieve state change since last call of this function. More...
 
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. More...
 
void USBH_HID_DataReceived (uint8_t instance, uint32_t len)
 Callback function called when data is received from the Human Interface Device. More...
 

Description

User API reference of the Human Interface Device Class.

Function Documentation

void USBH_HID_DataReceived ( uint8_t  instance,
uint32_t  len 
)

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

Parameters
[in]instanceinstance index.
[in]lenlength of received data.
Returns
none.

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

uint8_t USBH_HID_GetDevice ( uint8_t  instance)

Get Device instance of Human Interface Device.

Parameters
[in]instanceinstance 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.

int32_t USBH_HID_GetKeyboardKey ( uint8_t  instance)

Retrieve first pending pressed keyboard key on HID Keyboard.

Parameters
[in]instanceinstance 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);
}
}
bool USBH_HID_GetMouseState ( uint8_t  instance,
usbHID_MouseState state 
)

Retrieve state change since last call of this function.

Parameters
[in]instanceinstance of HID Device.
[out]statepointer 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
..
}
)
usbStatus USBH_HID_GetStatus ( uint8_t  instance)

Get status of Human Interface Device.

Parameters
[in]instanceinstance 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
}
}
}
void USBH_HID_Initialize ( uint8_t  instance)

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

Parameters
[in]instanceinstance of HID Device.
Returns
none.

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.

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]instanceinstance index.
[in]ptr_hid_report_descpointer to HID report descriptor.
[in]lenlength of HID report descriptor.
Returns
none.

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.

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

Read data received from Human Interface Device.

Parameters
[in]instanceinstance of HID Device.
[out]bufbuffer that receives data.
[in]lenmaximum 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
..
}
)
void USBH_HID_Uninitialize ( uint8_t  instance)

Callback function called when Human Interface Device was disconnected.

Parameters
[in]instanceinstance of HID Device.
Returns
none.

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.

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

Write data to Human Interface Device.

Parameters
[in]instanceinstance of HID Device.
[in]bufdata buffer containing data to write.
[in]lennumber 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);
}
}