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