USB Device HID API#
USB Device HID API.
Modules#
Enumerations#
DEFINES.
Typedefs#
GLOBAL CONSTANTS.
Functions#
GLOBAL CONSTANTS.
Add a new instance of the HID class.
Add the HID class instance to the USB device configuration (see Note #1).
Get the HID class enable state.
Send data to the host through the Interrupt IN endpoint.
Receive data from the host through the Interrupt OUT endpoint.
Receive data from the host through the Interrupt OUT endpoint.
Send data to the host through the Interrupt IN endpoint.
Macros#
MODULE.
HUMAN INTERFACE DEVICE CLASS SUBCLASS CODES DEFINES.
HUMAN INTERFACE DEVICE CLASS PROTOCOL CODES DEFINES.
ITEM TYPES.
HID PHYSICAL DESCRIPTOR DEFINES
Note(s) : (1) See 'Device Class Definition for Human Interface Devices Version 1.11', Section 6.2.3.
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.
Enumeration Documentation#
sl_usbd_hid_country_code_t#
sl_usbd_hid_country_code_t
DEFINES.
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.
| Enumerator | |
|---|---|
| SL_USBD_HID_COUNTRY_CODE_NOT_SUPPORTED | |
| SL_USBD_HID_COUNTRY_CODE_ARABIC | |
| SL_USBD_HID_COUNTRY_CODE_BELGIAN | |
| SL_USBD_HID_COUNTRY_CODE_CANADIAN_BILINGUAL | |
| SL_USBD_HID_COUNTRY_CODE_CANADIAN_FRENCH | |
| SL_USBD_HID_COUNTRY_CODE_CZECH_REPUBLIC | |
| SL_USBD_HID_COUNTRY_CODE_DANISH | |
| SL_USBD_HID_COUNTRY_CODE_FINNISH | |
| SL_USBD_HID_COUNTRY_CODE_FRENCH | |
| SL_USBD_HID_COUNTRY_CODE_GERMAN | |
| SL_USBD_HID_COUNTRY_CODE_GREEK | |
| SL_USBD_HID_COUNTRY_CODE_HEBREW | |
| SL_USBD_HID_COUNTRY_CODE_HUNGARY | |
| SL_USBD_HID_COUNTRY_CODE_INTERNATIONAL | |
| SL_USBD_HID_COUNTRY_CODE_ITALIAN | |
| SL_USBD_HID_COUNTRY_CODE_JAPAN_KATAKANA | |
| SL_USBD_HID_COUNTRY_CODE_KOREAN | |
| SL_USBD_HID_COUNTRY_CODE_LATIN_AMERICAN | |
| SL_USBD_HID_COUNTRY_CODE_NETHERLANDS_DUTCH | |
| SL_USBD_HID_COUNTRY_CODE_NORWEGIAN | |
| SL_USBD_HID_COUNTRY_CODE_PERSIAN_FARSI | |
| SL_USBD_HID_COUNTRY_CODE_POLAND | |
| SL_USBD_HID_COUNTRY_CODE_PORTUGUESE | |
| SL_USBD_HID_COUNTRY_CODE_RUSSIA | |
| SL_USBD_HID_COUNTRY_CODE_SLOVAKIA | |
| SL_USBD_HID_COUNTRY_CODE_SPANISH | |
| SL_USBD_HID_COUNTRY_CODE_SWEDISH | |
| SL_USBD_HID_COUNTRY_CODE_SWISS_FRENCH | |
| SL_USBD_HID_COUNTRY_CODE_SWISS_GERMAN | |
| SL_USBD_HID_COUNTRY_CODE_SWITZERLAND | |
| SL_USBD_HID_COUNTRY_CODE_TAIWAN | |
| SL_USBD_HID_COUNTRY_CODE_TURKISH_Q | |
| SL_USBD_HID_COUNTRY_CODE_UK | |
| SL_USBD_HID_COUNTRY_CODE_US | |
| SL_USBD_HID_COUNTRY_CODE_YUGOSLAVIA | |
| SL_USBD_HID_COUNTRY_CODE_TURKISH_F | |
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) )(uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_callback_arg, sl_status_t status)
GLOBAL CONSTANTS.
DATA TYPES Async comm callback
Function Documentation#
sl_usbd_hid_init#
sl_status_t sl_usbd_hid_init (void )
GLOBAL CONSTANTS.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
FUNCTION PROTOTYPES HID FUNCTIONS
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | subclass | Subclass code. |
| uint8_t | N/A | protocol | protocol code. |
| sl_usbd_hid_country_code_t | N/A | country_code | Country code id. |
| uint16_t | N/A | interval_in | Polling interval for input transfers, in milliseconds. It must be a power of 2. |
| uint16_t | N/A | 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. |
| bool | N/A | ctrl_rd_en | Enable read operations through the control transfers. |
| sl_usbd_hid_callbacks_t * | N/A | p_hid_callbacks | Pointer to HID descriptor and request callback structure. [Content MUST be persistent] |
| uint8_t * | N/A | 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).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| uint8_t | N/A | 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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| bool * | N/A | 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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| void * | N/A | p_buf | Pointer to the transmit buffer. If more than one input report exists, the first byte must represent the report id. |
| uint32_t | N/A | buf_len | Transmit buffer length, in octets. |
| uint16_t | N/A | timeout | Timeout in milliseconds. |
| uint32_t * | N/A | 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. |
This function is blocking.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| void * | N/A | p_buf | Pointer to the receive buffer. |
| uint32_t | N/A | buf_len | Receive the buffer length, in octets. |
| uint16_t | N/A | timeout | Timeout, in milliseconds. |
| uint32_t * | N/A | 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. |
This function is blocking.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| void * | N/A | p_buf | Pointer to receive buffer. |
| uint32_t | N/A | buf_len | Receive buffer length, in octets. |
| sl_usbd_hid_async_function_t | N/A | async_fnct | Receive callback. |
| void * | N/A | p_async_arg | Additional argument provided by application for receive callback. |
This function is non-blocking and returns immediately after transfer preparation. Upon transfer completion, the provided callback is called to notify the application.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | N/A | class_nbr | Class instance number. |
| void * | N/A | p_buf | Pointer to transmit buffer. If more than one input report exists, the first byte must represent the report id. |
| uint32_t | N/A | buf_len | Transmit buffer length, in octets. |
| sl_usbd_hid_async_function_t | N/A | async_fnct | Transmit callback. |
| void * | N/A | p_async_arg | Additional argument provided by application for transmit callback. |
This function is non-blocking, and returns immediately after transfer preparation. Upon transfer completion, the provided callback is called to notify the application.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Macro Definition Documentation#
SL_USBD_HID_SUBCLASS_NONE#
#define SL_USBD_HID_SUBCLASS_NONEValue:
0x00u
HUMAN INTERFACE DEVICE CLASS SUBCLASS CODES DEFINES.
Note(s) : (1) Human interface device class subclass codes are defined in section 4.2 of HID specification revision 1.11.
SL_USBD_HID_PROTOCOL_NONE#
#define SL_USBD_HID_PROTOCOL_NONEValue:
0x00u
HUMAN INTERFACE DEVICE CLASS PROTOCOL CODES DEFINES.
Note(s) : (1) Human interface device class protocol codes are defined in section 4.3 of HID specification revision 1.11.
SL_USBD_HID_BIAS_NOT_APPLICABLE#
#define SL_USBD_HID_BIAS_NOT_APPLICABLEValue:
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_UNDEFINEDValue:
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.
SL_USBD_HID_USAGE_PAGE_GENERIC_DESKTOP_CONTROLS#
#define SL_USBD_HID_USAGE_PAGE_GENERIC_DESKTOP_CONTROLSValue:
0x01
SL_USBD_HID_USAGE_PAGE_SIMULATION_CONTROLS#
#define SL_USBD_HID_USAGE_PAGE_SIMULATION_CONTROLSValue:
0x02
SL_USBD_HID_USAGE_PAGE_GENERIC_DEVICE_CONTROLS#
#define SL_USBD_HID_USAGE_PAGE_GENERIC_DEVICE_CONTROLSValue:
0x06
SL_USBD_HID_USAGE_PAGE_BUTTON
#define SL_USBD_HID_USAGE_PAGE_BUTTONValue:
0x09
SL_USBD_HID_USAGE_PAGE_ALPHANUMERIC_DISPLAY#
#define SL_USBD_HID_USAGE_PAGE_ALPHANUMERIC_DISPLAYValue:
0x14
SL_USBD_HID_USAGE_PAGE_MEDICAL_INSTRUMENTS#
#define SL_USBD_HID_USAGE_PAGE_MEDICAL_INSTRUMENTSValue:
0x40
SL_USBD_HID_USAGE_PAGE_BAR_CODE_SCANNER_PAGE#
#define SL_USBD_HID_USAGE_PAGE_BAR_CODE_SCANNER_PAGEValue:
0x8C
SL_USBD_HID_USAGE_PAGE_POINT_OF_SALE_PAGES#
#define SL_USBD_HID_USAGE_PAGE_POINT_OF_SALE_PAGESValue:
0x8F
SL_USBD_HID_USAGE_PAGE_CAMERA_CONTROL_PAGE#
#define SL_USBD_HID_USAGE_PAGE_CAMERA_CONTROL_PAGEValue:
0x90