FAQ-Keymap.md

   1 ## READ FIRST
   2 https://github.com/tmk/tmk_core/blob/master/doc/keymap.md
   3
   4 ## How to get keycode
   5 See [Keycodes](Keycodes). Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
   6
   7 ## Sysrq key
   8 Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
   9
  10 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
  11 - http://en.wikipedia.org/wiki/Magic_SysRq_key
  12 - http://en.wikipedia.org/wiki/System_request
  13
  14 ## Power key doesn't work
  15 Use `KC_PWR` instead of `KC_POWER` or vice versa.
  16 - `KC_PWR` works with Windows and Linux, not with OSX.
  17 - `KC_POWER` works with OSX and Linux, not with Windows.
  18
  19 http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
  20
  21 ## Oneshot modifier
  22 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  Oneshot Shift mitgates this for me.
  23 https://github.com/tmk/tmk_keyboard/issues/67
  24
  25 ## Modifier/Layer stuck
  26 Modifier keys or layers can be stuck unless layer switching is configured properly.
  27 For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to  unregister the modifier key or return to previous layer on release event.
  28
  29 - https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
  30 - http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
  31 - https://github.com/tmk/tmk_keyboard/issues/248
  32
  33
  34 ## Mechanical Lock Switch Support
  35 https://github.com/tmk/tmk_keyboard#mechanical-locking-support
  36
  37 This feature is for *mechanical lock switch* like this Alps one.
  38 http://deskthority.net/wiki/Alps_SKCL_Lock
  39
  40 Using enabling this feature and using keycodes `LCAP`, `LNUM` or `LSCR` in keymap you can use physical locking CapsLock, NumLock or ScrollLock keys as you expected.
  41
  42 Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `CAPS`, `NLCK` and `SLCK`.***
  43
  44
  45 ## Input special charactors other than ASCII like Cédille 'Ç'
  46 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
  47
  48 See this post for example **MACRO** code.
  49
  50 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
  51
  52 On **Windows** you can use `AltGr` key or **Alt code**.
  53 - http://en.wikipedia.org/wiki/AltGr_key
  54 - http://en.wikipedia.org/wiki/Alt_code
  55
  56 On **Mac** OS defines `Option` key combinations.
  57 - http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
  58
  59 On **Xorg** you can use `compose` key, instead.
  60 - http://en.wikipedia.org/wiki/Compose_key
  61
  62 And see this for **Unicode** input.
  63 - http://en.wikipedia.org/wiki/Unicode_input
  64
  65
  66 ## Apple/Mac keyboard Fn
  67 Not supported.
  68
  69 Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
  70 I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
  71
  72 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
  73
  74
  75 ## Media control keys in Mac OSX
  76 #### KC_MNXT and KC_MPRV does not work on Mac
  77 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
  78 See https://github.com/tmk/tmk_keyboard/issues/195
  79
  80
  81 ## Keys supported in Mac OSX?
  82 You can know which keycodes are supported in OSX from this source code.
  83
  84 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
  85
  86 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
  87
  88 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
  89
  90 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
  91
  92
  93 ## JIS keys in Mac OSX
  94 Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
  95
  96 * Enable NFER Key on PC keyboard
  97 * Enable XFER Key on PC keyboard
  98 * Enable KATAKANA Key on PC keyboard
  99
 100 https://pqrs.org/osx/karabiner/seil.html
 101
 102
 103 ## RN-42 Bluetooth doesn't work with Karabiner
 104 Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
 105 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 106
 107 See these for the deail of this problem.
 108 https://github.com/tmk/tmk_keyboard/issues/213
 109 https://github.com/tekezo/Karabiner/issues/403
 110
 111
 112 ## Esc and `~ on a key
 113
 114
 115 You can define FC660 and Poker style ESC with `ACTION_LAYER_MODS`.
 116 https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers
 117
 118 ```
 119 #include "keymap_common.h"
 120
 121
 122 /* Leopold FC660
 123  * https://elitekeyboards.com/products.php?sub=leopold,compact&pid=fc660c
 124  * Shift + Esc = ~
 125  * Fn    + Esc = `
 126  *
 127  * Votex Poker II
 128  * https://adprice.fedorapeople.org/poker2_manual.pdf
 129  * Fn         + Esc = `
 130  * Fn + Shift + Esc = ~
 131  */
 132 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 133     /* 0: qwerty */
 134     [0] = KEYMAP( \
 135         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 136         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 137         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 138         FN0, NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,ESC, \
 139         LCTL,LGUI,LALT,          SPC,                     RALT,FN1, RGUI,RCTL),
 140     [1] = KEYMAP( \
 141         GRV, TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 142         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 143         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 144         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 145         TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
 146     [2] = KEYMAP( \
 147         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 148         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 149         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 150         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 151         TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
 152 };
 153
 154 const uint16_t PROGMEM fn_actions[] = {
 155     // https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers
 156     [0] = ACTION_LAYER_MODS(1, MOD_LSFT),
 157     [1] = ACTION_LAYER_MOMENTARY(2),
 158 };
 159 ```
 160
 161 Otherwise, you can write code, see this.
 162 https://github.com/p3lim/keyboard_firmware/commit/fd799c12b69a5ab5addd1d4c03380a1b8ef8e9dc
 163
 164
 165 ## 32 Fn keys are not enough?
 166 ### actionmap
 167 It uses 16 bit codes and has no limitation of 32 Fn at the expense of memory space. TMK keymap is actually is 8 bit codes as subset of the actionmap.
 168 https://github.com/tmk/tmk_keyboard/issues?utf8=%E2%9C%93&q=is%3Aissue+actionmap
 169
 170 ### extension for modified keys
 171 https://geekhack.org/index.php?topic=41989.msg1885526#msg1885526
 172
 173
 174 ## Arrow on Right Modifier keys with Dual-Role
 175 This turns right modifer keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
 176 ```
 177 #include "keymap_common.h"
 178
 179
 180 /* Arrow keys on right modifier keys with TMK dual role feature
 181  *
 182  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 183  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 184  */
 185 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 186     /* 0: qwerty */
 187     [0] = KEYMAP( \
 188         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 189         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 190         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 191         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 192         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 193     [1] = KEYMAP( \
 194         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 195         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 196         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 197         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
 198         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 199 };
 200
 201 const uint16_t PROGMEM fn_actions[] = {
 202     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 203     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 204     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 205     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 206     [4] = ACTION_LAYER_MOMENTARY(1),
 207     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 208     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 209     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 210     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 211 };
 212
 213 ```
 214
 215
 216 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 217
 218
 219 ## Eject on Mac OSX
 220 `EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 221 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 222
 223 Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
 224
 225
 226
 227 ## What's weak_mods and real_mods in action_util.c
 228 ___TO BE IMPROVED___
 229
 230 real_mods is intended to retains state of real/physical modifier key state, while
 231 weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
 232
 233 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 234
 235 with weak_mods,
 236 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 237 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 238 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
 239 real_mods still keeps modifier state.
 240
 241 without weak mods,
 242 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 243 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 244 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 245 here real_mods lost state for 'physical left shift'.
 246
 247 weak_mods is ORed with real_mods when keyboard report is sent.
 248 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57