Add README.md

Add README.md with the slightly modified wiki page contents.

1 files changed, 112 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c8c095d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+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. 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