Usbhid-dump
Usbhid-dump is a USB HID dumping utility based on libusb 1.0. It dumps USB HID device report descriptors and reports themselves as they are being sent, for all or specific device interfaces.
Installation
Run ./configure && make to build and make install to install. If building from a Git tree, run ./bootstrap first. Usbhid-dump can also be run directly from the source directory as src/usbhid-dump, without installation.
Usage
Here is the output of usbhid-dump --help:
$ usbhid-dump --help
Usage: usbhid-dump [OPTION]...
Dump USB device HID report descriptor(s) and/or stream(s).
Options:
-h, --help output this help message and exit
-v, --version output version information and exit
-s, -a, --address=bus[:dev] limit interfaces by bus number
(1-255) and device address (1-255),
decimal; zeroes match any
-d, -m, --model=vid[:pid] limit interfaces by vendor and
product IDs (0001-ffff), hexadecimal;
zeroes match any
-i, --interface=NUMBER limit interfaces by number (0-254),
decimal; 255 matches any
-e, --entity=STRING what to dump: either "descriptor",
"stream" or "all"; value can be
abbreviated
-t, --stream-timeout=NUMBER stream interrupt transfer timeout, ms;
zero means infinity
-p, --stream-paused start with the stream dump output
paused
-f, --stream-feedback enable stream dumping feedback: for
every transfer dumped a dot is
printed to stderr
Default options: --stream-timeout=60000 --entity=descriptor
Signals:
USR1/USR2 pause/resume the stream dump output
Warning: please be careful running usbhid-dump as a superuser without limiting your device selection with options. Usbhid-dump will try to dump every device possible and If you're using a USB keyboard to control your terminal, it will be detached and you will be unable to terminate usbhid-dump and regain control.
If that happens just don't touch your keyboard for the duration of the interrupt transfer timeout (1 minute by default) and the dumping will be aborted.
Here is an example of a report descriptor and stream dump from a mouse:
$ sudo usbhid-dump --entity=all --address=2:3
002:003:000:DESCRIPTOR 1290272184.081322
05 01 09 02 A1 01 09 01 A1 00 05 09 19 01 29 03
15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01
05 01 09 30 09 31 09 38 15 81 25 7F 75 08 95 03
81 06 C0 C0
Starting dumping interrupt transfer stream
with 1 minute timeout.
002:003:000:STREAM 1290272185.210022
00 FF 00 00
002:003:000:STREAM 1290272185.217988
00 FE 00 00
002:003:000:STREAM 1290272185.225985
00 FC 01 00
002:003:000:STREAM 1290272185.233995
00 FE 01 00
002:003:000:STREAM 1290272185.241992
00 FF 01 00
002:003:000:STREAM 1290272185.249995
00 FE 02 00
002:003:000:STREAM 1290272185.257993
00 FF 01 00
^C
In the output above "002" is the bus number, "003" is the device address and "000" is the interface number. "DESCRIPTOR" indicates descriptor chunk and "STREAM" - stream chunk. The number to the right is the timestamp in seconds since epoch. The hexadecimal numbers below is the chunk dump itself. Usually every stream chunk includes a whole report, but if the report is bigger than endpoint's wMaxPacketSize, it will span several chunks.
You can use usbhid-dump along with hidrd-convert to dump report descriptors in human-readable format. Like this:
$ sudo usbhid-dump -a2:3 -i0 | grep -v : | xxd -r -p | hidrd-convert -o spec
Usage Page (Desktop), ; Generic desktop controls (01h)
Usage (Mouse), ; Mouse (02h, application collection)
Collection (Application),
Usage (Pointer), ; Pointer (01h, physical collection)
Collection (Physical),
Usage Page (Button), ; Button (09h)
Usage Minimum (01h),
Usage Maximum (03h),
Logical Minimum (0),
Logical Maximum (1),
Report Size (1),
Report Count (3),
Input (Variable),
Report Size (5),
Report Count (1),
Input (Constant),
Usage Page (Desktop), ; Generic desktop controls (01h)
Usage (X), ; X (30h, dynamic value)
Usage (Y), ; Y (31h, dynamic value)
Usage (Wheel), ; Wheel (38h, dynamic value)
Logical Minimum (-127),
Logical Maximum (127),
Report Size (8),
Report Count (3),
Input (Variable, Relative),
End Collection,
End Collection