docs/faq_keymap.md

   1 # Frequently Asked Keymap Questions
   2
   3 This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.html) first.
   4
   5 ## What Keycodes Can I Use?
   6 See [Basic Keycodes](keycodes.html) and [Quantum Keycodes](quantum_keycodes.html) for most of the keys you can define.
   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 ## `KC_SYSREQ` isn't working
  11 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'.
  12
  13 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
  14 - http://en.wikipedia.org/wiki/Magic_SysRq_key
  15 - http://en.wikipedia.org/wiki/System_request
  16
  17 ## Power key doesn't work
  18 Use `KC_PWR` instead of `KC_POWER` or vice versa.
  19 - `KC_PWR` works with Windows and Linux, not with OSX.
  20 - `KC_POWER` works with OSX and Linux, not with Windows.
  21
  22 More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
  23
  24 ## Oneshot modifier
  25 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  Oneshot Shift mitgates this for me.
  26 https://github.com/tmk/tmk_keyboard/issues/67
  27
  28 ## Modifier/Layer stuck
  29 Modifier keys or layers can be stuck unless layer switching is configured properly.
  30 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.
  31
  32 - https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
  33 - http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
  34 - https://github.com/tmk/tmk_keyboard/issues/248
  35
  36
  37 ## Mechanical Lock Switch Support
  38
  39 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`:
  40
  41 ```
  42 #define LOCKING_SUPPORT_ENABLE
  43 #define LOCKING_RESYNC_ENABLE
  44 ```
  45
  46 After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
  47
  48 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`.***
  49
  50 ## Input special charactors other than ASCII like Cédille 'Ç'
  51 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
  52
  53 See this post for example **MACRO** code.
  54
  55 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
  56
  57 On **Windows** you can use `AltGr` key or **Alt code**.
  58 - http://en.wikipedia.org/wiki/AltGr_key
  59 - http://en.wikipedia.org/wiki/Alt_code
  60
  61 On **Mac** OS defines `Option` key combinations.
  62 - http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
  63
  64 On **Xorg** you can use `compose` key, instead.
  65 - http://en.wikipedia.org/wiki/Compose_key
  66
  67 And see this for **Unicode** input.
  68 - http://en.wikipedia.org/wiki/Unicode_input
  69
  70
  71 ## Apple/Mac keyboard Fn
  72 Not supported.
  73
  74 Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
  75 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.
  76
  77 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
  78
  79
  80 ## Media control keys in Mac OSX
  81 #### KC_MNXT and KC_MPRV does not work on Mac
  82 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
  83 See https://github.com/tmk/tmk_keyboard/issues/195
  84
  85
  86 ## Keys supported in Mac OSX?
  87 You can know which keycodes are supported in OSX from this source code.
  88
  89 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
  90
  91 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
  92
  93 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
  94
  95 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
  96
  97
  98 ## JIS keys in Mac OSX
  99 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.
 100
 101 * Enable NFER Key on PC keyboard
 102 * Enable XFER Key on PC keyboard
 103 * Enable KATAKANA Key on PC keyboard
 104
 105 https://pqrs.org/osx/karabiner/seil.html
 106
 107
 108 ## RN-42 Bluetooth doesn't work with Karabiner
 109 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.
 110 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 111
 112 See these for the deail of this problem.
 113 https://github.com/tmk/tmk_keyboard/issues/213
 114 https://github.com/tekezo/Karabiner/issues/403
 115
 116
 117 ## Esc and `~ on a key
 118
 119 Use `GRAVE_ESC` or `KC_GESC` in your keymap.
 120
 121 ## Arrow on Right Modifier keys with Dual-Role
 122 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**.
 123 ```
 124
 125 #include "keymap_common.h"
 126
 127
 128 /* Arrow keys on right modifier keys with TMK dual role feature
 129  *
 130  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 131  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 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         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 140         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 141     [1] = KEYMAP( \
 142         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, 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,FN5, TRNS, \
 146         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 147 };
 148
 149 const uint16_t PROGMEM fn_actions[] = {
 150     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 151     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 152     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 153     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 154     [4] = ACTION_LAYER_MOMENTARY(1),
 155     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 156     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 157     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 158     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 159 };
 160
 161 ```
 162
 163 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 164
 165
 166 ## Eject on Mac OSX
 167 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 168 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 169
 170 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.
 171
 172
 173 ## What's weak_mods and real_mods in action_util.c
 174 ___TO BE IMPROVED___
 175
 176 real_mods is intended to retains state of real/physical modifier key state, while
 177 weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
 178
 179 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 180
 181 with weak_mods,
 182 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 183 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 184 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
 185 real_mods still keeps modifier state.
 186
 187 without weak mods,
 188 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 189 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 190 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 191 here real_mods lost state for 'physical left shift'.
 192
 193 weak_mods is ORed with real_mods when keyboard report is sent.
 194 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
 195
 196 ## Timer functionality
 197
 198 It's possible to start timers and read values for time-specific events - here's an example:
 199
 200 ```c
 201 static uint16_t key_timer;
 202 key_timer = timer_read();
 203
 204 if (timer_elapsed(key_timer) < 100) {
 205   // do something if less than 100ms have passed
 206 } else {
 207   // do something if 100ms or more have passed
 208 }
 209 ```
 210
 211 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.