lunny/qmk_firmware-mirror
1
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware synced 2024-12-22 16:36:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Keymap FAQ updates (#17130)

Browse Source
This commit is contained in:
Ryan 2022-05-18 04:48:59 +10:00 committed by GitHub
parent f736828fa8
commit d241e80533
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 33 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/faq_keymap.md
View File

@ -3,6 +3,7 @@
This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
## What Keycodes Can I Use?
See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
Keycodes are actually defined in [quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
@ -25,25 +26,30 @@ Sometimes, for readability's sake, it's useful to define custom names for some k
This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
## My Keymap Doesn't Update When I Flash It
This is usually due to VIA, and has to do with how it deals with keymaps.
On 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.
The simple fix for this is to clear the EEPROM. You can do this in several ways:
* Hold the Bootmagic Lite 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.
* Press the `QK_CLEAR_EEPROM`/`EE_CLR` keycode if it is accessible on your keymap.
* 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.
## Some Of My Keys Are Swapped Or Not Working
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.
QMK 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.
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:
Refer to the EEPROM clearing methods above, which should return those keys to normal operation. If that doesn't work, look here:
* [Bootmagic Lite](feature_bootmagic.md)
* [Command](feature_command.md)
* [Magic Keycodes](keycodes_magic.md)
* [Command](feature_command.md)
## The Menu Key Isn't Working
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.
## `KC_SYSTEM_REQUEST` Isn't Working
Use keycode for Print Screen (`KC_PRINT_SCREEN`/`KC_PSCR`) instead of `KC_SYSTEM_REQUEST`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
* https://en.wikipedia.org/wiki/Magic_SysRq_key
* https://en.wikipedia.org/wiki/System_request
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 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".
## Power Keys Aren't Working
@ -52,10 +58,12 @@ Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_KB_POWER` in th
The 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.
## One Shot Modifier
Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. One Shot Shift mitigates this for me.
https://github.com/tmk/tmk_keyboard/issues/67
## Modifier/Layer Stuck
Modifier keys or layers can be stuck unless layer switching is configured properly.
For 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.
@ -63,12 +71,11 @@ For Modifier keys and layer actions you have to place `KC_TRNS` on same position
* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
* https://github.com/tmk/tmk_keyboard/issues/248
## Mechanical Lock Switch Support
This 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`:
```
```c
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
```
@ -91,6 +98,7 @@ Even worse, it is not recognized unless the keyboard's VID and PID match that of
See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
## Keys Supported in Mac OSX?
You can know which keycodes are supported in OSX from this source code.
`usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
@ -101,8 +109,8 @@ And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
## JIS Keys in Mac OSX
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.
* Enable NFER Key on PC keyboard
@ -111,8 +119,8 @@ Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`
https://pqrs.org/osx/karabiner/seil.html
## RN-42 Bluetooth Doesn't Work with Karabiner
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.
https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
@ -120,37 +128,24 @@ See these for the detail of this problem.
https://github.com/tmk/tmk_keyboard/issues/213
https://github.com/tekezo/Karabiner/issues/403
## Esc and <code>&#96;</code> on a Single Key
See the [Grave Escape](feature_grave_esc.md) feature.
## Eject on Mac OSX
`KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
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.
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.
## What are "Real" and "Weak" modifiers?
## What's `weak_mods` and `real_mods` in `action_util.c`
___TO BE IMPROVED___
Real 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.
real_mods is intended to retains state of real/physical modifier key state, while
weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
The 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:
Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
with weak_mods,
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
real_mods still keeps modifier state.
without weak mods,
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
here real_mods lost state for 'physical left shift'.
weak_mods is ORed with real_mods when keyboard report is sent.
https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
1. **Hold down physical Left Shift:** Real mods now contains Left Shift, final state is Left Shift
2. **Add weak Left Shift:** Weak mods now contains Left Shift, final state is Left Shift
3. **Remove weak Left Shift:** Weak mods now contains nothing, final state is Left Shift
4. **Release physical Left Shift:** Real mods now contains nothing, final state is nothing