USB Human Interface Devices (HID) support¶

Since the USB HID specification is not only used by the USB subsystem, the USB HID API is split into two header files include/usb/class/hid.h and include/usb/class/usb_hid.h. The second includes a specific part for HID support in the USB device stack.

HID Item helpers¶

HID item helper macros can be used to compose a HID Report Descriptor. The names correspond to those used in the USB HID Specification.

Example of a HID Report Descriptor:

static const uint8_t hid_report_desc[] = {
    HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
    HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
    HID_COLLECTION(HID_COLLECTION_APPLICATION),
    HID_LOGICAL_MIN8(0),
    /* logical maximum 255 */
    HID_LOGICAL_MAX16(0xFF, 0x00),
    HID_REPORT_ID(1),
    HID_REPORT_SIZE(8),
    HID_REPORT_COUNT(1),
    HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
    /* HID_INPUT (Data, Variable, Absolute) */
    HID_INPUT(0x02),
    HID_END_COLLECTION,
};

HID items reference¶

group usb_hid_items

Defines

HID_ITEM(bTag, bType, bSize)¶

Define HID short item.

Parameters

bTag – Item tag
bType – Item type
bSize – Item data size

Returns

HID Input item

HID_INPUT(a)¶

Define HID Input item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Input item data

Returns

HID Input item

HID_OUTPUT(a)¶

Define HID Output item with the data length of one byte.

For usage examples, see HID_KEYBOARD_REPORT_DESC()

Parameters

a – Output item data

Returns

HID Output item

HID_FEATURE(a)¶

Define HID Feature item with the data length of one byte.

Parameters

a – Feature item data

Returns

HID Feature item

HID_COLLECTION(a)¶

Define HID Collection item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Collection item data

Returns

HID Collection item

HID_END_COLLECTION¶

Define HID End Collection (non-data) item.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Returns: HID End Collection item

HID_USAGE_PAGE(page)¶

Define HID Usage Page item.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

page – Usage Page

Returns

HID Usage Page item

HID_LOGICAL_MIN8(a)¶

Define HID Logical Minimum item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Minimum value in logical units

Returns

HID Logical Minimum item

HID_LOGICAL_MAX8(a)¶

Define HID Logical Maximum item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Maximum value in logical units

Returns

HID Logical Maximum item

HID_LOGICAL_MIN16(a, b)¶

Define HID Logical Minimum item with the data length of two bytes.

Parameters

a – Minimum value lower byte
b – Minimum value higher byte

Returns

HID Logical Minimum item

HID_LOGICAL_MAX16(a, b)¶

Define HID Logical Maximum item with the data length of two bytes.

Parameters

a – Minimum value lower byte
b – Minimum value higher byte

Returns

HID Logical Maximum item

HID_LOGICAL_MIN32(a, b, c, d)¶

Define HID Logical Minimum item with the data length of four bytes.

Parameters

a – Minimum value lower byte
b – Minimum value low middle byte
c – Minimum value high middle byte
d – Minimum value higher byte

Returns

HID Logical Minimum item

HID_LOGICAL_MAX32(a, b, c, d)¶

Define HID Logical Maximum item with the data length of four bytes.

Parameters

a – Minimum value lower byte
b – Minimum value low middle byte
c – Minimum value high middle byte
d – Minimum value higher byte

Returns

HID Logical Maximum item

HID_REPORT_SIZE(size)¶

Define HID Report Size item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

size – Report field size in bits

Returns

HID Report Size item

HID_REPORT_ID(id)¶

Define HID Report ID item with the data length of one byte.

Parameters

id – Report ID

Returns

HID Report ID item

HID_REPORT_COUNT(count)¶

Define HID Report Count item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

count – Number of data fields included in the report

Returns

HID Report Count item

HID_USAGE(idx)¶

Define HID Usage Index item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

idx – Number of data fields included in the report

Returns

HID Usage Index item

HID_USAGE_MIN8(a)¶

Define HID Usage Minimum item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Starting Usage

Returns

HID Usage Minimum item

HID_USAGE_MAX8(a)¶

Define HID Usage Maximum item with the data length of one byte.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Ending Usage

Returns

HID Usage Maximum item

HID_USAGE_MIN16(a, b)¶

Define HID Usage Minimum item with the data length of two bytes.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Starting Usage lower byte
b – Starting Usage higher byte

Returns

HID Usage Minimum item

HID_USAGE_MAX16(a, b)¶

Define HID Usage Maximum item with the data length of two bytes.

For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()

Parameters

a – Ending Usage lower byte
b – Ending Usage higher byte

Returns

HID Usage Maximum item

