kmonad/doc/faq.md at master

Table of Contents

Linux

Q: How do I get Uinput permissions?

A: In Linux KMonad needs to be able to access the input and uinput subsystem to inject events. To do this, your user needs to have permissions. To achieve this, take the following steps:

If the uinput group does not exist, create a new group with:

Make sure the uinput group exists

sudo groupadd --system uinput

Add your user to the input and the uinput group:

sudo usermod -aG input,uinput username

Make sure that it's effective by running groups. You might have to logout and login. In some cases a reboot may also be required.

Make sure the uinput device file has the right permissions: Add a udev rule (in either /etc/udev/rules.d or /lib/udev/rules.d) with the following content:

KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"

You will need to restart udevd via

sudo systemctl restart systemd-udevd.service

to get the new permissions.

Make sure the uinput drivers are loaded. You will probably have to run this command whenever you start kmonad for the first time.

Q: How do I know which event-file corresponds to my keyboard?

A: By far the best solution is to use the keyboard devices listed under /dev/input/by-id. In some case, you could also try /dev/input/by-path. If you can't figure out which file just by the filenames, the evtest program is very helpful.

Q: `/dev/input` does not exist?

A: This may be due to the kernel module evdev not being loaded. Try to run sudo modprobe evdev.

Q: How do I emit Hyper_L?

A: Hyper_L is not a core Linux keycode, but is X11 specific instead. KMonad tries to stay as close to the kernel as possible, so you can run it on other OSes or without X11. If you want Hyper_L to work, you have to make sure that X11 lines up well with KMonad. See this issue for more explanation.

Q: How does Unicode entry work?

A: Unicode entry works via X11 compose-key sequences. For information on how to configure KMonad to make use of this, please see the tutorial.

Q: How do I use the same layout definition for different keyboards?

A: Create a layout file with an environment variable instead of device-file option, i.e. kmonad.kbd.

(defcfg
    input (device-file "$KBD_DEV")
    output (uinput-sink "KMonad kbd")
    fallthrough true
    cmp-seq lctl
)

Use following shell script to list available keyboard devices and select one of them. You will need fzf and kmonad available in your $PATH.

#!/bin/bash

