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/9ce023dc6caadc0cf11c88c782350a8c -->
  15 ![Keyboard Layout Image](https://i.imgur.com/45m4mRf.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 Key Doesn't Work
  38 Use `KC_PWR` instead of `KC_POWER` or vice versa.
  39 * `KC_PWR` works with Windows and Linux, not with OSX.
  40 * `KC_POWER` works with OSX and Linux, not with Windows.
  41
  42 More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
  43
  44 ## One Shot Modifier
  45 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
  46 https://github.com/tmk/tmk_keyboard/issues/67
  47
  48 ## Modifier/Layer Stuck
  49 Modifier keys or layers can be stuck unless layer switching is configured properly.
  50 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.
  51
  52 * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
  53 * http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
  54 * https://github.com/tmk/tmk_keyboard/issues/248
  55
  56
  57 ## Mechanical Lock Switch Support
  58
  59 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`:
  60
  61 ```
  62 #define LOCKING_SUPPORT_ENABLE
  63 #define LOCKING_RESYNC_ENABLE
  64 ```
  65
  66 After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
  67
  68 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`.***
  69
  70 ## Input Special Characters Other Than ASCII like Cédille 'Ç'
  71 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
  72
  73 See this post for example **MACRO** code.
  74
  75 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
  76
  77 On **Windows** you can use `AltGr` key or **Alt code**.
  78 * http://en.wikipedia.org/wiki/AltGr_key
  79 * http://en.wikipedia.org/wiki/Alt_code
  80
  81 On **Mac** OS defines `Option` key combinations.
  82 * http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
  83
  84 On **Xorg** you can use `compose` key, instead.
  85 * http://en.wikipedia.org/wiki/Compose_key
  86
  87 And see this for **Unicode** input.
  88 * http://en.wikipedia.org/wiki/Unicode_input
  89
  90
  91 ## Apple/Mac Keyboard `Fn`
  92 Not supported.
  93
  94 Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
  95 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.
  96
  97 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
  98
  99
 100 ## Media Control Keys in Mac OSX
 101 #### KC_MNXT and KC_MPRV Does Not Work on Mac
 102 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
 103 See https://github.com/tmk/tmk_keyboard/issues/195
 104
 105
 106 ## Keys Supported in Mac OSX?
 107 You can know which keycodes are supported in OSX from this source code.
 108
 109 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
 110
 111 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
 112
 113 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
 114
 115 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
 116
 117
 118 ## JIS Keys in Mac OSX
 119 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.
 120
 121 * Enable NFER Key on PC keyboard
 122 * Enable XFER Key on PC keyboard
 123 * Enable KATAKANA Key on PC keyboard
 124
 125 https://pqrs.org/osx/karabiner/seil.html
 126
 127
 128 ## RN-42 Bluetooth Doesn't Work with Karabiner
 129 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.
 130 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 131
 132 See these for the detail of this problem.
 133 https://github.com/tmk/tmk_keyboard/issues/213
 134 https://github.com/tekezo/Karabiner/issues/403
 135
 136
 137 ## Esc and <code>&#96;</code> on a Single Key
 138
 139 See the [Grave Escape](feature_grave_esc.md) feature.
 140
 141 ## Arrow on Right Modifier Keys with Dual-Role
 142 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**.
 143 ```
 144
 145 #include "keymap_common.h"
 146
 147
 148 /* Arrow keys on right modifier keys with TMK dual role feature
 149  *
 150  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 151  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 152  */
 153 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 154     /* 0: qwerty */
 155     [0] = KEYMAP( \
 156         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 157         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 158         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 159         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 160         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 161     [1] = KEYMAP( \
 162         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
 163         TRNS,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,TRNS, \
 165         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
 166         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 167 };
 168
 169 const uint16_t PROGMEM fn_actions[] = {
 170     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 171     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 172     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 173     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 174     [4] = ACTION_LAYER_MOMENTARY(1),
 175     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 176     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 177     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 178     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 179 };
 180
 181 ```
 182
 183 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 184
 185
 186 ## Eject on Mac OSX
 187 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 188 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 189
 190 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.
 191
 192
 193 ## What's `weak_mods` and `real_mods` in `action_util.c`
 194 ___TO BE IMPROVED___
 195
 196 real_mods is intended to retains state of real/physical modifier key state, while
 197 weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
 198
 199 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 200
 201 with weak_mods,
 202 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 203 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 204 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
 205 real_mods still keeps modifier state.
 206
 207 without weak mods,
 208 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 209 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 210 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 211 here real_mods lost state for 'physical left shift'.
 212
 213 weak_mods is ORed with real_mods when keyboard report is sent.
 214 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
 215
 216 ## Timer Functionality
 217
 218 It's possible to start timers and read values for time-specific events - here's an example:
 219
 220 ```c
 221 static uint16_t key_timer;
 222 key_timer = timer_read();
 223
 224 if (timer_elapsed(key_timer) < 100) {
 225   // do something if less than 100ms have passed
 226 } else {
 227   // do something if 100ms or more have passed
 228 }
 229 ```
 230
 231 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.