auri.ee
keyboard stuff
1# Keymap FAQ
2
3This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap) first.
4
5## What Keycodes Can I Use?
6
7See [Keycodes](keycodes) for an index of keycodes available to you. These link to more extensive documentation when available.
8
9Keycodes are actually defined in [quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
10
11## What Are the Default Keycodes?
12
13There 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
15<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
16
17
18## How Can I Make Custom Names For Complex Keycodes?
19
20Sometimes, for readability's sake, it's useful to define custom names for some keycodes. People often define custom names using `#define`. For example:
21
22```c
23#define FN_CAPS LT(_FL, KC_CAPS)
24#define ALT_TAB LALT(KC_TAB)
25```
26
27This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
28
29## My Keymap Doesn't Update When I Flash It
30
31This is usually due to VIA, and has to do with how it deals with keymaps.
32
33On first run, the VIA code in the firmware will copy the keymap from flash memory into EEPROM so that it can be rewritten at runtime by the VIA app. From this point QMK will use the keymap stored in EEPROM instead of flash, and so updates to your `keymap.c` will not be reflected.
34
35The simple fix for this is to clear the EEPROM. You can do this in several ways:
36
37* Hold the Bootmagic key (usually top left/Escape) while plugging the board in, which will also place the board into bootloader mode; then unplug and replug the board.
38* Press the `QK_CLEAR_EEPROM`/`EE_CLR` keycode if it is accessible on your keymap.
39* Place the board into bootloader mode and hit the "Clear EEPROM" button. This may not be available for all bootloaders, and you may need to reflash the board afterwards.
40
41## Some Of My Keys Are Swapped Or Not Working
42
43QMK has a couple of features 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.
44
45Refer to the EEPROM clearing methods above, which should return those keys to normal operation. If that doesn't work, look here:
46
47* [Magic Keycodes](keycodes_magic)
48* [Command](features/command)
49
50## The Menu Key Isn't Working
51
52The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when the key was invented, there was already a key named "Menu" in the HID specification, so for whatever reason, Microsoft chose to create a new key and call it "Application".
53
54## Power Keys Aren't Working
55
56Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_KB_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
57
58The 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.
59
60## One Shot Modifier
61
62Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. One Shot Shift mitigates this for me.
63https://github.com/tmk/tmk_keyboard/issues/67
64
65## Modifier/Layer Stuck
66
67Modifier keys or layers can be stuck unless layer switching is configured properly.
68For Modifier keys and layer actions you have to place `KC_TRNS` on same position of destination layer to unregister the modifier key or return to previous layer on release event.
69
70* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
71* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
72* https://github.com/tmk/tmk_keyboard/issues/248
73
74## Mechanical Lock Switch Support
75
76This feature is for *mechanical lock switch* like [this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
77
78```c
79#define LOCKING_SUPPORT_ENABLE
80#define LOCKING_RESYNC_ENABLE
81```
82
83After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
84
85Old 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_NUM` and `KC_SCRL`.***
86
87## Input Special Characters Other Than ASCII like Cédille 'Ç'
88
89See the [Unicode](features/unicode) feature.
90
91## `Fn` Key on macOS
92
93Unlike 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.
94
95It 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.
96Even 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.
97
98See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
99
100## Keys Supported in Mac OSX?
101
102You can know which keycodes are supported in OSX from this source code.
103
104`usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
105
106https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
107
108And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
109
110https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
111
112## JIS Keys in Mac OSX
113
114Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
115
116* Enable NFER Key on PC keyboard
117* Enable XFER Key on PC keyboard
118* Enable KATAKANA Key on PC keyboard
119
120https://pqrs.org/osx/karabiner/seil.html
121
122## RN-42 Bluetooth Doesn't Work with Karabiner
123
124Karabiner - 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.
125https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
126
127See these for the detail of this problem.
128https://github.com/tmk/tmk_keyboard/issues/213
129https://github.com/tekezo/Karabiner/issues/403
130
131## Esc and <code>`</code> on a Single Key
132
133See the [Grave Escape](features/grave_esc) feature.
134
135## Eject on Mac OSX
136
137`KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
138It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
139
140Not 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.
141
142## What are "Real" and "Weak" modifiers?
143
144Real modifiers refer to the state of the real/physical modifier keys, while weak modifiers are the state of "virtual" or temporary modifiers which should not interfere with the internal state of the real modifier keys.
145
146The real and weak modifier states are ORed together when the keyboard report is sent, so if you release a weak modifier while the same real modifier is still held, the report does not change:
147
148 1. **Hold down physical Left Shift:** Real mods now contains Left Shift, final state is Left Shift
149 2. **Add weak Left Shift:** Weak mods now contains Left Shift, final state is Left Shift
150 3. **Remove weak Left Shift:** Weak mods now contains nothing, final state is Left Shift
151 4. **Release physical Left Shift:** Real mods now contains nothing, final state is nothing