USB Device HID API

Description

USB Device HID API.

Data Structures

struct sl_usbd_hid_callbacks_t
HID callbacks.

Functions

sl_status_t sl_usbd_hid_init (void)
Initialize HID class.
sl_status_t sl_usbd_hid_create_instance (uint8_t subclass, uint8_t protocol, sl_usbd_hid_country_code_t country_code, uint16_t interval_in, uint16_t interval_out, bool ctrl_rd_en, sl_usbd_hid_callbacks_t *p_hid_callbacks, uint8_t *p_class_nbr)
Add a new instance of the HID class.
sl_status_t sl_usbd_hid_add_to_configuration (uint8_t class_nbr, uint8_t config_nbr)
Add the HID class instance to the USB device configuration (see Note #1).
sl_status_t sl_usbd_hid_is_enabled (uint8_t class_nbr, bool *p_enabled)
Get the HID class enable state.
sl_status_t sl_usbd_hid_write_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, uint32_t *p_xfer_len)
Send data to the host through the Interrupt IN endpoint.
sl_status_t sl_usbd_hid_read_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, uint32_t *p_xfer_len)
Receive data from the host through the Interrupt OUT endpoint.
sl_status_t sl_usbd_hid_read_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_hid_async_function_t async_fnct, void *p_async_arg)
Receive data from the host through the Interrupt OUT endpoint.
sl_status_t sl_usbd_hid_write_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_hid_async_function_t async_fnct, void *p_async_arg)
Send data to the host through the Interrupt IN endpoint.

Macros

