docs/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 You can define FC660 and Poker style ESC with `ACTION_LAYER_MODS`.
 115 https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers
 116
 117 ```
 118 #include "keymap_common.h"
 119
 120
 121 /* Leopold FC660
 122  * https://elitekeyboards.com/products.php?sub=leopold,compact&pid=fc660c
 123  * Shift + Esc = ~
 124  * Fn    + Esc = `
 125  *
 126  * Votex Poker II
 127  * https://adprice.fedorapeople.org/poker2_manual.pdf
 128  * Fn         + Esc = `
 129  * Fn + Shift + Esc = ~
 130  */
 131 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 132     /* 0: qwerty */
 133     [0] = KEYMAP( \
 134         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 135         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 136         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 137         FN0, NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,ESC, \
 138         LCTL,LGUI,LALT,          SPC,                     RALT,FN1, RGUI,RCTL),
 139     [1] = KEYMAP( \
 140         GRV, TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 141         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, \
 143         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 144         TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
 145     [2] = KEYMAP( \
 146         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 147         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 148         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,TRNS, \
 150         TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
 151 };
 152
 153 const uint16_t PROGMEM fn_actions[] = {
 154     // https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers
 155     [0] = ACTION_LAYER_MODS(1, MOD_LSFT),
 156     [1] = ACTION_LAYER_MOMENTARY(2),
 157 };
 158 ```
 159
 160 Otherwise, you can write code, see this.
 161 https://github.com/p3lim/keyboard_firmware/commit/fd799c12b69a5ab5addd1d4c03380a1b8ef8e9dc
 162
 163
 164 ## 32 Fn keys are not enough?
 165 ### actionmap
 166 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.
 167 https://github.com/tmk/tmk_keyboard/issues?utf8=%E2%9C%93&q=is%3Aissue+actionmap
 168
 169 ### extension for modified keys
 170 https://geekhack.org/index.php?topic=41989.msg1885526#msg1885526
 171
 172
 173 ## Arrow on Right Modifier keys with Dual-Role
 174 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**.
 175 ```
 176 #include "keymap_common.h"
 177
 178
 179 /* Arrow keys on right modifier keys with TMK dual role feature
 180  *
 181  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 182  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 183  */
 184 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 185     /* 0: qwerty */
 186     [0] = KEYMAP( \
 187         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 188         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 189         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 190         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 191         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 192     [1] = KEYMAP( \
 193         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 194         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 195         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,FN5, TRNS, \
 197         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 198 };
 199
 200 const uint16_t PROGMEM fn_actions[] = {
 201     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 202     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 203     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 204     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 205     [4] = ACTION_LAYER_MOMENTARY(1),
 206     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 207     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 208     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 209     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 210 };
 211
 212 ```
 213
 214
 215 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 216
 217
 218 ## Eject on Mac OSX
 219 `EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 220 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 221
 222 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.
 223
 224
 225
 226 ## What's weak_mods and real_mods in action_util.c
 227 ___TO BE IMPROVED___
 228
 229 real_mods is intended to retains state of real/physical modifier key state, while
 230 weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
 231
 232 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 233
 234 with weak_mods,
 235 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 236 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 237 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
 238 real_mods still keeps modifier state.
 239
 240 without weak mods,
 241 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 242 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 243 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 244 here real_mods lost state for 'physical left shift'.
 245
 246 weak_mods is ORed with real_mods when keyboard report is sent.
 247 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
 248
 249 ## Timer functionality
 250
 251 It's possible to start timers and read values for time-specific events - here's an example:
 252
 253 ```c
 254 static uint16_t key_timer;
 255 key_timer = timer_read();
 256
 257 if (timer_elapsed(key_timer) < 100) {
 258   // do something if less than 100ms have passed
 259 } else {
 260   // do something if 100ms or more have passed
 261 }
 262 ```
 263
 264 It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.
 265