5a7fd2d7b3
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>
123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
# 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](../README.md)
|
|
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>`.
|
|
|
|
```sh
|
|
sudo dmidecode -t bios | grep Version
|
|
```
|
|
|
|
From the [firmware-open](https://github.com/system76/firmware-open) repo,
|
|
determine the EC commit used for the BIOS version.
|
|
|
|
```sh
|
|
git ls-tree <bios_rev> ec
|
|
```
|
|
|
|
Checkout that commit in the EC repo and update the submodules.
|
|
|
|
```sh
|
|
git checkout <ec_rev>
|
|
git submodule update --recursive
|
|
```
|
|
|
|
## Adding a layout file
|
|
|
|
Determine the keyboard used for your model.
|
|
|
|
```sh
|
|
grep KEYBOARD src/board/system76/<model>/board.mk
|
|
```
|
|
|
|
Copy the default layout file for the keyboard to a separate file in the keymap
|
|
directory.
|
|
|
|
```sh
|
|
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 `LAYOUT`s 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.
|
|
|
|
```sh
|
|
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.
|
|
|
|
```mk
|
|
BOARD?=system76/lemp9
|
|
KEYMAP?=custom
|
|
```
|
|
|
|
Then building the firmware only requires calling make.
|
|
|
|
```sh
|
|
# Make will read config.mk to determine which board and keymap to use.
|
|
make
|
|
```
|
|
|
|
## Flashing the new firmware
|
|
|
|
See [flashing firmware](./flashing.md) for details.
|
|
|
|
```sh
|
|
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.
|