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.