USBHIDCTL(1)

💅 USBHIDCTL(1) — General Commands Manual energy ✨

okay so bestie, real talk: this is usbhidctl from the General Commands Manual section, and it's literally the tool that lets you peek at and poke your USB HID (Human Interface Device) friends. no cap, it's giving main character energy for USB nerds 🫶

---

✨ NAME ✨

usbhidctl — manipulate USB HID devices 💖

---

🎀 SYNOPSIS 🎀

usbhidctl -f device [-t table] [-v] [-x] -r
usbhidctl -f device [-t table] [-l] [-v] [-x] [-z] -a
usbhidctl -f device [-t table] [-l] [-n] [-v] [-x] [-z] item ...
usbhidctl -f device [-t table] [-v] [-z] -w item=value ...

---

🌸 DESCRIPTION 🌸

okay so picture this: usbhidctl is the utility you use to dump and modify the state of a USB HID (Human Interface Device). every named item gets printed, periodt. and if you throw in the -w flag, usbhidctl literally attempts to set the specified items to the given values. slay 💅

the options are as follows, and yes every single one matters:

• -a — Show all items and their current values if device returns. literally all of them 👑
• -f device — Specify a path name for the device to operate on. tell it where the device lives 🎀
• -l — Loop and dump the device data every time it changes. it keeps watching, lowkey obsessed 🦋
• -n — Suppress printing of the item name. just the vibes, no labels 🙈
• -r — Dump the report descriptor. the whole blueprint, iconic ⭐
• -t table — Specify a path name for the HID usage table file. a whole custom table, fancy 💜
• -v — Be verbose. say more, bestie 🗣️
• -w — Change item values. only 'output' and 'feature' kinds can be set with this option — like, those are the only two it'll touch, no cap 🔥
• -x — Dump data in hexadecimal as well as decimal. double the representation, double the fun 🌈
• -z — Reset reports to zero before processing other arguments. if not specified, current values will be requested from device. so it's zero-first vs. ask-the-device-first, iykyk 💫

---

🦋 SYNTAX 🦋

so here's the whole naming situation, and it's actually genius: usbhidctl compares the names of items specified on the command line against the human interface items reported by the USB device. each human interface item gets mapped from its native form to a human readable name, using the HID usage table file. then command line items are compared with the generated item names, and the USB HID device is operated on when a match is found. matching = action, periodt ✨

each human interface item is named by the "page" it appears in, the "usage" within that page, and the list of "collections" containing the item. and each collection in turn is also identified by page, and the usage within that page. nested naming, we love to see it 💖

on the usbhidctl command line the page name is separated from the usage name with the character ':'. the collections are separated by the character '.'. so : for page-to-usage, . for collection vibes 🎀

some devices give the same name to more than one item 😭 which is chaotic of them, honestly. but usbhidctl supports isolating each item by appending a '#' character and a decimal item instance number, starting at zero. so item zero, item one, etc. — you can tell them apart, thank goodness 🙏

---

🌈 FILES 🌈

• /usr/share/misc/usb_hid_usages — The default HID usage table. the go-to table, the standard issue 🍓

---

👑 SEE ALSO 👑

usbhid(3), uhid(4), usb(4) — go read these too, they're the supporting cast 💜

---

⭐ HISTORY ⭐

The usbhidctl command appeared in NetBSD 1.4. vintage. a classic. we stan a long-running icon 🧚

---

and that's the whole page, bestie 💅 this was usbhidctl from the General Commands Manual, Debian edition, dated August 1, 2011 — a whole era, fr fr. go forth and manipulate those HID devices responsibly 🫶✨