LinkedIn Sourceforge Twitter

Vincent's Blog

Pleasure in the job puts perfection in the work (Aristote)

Specific keys on USB keyboards and OpenBSD

Posted on 2016-09-28 22:41:00 from Vincent in OpenBSD Desktop

If you are using an USB keyboard, there is standard tool in OpenBSD which allows you to assign specific commands to each of those keys. No need to install extra package, it's already part of the default OpenBSD install

Like lot of persons, I'm using a laptop, but on my main desk, I plug this machine into a docking station allowing me to use a better screen, a mouse and a better keyboard.

But, as on most USB keyboards, we have some extra keys allowing us to create funny shortcuts. For example, launch a browser, an email application, a calculator, ...

I'll explain how to do it with OpenBSD. It works on my machines since several years (since OpenBSD 3.0 following the man pages) and works also on the current machine running OpenBSD 6.0.

The tool to use is usbhidaction.

Here a picture of the keyboard I'm currently using:

USB Hid Action

Let's see how to configure and use this tool.

Detecting the keys

To detect the correct keys, I propose to use usbhidctl.

First, you have to detect on which hid device your usb keyboard is connected to. It should be uhid0, but you can verify it in dmesg

Launch usbhictl from a terminal session with the following parameters:

$ usbhidctl -f /dev/uhid0 -l

Then, hit your specific keys on your keyboard. You should see something like this:

Consumer_Control.AC_Home=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Unassigned=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Eject=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Unassigned=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Volume_Decrement=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Unassigned=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Volume_Increment=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Unassigned=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Mute=1 [0]
Consumer_Control.Unassigned=1 [1]

Consumer_Control.Unassigned=1 [0]
Consumer_Control.Unassigned=1 [1]

In my case, I have hit the keys: Home, Eject, Volume down, Volume up and Mute

Configuring UsbHidAction

Once you have identified all your keys' names, you are ready to create the ~/.usbhid.conf file.

As stated in the man pages, this file must have 3 sections all separated by space(s):

  1. Name of the USB hid item. The name is composed by 2 parts separated by a column: "Page name:item name"
  2. A numeric value. Usually 1 or "*".
  3. The action to perform.

Here after an extract of my config:

Consumer:Volume_Increment 1
   mixerctl outputs.master=+10;mpc -q -h volume +10
Consumer:Volume_Decrement 1
   mixerctl outputs.master=-10;mpc -q -h volume -10
Consumer:Mute 1
   mixerctl outputs.master.mute=toggle;mpc -q -h toggle
Consumer:Eject 1
   eject /dev/rcd0c

As you can see, in some case the "command" part is composed of 2 commands. Indeed, I'm using the "volume down" key to reduce by 10 the volume on my laptop, but also on my mpd server.
In my case, the sounds come either from my laptop, either from my mpd server (cfr the post where I'm talking about my HiFi installation ). So, this command allows me to also manage my Hifi installation running on mpd.

Running it

If you just want to test is, you can launch it from the command line:

$ usbhidaction  -c ~/.usbhid.conf -f /dev/uhid0

If you want to run it permanently, please refer to your specific window manager to add it in the list of commands you want to launch at the start of your session.

I'm using Openbox. In such case add the following line in your ~/.config/openbox/ file:

$ usbhidaction  -c ~/.usbhid.conf -f /dev/uhid0


Thanks to this standard tools in OpenBSD, you will be allowed to impress your friends with the specific keys of your USB keyboard.

17, 21
displayed: 3433

What is the first letter of the word Moon?