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>
This commit is contained in:
Tim Crawford
committed by
Jeremy Soller
Jeremy Soller
parent
dab3a24fcb
commit
5a7fd2d7b3
@@ -1,66 +1,122 @@
|
|||||||
# Keyboard layout customization
|
# Keyboard layout customization
|
||||||
|
|
||||||
## Dependencies
|
System76 EC firmware suppports using custom keyboard layouts. For example,
|
||||||
* Dependencies are listed in the README file for the EC project.
|
having the physical "Caps Lock" key function as "Escape" when pressed.
|
||||||
|
|
||||||
## Select firmware version
|
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
|
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
|
version), it's recommended to flash the same firmware version as you're
|
||||||
currently using.
|
currently using.
|
||||||
* Go to Settings -> Firmware and check the current version. It will look
|
|
||||||
something like "2020-09-17_f10af76".
|
|
||||||
* Clone the [system76/firmware-open](https://github.com/system76/firmware-open)
|
|
||||||
repository.
|
|
||||||
* Checkout the version that matches your firmware, e.g.:
|
|
||||||
`git checkout f10af76`.
|
|
||||||
* Run `git submodule init && git submodule update && cd ec`.
|
|
||||||
* This documentation is subject to change, please use the version in the
|
|
||||||
repository you just cloned.
|
|
||||||
|
|
||||||
## Adding your layout
|
Determine the BIOS version using dmidecode. The BIOS version is formatted as
|
||||||
* In `src/board/system76/{your-model}/board.mk`, locate the line starting with
|
`<date>_<revision>`.
|
||||||
`KEYBOARD=`. The value after the equal sign is your keyboard type, the most
|
|
||||||
common is `15in_102`. We will use the `lemp9` keyboard as an example, which
|
|
||||||
is `14in_83`
|
|
||||||
* In `src/board/keyboard/{keyboard-type}/keymap/`, copy `default.c` and rename
|
|
||||||
it. There are two examples to reference in the `14in_83` directory:
|
|
||||||
`jeremy.c` and `levi.c`.
|
|
||||||
* In `src/common/include/common/keymap.h` you will find a list of the key
|
|
||||||
definitions.
|
|
||||||
* You will notice two sets of keys in these layout files. The top one is the
|
|
||||||
standard mapping. The bottom one is the Fn layer, meaning it is active when
|
|
||||||
the Fn key is being held. If you look at the Fn layer in the `levi.c` layout,
|
|
||||||
you will see that there are arrow keys at WASD, media and volume keys on the
|
|
||||||
bottom row, etc.
|
|
||||||
* Hint: To avoid losing your place change one key at a time, referencing the
|
|
||||||
key code you are deleting to keep yourself positioned correctly in the list
|
|
||||||
of keycodes.
|
|
||||||
|
|
||||||
## Configure your EC to build with your layout
|
```sh
|
||||||
* Create a file in the project's root directory called `config.mk` and add your
|
sudo dmidecode -t bios | grep Version
|
||||||
board and keyboard layout to it. For example, if you want to build lemp9
|
|
||||||
firmware with Jeremy's layout (which is at
|
|
||||||
`ec/src/keyboard/14in_83/keymap/jeremy.c`):
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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
|
BOARD?=system76/lemp9
|
||||||
KEYMAP?=jeremy
|
KEYMAP?=custom
|
||||||
```
|
```
|
||||||
|
|
||||||
## Test build your EC
|
Then building the firmware only requires calling make.
|
||||||
* Make sure all dependencies are installed (see above).
|
|
||||||
* From the `ec` directory, run `make` to make sure it builds correctly.
|
|
||||||
|
|
||||||
## Flash your EC
|
```sh
|
||||||
* If the test build went well, you should be ready to flash your EC:
|
# Make will read config.mk to determine which board and keymap to use.
|
||||||
- Close all running applications.
|
make
|
||||||
- Unplug everything from your laptop except the charger.
|
```
|
||||||
- Flash with `make flash_internal`
|
|
||||||
- When it says, "Waiting 5 seconds for all keys to be released", it is
|
## Flashing the new firmware
|
||||||
important to not touch the keyboard or trackpad until it finishes writing
|
|
||||||
the new EC and turns itself off.
|
See [flashing firmware](./flashing.md) for details.
|
||||||
- Once it shuts down, you can power it back on, and your keymap will be
|
|
||||||
active.
|
```sh
|
||||||
- If you changed your layout in such a way that you can't easily type, just
|
make flash_internal
|
||||||
plug in a USB keyboard and re-flash to the default layout until you can
|
```
|
||||||
fix. The USB keyboard's layout will be unaffected.
|
|
||||||
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user