#define SLI_USBD_HID_EXTERN extern
#define SL_USBD_HID_SUBCLASS_NONE 0x00u
#define SL_USBD_HID_SUBCLASS_BOOT 0x01u
#define SL_USBD_HID_PROTOCOL_NONE 0x00u
#define SL_USBD_HID_PROTOCOL_KBD 0x01u
#define SL_USBD_HID_PROTOCOL_MOUSE 0x02u
#define SL_USBD_HID_ITEM_LONG 0xFE
#define SL_USBD_HID_ITEM_TYPE_MAIN 0x00
#define SL_USBD_HID_ITEM_TYPE_GLOBAL 0x04
#define SL_USBD_HID_ITEM_TYPE_LOCAL 0x08
#define SL_USBD_HID_ITEM_TYPE_RESERVED 0x0C
#define SL_USBD_HID_MAIN_INPUT 0x80
#define SL_USBD_HID_MAIN_OUTPUT 0x90
#define SL_USBD_HID_MAIN_COLLECTION 0xA0
#define SL_USBD_HID_MAIN_FEATURE 0xB0
#define SL_USBD_HID_MAIN_ENDCOLLECTION 0xC0
#define SL_USBD_HID_MAIN_CONSTANT 0x01
#define SL_USBD_HID_MAIN_DATA 0x00
#define SL_USBD_HID_MAIN_VARIABLE 0x02
#define SL_USBD_HID_MAIN_ARRAY 0x00
#define SL_USBD_HID_MAIN_RELATIVE 0x04
#define SL_USBD_HID_MAIN_ABSOLUTE 0x00
#define SL_USBD_HID_MAIN_WRAP 0x08
#define SL_USBD_HID_MAIN_NOWRAP 0x00
#define SL_USBD_HID_MAIN_NONLINEAR 0x10
#define SL_USBD_HID_MAIN_LINEAR 0x00
#define SL_USBD_HID_MAIN_NOPREFERRED 0x20
#define SL_USBD_HID_MAIN_PREFERREDSTATE 0x00
#define SL_USBD_HID_MAIN_NULLSTATE 0x40
#define SL_USBD_HID_MAIN_NONULLPOSITION 0x00
#define SL_USBD_HID_MAIN_VOLATILE 0x80
#define SL_USBD_HID_MAIN_NONVOLATILE 0x00
#define SL_USBD_HID_MAIN_BUFFEREDBYTES 0x0100
#define SL_USBD_HID_MAIN_BITFIELD 0x0000
#define SL_USBD_HID_COLLECTION_PHYSICAL 0x00
#define SL_USBD_HID_COLLECTION_APPLICATION 0x01
#define SL_USBD_HID_COLLECTION_LOGICAL 0x02
#define SL_USBD_HID_COLLECTION_REPORT 0x03
#define SL_USBD_HID_COLLECTION_NAMEDARRAY 0x04
#define SL_USBD_HID_COLLECTION_USAGESWITCH 0x05
#define SL_USBD_HID_COLLECTION_USAGEMODIFIER 0x06
#define SL_USBD_HID_GLOBAL_USAGE_PAGE 0x04
#define SL_USBD_HID_GLOBAL_LOG_MIN 0x14
#define SL_USBD_HID_GLOBAL_LOG_MAX 0x24
#define SL_USBD_HID_GLOBAL_PHY_MIN 0x34
#define SL_USBD_HID_GLOBAL_PHY_MAX 0x44
#define SL_USBD_HID_GLOBAL_UNIT_EXPONENT 0x54
#define SL_USBD_HID_GLOBAL_UNIT 0x64
#define SL_USBD_HID_GLOBAL_REPORT_SIZE 0x74
#define SL_USBD_HID_GLOBAL_REPORT_ID 0x84
#define SL_USBD_HID_GLOBAL_REPORT_COUNT 0x94
#define SL_USBD_HID_GLOBAL_PUSH 0xA4
#define SL_USBD_HID_GLOBAL_POP 0xB4
#define SL_USBD_HID_LOCAL_USAGE 0x08
#define SL_USBD_HID_LOCAL_USAGE_MIN 0x18
#define SL_USBD_HID_LOCAL_USAGE_MAX 0x28
#define SL_USBD_HID_LOCAL_DESIGNATOR_INDEX 0x38
#define SL_USBD_HID_LOCAL_DESIGNATOR_MIN 0x48
#define SL_USBD_HID_LOCAL_DESIGNATOR_MAX 0x58
#define SL_USBD_HID_LOCAL_STRING_INDEX 0x78
#define SL_USBD_HID_LOCAL_STRING_MIN 0x88
#define SL_USBD_HID_LOCAL_STRING_MAX 0x98
#define SL_USBD_HID_LOCAL_DELIMITER 0xA8
#define SL_USBD_HID_BIAS_NOT_APPLICABLE 0
#define SL_USBD_HID_BIAS_RIGHT_HAND 1
#define SL_USBD_HID_BIAS_LEFT_HAND 2
#define SL_USBD_HID_BIAS_BOTH_HANDS 3
#define SL_USBD_HID_BIAS_EITHER_HAND 4
#define SL_USBD_HID_DESIGNATOR_NONE 0x00
#define SL_USBD_HID_DESIGNATOR_HAND 0x01
#define SL_USBD_HID_DESIGNATOR_EYEBALL 0x02
#define SL_USBD_HID_DESIGNATOR_EYEBROW 0x03
#define SL_USBD_HID_DESIGNATOR_EYELID 0x04
#define SL_USBD_HID_DESIGNATOR_EAR 0x05
#define SL_USBD_HID_DESIGNATOR_NOSE 0x06
#define SL_USBD_HID_DESIGNATOR_MOUTH 0x07
#define SL_USBD_HID_DESIGNATOR_UPPER_LIP 0x08
#define SL_USBD_HID_DESIGNATOR_LOWER_LIP 0x09
#define SL_USBD_HID_DESIGNATOR_JAW 0x0A
#define SL_USBD_HID_DESIGNATOR_NECK 0x0B
#define SL_USBD_HID_DESIGNATOR_UPPER_ARM 0x0C
#define SL_USBD_HID_DESIGNATOR_ELBOW 0x0D
#define SL_USBD_HID_DESIGNATOR_FOREARM 0x0E
#define SL_USBD_HID_DESIGNATOR_WRIST 0x0F
#define SL_USBD_HID_DESIGNATOR_PALM 0x10
#define SL_USBD_HID_DESIGNATOR_THUMB 0x11
#define SL_USBD_HID_DESIGNATOR_INDEX_FINGER 0x12
#define SL_USBD_HID_DESIGNATOR_MIDDLE_FINGER 0x13
#define SL_USBD_HID_DESIGNATOR_RING_FINGER 0x14
#define SL_USBD_HID_DESIGNATOR_LITTLE_FINGER 0x15
#define SL_USBD_HID_DESIGNATOR_HEAD 0x16
#define SL_USBD_HID_DESIGNATOR_SHOULDER 0x17
#define SL_USBD_HID_DESIGNATOR_HIP 0x18
#define SL_USBD_HID_DESIGNATOR_WAIST 0x19
#define SL_USBD_HID_DESIGNATOR_THIGH 0x1A
#define SL_USBD_HID_DESIGNATOR_KNEE 0x1B
#define SL_USBD_HID_DESIGNATOR_CALF 0x1C
#define SL_USBD_HID_DESIGNATOR_ANKLE 0x1D
#define SL_USBD_HID_DESIGNATOR_FOOT 0x1E
#define SL_USBD_HID_DESIGNATOR_HEEL 0x1F
#define SL_USBD_HID_DESIGNATOR_BALL_OF_FOOT 0x20
#define SL_USBD_HID_DESIGNATOR_BIG_TOE 0x21
#define SL_USBD_HID_DESIGNATOR_SECOND_TOE 0x22
#define SL_USBD_HID_DESIGNATOR_THIRD_TOE 0x23
#define SL_USBD_HID_DESIGNATOR_FOURTH_TOE 0x24
#define SL_USBD_HID_DESIGNATOR_LITTLE_TOE 0x25
#define SL_USBD_HID_DESIGNATOR_BROW 0x26
#define SL_USBD_HID_DESIGNATOR_CHEEK 0x27
#define SL_USBD_HID_QUALIFIER_NOT_APPLICABLE 0
#define SL_USBD_HID_QUALIFIER_RIGHT 1
#define SL_USBD_HID_QUALIFIER_LEFT 2
#define SL_USBD_HID_QUALIFIER_BOTH 3
#define SL_USBD_HID_QUALIFIER_EITHER 4
#define SL_USBD_HID_QUALIFIER_CENTER 5
#define SL_USBD_HID_USAGE_PAGE_UNDEFINED 0x00
#define SL_USBD_HID_USAGE_PAGE_GENERIC_DESKTOP_CONTROLS 0x01
#define SL_USBD_HID_USAGE_PAGE_SIMULATION_CONTROLS 0x02
#define SL_USBD_HID_USAGE_PAGE_VR_CONTROLS 0x03
#define SL_USBD_HID_USAGE_PAGE_SPORT_CONTROLS 0x04
#define SL_USBD_HID_USAGE_PAGE_GAME_CONTROLS 0x05
#define SL_USBD_HID_USAGE_PAGE_GENERIC_DEVICE_CONTROLS 0x06
#define SL_USBD_HID_USAGE_PAGE_KEYBOARD 0x07
#define SL_USBD_HID_USAGE_PAGE_LEDS 0x08
#define SL_USBD_HID_USAGE_PAGE_BUTTON 0x09
#define SL_USBD_HID_USAGE_PAGE_ORDINAL 0x0A
#define SL_USBD_HID_USAGE_PAGE_TELEPHONY 0x0B
#define SL_USBD_HID_USAGE_PAGE_CONSUMER 0x0C
#define SL_USBD_HID_USAGE_PAGE_DIGITIZER 0x0D
#define SL_USBD_HID_USAGE_PAGE_PID_PAGE 0x0F
#define SL_USBD_HID_USAGE_PAGE_UNICODE 0x10
#define SL_USBD_HID_USAGE_PAGE_ALPHANUMERIC_DISPLAY 0x14
#define SL_USBD_HID_USAGE_PAGE_MEDICAL_INSTRUMENTS 0x40
#define SL_USBD_HID_USAGE_PAGE_MONITOR_0 0x80
#define SL_USBD_HID_USAGE_PAGE_MONITOR_1 0x81
#define SL_USBD_HID_USAGE_PAGE_MONITOR_2 0x82
#define SL_USBD_HID_USAGE_PAGE_MONITOR_3 0x83
#define SL_USBD_HID_USAGE_PAGE_POWER_0 0x84
#define SL_USBD_HID_USAGE_PAGE_POWER_1 0x85
#define SL_USBD_HID_USAGE_PAGE_POWER_2 0x86
#define SL_USBD_HID_USAGE_PAGE_POWER_3 0x87
#define SL_USBD_HID_USAGE_PAGE_BAR_CODE_SCANNER_PAGE 0x8C
#define SL_USBD_HID_USAGE_PAGE_SCALE_PAGE 0x8D
#define SL_USBD_HID_USAGE_PAGE_MSR_DEVICES 0x8E
#define SL_USBD_HID_USAGE_PAGE_POINT_OF_SALE_PAGES 0x8F
#define SL_USBD_HID_USAGE_PAGE_CAMERA_CONTROL_PAGE 0x90
#define SL_USBD_HID_USAGE_PAGE_ARCADE_PAGE 0x91
#define SL_USBD_HID_CP_POINTER 0x01
#define SL_USBD_HID_CA_MOUSE 0x02
#define SL_USBD_HID_CA_JOYSTICK 0x04
#define SL_USBD_HID_CA_GAME_PAD 0x05
#define SL_USBD_HID_CA_KEYBOARD 0x06
#define SL_USBD_HID_CA_KEYPAD 0x07
#define SL_USBD_HID_CA_MULTI_AXIS_CONTROLLER 0x08
#define SL_USBD_HID_DV_X 0x30
#define SL_USBD_HID_DV_Y 0x31
#define SL_USBD_HID_DV_Z 0x32
#define SL_USBD_HID_DV_WHEEL 0x38
#define SL_USBD_HID_CA_SYSTEM_CONTROL 0x80

