Merge pull request #1184 from osamuaoki/master

Update keymap.md to QMK

1 files changed, 143 insertions, 89 deletions

diff --git a/doc/keymap.md b/doc/keymap.md
index 2b0d2cd959..bc7809905a 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.
@@ -584,15 +641,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
@@ -606,6 +659,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***