1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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
|
