Customizing keyboard layout - junaruga/framework-laptop-config GitHub Wiki

Customizing the keyboard layout by changing key bindings is very fun. I hope this document helps you to start your journey of pursuing your most comfortable and effective keyboard layout through the activity.

I enjoyed the keyboard layout customizing by ZSA's Moonlander. Moonlander and ZSA's keyboards provide keyboard layout customization by QMK at the firmware level. Initially, I was using the full keys on Moonlander. Then I started to reduce the unused keys. And here is my 34 keys keyboard layout on Moonlander. Note I am not actively using Moonlander now.

Framework Laptop 16 supporting QMK has not been shipped yet, and Framework Laptop 13 doesn't support QMK. However, I also enjoyed the keyboard layout customization at the software level on Framework Laptop 13. My favorite keyboard layout was affected by my experience in Moonlander.

Customizing the keyboard layout at the software level on Framework Laptop 13 is still very fun, and makes me happy. So, on this page, I want to tell you how to do it. I want you to experience it.

The content is with Sway window manager as a basic customizing and Mouseless as an advanced customizing, because I am using these applications. However, you can apply the idea to other applications.

The idea is a keyboard layout filling the following 2 requirements.

1. Being comfortable when using the full keys on Framework Laptop 13. It's possible by using Sway.
2. Being comfortable when using only the following 33 keys. It's possible by using Mouseless.

When thinking about how to minimize moving fingers for the best accessibility, comfortability, and effectiveness, I am trying to use only the following 33 keys on the keyboard on my Framework Laptop 13. There are 34 keys layout such as Ferris Sweep, 32, 30 keys layout such as this, 18 keys layout such as Nine Keyboard. So, only using 33 keys is realistic.

q w e r t     y u i o p
a s d f g     h j k l ;
z x c v b     n m , . /
    lalt space ralt

As you may know, Sway is a Wayland-based tiling window manager. Here I will explain how to customize the keyboard layout by the input configuration, and sway's mode (keyboard layer) in your sway config file.

• ~/.config/sway/config: sway config (common)
• ~/.config/sway/confid.d/00-framwork: sway config (Framework Laptop 13 specific)
• ~/.config/xkb/rules/evdev: A keyboard input configuration called in Sway config.
• ~/.config/xkb/symbols/custom: A keyboard input configuration for key bindings called in Sway config.

Below is the part of my keyboard customizing in the Sway config file. I customize the keyboard layout only by xkb_options "custom:basic" because of the easiness and visibility. The xkb custom config file is here.

~/.config/sway/config

...
input type:keyboard {
    xkb_layout us
    # See the following xkb config files.
    # ~/.config/xkb/rules/evdev
    # ~/.config/xkb/symbols/custom
    xkb_options "custom:basic"
}
...

You may find how to write by checking man 5 sway-input, sway wiki keyboard layout, or the /usr/share/X11/xkb/symbols/* files. My best setting to make me happy and comfortable is the following setting that is to assign the left alt key as the left super (Windows) key. because I often use the super (Windows) key on Sway.

~/.config/xkb/symbols/custom

# Left Alt as Left Super key.
key <LALT> { type[Group1] = "ONE_LEVEL", [ Super_L ] };

As an alternative way, you may just set up the altwin:swap_lalt_lwin to swap the left super (windows) key with the left alt key.

~/.config/sway/config

xkb_options "altwin:swap_lalt_lwin,custom:basic"

Sway has a keyboard layout layer called "mode". My config file has "default", "resize", "symbol", and "media" modes. I am not setting the mode for function keys such as F1, F2, etc, because I am not using the keys in my use case.

• default: The default keyboard layer.
• resize: The layer to resize window size.
• symbol: The layer to type symbol and number keys.
• media: The layer to type media keys.

Mouseless emulates the mouse or touchpad experience by the keyboard. It also has a feature to customize the keyboard layout with keyboard layers and key bindings. In my experience, the mouse emulation is smooth like QMK's mouse emulation.

• ~/.config/mouseless/example.yaml: An example config file that may be good for you to try at first.
• ~/.config/mouseless/config.yaml: The config file which I am using.

You can build and run by user privileges.

You may install the Go programming language. In Fedora, you can check this document to install and set up Go language.

You need to run Mouseless as a daemon (service) process. I am installing and running Mouseless by user privileges because it's safer as Mouseless overrides the key bindings.

You can check the README on my forked repository, until my pull-request will be merged to the original repository.

You can check the help.

$ mouseless --help

As the default config file path is ~/.config/mouseless/config.yaml according to this code, if you create the file on the file path, you can run mouseless without --config option.

During customizing your config file,

You can edit the config file with your editor on one terminal.

$ vi ~/.config/mouseless/config.yaml

Then you can open another terminal, and run the following command to verify the config file. And you can type Ctrl+C to stop the process.

$ mouseless --debug

After verifying the config file, you can run Mouseless as a Systemd user service. Check the Mouseless README.md above.

First, you can try, and learn how to customize by running the example.yaml without using Systemd first. Don't worry. It's a small config file that doesn't affect your current keyboard layout much.

$ mouseless --config ~/.config/mouseless/example.yaml --debug

Below is the example.yaml file.

example.yaml

# The keyboard devices it reads from, if no devices are specified, it reads
# from all.
devices:

layers:
- name: base
  bindings:
    # The best way for hodling keys is
    # `a_key: tap-hold-next-release a_key ; something ; 0`.
    # https://github.com/jbensmann/mouseless/issues/40
    space: tap-hold-next-release space ; toggle-layer control ; 0
    z: tap-hold-next-release z ; leftctrl ; 0
    slash: tap-hold-next-release slash ; rightctrl ; 0

- name: control
  passThrough: true
  bindings:
    h: backspace
    j: enter

The file is small, but it includes the key points to set up the file, and my favorite settings.

The first layer "base" means the based keyboard layer.

The space key is one of the most accessible keys. The setting is to use the space key as a modifier. By only holding the space key, you can access the "control" layer. So, you can type backspace by holding the space key and tapping the "h" key. You can type enter by holding the space key and tapping the "j" key.

You can also type ctrl when holding z or slash keys.

As a tip of the setting, the setting syntax a_key: tap-hold-next-release a_key ; something ; 0 is the most effective and safe to avoid typing unintentional keys in the case of holding a key.

The tap-hold-next-release space ; toggle-layer control ; 0 will type backspace when typing space down, h down, h up, space up, but will type space + h when typing space down, h down, space up, h up. And when holding space with space down, space up for a long time, still just type space.

I would explain my mouseless config, ~/.config/mouseless/config.yaml based on the content of the file on the commit b42c26883bb69b0661f4d93d6ed8a2cab688ad9c on this repository. It's possible to use only the 33 keys explained above with this config file.

The config has the following keyboard layers.

• base: The default keyboard layer.
• control: The layer to access by holding the space key. The enter, backspace, tab, escape keys + the keys to move to another layer. For example, holding space + k changes the current layer to the mouse layer.
• mouse: The layer to use the mouse emulation + shortcuts for the Firefox browser.
• nav: The layer to do something arrow keys.
• symbol: The layer to type symbol and number keys.
• symbol-shift: The layer to type symbol and number keys by holding shift on the symbol layer.

I can change the keyboard layer by holding the space key + typing something on the base layer. I can go back to the base layer by typing the left alt key in other layers.

The customizing keyboard layout is still very fun at the software level. My favorite key bindings are

• Use the left alt key as the left super (windows) key by Sway input configuration.
• Use the space key as a modifier key on holding by Mouseless.

That's all. I hope you enjoy it.