Merge pull request #76 from system76/levi-keyboard-layout

Create doc explaining keyboard customization

doc/keyboard-layout-customization.md

@@ -0,0 +1,46 @@
+# Keyboard layout customization
+
+## Dependencies
+* Dependencies are listed in the README file for the EC project.
+
+## Adding your layout
+* In `src/board/system76/{your-model}/keymap/`, copy `default.c` and rename it.
+  There are two examples to reference in the `lemp9` 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
+* Create a file in the project's root directory called `config.mk` and add your
+  board and keyboard layout to it. For example, if you want to build lemp9
+  firmware with Jeremy's layout (which is at 
+  `ec/src/board/system76/lemp9/keymap/jeremy.c`):
+```
+BOARD?=system76/lemp9
+KEYMAP?=jeremy
+```
+
+## Test build your EC
+* From the `ec` directory, run `make` to make sure it builds correctly.
+
+## Flash your EC
+* If the test build went well, you should be ready to flash your EC:
+  - Close all running applications.
+  - 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
+    important to not touch the keyboard or trackpad until it finishes writing
+    the new EC and turns itself off. 
+  - Once it shuts down, you can power it back on, and your keymap will be
+    active. 
+  - If you changed your layout in such a way that you can't easily type, just
+    plug in a USB keyboard and re-flash to the default layout until you can
+    fix. The USB keyboard's layout will be unaffected.

src/board/system76/lemp9/keymap/levi.c

@@ -0,0 +1,24 @@
+// Default layout
+
+#include <board/keymap.h>
+
+uint16_t __code KEYMAP[KM_LAY][KM_OUT][KM_IN] = {
+LAYOUT(
+    K_ESC, K_F1, K_F2, K_F3, K_F4, K_F5, K_F6, K_F7, K_F8, K_F9, K_F10, K_F11, K_F12, K_HOME, K_END, K_PRINT_SCREEN, K_DEL,
+    K_TICK, K_1, K_2, K_3, K_4, K_5, K_6, K_7, K_8, K_9, K_0, K_BRACE_OPEN, K_BRACE_CLOSE, K_BKSP,
+    K_TAB, K_QUOTE, K_COMMA, K_PERIOD, K_P, K_Y, K_F, K_G, K_C, K_R, K_L, K_SLASH, K_EQUALS, K_BACKSLASH,
+    K_LEFT_CTRL, K_A, K_O, K_E, K_U, K_I, K_D, K_H, K_T, K_N, K_S, K_MINUS, K_ENTER,
+    K_LEFT_SHIFT, K_SEMICOLON, K_Q, K_J, K_K, K_X, K_B, K_M, K_W, K_V, K_Z, K_RIGHT_SHIFT,
+    KT_FN, K_Z, K_LEFT_ALT, K_LEFT_SUPER, K_SPACE, K_RIGHT_ALT, K_RIGHT_CTRL, K_PGUP, K_UP, K_PGDN,
+    K_LEFT, K_DOWN, K_RIGHT
+),
+LAYOUT(
+    K_ESC, K_TOUCHPAD, KT_SCI | SCI_DISPLAY_TOGGLE, K_MUTE, KT_SCI_EXTRA | SCI_EXTRA_KBD_BKL, K_VOLUME_DOWN, K_VOLUME_UP, K_DISPLAY_MODE, KT_SCI | SCI_BRIGHTNESS_DOWN, KT_SCI | SCI_BRIGHTNESS_UP, KT_SCI | SCI_CAMERA_TOGGLE, KT_SCI | SCI_AIRPLANE_MODE, KT_SCI | SCI_SUSPEND, K_HOME, K_END, K_PRINT_SCREEN, K_DEL,
+    K_PLAY_PAUSE, K_1, K_2, K_3, K_4, K_5, K_6, K_7, K_8, K_9, K_0, K_MINUS, K_EQUALS, K_BKSP,
+    K_TAB, K_HOME, K_UP, K_END, K_PGUP, K_Y, K_PGUP, K_HOME, K_UP, K_END, K_L, K_SLASH, K_EQUALS, K_BACKSLASH,
+    K_LEFT_CTRL, K_LEFT, K_DOWN, K_RIGHT, K_PGDN, K_I, K_PGDN, K_LEFT, K_DOWN, K_RIGHT, K_S, K_MINUS, K_ENTER,
+    K_LEFT_SHIFT, K_PLAY_PAUSE, K_MEDIA_PREV, K_MEDIA_NEXT, K_VOLUME_DOWN, K_VOLUME_UP, K_MUTE, K_M, K_W, K_V, K_Z, K_RIGHT_SHIFT,
+    KT_FN, K_Z, K_LEFT_ALT, K_LEFT_SUPER, K_SPACE, K_RIGHT_ALT, K_RIGHT_CTRL, K_PGUP, K_UP, K_PGDN,
+    K_LEFT, K_DOWN, K_RIGHT
+)
+};

src/common/include/common/keymap.h

@@ -54,6 +54,9 @@ uint16_t keymap_translate(uint16_t key);
 #define K_MUTE (K_E0 | 0x23)
 #define K_VOLUME_DOWN (K_E0 | 0x21)
 #define K_VOLUME_UP (K_E0 | 0x32)
+// More media keys
+#define K_MEDIA_NEXT (K_E0 | 0x4D)
+#define K_MEDIA_PREV (K_E0 | 0x15)
 // Custom scancode
 #define K_TOUCHPAD (K_E0 | 0x63)