KBD_DEV=$(find /dev/input/by-path/*kbd* | fzf)
export KBD_DEV
KBDCFG=$(envsubst < kmonad.kbd)

kmonad <(echo "$KBDCFG")

Windows

Q: How do I start KMonad?

A: This might be confusing if you are used to using a GUI and clicking on things. Double clicking KMonad will look like it does nothing. KMonad is a command-line utility, so, to run it you need to:

Using the command-line

Start a 'Command Prompt' (no need for 'as administrator')
'cd' to where you've stored KMonad, like this:

cd "C:\Users\david\Desktop\Just an Example"

NOTE: The double-tick marks around the path let you easily use directories with spaces in the names.

Run the kmonad command (make sure the name matches exactly, so for the 0.4.0 version, that would be: kmonad-0.4.0-windows.exe, alternatively, rename the kmonad file to whatever you like and use that name). Depending on how you call it different things happen.

This will print the help and do nothing.

This will start KMonad with the provided configuration file:

If the my_config.cfg file is not in the same directory as kmonad, you will need to specify the full path to this file. (See the tutorial for more information on how to write a configuration.

kmonad.exe C:\Users\david\Documents\my_config.kbd

You can even launch KMonad from anywhere (without having to do step 2. first) if you use the full path for KMonad and the config file like this:

"C:\Users\david\Desktop\Just an Example\kmonad.exe" C:\Users\david\Documents\my_config.kbd

If you want to really see what is happening on the inside of KMonad as it runs, consider adding the --log-level debug flag like this:

C:\pth\to\kmonad.exe some_config.kbd --log-level debug

This will cause KMonad to print out more information about what it is doing moment to moment (without affecting anything else).

Making a launcher

If you want to start KMonad at the click of a button, consider making a shortcut using the 'New' > 'Shortcut' entry on the right-click menu (if you right-click the Desktop). Just select 'KMonad' and give it a name. Afterwards, right click the shortcut and select 'Properties'. This should put you in the 'Shortcut' tab of the properties, here there is a field called 'Target'. This field is exactly like the shell command we used above, so copy-paste the exact command you used to start KMonad into 'Target', then click apply, and you should now have a clickable KMonad launcher.

Mac

Q: How to use the special features printed on Apple function keys?

A: By default, function keys on Apple keyboards trigger special features (changing brightness, volume, etc.) when pressed alone, and act as traditional function keys (F1, F2, etc.) when pressed with fn. Technically, when F1 (e.g.) is pressed on an Apple keyboard, it sends the keycode corresponding to F1; macOS then translates this keycode to a special feature (depending on whether fn was pressed) in the keyboard driver. But kmonad intercepts key presses before this translation can occur, and it emits keypresses through a driver of its own. Therefore macOS does not translate any keypresses emitted by KMonad, and the checkbox labeled "Use F1, F2, etc. keys as standard function keys" in System Preferences will have no effect on keyboards modified by KMonad.

However, we can simulate the default behavior of Apple keyboards by emitting keycodes that correspond to the special features printed on the function keys. See keymap/template/apple.kbd for an example.

General

Q: Why can't I remap certain (non US) buttons?

KMonad works prior to your OS keymapping taking affect. It also uses the names taken from the standard US qwerty layout.

If you were for example looking to remap an ü on a german qwertz keyboard you would specify the letter that would be there in qwerty ([).

This is of course also true for buttons which are in a different place. On the german layout the + is reached without shift, while on US qwerty it's on S-=. This means it's also not a valid keycode to specify in your defsrc.

Q: How can I remap the Copilot key / other hardware macro keys?

By mapping the corresponding primary key (e.g. f23) and optionally dropping modifiers with (tap-hold-next 1 XX XX :timeout ...).

For a detailed explanation, see Hardware Macro Keys.

Q: Why don't shifted symbols work (sometimes)?

A: In some environments, applications cannot process key events that are too fast. If you notice this with tap-macro or shifted symbols (like A) you may want to increase the value for key-seq-delay in defcfg to something like 5ms. Here is the original bug report.

Q: What does `Ta`, `Pa` and `Ra` stand for?

A: Those are part of a mini-language from the tutorial:

Px signifies the press of the button (or keycode) x
Rx signifies the release of x
Tx signifies the sequential and near instantaneous press and release of x
100 signifies 100ms passing without any action

So for example when talking about buttons:

Tesc Pa is a tap of Esc and a press of a
P@a Tb R@a is the alias @a pressed around the button b

This language is useful since "tap" is normally a synonym for "press" and this may lead to confusion in discussions and issues.

Q: Why doesn't the 'Print' keycode work for my print screen button?

A: Because the keycode for "print screen" is actually 'SysReq' ("ssrq" or "sys") for relatively interesting historical reasons. Have a look at this issue if you want more information.

Q: Why can't I remap the Fn key on my laptop?

A: You cannot. Many laptops have a Fn key that mimics some of the functionality that KMonad tries to offer: it changes the mapping of certain keys, like creating a numpad in the middle of the laptop keyboard. This remapping happens in the hardware, before any event is ever registered with the operating system, therefore KMonad has no way to 'get' at any of those events. This means that we cannot remap them in any way.

Q: Why do some key combination not work?

A: Some keyboards have a low rollover. It is the lowest maximum number of keys which can be pressed together and handled correctly. Most keyboards then have to resort to blocking. So If you have buttons which work fine individually but some special combination does not, check whether you are affected by it. To do this you can use an online rollover test. For correct results it is recommended to turn off KMonad (Also note that some keys cannot be captured by a website). Another option is to try a different keyboard. The only other fix is circumvention.

Q: When I run KMonad I get error `Not available under this OS`

A: This error occurs when there are OS-specific options in the used configuration file. Usually this happens when you are on windows, try to run the tutorial file and do not comment out or delete the Linux options in defcfg and uncomment the Windows options. Nevertheless, this still can happen on other operating systems, the error message changes slightly based on the operating system (e.g. Not available under this OS: LowLevelHookSource, Not available under this OS: DeviceSource), but they all start with Not available under this OS and all have the same solution.

TL;DR: Make sure the options in defcfg are for your operating system.

Q: Where can I find a list of keycodes which can be used in KMonad?

A: List of keycodes can be found here.

Q: How do I provide the input and output from the command line?

A: The input / output can be assigned via the --input / --output (or the short style -i / -o) options to override the value in the .kbd config file. These options take exactly the same assignment as the input / output statement in the defcfg block. For example, if we have this line in our .kbd config file:

  input  (device-file "/dev/input/by-id/my-kbd")

We may instead call KMonad using:

kmonad --input 'device-file "/dev/input/by-id/my-kbd"' my-kbd.kbd

Notice that single quotes are used to pack the device-file and the path into one string, and also note that the path needs to be wrapped with double quotes. If your shell does not support single quotes, you can also escape the double quotes.

kmonad --input "device-file \"/dev/input/by-id/my-kbd\"" my-kbd.kbd