This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

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/zephyr/usb/class/hid.h and include/zephyr/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_HID_VERSION

HID Specification release v1.11

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.