---
name: "usbhidaction"
section: "1"
platform: "openbsd"
package: "man"
version: "8.0-current-20261101"
release: "OpenBSD 8.0-current (2026-11-01)"
platforms: ["freebsd", "openbsd"]
url: "https://new.carta.tech/usbhidaction"
---

# usbhidaction(1)

perform actions according to USB HID controls

## NAME

**usbhidaction** – perform actions according to USB HID controls

## SYNOPSIS

**usbhidaction** \[**-div**\] **-c** *config-file* **-f** *device* *arg* *...*

## DESCRIPTION

**usbhidaction** can be used to execute commands when certain values appear on HID controls. 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. If a read from the HID device fails, the program dies; this will make it die when the USB device is unplugged.

The options are as follows:

- **-c** *config-file*

  Specify a path name for the config file.

- **-d**

  Toggle the daemon flag.

- **-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.

- **-i**

  Ignore HID items in the config file that do not exist in the device.

- **-v**

  Be verbose, and do not become a daemon.

The config file will be re-read upon receiving SIGHUP.

## 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 \`#' are considered as comments.

Each line has three parts: a name of a USB HID item, a value for that item, and an action. There must be whitespace between the parts.

The item names are similar to those used by [usbhidctl(1)](/usbhidctl/1.md), but each part must be prefixed by its page name.

The value is simply a numeric value. When the item reports this value, the action will be performed. If the value is \`\*', it will match any value.

The action is a normal command that is executed by using [fork(2)](/fork/2.md). Before it is executed some substitution will occur: \`$n' will be replaced by the nth argument on the command line, \`$V' will be replaced by the numeric value of the HID item, \`$N' will be replaced by the name of the control, and \`$H' will be replaced by the name of the HID device.

## FILES

*/usr/share/misc/usb\_hid\_usages* The HID usage table.

## EXAMPLES

The following configuration file can be used to control the master volume and muting of an [azalia(4)](/azalia/4.md) device using the multimedia keys on a Belkin USB keyboard.

```
# The volume range is 0..1. Moving 0.05 volume steps, each keypress
# moves quickly through the volume range but still has decent
# granularity.
Consumer:Volume_Increment					   1
	sndioctl -f $1 output.level=+0.05
Consumer:Volume_Decrement					   1
	sndioctl -f $1 output.level=-0.05
Consumer:Mute							   1
	sndioctl -f $1 output.mute=!
```

A sample invocation using this configuration would be

```
$ usbhidaction -f /dev/uhid1 -c conf snd/0
```

## SEE ALSO

[usbhidctl(1)](/usbhidctl/1.md), [usbhid(3)](/usbhid/3.md), [uhid(4)](/uhid/4.md), [usb(4)](/usb/4.md)

## HISTORY

The **usbhidaction** command first appeared in OpenBSD 3.2.