Typedefs

typedef void(* sl_usbd_hid_async_function_t ) (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_callback_arg, sl_status_t status)
Async comm callback.

Enumerations

enum sl_usbd_hid_country_code_t {
SL_USBD_HID_COUNTRY_CODE_NOT_SUPPORTED = 0u ,
SL_USBD_HID_COUNTRY_CODE_ARABIC = 1u ,
SL_USBD_HID_COUNTRY_CODE_BELGIAN = 2u ,
SL_USBD_HID_COUNTRY_CODE_CANADIAN_BILINGUAL = 3u ,
SL_USBD_HID_COUNTRY_CODE_CANADIAN_FRENCH = 4u ,
SL_USBD_HID_COUNTRY_CODE_CZECH_REPUBLIC = 5u ,
SL_USBD_HID_COUNTRY_CODE_DANISH = 6u ,
SL_USBD_HID_COUNTRY_CODE_FINNISH = 7u ,
SL_USBD_HID_COUNTRY_CODE_FRENCH = 8u ,
SL_USBD_HID_COUNTRY_CODE_GERMAN = 9u ,
SL_USBD_HID_COUNTRY_CODE_GREEK = 10u ,
SL_USBD_HID_COUNTRY_CODE_HEBREW = 11u ,
SL_USBD_HID_COUNTRY_CODE_HUNGARY = 12u ,
SL_USBD_HID_COUNTRY_CODE_INTERNATIONAL = 13u ,
SL_USBD_HID_COUNTRY_CODE_ITALIAN = 14u ,
SL_USBD_HID_COUNTRY_CODE_JAPAN_KATAKANA = 15u ,
SL_USBD_HID_COUNTRY_CODE_KOREAN = 16u ,
SL_USBD_HID_COUNTRY_CODE_LATIN_AMERICAN = 17u ,
SL_USBD_HID_COUNTRY_CODE_NETHERLANDS_DUTCH = 18u ,
SL_USBD_HID_COUNTRY_CODE_NORWEGIAN = 19u ,
SL_USBD_HID_COUNTRY_CODE_PERSIAN_FARSI = 20u ,
SL_USBD_HID_COUNTRY_CODE_POLAND = 21u ,
SL_USBD_HID_COUNTRY_CODE_PORTUGUESE = 22u ,
SL_USBD_HID_COUNTRY_CODE_RUSSIA = 23u ,
SL_USBD_HID_COUNTRY_CODE_SLOVAKIA = 24u ,
SL_USBD_HID_COUNTRY_CODE_SPANISH = 25u ,
SL_USBD_HID_COUNTRY_CODE_SWEDISH = 26u ,
SL_USBD_HID_COUNTRY_CODE_SWISS_FRENCH = 27u ,
SL_USBD_HID_COUNTRY_CODE_SWISS_GERMAN = 28u ,
SL_USBD_HID_COUNTRY_CODE_SWITZERLAND = 29u ,
SL_USBD_HID_COUNTRY_CODE_TAIWAN = 30u ,
SL_USBD_HID_COUNTRY_CODE_TURKISH_Q = 31u ,
SL_USBD_HID_COUNTRY_CODE_UK = 32u ,
SL_USBD_HID_COUNTRY_CODE_US = 33u ,
SL_USBD_HID_COUNTRY_CODE_YUGOSLAVIA = 34u ,
SL_USBD_HID_COUNTRY_CODE_TURKISH_F = 35u
}

