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_COLLECTION_LOGICAL

Logical collection type

HID_COLLECTION_REPORT

Report collection type

HID_COLLECTION_NAMED_ARRAY

Named Array collection type

HID_COLLECTION_USAGE_SWITCH

Usage Switch collection type

HID_COLLECTION_MODIFIER

Modifier 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 max_data_len 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.