summaryrefslogtreecommitdiffstats
path: root/usbhid-dump/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'usbhid-dump/README.md')
-rw-r--r--usbhid-dump/README.md126
1 files changed, 126 insertions, 0 deletions
diff --git a/usbhid-dump/README.md b/usbhid-dump/README.md
new file mode 100644
index 0000000..001b858
--- /dev/null
+++ b/usbhid-dump/README.md
@@ -0,0 +1,126 @@
+<!---
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) 2010 Nikolai Kondrashov
+-->
+
+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](https://github.com/DIGImend/hidrd) 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