Function Documentation

sl_usbd_hid_init()

sl_status_t sl_usbd_hid_init ( void )

Initialize HID class.

Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_create_instance()

sl_status_t sl_usbd_hid_create_instance ( uint8_t subclass,
uint8_t protocol,
sl_usbd_hid_country_code_t country_code,
uint16_t interval_in,
uint16_t interval_out,
bool ctrl_rd_en,
sl_usbd_hid_callbacks_t * p_hid_callbacks,
uint8_t * p_class_nbr
)

Add a new instance of the HID class.

Parameters
subclass Subclass code.
protocol protocol code.
country_code Country code id.
interval_in Polling interval for input transfers, in milliseconds. It must be a power of 2.
interval_out Polling interval for output transfers, in milliseconds. It must be a power of 2. Used only when read operations are not through control transfers.
ctrl_rd_en Enable read operations through the control transfers.
p_hid_callbacks Pointer to HID descriptor and request callback structure. [Content MUST be persistent]
p_class_nbr Pointer to variable that will receive class instance number. The variable is set to class instance number if no errors are returned, otherwise it is set to SL_USBD_CLASS_NBR_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_add_to_configuration()

sl_status_t sl_usbd_hid_add_to_configuration ( uint8_t class_nbr,
uint8_t config_nbr
)

