Rename doc/ to docs/

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

docs/keyboard-layout-customization.md

@@ -0,0 +1,122 @@
+# 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.