KMonad on Ubuntu: Programming your keyboard

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

(defcfg
  ;; 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
)
(defsrc
  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 
)

(defalias
  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.

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.

[Unit]
Description=kmonad keyboard config

[Service]
Restart=always
RestartSec=3
ExecStart=/usr/bin/kmonad /path/to/your/config/file.kbd
Nice=-20

[Install]
WantedBy=default.target

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!