This utility intercepts the key events from a specific input device. LayerZ then allow you to rewrite those events on the fly and change what the rest of the OS receives as input.

I've got used to be able to program my mechanical keyboard for a few years now. And when I've to type on my laptop keyboard I also want to control exactly what happens and I want to make some keys easier to reach.

/!\ This software is still in early stage, and the user experience need to be improved.

1. Configure which device you want to intercept. This allow to eg only intercept events from your laptop keyboard and ignore external keyboards. To do that edit the KEEB variable in start.sh

2. Check the keyboard layout and potentially customize it. The layout is specified in main.zig. The default layout adds a new layer which is activated while holding the space bar. Don't hesitate to customize a bit. See below for the reference of what you can do.

3. Install Zig with a package manager This code was written with Zig 0.11.0. Alternativelly you can use devbox which is an easy to use package manager backed by Nix.

4. Identify the name of the builting keyboard. Run ls /dev/input/by-path/ to find the name of the usb devices plugged in your laptop.

5. Run sudo ./start.sh $KEEB from a terminal. This will build the utility and start intercepting the keyboard events. sudo is required for the interception. If the keyboard is not behaving as you would like close the terminal with the mouse :-)

TODO Figure out how to launch this in a daemon

The first thing to do is to build Layerz in debug mode. This will output the received events and the output. Sometimes the keyboard themselves don't send the correct input. For instance my laptop keyboard doesn't detect when "space", "capslock" and "f" are pressed at the same time.

This probably means that you can't write to this device, is it open in another terminal/process ? Run pgrep uinput.

The keyboard protocol doesn't support localized characters. Those are generated by XKB. Typically you should chose a keyboard layout that have special characters when holding "RightAlt". Then use LayerZ to yield RightAlt and the character of your choice. If you don't find a keyboard layout that has all the special characters you want, you will need to modify an exisiting one. Note that not all applications receives the special characters from XKB.

TODO: could we generate the XKB layout ourselves ?

I didn't find a good way to measure the latency, because depending on the layout, Layerz will delay some ambiguous key presses until the next key. So in this case the latency is a feature. Instead I'm measuring throughput, by piping a full list of keys event through the program. Layerz then don't need to wait for keys and we can measure the actual time per key. This include reading and writing, but that's a cost created by using Layerz. We spend about 25% of our time in the kernel mode, making syscalls to read/write events.

Features:

• k: Remap a key to another key
• Remap a key to two keys (typically shift + key)
  • s: Remap a key to a shifted key
  • ctrl: Remap a key to ctrl+key
  • altgr: Remap a key to a key + altgr. Useful for inputing localized chars.
• lt: Layer toggle
• lh: Layer hold
• xx: Disable a key
• __: Don't modify key behavior

TODO: allow to input several modifiers TODO: mod hold TODO: add combos (map a combination of keys to another) TODO: add chord (map a succession of keys to another) TODO: generate Zig doc for the DSL

I discovered those tools after I started myself, otherwise I would probably just have chose one of them, but hey, maybe it will save you some trouble:

• https://github.com/ItayGarin/ktrl
• https://github.com/kmonad/kmonad
• https://github.com/thkala/evmapd
• https://github.com/samvel1024/kbct
• https://github.com/snyball/Hawck