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/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.