docs/faq_keymap.md

   1 # Keymap FAQ
   2
   3 This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
   4
   5 ## What Keycodes Can I Use?
   6 See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
   7
   8 Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
   9
  10 ## What Are the Default Keycodes?
  11
  12 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
  13
  14 <!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
  15 ![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
  16
  17 ## Some Of My Keys Are Swapped Or Not Working
  18
  19 QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications.
  20
  21 As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
  22
  23 * [Bootmagic](feature_bootmagic.md)
  24 * [Command](feature_command.md)
  25
  26 ## The Menu Key Isn't Working
  27
  28 The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
  29
  30 ## `KC_SYSREQ` Isn't Working
  31 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'.
  32
  33 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
  34 * http://en.wikipedia.org/wiki/Magic_SysRq_key
  35 * http://en.wikipedia.org/wiki/System_request
  36
  37 ## Power Keys Aren't Working
  38
  39 Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
  40
  41 The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
  42
  43 ## One Shot Modifier
  44 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
  45 https://github.com/tmk/tmk_keyboard/issues/67
  46
  47 ## Modifier/Layer Stuck
  48 Modifier keys or layers can be stuck unless layer switching is configured properly.
  49 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.
  50
  51 * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
  52 * http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
  53 * https://github.com/tmk/tmk_keyboard/issues/248
  54
  55
  56 ## Mechanical Lock Switch Support
  57
  58 This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
  59
  60 ```
  61 #define LOCKING_SUPPORT_ENABLE
  62 #define LOCKING_RESYNC_ENABLE
  63 ```
  64
  65 After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
  66
  67 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 `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
  68
  69 ## Input Special Characters Other Than ASCII like Cédille 'Ç'
  70 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
  71
  72 See this post for example **MACRO** code.
  73
  74 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
  75
  76 On **Windows** you can use `AltGr` key or **Alt code**.
  77 * http://en.wikipedia.org/wiki/AltGr_key
  78 * http://en.wikipedia.org/wiki/Alt_code
  79
  80 On **Mac** OS defines `Option` key combinations.
  81 * http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
  82
  83 On **Xorg** you can use `compose` key, instead.
  84 * http://en.wikipedia.org/wiki/Compose_key
  85
  86 And see this for **Unicode** input.
  87 * http://en.wikipedia.org/wiki/Unicode_input
  88
  89 ## `Fn` Key on macOS
  90
  91 Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
  92
  93 It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
  94 Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
  95
  96 See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
  97
  98
  99 ## Media Control Keys in Mac OSX
 100 #### KC_MNXT and KC_MPRV Does Not Work on Mac
 101 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
 102 See https://github.com/tmk/tmk_keyboard/issues/195
 103
 104
 105 ## Keys Supported in Mac OSX?
 106 You can know which keycodes are supported in OSX from this source code.
 107
 108 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
 109
 110 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
 111
 112 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
 113
 114 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
 115
 116
 117 ## JIS Keys in Mac OSX
 118 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.
 119
 120 * Enable NFER Key on PC keyboard
 121 * Enable XFER Key on PC keyboard
 122 * Enable KATAKANA Key on PC keyboard
 123
 124 https://pqrs.org/osx/karabiner/seil.html
 125
 126
 127 ## RN-42 Bluetooth Doesn't Work with Karabiner
 128 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.
 129 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 130
 131 See these for the detail of this problem.
 132 https://github.com/tmk/tmk_keyboard/issues/213
 133 https://github.com/tekezo/Karabiner/issues/403
 134
 135
 136 ## Esc and <code>&#96;</code> on a Single Key
 137
 138 See the [Grave Escape](feature_grave_esc.md) feature.
 139
 140 ## Arrow on Right Modifier Keys with Dual-Role
 141 This turns right modifier 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**.
 142 ```
 143
 144 #include "keymap_common.h"
 145
 146
 147 /* Arrow keys on right modifier keys with TMK dual role feature
 148  *
 149  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 150  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 151  */
 152 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 153     /* 0: qwerty */
 154     [0] = LAYOUT( \
 155         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 156         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 157         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 158         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 159         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 160     [1] = LAYOUT( \
 161         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 162         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
 163         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
 164         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
 165         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 166 };
 167
 168 const uint16_t PROGMEM fn_actions[] = {
 169     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 170     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 171     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 172     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 173     [4] = ACTION_LAYER_MOMENTARY(1),
 174     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 175     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 176     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 177     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 178 };
 179
 180 ```
 181
 182 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 183
 184
 185 ## Eject on Mac OSX
 186 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 187 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 188
 189 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.
 190
 191
 192 ## What's `weak_mods` and `real_mods` in `action_util.c`
 193 ___TO BE IMPROVED___
 194
 195 real_mods is intended to retains state of real/physical modifier key state, while
 196 weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
 197
 198 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 199
 200 with weak_mods,
 201 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 202 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 203 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
 204 real_mods still keeps modifier state.
 205
 206 without weak mods,
 207 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 208 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 209 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 210 here real_mods lost state for 'physical left shift'.
 211
 212 weak_mods is ORed with real_mods when keyboard report is sent.
 213 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57