Tim Crawford 5a7fd2d7b3 docs: Rewrite the keyboard layout doc

Use of shorter sentences should reduce cognitive load. Example shell
commands should improve understanding of the description.

Signed-off-by: Tim Crawford <tcrawford@system76.com>

2021-06-08 11:23:44 -06:00

3.2 KiB

Raw Blame History

Keyboard layout customization

System76 EC firmware suppports using custom keyboard layouts. For example, having the physical "Caps Lock" key function as "Escape" when pressed.

This only applies to the internal keyboard. External keyboards are not affected.

Advanced functionality, such as macros or QMK's Mod-Tap, are not supported.

You must be able to build and flash firmware. See the README if you have not built the firmware before.

Firmware version

To ensure compatibility with other system components (e.g. your current BIOS version), it's recommended to flash the same firmware version as you're currently using.

Determine the BIOS version using dmidecode. The BIOS version is formatted as <date>_<revision>.

sudo dmidecode -t bios | grep Version

From the firmware-open repo, determine the EC commit used for the BIOS version.

git ls-tree <bios_rev> ec

Checkout that commit in the EC repo and update the submodules.

git checkout <ec_rev>
git submodule update --recursive

Adding a layout file

Determine the keyboard used for your model.

grep KEYBOARD src/board/system76/<model>/board.mk

Copy the default layout file for the keyboard to a separate file in the keymap directory.

cp src/keyboard/system76/<keyboard>/keymap/default.c src/keyboard/system76/<keyboard>/keymap/<custom>.c

The name of the keymap can be anything. Following QMK convention, the file name could be your username.

Modifying the layout

A keymap file is a C file that defines the position of key and its function. Only the LAYOUTs should be modified.

There are 2 layers in a keymap file.

KEYMAP[0]: The first LAYOUT defines the default layer
KEYMAP[1]: The second LAYOUT defines the function layer

A KT_FN key must be assigned on the first layer in order to access the second layer. The KT_FN key must be held to use keys on the second layer.

Change one key at a time to avoid losing your place.

Some related files are:

src/common/include/common/keymap.h: Defines the key scancodes
src/keyboard/system76/<keyboard>/include/board/keymap.h: Defines the keyboard matrix

Building with the new layout

Build the firmware specifying the KEYMAP you have added.

make BOARD=system76/lemp9 KEYMAP=custom

Use a config file to simplify this. In the EC project's root directory, create a file named config.mk. Define the BOARD and KEYMAP variables.

BOARD?=system76/lemp9
KEYMAP?=custom

Then building the firmware only requires calling make.

# Make will read config.mk to determine which board and keymap to use.
make

Flashing the new firmware

See flashing firmware for details.

make flash_internal

Do not use the keyboard or touchpad while it is flashing.

The system will power off as part of the flash process. Turn it back on after it has powered off.

The keyboard can now be used with your new layout.

Troubleshooting

If your layout does not work as you intended, only the internal keyboard will be affected. An external USB keyboard or SSH session can be used to correct the layout and reflash the firmware.

3.2 KiB Raw Blame History