sphinx.addnodesdocument)}( rawsource children]( translations
LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba
attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget /translations/zh_CN/hid/hidintromodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/zh_TW/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/it_IT/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ja_JP/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ko_KR/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/pt_BR/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah }(h ]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/sp_SP/hid/hidintromodnameN classnameN refexplicituh1hhh ubeh }(h ]h ]h"]h$]h&]current_languageEnglishuh1h
hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah }(h ]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh:/var/lib/git/docbuild/linux/Documentation/hid/hidintro.rsthKubhsection)}(hhh](htitle)}(h&Introduction to HID report descriptorsh]h&Introduction to HID report descriptors}(hhhhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThis chapter is meant to give a broad overview of what HID report
descriptors are, and of how a casual (non-kernel) programmer can deal
with HID devices that are not working well with Linux.h]hThis chapter is meant to give a broad overview of what HID report
descriptors are, and of how a casual (non-kernel) programmer can deal
with HID devices that are not working well with Linux.}(hhhhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhhhhubhtopic)}(hhh]h bullet_list)}(hhh](h list_item)}(hhh]h)}(hhh]h reference)}(hhh]h Introduction}(hj hhhNhNubah }(h ]id4ah ]h"]h$]h&]refid introductionuh1hhhubah }(h ]h ]h"]h$]h&]uh1hhhubah }(h ]h ]h"]h$]h&]uh1hhhubh)}(hhh](h)}(hhh]j )}(hhh]h Parsing HID report descriptors}(hj# hhhNhNubah }(h ]id5ah ]h"]h$]h&]refid parsing-hid-report-descriptorsuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hhh]h)}(hhh]h)}(hhh]j )}(hhh]h!Output, Input and Feature Reports}(hjB hhhNhNubah }(h ]id6ah ]h"]h$]h&]refid output-input-and-feature-reportsuh1hhj? ubah }(h ]h ]h"]h$]h&]uh1hhj< ubah }(h ]h ]h"]h$]h&]uh1hhj9 ubah }(h ]h ]h"]h$]h&]uh1hhj ubeh }(h ]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]j )}(hhh]h(Collections, Report IDs and Evdev events}(hjp hhhNhNubah }(h ]id7ah ]h"]h$]h&]refid'collections-report-ids-and-evdev-eventsuh1hhjm ubah }(h ]h ]h"]h$]h&]uh1hhjj ubah }(h ]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]j )}(hhh]hEvents}(hj hhhNhNubah }(h ]id8ah ]h"]h$]h&]refideventsuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhhubh)}(hhh](h)}(hhh]j )}(hhh]h When something does not work}(hj hhhNhNubah }(h ]id9ah ]h"]h$]h&]refid when-something-does-not-workuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hhh](h)}(hhh]h)}(hhh]j )}(hhh]hQuirks}(hj hhhNhNubah }(h ]id10ah ]h"]h$]h&]refidquirksuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hhh]h)}(hhh]j )}(hhh]h Fixing HID report descriptors}(hj hhhNhNubah }(h ]id11ah ]h"]h$]h&]refid fixing-hid-report-descriptorsuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hhh]h)}(hhh]j )}(hhh]h)Modifying the transmitted data on the fly}(hj hhhNhNubah }(h ]id12ah ]h"]h$]h&]refid)modifying-the-transmitted-data-on-the-flyuh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hhh]h)}(hhh]j )}(hhh]h Writing a specialized driver}(hj9 hhhNhNubah }(h ]id13ah ]h"]h$]h&]refid writing-a-specialized-driveruh1hhj6 ubah }(h ]h ]h"]h$]h&]uh1hhj3 ubah }(h ]h ]h"]h$]h&]uh1hhj ubeh }(h ]h ]h"]h$]h&]uh1hhj ubeh }(h ]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]j )}(hhh]h'Input Device Registration and Lifecycle}(hjg hhhNhNubah }(h ]id14ah ]h"]h$]h&]refid'input-device-registration-and-lifecycleuh1hhjd ubah }(h ]h ]h"]h$]h&]uh1hhja ubah }(h ]h ]h"]h$]h&]uh1hhhubeh }(h ]h ]h"]h$]h&]uh1hhhhhhNhNubah }(h ]contentsah ](contentslocaleh"]contentsah$]h&]uh1hhhhK
hhhhubhcompound)}(hhh]h toctree)}(hhh]h }(h ]h ]h"]h$]h&]h hid/hidintroentries]Nhid/hidreport-parsinga includefiles]j amaxdepthKcaptionNglobhidden
includehiddennumberedK
titlesonly
rawentries]uh1j hhhKhj ubah }(h ]h ]toctree-wrapperah"]h$]h&]uh1j hhhhhhhNubh)}(hhh](h)}(h Introductionh]h Introduction}(hj hhhNhNubah }(h ]h ]h"]h$]h&]refidj
uh1hhj hhhhhKubh)}(hHID stands for Human Interface Device, and can be whatever device you
are using to interact with a computer, be it a mouse, a touchpad, a
tablet, a microphone.h]hHID stands for Human Interface Device, and can be whatever device you
are using to interact with a computer, be it a mouse, a touchpad, a
tablet, a microphone.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hXk Many HID devices work out the box, even if their hardware is different.
For example, mice can have any number of buttons; they may have a
wheel; movement sensitivity differs between different models, and so
on. Nonetheless, most of the time everything just works, without the
need to have specialized code in the kernel for every mouse model
developed since 1970.h]hXk Many HID devices work out the box, even if their hardware is different.
For example, mice can have any number of buttons; they may have a
wheel; movement sensitivity differs between different models, and so
on. Nonetheless, most of the time everything just works, without the
need to have specialized code in the kernel for every mouse model
developed since 1970.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK hj hhubh)}(hX This is because modern HID devices do advertise their capabilities
through the *HID report descriptor*, a fixed set of bytes describing
exactly what *HID reports* may be sent between the device and the host
and the meaning of each individual bit in those reports. For example,
a HID Report Descriptor may specify that "in a report with ID 3 the
bits from 8 to 15 is the delta x coordinate of a mouse".h](hOThis is because modern HID devices do advertise their capabilities
through the }(hj hhhNhNubhemphasis)}(h*HID report descriptor*h]hHID report descriptor}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1j hj ubh/, a fixed set of bytes describing
exactly what }(hj hhhNhNubj )}(h
*HID reports*h]h HID reports}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1j hj ubh may be sent between the device and the host
and the meaning of each individual bit in those reports. For example,
a HID Report Descriptor may specify that “in a report with ID 3 the
bits from 8 to 15 is the delta x coordinate of a mouse”.}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhK#hj hhubh)}(hXU The HID report itself then merely carries the actual data values
without any extra meta information. Note that HID reports may be sent
from the device ("Input Reports", i.e. input events), to the device
("Output Reports" to e.g. change LEDs) or used for device configuration
("Feature reports"). A device may support one or more HID reports.h]hXa The HID report itself then merely carries the actual data values
without any extra meta information. Note that HID reports may be sent
from the device (“Input Reports”, i.e. input events), to the device
(“Output Reports” to e.g. change LEDs) or used for device configuration
(“Feature reports”). A device may support one or more HID reports.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK*hj hhubh)}(hX The HID subsystem is in charge of parsing the HID report descriptors,
and converts HID events into normal input device interfaces (see
Documentation/hid/hid-transport.rst). Devices may misbehave because the
HID report descriptor provided by the device is wrong, or because it
needs to be dealt with in a special way, or because some special
device or interaction mode is not handled by the default code.h]hX The HID subsystem is in charge of parsing the HID report descriptors,
and converts HID events into normal input device interfaces (see
Documentation/hid/hid-transport.rst). Devices may misbehave because the
HID report descriptor provided by the device is wrong, or because it
needs to be dealt with in a special way, or because some special
device or interaction mode is not handled by the default code.}(hj* hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK0hj hhubh)}(hThe format of HID report descriptors is described by two documents,
available from the `USB Implementers Forum `_
`HID web page `_ address:h](hWThe format of HID report descriptors is described by two documents,
available from the }(hj8 hhhNhNubj )}(h0`USB Implementers Forum `_h]hUSB Implementers Forum}(hj@ hhhNhNubah }(h ]h ]h"]h$]h&]nameUSB Implementers Forumrefurihttps://www.usb.org/uh1hhj8 ubhtarget)}(h h]h }(h ]usb-implementers-forumah ]h"]usb implementers forumah$]h&]refurijQ uh1jR
referencedKhj8 ubh
}(hj8 hhhNhNubj )}(h)`HID web page `_h]h HID web page}(hjf hhhNhNubah }(h ]h ]h"]h$]h&]name HID web pagejP https://www.usb.org/hiduh1hhj8 ubjS )}(h h]h }(h ] hid-web-pageah ]h"] hid web pageah$]h&]refurijv uh1jR ja Khj8 ubh address:}(hj8 hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhK7hj hhubh block_quote)}(h* the `HID USB Device Class Definition
`_ (HID Spec from now on)
* the `HID Usage Tables `_ (HUT from now on)
h]h)}(hhh](h)}(hthe `HID USB Device Class Definition
`_ (HID Spec from now on)h]h)}(hthe `HID USB Device Class Definition
`_ (HID Spec from now on)h](hthe }(hj hhhNhNubj )}(hi`HID USB Device Class Definition
`_h]h HID USB Device Class Definition}(hj hhhNhNubah }(h ]h ]h"]h$]h&]name HID USB Device Class DefinitionjP Dhttps://www.usb.org/document-library/device-class-definition-hid-111uh1hhj ubjS )}(hG
h]h }(h ] hid-usb-device-class-definitionah ]h"] hid usb device class definitionah$]h&]refurij uh1jR ja Khj ubh (HID Spec from now on)}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhK;hj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hathe `HID Usage Tables `_ (HUT from now on)
h]h)}(h`the `HID Usage Tables `_ (HUT from now on)h](hthe }(hj hhhNhNubj )}(hJ`HID Usage Tables `_h]hHID Usage Tables}(hj hhhNhNubah }(h ]h ]h"]h$]h&]nameHID Usage TablesjP 4https://usb.org/document-library/hid-usage-tables-14uh1hhj ubjS )}(h7 h]h }(h ]hid-usage-tablesah ]h"]hid usage tablesah$]h&]refurij uh1jR ja Khj ubh (HUT from now on)}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhK=hj ubah }(h ]h ]h"]h$]h&]uh1hhj ubeh }(h ]h ]h"]h$]h&]bullet*uh1hhhhK;hj ubah }(h ]h ]h"]h$]h&]uh1j hhhK;hj hhubh)}(hThe HID subsystem can deal with different transport drivers
(USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.h]hThe HID subsystem can deal with different transport drivers
(USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK?hj hhubeh }(h ]j ah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Parsing HID report descriptorsh]h Parsing HID report descriptors}(hj1 hhhNhNubah }(h ]h ]h"]h$]h&]j j, uh1hhj. hhhhhKCubh)}(hThe current list of HID devices can be found at ``/sys/bus/hid/devices/``.
For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``,
one can read the corresponding report descriptor::h](h0The current list of HID devices can be found at }(hj? hhhNhNubhliteral)}(h``/sys/bus/hid/devices/``h]h/sys/bus/hid/devices/}(hjI hhhNhNubah }(h ]h ]h"]h$]h&]uh1jG hj? ubh.
For each device, say }(hj? hhhNhNubjH )}(h/``/sys/bus/hid/devices/0003\:093A\:2510.0002/``h]h+/sys/bus/hid/devices/0003\:093A\:2510.0002/}(hj[ hhhNhNubah }(h ]h ]h"]h$]h&]uh1jG hj? ubh3,
one can read the corresponding report descriptor:}(hj? hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKEhj. hhubh
literal_block)}(hX $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|
00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|
00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|
00000030 81 06 c0 c0 |....|
00000034h]hX $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|
00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|
00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|
00000030 81 06 c0 c0 |....|
00000034}hju sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKIhj. hhubh)}(hhOptional: the HID report descriptor can be read also by
directly accessing the hidraw driver [#hidraw]_.h](h]Optional: the HID report descriptor can be read also by
directly accessing the hidraw driver }(hj hhhNhNubhfootnote_reference)}(h
[#hidraw]_h]h1}(hj hhhNhNubah }(h ]id1ah ]h"]h$]h&]autoKj hidrawdocnamej uh1j hj resolvedKubh.}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKPhj. hhubh)}(hX The basic structure of HID report descriptors is defined in the HID
spec, while HUT "defines constants that can be interpreted by an
application to identify the purpose and meaning of a data field in a
HID report". Each entry is defined by at least two bytes, where the
first one defines what type of value is following and is described in
the HID spec, while the second one carries the actual value and is
described in the HUT.h]hX The basic structure of HID report descriptors is defined in the HID
spec, while HUT “defines constants that can be interpreted by an
application to identify the purpose and meaning of a data field in a
HID report”. Each entry is defined by at least two bytes, where the
first one defines what type of value is following and is described in
the HID spec, while the second one carries the actual value and is
described in the HUT.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKShj. hhubh)}(hXHID report descriptors can, in principle, be painstakingly parsed by
hand, byte by byte.h]hXHID report descriptors can, in principle, be painstakingly parsed by
hand, byte by byte.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK[hj. hhubh)}(hA short introduction on how to do this is sketched in
Documentation/hid/hidreport-parsing.rst; you only need to understand it
if you need to patch HID report descriptors.h]hA short introduction on how to do this is sketched in
Documentation/hid/hidreport-parsing.rst; you only need to understand it
if you need to patch HID report descriptors.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK^hj. hhubh)}(hIn practice you should not parse HID report descriptors by hand; rather,
you should use an existing parser. Among all the available onesh]hIn practice you should not parse HID report descriptors by hand; rather,
you should use an existing parser. Among all the available ones}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKbhj. hhubj )}(hX@ * the online `USB Descriptor and Request Parser
`_;
* `hidrdd `_,
that provides very detailed and somewhat verbose descriptions
(verbosity can be useful if you are not familiar with HID report
descriptors);
* `hid-tools `_,
a complete utility set that allows, among other things,
to record and replay the raw HID reports and to debug
and replay HID devices.
It is being actively developed by the Linux HID subsystem maintainers.
h]h)}(hhh](h)}(h]the online `USB Descriptor and Request Parser
`_;h]h)}(h]the online `USB Descriptor and Request Parser
`_;h](h the online }(hj hhhNhNubj )}(hQ`USB Descriptor and Request Parser
`_h]h!USB Descriptor and Request Parser}(hj hhhNhNubah }(h ]h ]h"]h$]h&]name!USB Descriptor and Request ParserjP *http://eleccelerator.com/usbdescreqparser/uh1hhj ubjS )}(h-
h]h }(h ]!usb-descriptor-and-request-parserah ]h"]!usb descriptor and request parserah$]h&]refurij uh1jR ja Khj ubh;}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKehj ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(h`hidrdd `_,
that provides very detailed and somewhat verbose descriptions
(verbosity can be useful if you are not familiar with HID report
descriptors);h]h)}(h`hidrdd `_,
that provides very detailed and somewhat verbose descriptions
(verbosity can be useful if you are not familiar with HID report
descriptors);h](j )}(h.`hidrdd `_h]hhidrdd}(hj+ hhhNhNubah }(h ]h ]h"]h$]h&]namehidrddjP "https://github.com/abend0c1/hidrdduh1hhj' ubjS )}(h% h]h }(h ]hidrddah ]h"]hidrddah$]h&]refurij; uh1jR ja Khj' ubh,
that provides very detailed and somewhat verbose descriptions
(verbosity can be useful if you are not familiar with HID report
descriptors);}(hj' hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKghj# ubah }(h ]h ]h"]h$]h&]uh1hhj ubh)}(hX `hid-tools `_,
a complete utility set that allows, among other things,
to record and replay the raw HID reports and to debug
and replay HID devices.
It is being actively developed by the Linux HID subsystem maintainers.
h]h)}(hX `hid-tools `_,
a complete utility set that allows, among other things,
to record and replay the raw HID reports and to debug
and replay HID devices.
It is being actively developed by the Linux HID subsystem maintainers.h](j )}(h@`hid-tools `_h]h hid-tools}(hja hhhNhNubah }(h ]h ]h"]h$]h&]name hid-toolsjP 1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhj] ubjS )}(h4 h]h }(h ] hid-toolsah ]h"] hid-toolsah$]h&]refurijq uh1jR ja Khj] ubh,
a complete utility set that allows, among other things,
to record and replay the raw HID reports and to debug
and replay HID devices.
It is being actively developed by the Linux HID subsystem maintainers.}(hj] hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKkhjY ubah }(h ]h ]h"]h$]h&]uh1hhj ubeh }(h ]h ]h"]h$]h&]j j uh1hhhhKehj ubah }(h ]h ]h"]h$]h&]uh1j hhhKehj. hhubh)}(hParsing the mouse HID report descriptor with `hid-tools
`_ leads to
(explanations interposed)::h](h-Parsing the mouse HID report descriptor with }(hj hhhNhNubj )}(h@`hid-tools
`_h]h hid-tools}(hj hhhNhNubah }(h ]h ]h"]h$]h&]name hid-toolsjP 1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhj ubjS )}(h4
h]h }(h ]id2ah ]h"]h$] hid-toolsah&]refurij uh1jR ja Khj ubh$ leads to
(explanations interposed):}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKqhj. hhubjt )}(hX $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
# device 0:0
# 0x05, 0x01, // Usage Page (Generic Desktop) 0
# 0x09, 0x02, // Usage (Mouse) 2
# 0xa1, 0x01, // Collection (Application) 4
# 0x09, 0x01, // Usage (Pointer) 6
# 0xa1, 0x00, // Collection (Physical) 8
# 0x05, 0x09, // Usage Page (Button) 10h]hX $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
# device 0:0
# 0x05, 0x01, // Usage Page (Generic Desktop) 0
# 0x09, 0x02, // Usage (Mouse) 2
# 0xa1, 0x01, // Collection (Application) 4
# 0x09, 0x01, // Usage (Pointer) 6
# 0xa1, 0x00, // Collection (Physical) 8
# 0x05, 0x09, // Usage Page (Button) 10}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKuhj. hhubh)}(hwhat follows is a button ::h]hwhat follows is a button}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhK~hj. hhubjt )}(h# 0x19, 0x01, // Usage Minimum (1) 12
# 0x29, 0x03, // Usage Maximum (3) 14h]h# 0x19, 0x01, // Usage Minimum (1) 12
# 0x29, 0x03, // Usage Maximum (3) 14}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(hBfirst button is button number 1, last button is button number 3 ::h]h?first button is button number 1, last button is button number 3}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(h# 0x15, 0x00, // Logical Minimum (0) 16
# 0x25, 0x01, // Logical Maximum (1) 18h]h# 0x15, 0x00, // Logical Minimum (0) 16
# 0x25, 0x01, // Logical Maximum (1) 18}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(hVeach button can send values from 0 up to including 1
(i.e. they are binary buttons) ::h]hSeach button can send values from 0 up to including 1
(i.e. they are binary buttons)}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x75, 0x01, // Report Size (1) 20h]hI# 0x75, 0x01, // Report Size (1) 20}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(h)each button is sent as exactly one bit ::h]h&each button is sent as exactly one bit}(hj- hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x95, 0x03, // Report Count (3) 22h]hI# 0x95, 0x03, // Report Count (3) 22}hj; sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(hAand there are three of those bits (matching the three buttons) ::h]h>and there are three of those bits (matching the three buttons)}(hjI hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x81, 0x02, // Input (Data,Var,Abs) 24h]hI# 0x81, 0x02, // Input (Data,Var,Abs) 24}hjW sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(hit's actual Data (not constant padding), they represent
a single variable (Var) and their values are Absolute (not relative);
See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::h]hit’s actual Data (not constant padding), they represent
a single variable (Var) and their values are Absolute (not relative);
See HID spec Sec. 6.2.2.5 “Input, Output, and Feature Items”}(hje hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x75, 0x05, // Report Size (5) 26h]hI# 0x75, 0x05, // Report Size (5) 26}hjs sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(h7five additional padding bits, needed to reach a byte ::h]h4five additional padding bits, needed to reach a byte}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x95, 0x01, // Report Count (1) 28h]hI# 0x95, 0x01, // Report Count (1) 28}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(h)those five bits are repeated only once ::h]h&those five bits are repeated only once}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hI# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30h]hI# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(h`_:
The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is::h](h-Indeed, for any event, the mouse will send a }(hjo hhhNhNubj )}(h*report*h]hreport}(hjw hhhNhNubah }(h ]h ]h"]h$]h&]uh1j hjo ubhF of four bytes.
We can check the values sent by resorting e.g. to the }(hjo hhhNhNubhtitle_reference)}(h`hid-recorder`h]h hid-recorder}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1j hjo ubh
tool, from }(hjo hhhNhNubj )}(h@`hid-tools `_h]h hid-tools}(hj hhhNhNubah }(h ]h ]h"]h$]h&]name hid-toolsjP 1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhjo ubjS )}(h4 h]h }(h ]id3ah ]h"]h$] hid-toolsah&]refurij uh1jR ja Khjo ubha:
The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:}(hjo hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhKhj. hhubjt )}(hXS $ sudo ./hid-recorder /dev/hidraw1
....
output of hid-decode
....
# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000000.000000 4 01 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000000.183949 4 00 00 00 00
# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000001.959698 4 02 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000002.103899 4 00 00 00 00
# Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0
E: 000004.855799 4 04 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000005.103864 4 00 00 00 00h]hXS $ sudo ./hid-recorder /dev/hidraw1
....
output of hid-decode
....
# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000000.000000 4 01 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000000.183949 4 00 00 00 00
# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000001.959698 4 02 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000002.103899 4 00 00 00 00
# Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0
E: 000004.855799 4 04 00 00 00
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
E: 000005.103864 4 00 00 00 00}hj sbah }(h ]h ]h"]h$]h&]hhuh1js hhhKhj. hhubh)}(hThis example shows that when button 2 is clicked,
the bytes ``02 00 00 00`` are sent, and the immediately subsequent
event (``00 00 00 00``) is the release of button 2 (no buttons are
pressed, remember that the data values are *absolute*).h](hinput;
/* Initialize private data and capabilities here */
set_bit(EV_FF, input->evbit);
return input_ff_create_memless(input, NULL, my_play_effect);
}
static struct hid_driver my_driver = {
.name = "my_driver",
.probe = my_probe,
.input_configured = my_input_configured,
};h]hX static int my_input_configured(struct hid_device *hdev, struct hid_input *hidinput)
{
struct input_dev *input = hidinput->input;
/* Initialize private data and capabilities here */
set_bit(EV_FF, input->evbit);
return input_ff_create_memless(input, NULL, my_play_effect);
}
static struct hid_driver my_driver = {
.name = "my_driver",
.probe = my_probe,
.input_configured = my_input_configured,
};}hj sbah }(h ]h ]h"]h$]h&]hhƌforcelanguagechighlight_args}uh1js hhhM+hj4 hhubh)}(hDrivers that require even more control over the lifecycle should mask out
``HID_CONNECT_HIDINPUT`` and call ``input_register_device()`` manually
when they are ready.h](hJDrivers that require even more control over the lifecycle should mask out
}(hj hhhNhNubjH )}(h``HID_CONNECT_HIDINPUT``h]hHID_CONNECT_HIDINPUT}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1jG hj ubh
and call }(hj hhhNhNubjH )}(h``input_register_device()``h]hinput_register_device()}(hj
hhhNhNubah }(h ]h ]h"]h$]h&]uh1jG hj ubh manually
when they are ready.}(hj hhhNhNubeh }(h ]h ]h"]h$]h&]uh1hhhhM<hj4 hhubeh }(h ]jv ah ]h"]'input device registration and lifecycleah$]h&]uh1hhhhhhhhMubeh }(h ]&introduction-to-hid-report-descriptorsah ]h"]&introduction to hid report descriptorsah$]h&]uh1hhhhhhhhKubeh }(h ]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN
source_urlN
toc_backlinksentryfootnote_backlinksK
sectnum_xformKstrip_commentsNstrip_elements_with_classesN
strip_classesN report_levelK
halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-sig input_encoding_error_handlerstrictoutput_encodingutf-8 output_encoding_error_handlerjT error_encodingutf-8 error_encoding_error_handlerbackslashreplace
language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid
dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN
_config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthK trim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales] character_level_inline_markupdoctitle_xform
docinfo_xformKsectsubtitle_xform
image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}hidraw]j asrefids}j ]j asnameids}(j. j+ j j j+ j j] jZ j j} j j j j j j2 j j jE jB j{ jx j jQ j
j j
j j1 j j j j@ j j j& j* jH j# j j& jv u nametypes}(j. j j+ j] j j j j j jE j{ j j
j
j1 j j@ j j* j# j& uh }(j+ hj hj j jZ jT j} jw j j j j j2 j. j j j j jB j< jx jr j j j j jQ je j j j j
j j
j j[ j j j& jC jH j j j jv j4 j
j j, j# jK jB jy jp j j j j j j j j j j jB j9 jp jg u
footnote_refs}j ]j as
citation_refs}
autofootnotes]j aautofootnote_refs]j asymbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK
id_counter collectionsCounter}jb KsRparse_messages](hsystem_message)}(hhh]h)}(h,Duplicate explicit target name: "hid-tools".h]h0Duplicate explicit target name: “hid-tools”.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]j alevelKtypeINFOsourcehnjlineKuh1j hj. hhhhhKsubj )}(hhh]h)}(h,Duplicate explicit target name: "hid-tools".h]h0Duplicate explicit target name: “hid-tools”.}(hj hhhNhNubah }(h ]h ]h"]h$]h&]uh1hhj ubah }(h ]h ]h"]h$]h&]j alevelKtypej sourcehnjlineKuh1j hj. hhhhhKubetransform_messages] transformerN include_log]
decorationNhhub.