Key remapping with keymapper

The keymapper daemon is a very neat utility that allows you to re-map any keys in your keyboard in all sorts of configurations.

It is similar to keyd (which I also recommend you check out if you use only Linux), but keymapper has the added benefit of working cross-platform in Linux, Windows and macOS, allowing you to share one configuration file across many systems. It also comes packed with several more features.

Installation

1. To begin, install the keymapper package:

   sudo xbps-install keymapper

2. Enable the system-wide service with:

   sudo ln -s /etc/sv/keymapperd /var/service

3. Write the following to ~/.config/keymapper.conf:

   # Holding [CapsLk], [W] [A] [S] [D] keys become [↑] [←] [↓] [→].
   [modifier="CapsLock"]
   W >> ArrowUp
   A >> ArrowLeft
   S >> ArrowDown
   D >> ArrowRight
   
   # Tapping [CapsLk] just generates [Esc].
   [default]
   CapsLock >> Escape

   The above is just example content. You can replace it with your own later.

4. Start the user-owned keymapper service:

   keymapper -u

   To do it automatically after login, see Running user scripts after login. On Sway, just use an exec.

Further configuration

You'll want to take a look at the keymapper repo, which is where all the documentation for keymapper resides.

Troubleshooting

Keymapper and PCI passthrough

If you followed my GPU passthrough in Void Linux, you may have run into an issue with keymapper intercepting input devices.

It is possible to keep keymapper running on the host and use its output as keyboard in the guest, but it requires a little bit of hacking.

1. Firstly, for this hack keymapper should only intercept one device (presumably your keyboard). You can ensure this is the case by adding the following directives to the top of your keymapper.conf:

   @skip-device-id /.*/
   @grab-device-id /<YOUR_DEVICE_NAME>/

   Replace <YOUR_DEVICE_NAME> as appropiate; you can figure it out by looking at /dev/input/by-id contents and cat'ing devices with keymapper disabled as explained in Creating the virtual machine. You don't need to write out the full name, just the identifying part is good enough.

2. You should be able to use sudo dmesg | grep "keymapper" to figure out what ID the keymapper output got assigned. Look for a message like:

   elogind-daemon[1028]: Watching system buttons on /dev/input/event20 (keymapper)

   In my case, /dev/input/event20 contains my keymapper output. If I set that as the dev of the keyboard in the VM config, I can use my keymapper-remapped keyboard in the VM without issue.

3. Because the virtual keymapper device may be assigned a different number in a future boot, it is best to determine it automatically on startup.

   Save the following script as a file somewhere:

   #!/bin/bash
   
   while true; do
       device=$(dmesg | grep -m1 -o -E '/dev/input/event[0-9]+ \(keymapper\)')
   
       if [[ -z $device ]]; then
           sleep 1
           continue
       fi
   
       device=${device::-12}
       mkdir -p /tmp/dev/input && ln -s "$device" /tmp/dev/input/keymapper
       break
   done

   This creates /tmp/dev/input/keymapper as a symlink to the actual device, so your VM can point to that instead of to /dev/input/event<N>.

   Then to have it execute on boot, append the following to /etc/rc.local, adjusting the given path as necessary:

   (bash /path/to/script >/dev/null 2>&1) &

   If everything went well, /tmp/dev/input/keymapper should be created automatically everytime you start your computer.