3 This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
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.
8 Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
10 ## What Are The Default Keycodes?
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:
14 <!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/9ce023dc6caadc0cf11c88c782350a8c -->
15 ![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
17 ## The Menu Key Isn't Working
19 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.
21 ## `KC_SYSREQ` isn't working
22 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'.
24 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
25 - http://en.wikipedia.org/wiki/Magic_SysRq_key
26 - http://en.wikipedia.org/wiki/System_request
28 ## Power key doesn't work
29 Use `KC_PWR` instead of `KC_POWER` or vice versa.
30 - `KC_PWR` works with Windows and Linux, not with OSX.
31 - `KC_POWER` works with OSX and Linux, not with Windows.
33 More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
36 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. Oneshot Shift mitgates this for me.
37 https://github.com/tmk/tmk_keyboard/issues/67
39 ## Modifier/Layer stuck
40 Modifier keys or layers can be stuck unless layer switching is configured properly.
41 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.
43 - https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
44 - http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
45 - https://github.com/tmk/tmk_keyboard/issues/248
48 ## Mechanical Lock Switch Support
50 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`:
53 #define LOCKING_SUPPORT_ENABLE
54 #define LOCKING_RESYNC_ENABLE
57 After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
59 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`.***
61 ## Input special charactors other than ASCII like Cédille 'Ç'
62 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
64 See this post for example **MACRO** code.
66 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
68 On **Windows** you can use `AltGr` key or **Alt code**.
69 - http://en.wikipedia.org/wiki/AltGr_key
70 - http://en.wikipedia.org/wiki/Alt_code
72 On **Mac** OS defines `Option` key combinations.
73 - http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
75 On **Xorg** you can use `compose` key, instead.
76 - http://en.wikipedia.org/wiki/Compose_key
78 And see this for **Unicode** input.
79 - http://en.wikipedia.org/wiki/Unicode_input
82 ## Apple/Mac keyboard Fn
85 Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
86 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.
88 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
91 ## Media control keys in Mac OSX
92 #### KC_MNXT and KC_MPRV does not work on Mac
93 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
94 See https://github.com/tmk/tmk_keyboard/issues/195
97 ## Keys supported in Mac OSX?
98 You can know which keycodes are supported in OSX from this source code.
100 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
102 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
104 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
106 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
109 ## JIS keys in Mac OSX
110 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.
112 * Enable NFER Key on PC keyboard
113 * Enable XFER Key on PC keyboard
114 * Enable KATAKANA Key on PC keyboard
116 https://pqrs.org/osx/karabiner/seil.html
119 ## RN-42 Bluetooth doesn't work with Karabiner
120 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.
121 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
123 See these for the deail of this problem.
124 https://github.com/tmk/tmk_keyboard/issues/213
125 https://github.com/tekezo/Karabiner/issues/403
128 ## Esc and `~ on a key
130 Use `GRAVE_ESC` or `KC_GESC` in your keymap. `GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
132 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.
134 ## Arrow on Right Modifier keys with Dual-Role
135 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**.
138 #include "keymap_common.h"
141 /* Arrow keys on right modifier keys with TMK dual role feature
143 * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
144 * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
146 const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
149 ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \
150 TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \
151 LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \
152 LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \
153 FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3),
155 GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \
156 TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
157 TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
158 TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
159 TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8),
162 const uint16_t PROGMEM fn_actions[] = {
163 [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
164 [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
165 [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
166 [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
167 [4] = ACTION_LAYER_MOMENTARY(1),
168 [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
169 [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
170 [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
171 [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
176 Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
180 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
181 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
183 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.
186 ## What's weak_mods and real_mods in action_util.c
189 real_mods is intended to retains state of real/physical modifier key state, while
190 weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
192 Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
195 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
196 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
197 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
198 real_mods still keeps modifier state.
201 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
202 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
203 * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
204 here real_mods lost state for 'physical left shift'.
206 weak_mods is ORed with real_mods when keyboard report is sent.
207 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
209 ## Timer functionality
211 It's possible to start timers and read values for time-specific events - here's an example:
214 static uint16_t key_timer;
215 key_timer = timer_read();
217 if (timer_elapsed(key_timer) < 100) {
218 // do something if less than 100ms have passed
220 // do something if 100ms or more have passed
224 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.