HID types reference¶

group usb_hid_types

Defines

USB_DESC_HID¶: USB HID Class HID descriptor type

USB_DESC_HID_REPORT¶: USB HID Class Report descriptor type

USB_DESC_HID_PHYSICAL¶: USB HID Class physical descriptor type

USB_HID_GET_REPORT¶: USB HID Class GetReport bRequest value

USB_HID_GET_IDLE¶: USB HID Class GetIdle bRequest value

USB_HID_GET_PROTOCOL¶: USB HID Class GetProtocol bRequest value

USB_HID_SET_REPORT¶: USB HID Class SetReport bRequest value

USB_HID_SET_IDLE¶: USB HID Class SetIdle bRequest value

USB_HID_SET_PROTOCOL¶: USB HID Class SetProtocol bRequest value

HID_BOOT_IFACE_CODE_NONE¶: USB HID Boot Interface Protocol (bInterfaceProtocol) Code None

HID_BOOT_IFACE_CODE_KEYBOARD¶: USB HID Boot Interface Protocol (bInterfaceProtocol) Code Keyboard

HID_BOOT_IFACE_CODE_MOUSE¶: USB HID Boot Interface Protocol (bInterfaceProtocol) Code Mouse

HID_PROTOCOL_BOOT¶: USB HID Class Boot protocol code

HID_PROTOCOL_REPORT¶: USB HID Class Report protocol code

HID_ITEM_TYPE_MAIN¶: HID Main item type

HID_ITEM_TYPE_GLOBAL¶: HID Global item type

HID_ITEM_TYPE_LOCAL¶: HID Local item type

HID_ITEM_TAG_INPUT¶: HID Input item tag

HID_ITEM_TAG_OUTPUT¶: HID Output item tag

HID_ITEM_TAG_COLLECTION¶: HID Collection item tag

HID_ITEM_TAG_FEATURE¶: HID Feature item tag

HID_ITEM_TAG_COLLECTION_END¶: HID End Collection item tag

HID_ITEM_TAG_USAGE_PAGE¶: HID Usage Page item tag

HID_ITEM_TAG_LOGICAL_MIN¶: HID Logical Minimum item tag

HID_ITEM_TAG_LOGICAL_MAX¶: HID Logical Maximum item tag

HID_ITEM_TAG_PHYSICAL_MIN¶: HID Physical Minimum item tag

HID_ITEM_TAG_PHYSICAL_MAX¶: HID Physical Maximum item tag

HID_ITEM_TAG_UNIT_EXPONENT¶: HID Unit Exponent item tag

HID_ITEM_TAG_UNIT¶: HID Unit item tag

HID_ITEM_TAG_REPORT_SIZE¶: HID Report Size item tag

HID_ITEM_TAG_REPORT_ID¶: HID Report ID item tag

HID_ITEM_TAG_REPORT_COUNT¶: HID Report count item tag

HID_ITEM_TAG_USAGE¶: HID Usage item tag

HID_ITEM_TAG_USAGE_MIN¶: HID Usage Minimum item tag

HID_ITEM_TAG_USAGE_MAX¶: HID Usage Maximum item tag

HID_COLLECTION_PHYSICAL¶: Physical collection type

HID_COLLECTION_APPLICATION¶: Application collection type

HID_USAGE_GEN_DESKTOP¶: HID Generic Desktop Controls Usage page

HID_USAGE_GEN_KEYBOARD¶: HID Keyboard Usage page

HID_USAGE_GEN_LEDS¶: HID LEDs Usage page

HID_USAGE_GEN_BUTTON¶: HID Button Usage page

HID_USAGE_GEN_DESKTOP_UNDEFINED¶: HID Generic Desktop Undefined Usage ID

HID_USAGE_GEN_DESKTOP_POINTER¶: HID Generic Desktop Pointer Usage ID

HID_USAGE_GEN_DESKTOP_MOUSE¶: HID Generic Desktop Mouse Usage ID

HID_USAGE_GEN_DESKTOP_JOYSTICK¶: HID Generic Desktop Joystick Usage ID

HID_USAGE_GEN_DESKTOP_GAMEPAD¶: HID Generic Desktop Gamepad Usage ID

HID_USAGE_GEN_DESKTOP_KEYBOARD¶: HID Generic Desktop Keyboard Usage ID

HID_USAGE_GEN_DESKTOP_KEYPAD¶: HID Generic Desktop Keypad Usage ID

HID_USAGE_GEN_DESKTOP_X¶: HID Generic Desktop X Usage ID

HID_USAGE_GEN_DESKTOP_Y¶: HID Generic Desktop Y Usage ID

