usbhid-dump(8)

📦
version 020 · 4 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ usbhid-dump(8) — NAME ✨

usbhid-dump 🦋 is the tool that lets you dump USB HID device report descriptors and streams. Iconic, right?

📋 SYNOPSIS 📋

usbhid-dump [OPTION]...

💖 DESCRIPTION 💖

okay so usbhid-dump uses libusb to dump report descriptors and streams from HID (human interface device) interfaces of USB devices. By default it dumps HID interfaces of all connected USB devices, but you can narrow it down to a subset of them, or to a single interface, using options. main character energy 💅

🚨 NOTE: usbhid-dump detaches kernel drivers from the interfaces it dumps and uses them exclusively, so no other program receives the input in the meantime. The report descriptor dumping is instantaneous, but the stream dumping keeps going until you terminate it with SIGINT (^C from the terminal) or a timeout expires.

bestie, listen 🫶 if you accidentally start dumping a stream from the USB keyboard you're using to control the terminal, the system stops receiving your input and you can't terminate usbhid-dump. 💀 Just stop typing and wait for the timeout to expire. The stream dumping will stop, the keyboard gets reattached to the kernel driver, and you'll regain control. phew 😭

The default stream dumping timeout is 60 seconds, and you can change it with the -t option. ⏰

🎀 OPTIONS 🎀

  • -h, --help — Output a help message and exit. 🌸
  • -v, --version — Output version information and exit. ✨
  • -s, -a, --address=bus[:dev] — Limit interfaces by bus number and device address. Both are 1-255, decimal. Zeroes match any bus or device. 🧚
  • -d, -m, --model=vid[:pid] — Limit interfaces by device vendor and product IDs. Both are 1-FFFF, hexadecimal. Zeroes match any vendor or product. 💜
  • -i, --interface=NUMBER — Limit interfaces by number (0-254), decimal. 255 matches any interface. 🦋
  • -e, --entity=STRING — The entity to dump: either "descriptor", "stream" or "all". You can shorten it down to one letter. The default is "descriptor". 💅
  • -t, --stream-timeout=NUMBER — Stream interrupt transfer timeout, in ms. Zero means infinity. The default is 60000 (60 seconds). ⏳
  • -p, --stream-paused — Start with the stream dump output paused. 🙈
  • -f, --stream-feedback — Enable stream dumping feedback: print a dot to stderr for every transfer dumped. 🍓

🌈 SIGNALS 🌈

  • USR1/USR2 — Pause/resume stream dump output. 🔥

🧾 OUTPUT FORMAT 🧾

okay so usbhid-dump outputs dumps in chunks. Each chunk is separated by an empty line and starts with this header line:

BUS:DEVICE:INTERFACE:ENTITY TIMESTAMP

Here, BUS, DEVICE and INTERFACE are the bus, device and interface numbers respectively. ENTITY is either "DESCRIPTOR" or "STREAM". TIMESTAMP is the timestamp in seconds since epoch. ⌛

After the header, the actual dump data follows as hex bytes. A descriptor chunk includes the whole report descriptor. Every stream chunk usually includes a whole report, but if a report is bigger than the endpoint's wMaxPacketSize, it will span several chunks. 🧩

🍓 EXAMPLES 🍓

Dump the report descriptor for a device with address 3 on bus number 2: 💻

usbhid-dump -a 2:3

Dump the report stream for a device with vendor ID 0x5543 and product ID 0x0005: 🎮

usbhid-dump -m 5543:0005 -es

Dump the report descriptor from interface 1 of a device with vendor ID 0x5543: 🔍

usbhid-dump -m 5543 -i 1 -ed

Dump report streams from all HID interfaces of all USB devices (caution: you will lose control over the terminal if you use a USB keyboard): ⚠️

usbhid-dump -es

👑 AUTHOR 👑

Nikolai Kondrashov <spbnick@gmail.com> 🫶

bestie, this was the usbutils package's usbhid-dump(8) page from the Linux USB Utilities set, last updated February 2012. Go slay your HID devices responsibly 💅✨🦋

📦 where this page comes from