KMonad on Ubuntu: Programming your keyboard

March 18, 2024

Last updated: March 18, 2024

KMonad on Ubuntu.

KMonad is a powerful and customizable keyboard manager, offering users the ability to tailor their keyboard layouts and bindings to suit their preferences. However, if you're using Ubuntu like me, there is no clear setup guide. In this guide, I will walk through the steps to get KMonad up and running on your Ubuntu system.

To begin, head over to the KMonad GitHub repository and download the kmonad executable from the Releases page. At the time of writing, the version was v0.4.2. Once downloaded, make it executable and try running it to ensure everything is working as expected.

cd ~/Downloads
chmod +x kmonad

If the executable runs without issues, you should see some output confirming its functionality.

kmonad - an onion of buttons.
Usage: kmonad FILE [-d|--dry-run] [-l|--log-level Log level]

Next, let's create a configuration file for KMonad. You can use the following sample config or customize it according to your preferences.

;; For Linux
input (device-file "/dev/input/by-path/platform-i8042-serio-0-event-kbd")
output (uinput-sink "My KMonad output"
;; To understand the importance of the following line, see the section on
;; Compose-key sequences at the near-bottom of this file.
"/run/current-system/sw/bin/sleep 1 && /run/current-system/sw/bin/setxkbmap -option compose:ralt")
;; cmp-seq ralt ;; Set the compose key to `RightAlt'
;; cmp-seq-delay 5 ;; 5ms delay between each compose-key sequence press
;; For Windows
;; input (low-level-hook)
;; output (send-event-sink)
;; For MacOS
;; input (iokit-name "my-keyboard-product-string")
;; output (kext)
;; Comment this if you want unhandled events not to be emitted
fallthrough true
;; Set this to false to disable any command-execution in KMonad
allow-cmd true
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft up
lctl lmet lalt spc ralt rmet rctl left down rght
;; (deflayer empty
;; _ _ _ _ _ _ _ _ _ _ _ _ _
;; _ _ _ _ _ _ _ _ _ _ _ _ _ _
;; _ _ _ _ _ _ _ _ _ _ _ _ _ _
;; _ _ _ _ _ _ _ _ _ _ _ _ _
;; _ _ _ _ _ _ _ _ _ _ _ _ _
;; _ _ _ _ _ _ _ _ _ _
;; )
(deflayer qwerty
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft up
lctl lmet lalt spc @nav rmet rctl left down rght
nav (layer-toggle navigation)
(deflayer navigation
_ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ pgup up del _ _ _ _
_ _ _ _ _ _ home left down rght end _ _
_ _ _ _ _ _ bspc pgdn _ _ _ _ _
_ _ _ _ _ _ _ _ _ _

This configuration adds an extra layer that can be activated by pressing AltGr (the alt button to the right of the space bar). Make sure to specify the correct input device in the configuration file by changing the line

+ input (device-file "/dev/input/by-path/platform-i8042-serio-0-event-kbd")

To specify the correct input device for your keyboard configuration in KMonad, it's crucial to identify the appropriate /dev/input device file. While this may seem daunting at first, there are helpful methods to determine the right device.

By far, the most reliable method is to utilize the keyboard devices listed under /dev/input/by-id. These devices are typically named in a way that makes it easier to identify your specific keyboard.

Alternatively, you can explore the devices listed under /dev/input/by-path. While not as precise as /by-id, it can still provide useful insights into the connected input devices.

If you're still uncertain about which device file corresponds to your keyboard, the evtest program can be immensely helpful. This utility allows you to interactively test and identify input devices.

By employing these methods, you can confidently determine the correct /dev/input device for your keyboard configuration in KMonad, ensuring seamless integration with your desired layout and bindings.

When your configuration file is ready, run a dry-run to check for any parsing errors.

./kmonad ./kmonad-keyboard-config.kbd -d

If no errors are logged, proceed to run KMonad with the configuration file.

sudo ./kmonad ./kmonad-keyboard-config.kbd

You should now be able to use your customized keyboard configuration. In the case for the above configuration file, press and hold the AltGr key to activate the navigation layer. You should now be able to navigate using the i, j, k, and l keys as arrow keys.

To ensure KMonad starts automatically and runs in the background, we'll set it up as a service. Begin by moving the kmonad executable to /usr/bin/kmonad.

sudo cp ./kmonad /usr/bin/kmonad

Next, create a service file for KMonad in /etc/systemd/system/kmonad.service with appropriate configurations. Customize the ExecStart line to point to your desired configuration file.

Description=kmonad keyboard config
ExecStart=/usr/bin/kmonad /path/to/your/config/file.kbd

Finally, start and enable the service to ensure KMonad runs on system startup.

sudo systemctl start kmonad.service
sudo systemctl enable kmonad.service

KMonad is now set up on your Ubuntu system and ready for you to unleash its full potential in customizing your keyboard experience.

If you have multiple keyboards connected to your system, such as a laptop with an integrated keyboard along with an external one, you may want to customize the configuration for each keyboard separately. In such cases, you can generate multiple service configurations, each tailored to a specific keyboard.

To achieve this, you'll need to create separate configuration files for each keyboard layout. Then, create individual service files for each configuration, ensuring that KMonad is started twice with the appropriate config file for each keyboard.

For example, if you have a laptop with an integrated keyboard and a USB keyboard attached, you would create two service files, each specifying the corresponding configuration file. Ensure that the ExecStart line in each service file points to the correct configuration file for the respective keyboard.

By setting up KMonad in this manner, you can fully customize the keyboard layouts and bindings for each connected keyboard, providing a tailored typing experience for every device.

That's it! You should now have KMonad installed and running smoothly on your Ubuntu machine, allowing you to take full control of your keyboard layout and bindings. If you encounter any issues or have further questions, don't hesitate to consult the KMonad documentation or leave a comment. Happy typing!