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 ## `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. `GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
 120
 121 Note that this will break the CTRL+SHIFT+ESC shortcut to the Windows task manager. Use `#define GRAVE_ESC_CTRL_OVERRIDE` in your `config.h` to get the shortcut back. With this option, `ESC_GRAVE` results in `ESC` if `CTRL` is held, even if `SHIFT` or `GUI` are also held.
 122
 123 ## Arrow on Right Modifier keys with Dual-Role
 124 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**.
 125 ```
 126
 127 #include "keymap_common.h"
 128
 129
 130 /* Arrow keys on right modifier keys with TMK dual role feature
 131  *
 132  *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 133  *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 134  */
 135 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 136     /* 0: qwerty */
 137     [0] = KEYMAP( \
 138         ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
 139         TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
 140         LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
 141         LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
 142         FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
 143     [1] = KEYMAP( \
 144         GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, 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,TRNS,TRNS,TRNS,TRNS,TRNS, \
 147         TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
 148         TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
 149 };
 150
 151 const uint16_t PROGMEM fn_actions[] = {
 152     [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
 153     [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
 154     [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
 155     [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
 156     [4] = ACTION_LAYER_MOMENTARY(1),
 157     [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
 158     [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
 159     [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
 160     [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
 161 };
 162
 163 ```
 164
 165 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 166
 167
 168 ## Eject on Mac OSX
 169 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 170 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 171
 172 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.
 173
 174
 175 ## What's weak_mods and real_mods in action_util.c
 176 ___TO BE IMPROVED___
 177
 178 real_mods is intended to retains state of real/physical modifier key state, while
 179 weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
 180
 181 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 182
 183 with weak_mods,
 184 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 185 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
 186 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
 187 real_mods still keeps modifier state.
 188
 189 without weak mods,
 190 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 191 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
 192 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
 193 here real_mods lost state for 'physical left shift'.
 194
 195 weak_mods is ORed with real_mods when keyboard report is sent.
 196 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
 197
 198 ## Timer functionality
 199
 200 It's possible to start timers and read values for time-specific events - here's an example:
 201
 202 ```c
 203 static uint16_t key_timer;
 204 key_timer = timer_read();
 205
 206 if (timer_elapsed(key_timer) < 100) {
 207   // do something if less than 100ms have passed
 208 } else {
 209   // do something if 100ms or more have passed
 210 }
 211 ```
 212
 213 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.