HID_USAGE_GEN_DESKTOP_WHEEL¶: HID Generic Desktop Wheel Usage ID

HID Mouse and Keyboard report descriptors¶

The pre-defined Mouse and Keyboard report descriptors can be used by a HID device implementation or simply as examples.

group usb_hid_mk_report_desc

Defines

HID_MOUSE_REPORT_DESC(bcnt)¶

Simple HID mouse report descriptor for n button mouse.

Parameters

bcnt – Button count. Allowed values from 1 to 8.

HID_KEYBOARD_REPORT_DESC()¶: Simple HID keyboard report descriptor.

Enums

enum hid_kbd_code¶

HID keyboard button codes.

Values:

enumerator HID_KEY_A = 4¶

enumerator HID_KEY_B = 5¶

enumerator HID_KEY_C = 6¶

enumerator HID_KEY_D = 7¶

enumerator HID_KEY_E = 8¶

enumerator HID_KEY_F = 9¶

enumerator HID_KEY_G = 10¶

enumerator HID_KEY_H = 11¶

enumerator HID_KEY_I = 12¶

enumerator HID_KEY_J = 13¶

enumerator HID_KEY_K = 14¶

enumerator HID_KEY_L = 15¶

enumerator HID_KEY_M = 16¶

enumerator HID_KEY_N = 17¶

enumerator HID_KEY_O = 18¶

enumerator HID_KEY_P = 19¶

enumerator HID_KEY_Q = 20¶

enumerator HID_KEY_R = 21¶

enumerator HID_KEY_S = 22¶

enumerator HID_KEY_T = 23¶

enumerator HID_KEY_U = 24¶

enumerator HID_KEY_V = 25¶

enumerator HID_KEY_W = 26¶

enumerator HID_KEY_X = 27¶

enumerator HID_KEY_Y = 28¶

enumerator HID_KEY_Z = 29¶

enumerator HID_KEY_1 = 30¶

enumerator HID_KEY_2 = 31¶

enumerator HID_KEY_3 = 32¶

enumerator HID_KEY_4 = 33¶

enumerator HID_KEY_5 = 34¶

enumerator HID_KEY_6 = 35¶

enumerator HID_KEY_7 = 36¶

enumerator HID_KEY_8 = 37¶

enumerator HID_KEY_9 = 38¶

enumerator HID_KEY_0 = 39¶

enumerator HID_KEY_ENTER = 40¶

enumerator HID_KEY_ESC = 41¶

enumerator HID_KEY_BACKSPACE = 42¶

enumerator HID_KEY_TAB = 43¶

enumerator HID_KEY_SPACE = 44¶

enumerator HID_KEY_MINUS = 45¶

enumerator HID_KEY_EQUAL = 46¶

enumerator HID_KEY_LEFTBRACE = 47¶

enumerator HID_KEY_RIGHTBRACE = 48¶

enumerator HID_KEY_BACKSLASH = 49¶

enumerator HID_KEY_HASH = 50¶

enumerator HID_KEY_SEMICOLON = 51¶

enumerator HID_KEY_APOSTROPHE = 52¶

enumerator HID_KEY_GRAVE = 53¶

enumerator HID_KEY_COMMA = 54¶

enumerator HID_KEY_DOT = 55¶

enumerator HID_KEY_SLASH = 56¶

enumerator HID_KEY_CAPSLOCK = 57¶

enumerator HID_KEY_F1 = 58¶

enumerator HID_KEY_F2 = 59¶

enumerator HID_KEY_F3 = 60¶

enumerator HID_KEY_F4 = 61¶

enumerator HID_KEY_F5 = 62¶

enumerator HID_KEY_F6 = 63¶

enumerator HID_KEY_F7 = 64¶

enumerator HID_KEY_F8 = 65¶

enumerator HID_KEY_F9 = 66¶

enumerator HID_KEY_F10 = 67¶

enumerator HID_KEY_F11 = 68¶

enumerator HID_KEY_F12 = 69¶

enumerator HID_KEY_SYSRQ = 70¶

enumerator HID_KEY_SCROLLLOCK = 71¶

enumerator HID_KEY_PAUSE = 72¶

enumerator HID_KEY_INSERT = 73¶

enumerator HID_KEY_HOME = 74¶

enumerator HID_KEY_PAGEUP = 75¶

enumerator HID_KEY_DELETE = 76¶

enumerator HID_KEY_END = 77¶

enumerator HID_KEY_PAGEDOWN = 78¶

enumerator HID_KEY_RIGHT = 79¶

enumerator HID_KEY_LEFT = 80¶

