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.

Human Interface Devices (HID)

Common USB HID part that can be used outside of USB support, defined in header file include/zephyr/usb/class/hid.h.

HID types reference

group usb_hid_definitions

hid.h API

USB HID types and values

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 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 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