Add the HID class instance to the USB device configuration (see Note #1).

Parameters
class_nbr Class instance number.
config_nbr Configuration index to add HID class instance to.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Called several times, it creates multiple instances and configurations. For instance, the following architecture could be created :
*               FS
*               |-- Configuration 0 (HID class 0)
*                                   (HID class 1)
*                                   (HID class 2)
*                   |-- Interface 0
*               |-- Configuration 1 (HID class 0)
*                   |-- Interface 0
*               
(2) Configuration Descriptor corresponding to a HID device uses the following format :
*               Configuration Descriptor
*               |-- Interface Descriptor (HID class)
*                   |-- Endpoint Descriptor (Interrupt IN)
*                   |-- Endpoint Descriptor (Interrupt OUT) - optional
*               

sl_usbd_hid_is_enabled()

sl_status_t sl_usbd_hid_is_enabled ( uint8_t class_nbr,
bool * p_enabled
)

Get the HID class enable state.

Parameters
class_nbr Class instance number.
p_enabled Pointer to a variable that will receive HID class enable state. The variable is set to true if HID class is enabled, and is set to false if it is NOT enabled.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_write_sync()

sl_status_t sl_usbd_hid_write_sync ( uint8_t class_nbr,
void * p_buf,
uint32_t buf_len,
uint16_t timeout,
uint32_t * p_xfer_len
)

Send data to the host through the Interrupt IN endpoint.

This function is blocking.

Parameters
class_nbr Class instance number.
p_buf Pointer to the transmit buffer. If more than one input report exists, the first byte must represent the report id.
buf_len Transmit buffer length, in octets.
timeout Timeout in milliseconds.
p_xfer_len Pointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_read_sync()

sl_status_t sl_usbd_hid_read_sync ( uint8_t class_nbr,
void * p_buf,
uint32_t buf_len,
uint16_t timeout,
uint32_t * p_xfer_len
)

Receive data from the host through the Interrupt OUT endpoint.

This function is blocking.

Parameters
class_nbr Class instance number.
p_buf Pointer to the receive buffer.
buf_len Receive the buffer length, in octets.
timeout Timeout, in milliseconds.
p_xfer_len Pointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_read_async()

sl_status_t sl_usbd_hid_read_async ( uint8_t class_nbr,
void * p_buf,
uint32_t buf_len,
sl_usbd_hid_async_function_t async_fnct,
void * p_async_arg
)

Receive data from the host through the Interrupt OUT endpoint.

This function is non-blocking and returns immediately after transfer preparation. Upon transfer completion, the provided callback is called to notify the application.

Parameters
class_nbr Class instance number.
p_buf Pointer to receive buffer.
buf_len Receive buffer length, in octets.
async_fnct Receive callback.
p_async_arg Additional argument provided by application for receive callback.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

sl_usbd_hid_write_async()

sl_status_t sl_usbd_hid_write_async ( uint8_t class_nbr,
void * p_buf,
uint32_t buf_len,
sl_usbd_hid_async_function_t async_fnct,
void * p_async_arg
)

Send data to the host through the Interrupt IN endpoint.

This function is non-blocking, and returns immediately after transfer preparation. Upon transfer completion, the provided callback is called to notify the application.

Parameters
class_nbr Class instance number.
p_buf Pointer to transmit buffer. If more than one input report exists, the first byte must represent the report id.
buf_len Transmit buffer length, in octets.
async_fnct Transmit callback.
p_async_arg Additional argument provided by application for transmit callback.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

Macro Definition Documentation

SL_USBD_HID_BIAS_NOT_APPLICABLE

#define SL_USBD_HID_BIAS_NOT_APPLICABLE 0
                              HID PHYSICAL DESCRIPTOR DEFINES

Note(s) : (1) See 'Device Class Definition for Human Interface Devices Version 1.11', Section 6.2.3.

SL_USBD_HID_USAGE_PAGE_UNDEFINED

#define SL_USBD_HID_USAGE_PAGE_UNDEFINED 0x00
                                      HID USAGE PAGES

Note(s) : (1) See 'Universal Serial Bus HID Usage Tables', Version 1.12, Section 3 for more details about Usage Pages.

(2) See 'Universal Serial Bus HID Usage Tables', Version 1.12, Section 4 for more details about Generic Desktop Page usages and controls.

Typedef Documentation

sl_usbd_hid_async_function_t

typedef void(* sl_usbd_hid_async_function_t) (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_callback_arg, sl_status_t status)

Async comm callback.

Enumeration Type Documentation

sl_usbd_hid_country_code_t

                     HUMAN INTERFACE DEVICE COUNTRY CODES DEFINES

Note(s) : (1) See 'Device Class Definition for Human Interface Devices (HID), 6/27/01, Version 1.11', section 6.2.1 for more details about HID descriptor country code.

(a) The country code identifies which country the hardware is localized for. Most hardware is not localized and thus this value would be zero (0). However, keyboards may use the field to indicate the language of the key caps.