enumerator HID_KEY_DOWN = 81¶

enumerator HID_KEY_UP = 82¶

enumerator HID_KEY_NUMLOCK = 83¶

enumerator HID_KEY_KPSLASH = 84¶

enumerator HID_KEY_KPASTERISK = 85¶

enumerator HID_KEY_KPMINUS = 86¶

enumerator HID_KEY_KPPLUS = 87¶

enumerator HID_KEY_KPENTER = 88¶

enumerator HID_KEY_KP_1 = 89¶

enumerator HID_KEY_KP_2 = 90¶

enumerator HID_KEY_KP_3 = 91¶

enumerator HID_KEY_KP_4 = 92¶

enumerator HID_KEY_KP_5 = 93¶

enumerator HID_KEY_KP_6 = 94¶

enumerator HID_KEY_KP_7 = 95¶

enumerator HID_KEY_KP_8 = 96¶

enumerator HID_KEY_KP_9 = 97¶

enumerator HID_KEY_KP_0 = 98¶

enum hid_kbd_modifier¶

HID keyboard modifiers.

Values:

enumerator HID_KBD_MODIFIER_NONE = 0x00¶

enumerator HID_KBD_MODIFIER_LEFT_CTRL = 0x01¶

enumerator HID_KBD_MODIFIER_LEFT_SHIFT = 0x02¶

enumerator HID_KBD_MODIFIER_LEFT_ALT = 0x04¶

enumerator HID_KBD_MODIFIER_LEFT_UI = 0x08¶

enumerator HID_KBD_MODIFIER_RIGHT_CTRL = 0x10¶

enumerator HID_KBD_MODIFIER_RIGHT_SHIFT = 0x20¶

enumerator HID_KBD_MODIFIER_RIGHT_ALT = 0x40¶

enumerator HID_KBD_MODIFIER_RIGHT_UI = 0x80¶

enum hid_kbd_led¶

HID keyboard LEDs.

Values:

enumerator HID_KBD_LED_NUM_LOCK = 0x01¶

enumerator HID_KBD_LED_CAPS_LOCK = 0x02¶

enumerator HID_KBD_LED_SCROLL_LOCK = 0x04¶

enumerator HID_KBD_LED_COMPOSE = 0x08¶

enumerator HID_KBD_LED_KANA = 0x10¶

HID Class Device API reference¶

USB HID devices like mouse, keyboard, or any other specific device use this API.

group usb_hid_device_api

Typedefs

typedef int (*hid_cb_t)(const struct device *dev, struct usb_setup_packet *setup, int32_t *len, uint8_t **data)¶

typedef void (*hid_int_ready_callback)(const struct device *dev)¶

typedef void (*hid_protocol_cb_t)(const struct device *dev, uint8_t protocol)¶

typedef void (*hid_idle_cb_t)(const struct device *dev, uint16_t report_id)¶

Functions

void usb_hid_register_device(const struct device *dev, const uint8_t *desc, size_t size, const struct hid_ops *op)¶

Register HID device.

Parameters

dev – [in] Pointer to USB HID device
desc – [in] Pointer to HID report descriptor
size – [in] Size of HID report descriptor
op – [in] Pointer to USB HID device interrupt struct

int hid_int_ep_write(const struct device *dev, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret)¶

Write to USB HID interrupt endpoint buffer.

Parameters

dev – [in] Pointer to USB HID device
data – [in] Pointer to data buffer
data_len – [in] Length of data to copy
bytes_ret – [out] Bytes written to the EP buffer.

Returns

0 on success, negative errno code on fail.

int hid_int_ep_read(const struct device *dev, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes)¶

Read from USB HID interrupt endpoint buffer.

Parameters

dev – [in] Pointer to USB HID device
data – [in] Pointer to data buffer
max_data_len – [in] Max length of data to copy
ret_bytes – [out] Number of bytes to copy. If data is NULL and ret_bytes is 0 the number of bytes available in the buffer will be returned.

Returns

0 on success, negative errno code on fail.

int usb_hid_set_proto_code(const struct device *dev, uint8_t proto_code)¶

Set USB HID class Protocol Code.

Should be called before usb_hid_init().

Parameters

dev – [in] Pointer to USB HID device
proto_code – [in] Protocol Code to be used for bInterfaceProtocol

Returns

0 on success, negative errno code on fail.

int usb_hid_init(const struct device *dev)¶

Initialize USB HID class support.

Parameters

dev – [in] Pointer to USB HID device

Returns

0 on success, negative errno code on fail.

struct hid_ops¶: #include <usb_hid.h>

USB HID device interface.