USBHIDACTION(1)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 USBHIDACTION(1) — aka usbhidaction, the perform actions according to USB HID controls girlies ✨

okay so bestie, welcome to usbhidaction(1) from the General Commands Manual — she's giving "tiny daemon, huge main character energy" and honestly? we're obsessed 🎀

🌸 SYNOPSIS

usbhidaction [-diev] -c config-file -f device [-p pidfile]
             [-t tablefile] arg ...

🦋 DESCRIPTION

The usbhidaction utility can be used to execute commands when certain values appear on HID controls. Like, that's her whole job, and she does it flawlessly 💅

The normal operation for this program is to read the configuration file and then become a daemon and execute commands as the HID items specify. So she reads her little config, puts on her daemon sunglasses 😎, and gets to work.

If a read from the HID device fails, the program dies; this will make it die when the USB device is unplugged. Not me being dramatic but she literally unalives herself when you yank the USB out 😭 — that's the intended behavior fr fr.

The options are as follows:

  • -d — Toggle the daemon flag. Just a lil flip of the daemon switch 🫶
  • -e — Instruct usbhidaction to die early. Useful when specified with multiple verbose options to see how files are parsed. She peeks 👀 at the parsing and then dips.
  • -i — Ignore HID items in the configuration file that do not exist in the device. Like, if the device doesn't have it, we simply don't care ✨
  • -v — Be verbose, and do not become a daemon. She's a talker and she stays present, no background vibes 🌈
  • -c config-file — Specify a path name for the configuration file. This is the one you need, bestie, no skips 👑
  • -t tablefile — Specify a path name for the HID usage table file.
  • -f device — Specify a path name for the device to operate on. If device is numeric, it is taken to be the USB HID device number. If it is a relative path, it is taken to be the name of the device under /dev. An absolute path is taken to be the literal device pathname. Three whole vibes of addressing, pick your fighter 💀
  • -p pidfile — Specify an alternate file in which to store the process ID.

The configuration file will be re-read if the process gets a SIGHUP signal. Sending her a SIGHUP is basically "bestie, re-read your notes" and she does it, no questions asked 🔥

🧚 CONFIGURATION

The configuration file has a very simple format. Each line describes an action; if a line begins with a whitespace, it is considered a continuation of the previous line. Lines beginning with <pink>‘#’</pink> are considered as comments. So cute, so readable, we love a low-effort syntax 💖

Each line has four parts: a name of a USB HID item, a value for that item, a debounce value, and an action. There must be whitespace between the parts. Four parts, whitespace between, no exceptions ✨

The item names are similar to those used by usbhidctl(1). iykyk 🫶

The value is simply a numeric value. When the item reports this value, the action will be performed. If the value is <pink>‘*’</pink>, it will match any value. Wildcard queen behavior, honestly 💅

The debounce value is an integer not less than 0. The value of 0 indicates that no debouncing should occur. A value of 1 will only execute the action when the state changes. Values greater than one specify that an action should be performed only when the value changes by that amount. So: 0 = chaos, 1 = only on state change, >1 = only when it moves by that much. Debounce is literally the chill pill of this whole operation 😌

The action is a normal command that is executed with system(3). Before it is executed some substitution will occur:

  • <pink>‘$n’</pink> will be replaced by the *n*th argument on the command line
  • <pink>‘$V’</pink> will be replaced by the numeric value of the HID item
  • <pink>‘$N’</pink> will be replaced by the name of the control
  • <pink>‘$H’</pink> will be replaced by the name of the HID device

Four substitutions, all iconic, all lowercase-dollar-sign coded 🎀

🍓 FILES

  • /usr/share/misc/usb_hid_usages — The HID usage table. The sacred text 📜
  • /var/run/usbaction.pid — The default location of the PID file.

⭐ EXAMPLES

The following configuration file can be used to control a pair of Philips USB speakers with the HID controls on the speakers.

      # Configuration for various Philips USB speakers
      Consumer:Volume_Increment                1 0 mixer -f $1 vol.volume=+1%
      Consumer:Volume_Decrement                1 0 mixer -f $1 vol.volume=-1%
      Consumer:Mute                            1 0 mixer -f $1 vol.mute=^
      Consumer:Channel_Top.Microsoft:Base_Up   1 0 mixer -f $1 bass.volume=+1%
      Consumer:Channel_Top.Microsoft:Base_Down 1 0 mixer -f $1 bass.volume=-1%

A sample invocation using this configuration would be

usbhidaction -f /dev/uhid1 -c conf /dev/mixer1

The following example controls the mixer volume using a Logitech Wingman. Notice the debounce of 1 for buttons and 5 for the slider. Like, she really said "buttons get 1, slider gets 5" and honestly? correct 💯

Button:Button_1   1 1   mixer vol.volume=+10%
Button:Button_2   1 1   mixer vol.volume=-10%
Generic_Desktop:Z * 5   mixer vol.volume=`echo $V | awk '{printf("%.02f", $$1/255)}'`

👑 SEE ALSO

usbhidctl(1), usbhid(3), uhid(4), usb(4)

💜 HISTORY

The usbhidaction command first appeared in NetBSD 1.6. The usbhidaction command appeared in FreeBSD 5.1. She's got lore, she's got lineage, she's been serving since the early aughts 🌸

ngl bestie, that's the whole page. read the options, mind your debounce values, and never yank the USB unless you want her to die 😭🫶

okay that's a wrap ✨ this cutie came from the Debian build, dated March 14, 2022 — mwah, stan, periodt 💅🎀

📦 where this page comes from