diff options
| -rw-r--r-- | doc/keymap.md | 232 |
1 files changed, 143 insertions, 89 deletions
diff --git a/doc/keymap.md b/doc/keymap.md index 6f2a663fc8..c127db2b28 100644 --- a/doc/keymap.md +++ b/doc/keymap.md @@ -1,15 +1,30 @@ Keymap framework - how to define your keymap ============================================ -***NOTE: This is not final version, may be inconsistent with source code and changed occasionally for a while.*** +***NOTE: This is updated for QMK but this is still work in progress. This may still be inconsistent with the source code.*** + +QMK is based on TMK. Understanding the essential changes made should help you understand variable names etc. + +## TMK vs. QMK + +| Firmware |TMK |QMK | +|-------------------------------------------------|-----------------------|-------------------------| +| Maintainer |hasu |Jack Humbert et al. | +| Build path customization | `TMK_DIR = ...` | `include .../Makefile` | +| `keymaps` data | 3D array of `uint8_t` holding **keycode** | 3D array of `uint16_t` holding **action code** | +| `fn_actions` data | 1D array of `uint16_t` holding **action code** | 3D array of `uint16_t` holding **action code** | + +Since QMK is based on TMK and uses major portion of TMK code as is, understanding the essential changes made should help you understand the code. ## 0. Keymap and layers -**Keymap** is comprised of multiple layers of key layout, you can define **32 layers** at most. -**Layer** is an array of **keycodes** to define **actions** for each physical keys. -respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence. +In QMK, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** holds multiple **layers** of keymap information in **16 bit** data holding the **action code**. You can define **32 layers** at most. - Keymap: 32 Layers Layer: Keycode matrix +For trivial key definitions, the higher 8 bits of the **action code** are all 0 and the lower 8 bits holds the USB HID usage code generated by the key as **keycode**. + +Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence. + + Keymap: 32 Layers Layer: action code matrix ----------------- --------------------- - stack of layers array_of_keycode[row][column] + stack of layers array_of_action_code[row][column] ____________ precedence _______________________ / / | high / ESC / F1 / F2 / F3 .... 31 /___________// | /-----/-----/-----/----- @@ -22,11 +37,15 @@ respective layers can be validated simultaneously. Layers are indexed with 0 to 0 /___________/ V low 0 `-------------------------- +Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history. + +### 0.1 Keymap layer status +Keymap layer has its state in two 32 bit parameters: -### 0.1 Keymap status -Keymap has its state in two parameters: -**`default_layer`** indicates a base keymap layer(0-31) which is always valid and to be referred, **`keymap_stat`** is 16bit variable which has current on/off status of layers on its each bit. +* **`default_layer_state`** indicates a base keymap layer(0-31) which is always valid and to be referred. +* **`layer_state`** () has current on/off status of the layer on its each bit. +Keymap has its state in two parameter**`default_layer`** indicates a base keymap layer(0-31) which is always valid and to be referred, **`keymap_stat`** is 16bit variable which has current on/off status of layers on its each bit. Keymap layer '0' is usually `default_layer` and which is the only valid layer and other layers is initially off after boot up firmware, though, you can configured them in `config.h`. To change `default_layer` will be useful when you switch key layout completely, say you want Colmak instead of Qwerty. @@ -67,97 +86,132 @@ On the other hand, you shall change `layer_state` to overlay base layer with som ### 0.2 Layer Precedence and Transparency Note that ***higher layer has higher priority on stack of layers***, namely firmware falls down from top layer to bottom to look up keycode. Once it spots keycode other than **`KC_TRNS`**(transparent) on a layer it stops searching and lower layers aren't referred. -You can place `KC_TRNS` on overlay layer changes just part of layout to fall back on lower or base layer. -Key with `KC_TRANS` doesn't has its own keycode and refers to lower valid layers for keycode, instead. +You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer. +Key with `KC_TRANS` (`KC_TRNS` and `_______` are the alias) doesn't has its own keycode and refers to lower valid layers for keycode, instead. See example below. ### 0.3 Keymap Example -Keymap is **`keymaps[]`** C array in fact and you can define layers in it with **`KEYMAP()`** C macro and keycodes. To use complex actions you need to define `Fn` keycode in **`fn_actions[]`** array. +Keymap in this QMK is **`static const uint16_t PROGMEM keymaps[]`** C array in fact and you can define layers in it with **`KEYMAP()`** C macro and keycodes. To use complex actions you need to define `Fn` keycode in **`fn_actions[]`** array. It holds the 16 bit quantum keycode (action code). + +> Please note that keymap in the TMK, which QMK was forked from, is **`static const uint8_t PROGMEM keymaps[]`** C array which holds the 8 bit keycode (~USB HID usage code). This is a keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard. -This example has three layers, 'Qwerty' as base layer, 'Cursor' and 'Mousekey'. +This example has three layers, 'QWERTY' as base layer, 'FN' and 'MOUSE'. + In this example, - `Fn0` is a **momentary layer switching** key, you can use keys on Cursor layer while holding the key. + `MO(layer)` is a **momentary layer switching** key. - `Fn1` is a momentary layer switching key with tapping feature, you can get semicolon **';'** with taping the key and switch layers while holding the key. The word **'tap'** or **'tapping'** mean to press and release a key quickly. +You can find other keymap definitions in file `keymap.c` located on project directories. +``` +/* + * dbroqua HHKB Layout + */ +#include "hhkb.h" + +#define BASE 0 +#define FN 1 +#define MOUSE 2 + +const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + /* BASE Level: Default Layer + * ,-----------------------------------------------------------------------------------------. + * | Esc | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 | - | = | \ | ` | + * |-----------------------------------------------------------------------------------------+ + * | Tab | Q | W | E | R | T | Y | U | I | O | P | [ | ] | Bksp | + * |-----------------------------------------------------------------------------------------+ + * | Ctrl | A | S | D | F | G | H | J | K | L | ; | ' | Enter | + * |-----------------------------------------------------------------------------------------+ + * | Shift | Z | X | C | V | B | N | M | , | . | / | Shift | fn | + * +-----------------------------------------------------------------------------------------+ + * | Gui | Alt | Space | AltGr |Mouse| + * `----------------------------------------------------------------´ + */ + [BASE] = KEYMAP( + KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSLS, KC_GRV, \ + KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSPC, \ + KC_LCTL, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT, \ + KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, MO(FN), \ + KC_LGUI, KC_LALT, /* */ KC_SPC, KC_RALT, MO(MOUSE) + ), + + /* FN Layer + * ,-----------------------------------------------------------------------------------------. + * | Pwr | F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F0 | F11 | F12 | Ins | Del| + * |-----------------------------------------------------------------------------------------+ + * | Caps | | | | | | | |PrtSc| Slck| Paus| Up | | | + * |-----------------------------------------------------------------------------------------+ + * | | Vol-| Vol+| Mute| | | * | / | Home| PgUp| Left |Right| | + * |-----------------------------------------------------------------------------------------+ + * | | Prev| Play| Next| | | + | - | End |PgDwn| Down| | | + * +-----------------------------------------------------------------------------------------+ + * | | | | Stop | | + * `----------------------------------------------------------------´ + */ + [FN] = KEYMAP( + KC_PWR, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_INS, KC_DEL, \ + KC_CAPS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_PSCR, KC_SLCK, KC_PAUS, KC_UP, KC_TRNS, KC_TRNS, \ + KC_TRNS, KC_VOLD, KC_VOLU, KC_MUTE, KC_TRNS, KC_TRNS, KC_PAST, KC_PSLS, KC_HOME, KC_PGUP, KC_LEFT, KC_RGHT, KC_TRNS, \ + KC_TRNS, KC_MPRV, KC_MPLY, KC_MNXT, KC_TRNS, KC_TRNS, KC_PPLS, KC_PMNS, KC_END, KC_PGDN, KC_DOWN, KC_TRNS, KC_TRNS, \ + KC_TRNS, KC_TRNS, KC_TRNS, KC_MSTP, KC_TRNS + ), + + /* MOUSE Layer + * ,-----------------------------------------------------------------------------------------. + * | | | | | | | | | | | | | | | | + * |-----------------------------------------------------------------------------------------+ + * | | | WUp | | | | | | | | Btn1| Up | Btn2| | + * |-----------------------------------------------------------------------------------------+ + * | | WLt | WDn | WRt | | | | | | | Left |Right| | + * |-----------------------------------------------------------------------------------------+ + * | | | | | | | | | | Btn3| Down| | | + * +-----------------------------------------------------------------------------------------+ + * | | | | | | + * `----------------------------------------------------------------´ + */ + [MOUSE] = KEYMAP( + KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, \ + KC_TRNS, KC_TRNS, KC_WH_U, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_BTN1, KC_MS_U, KC_BTN2, KC_TRNS, \ + KC_TRNS, KC_WH_L, KC_WH_D, KC_WH_R, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MS_L, KC_MS_R, KC_TRNS, \ + KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_BTN3, KC_MS_D, KC_TRNS, KC_TRNS, \ + KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS + ) +}; - `Fn2` is a **toggle layer switch** key, you can stay switched layer after releasing the key unlike momentary switching. +const uint16_t PROGMEM fn_actions[] = { -You can find other keymap definitions in file `keymap.c` located on project directories. +}; - static const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - /* 0: Qwerty - * ,-----------------------------------------------------------. - * |Esc| 1| 2| 3| 4| 5| 6| 7| 8| 9| 0| -| =| \| `| - * |-----------------------------------------------------------| - * |Tab | Q| W| E| R| T| Y| U| I| O| P| [| ]|Backs| - * |-----------------------------------------------------------| - * |Contro| A| S| D| F| G| H| J| K| L|Fn1| '|Enter | - * |-----------------------------------------------------------| - * |Shift | Z| X| C| V| B| N| M| ,| .| /|Shift |Fn0| - * `-----------------------------------------------------------' - * |Gui|Alt |Space |Alt |Fn2| - * `-------------------------------------------' - */ - KEYMAP(ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, BSLS,GRV, \ - TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSPC, \ - LCTL,A, S, D, F, G, H, J, K, L, FN1, QUOT,ENT, \ - LSFT,Z, X, C, V, B, N, M, COMM,DOT, SLSH,RSFT,FN0, \ - LGUI,LALT, SPC, RALT,FN2), - /* 1: Cursor(HHKB mode) - * ,-----------------------------------------------------------. - * |Pwr| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del| - * |-----------------------------------------------------------| - * |Caps | | | | | | | |Psc|Slk|Pus|Up | |Backs| - * |-----------------------------------------------------------| - * |Contro|VoD|VoU|Mut| | | *| /|Hom|PgU|Lef|Rig|Enter | - * |-----------------------------------------------------------| - * |Shift | | | | | | +| -|End|PgD|Dow|Shift | | - * `-----------------------------------------------------------' - * |Gui |Alt |Space |Alt |Gui| - * `--------------------------------------------' - */ - KEYMAP(PWR, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, INS, DEL, \ - CAPS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,PSCR,SLCK,PAUS,UP, TRNS,BSPC, \ - LCTL,VOLD,VOLU,MUTE,TRNS,TRNS,PAST,PSLS,HOME,PGUP,LEFT,RGHT,ENT, \ - LSFT,TRNS,TRNS,TRNS,TRNS,TRNS,PPLS,PMNS,END, PGDN,DOWN,RSFT,TRNS, \ - LGUI,LALT, SPC, RALT,RGUI), - /* 2: Mousekey - * ,-----------------------------------------------------------. - * |Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del| - * |-----------------------------------------------------------| - * |Tab | | | | | |MwL|MwD|MwU|MwR| | | |Backs| - * |-----------------------------------------------------------| - * |Contro| | | | | |McL|McD|McU|McR| | |Return | - * |-----------------------------------------------------------| - * |Shift | | | | |Mb3|Mb2|Mb1|Mb4|Mb5| |Shift | | - * `-----------------------------------------------------------' - * |Gui |Alt |Mb1 |Alt | | - * `--------------------------------------------' - * Mc: Mouse Cursor / Mb: Mouse Button / Mw: Mouse Wheel - */ - KEYMAP(ESC, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, INS, DEL, \ - TAB, TRNS,TRNS,TRNS,TRNS,TRNS,WH_L,WH_D,WH_U,WH_R,TRNS,TRNS,TRNS,BSPC, \ - LCTL,TRNS,ACL0,ACL1,ACL2,TRNS,MS_L,MS_D,MS_U,MS_R,TRNS,QUOT,ENT, \ - LSFT,TRNS,TRNS,TRNS,TRNS,BTN3,BTN2,BTN1,BTN4,BTN5,SLSH,RSFT,TRNS, \ - LGUI,LALT, BTN1, RALT,TRNS), - }; +const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) +{ + // MACRODOWN only works in this function + switch(id) { + case 0: + if (record->event.pressed) { + register_code(KC_RSFT); + } else { + unregister_code(KC_RSFT); + } + break; + } + return MACRO_NONE; +}; +``` - static const uint16_t PROGMEM fn_actions[] = { - ACTION_LAYER_MOMENTARY(1), // FN0 - ACTION_LAYER_TAP_KEY(2, KC_SCLN), // FN1 - ACTION_LAYER_TOGGLE(2), // FN2 - }; +## 1. Keycode +See [`tmk_core/common/keycode.h`](../tmk_core/common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to indicate action performed on key in keymap. Keycodes are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) plus special codes in the `0xA5-DF` range. + +Keycode has `KC_` prefixed symbol respectively. Most of keycodes like `KC_A` have simple action registers key to host on press and unregister on release, while some of other keycodes has some special actions like `Fn` keys, Media control keys, System control keys and Mousekeys. +keymaps[] +In `KEYMAP()` macro, TMK recommends you to keep prefix part `KC_` of keycode to keep keymap compact. For example, just use `A` instead you place `KC_A` in `KEYMAP()`. But this doesn't apply for QMK. -## 1. Keycode -See [`common/keycode.h`](../common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to indicate action performed on key in keymap. Keycode has `KC_` prefixed symbol respectively. Most of keycodes like `KC_A` have simple action registers key to host on press and unregister on release, while some of other keycodes has some special actions like `Fn` keys, Media control keys, System control keys and Mousekeys. +The `KEYMAP()` macro defines correspondence between the physical key location to the electrical key connection. - ***In `KEYMAP()` macro you should omit prefix part `KC_` of keycode to keep keymap compact.*** For example, just use `A` instead you place `KC_A` in `KEYMAP()`. Some keycodes has 4-letter **short name** in addition to descriptive name, you'll prefer short one in `KEYMAP()`. +Some keycodes has 7-letter **short name** such as `KC_COMM` in addition to descriptive name `KC_COMMA`, you'll prefer short one in `KEYMAP()`. ### 1.0 Other key - `KC_NO` for no action @@ -192,7 +246,10 @@ There are 8 modifiers which has discrimination between left and right. - `KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation ### 1.5 Fn key -`KC_FNnn` are keycodes for `Fn` key which not given any actions at the beginning unlike most of keycodes has its own inborn action. To use these keycodes in `KEYMAP()` you need to assign action you want at first. Action of `Fn` key is defined in `fn_actions[]` and its index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` keycode indicates the action defined in first element of the array. ***32 `Fn` keys can be defined at most.*** +You don't need to use this functionality under QMK since this is a backward compatibility functionality. Unlike TMK, you can write action code itself directly in **`static const uint16_t PROGMEM keymaps[]`** C array using `MO(layer)`, etc. + +`KC_FNnn` are keycodes for `Fn` key which not given any actions at the beginning unlike most of keycodes has its own inborn action. To use these keycodes in `KEYMAP()` you need to assign action you want at first. Action of `Fn` key is defined in `fn_actions[]` and its index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` keycode indicates the action defined in first element of the array. ***Only 32 `Fn` keys can be defined at most.*** + ### 1.6 Keycode Table See keycode table in [`doc/keycode.txt`](./keycode.txt) for description of keycodes. @@ -581,15 +638,11 @@ Similar to layer tap toggle, this works as a momentary modifier when holding, bu ## 5. Legacy Keymap -This was used in prior version and still works due to legacy support code in `common/keymap.c`. Legacy keymap doesn't support many of features that new keymap offers. ***It is not recommended to use Legacy Keymap for new project.*** - -To enable Legacy Keymap support define this macro in `config.h`. - - #define USE_LEGACY_KEYMAP +In QMK, `tmk_core/common/keymap.c` is missing and its replacement `quantum/keymap_common.c` lacks Legacy Keymap support. Legacy Keymap uses two arrays `fn_layer[]` and `fn_keycode[]` to define Fn key. The index of arrays corresponds with postfix number of `Fn` key. Array `fn_layer[]` indicates destination layer to switch and `fn_keycode[]` has keycodes to send when tapping `Fn` key. -In following setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 respectively. `Fn2` registers `Space` key when tapping while `Fn0` and `Fn1` doesn't send any key. +In the following legacy keymap setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 respectively. `Fn2` registers `Space` key when tapping while `Fn0` and `Fn1` doesn't send any key. static const uint8_t PROGMEM fn_layer[] = { 1, // Fn0 @@ -603,6 +656,7 @@ In following setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 KC_SPC, // Fn2 }; +Under QMK, these can be realized using action code ACTION_LAYER_TAP_KEY(1, KC_NO), ACTION_LAYER_TAP_KEY(2, KC_NO), and ACTION_LAYER_TAP_KEY(2, KC_SPC) in the `keymaps` directly. ## 6. Terminology ***TBD*** |