Nulo/qmk_firmware
1
0
Fork 0
Code Releases Activity

More thoroughly document Bootmagic and Command (#2455)

Browse source
This commit is contained in:
skullydazed 2018-03-02 09:21:03 -08:00 committed by GitHub
parent e5c331e7be
commit e87c39d302
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 165 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/_summary.md
View file

@ -25,6 +25,7 @@
* [Auto Shift](feature_auto_shift.md)
* [Backlight](feature_backlight.md)
* [Bootmagic](feature_bootmagic.md)
* [Command](feature_command.md)
* [Dynamic Macros](feature_dynamic_macros.md)
* [Grave Escape](feature_grave_esc.md)
* [Key Lock](feature_key_lock.md)

33
docs/faq_keymap.md
View file

@ -14,6 +14,15 @@ There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JI
<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/9ce023dc6caadc0cf11c88c782350a8c -->
![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
## 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.
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:
* [Bootmagic](feature_bootmagic.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.
@ -22,13 +31,13 @@ The key found on most modern keyboards that is located between `KC_RGUI` and `KC
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'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
- http://en.wikipedia.org/wiki/Magic_SysRq_key
- http://en.wikipedia.org/wiki/System_request
* http://en.wikipedia.org/wiki/Magic_SysRq_key
* http://en.wikipedia.org/wiki/System_request
## Power Key Doesn't Work
Use `KC_PWR` instead of `KC_POWER` or vice versa.
- `KC_PWR` works with Windows and Linux, not with OSX.
- `KC_POWER` works with OSX and Linux, not with Windows.
* `KC_PWR` works with Windows and Linux, not with OSX.
* `KC_POWER` works with OSX and Linux, not with Windows.
More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
@ -40,9 +49,9 @@ https://github.com/tmk/tmk_keyboard/issues/67
Modifier keys or layers can be stuck unless layer switching is configured properly.
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.
- https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
- http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
- https://github.com/tmk/tmk_keyboard/issues/248
* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
* https://github.com/tmk/tmk_keyboard/issues/248
## Mechanical Lock Switch Support
@ -66,17 +75,17 @@ See this post for example **MACRO** code.
http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
On **Windows** you can use `AltGr` key or **Alt code**.
- http://en.wikipedia.org/wiki/AltGr_key
- http://en.wikipedia.org/wiki/Alt_code
* http://en.wikipedia.org/wiki/AltGr_key
* http://en.wikipedia.org/wiki/Alt_code
On **Mac** OS defines `Option` key combinations.
- http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
On **Xorg** you can use `compose` key, instead.
- http://en.wikipedia.org/wiki/Compose_key
* http://en.wikipedia.org/wiki/Compose_key
And see this for **Unicode** input.
- http://en.wikipedia.org/wiki/Unicode_input
* http://en.wikipedia.org/wiki/Unicode_input
## Apple/Mac Keyboard `Fn`

125
docs/feature_bootmagic.md
View file

@ -1,64 +1,89 @@
# Bootmagic
# Bootmagic and Magic Keycodes
<!-- FIXME: Describe the bootmagic feature here. -->
There are 3 separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality you access that functionality in different ways depending on how your keyboard is configured.
## Bootmagic Keycodes
Bootmagic is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command you hold down the bootmagic key (`KC_SPACE` on most keyboards) and one or more command keys.
Shortcuts for bootmagic options. You can use these even when bootmagic is off.
Bootmagic Keycodes allow you to access the Bootmagic functionality after your keyboard has initialized. To use Bootmagic Keycodes you assign keycodes starting with `MAGIC_`, much in the same way you define any other key.
|Key |Aliases |Description |
|----------------------------------|---------|------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock |
|`MAGIC_CAPSLOCK_TO_CONTROL` | |Treat Caps Lock as Control |
|`MAGIC_SWAP_LALT_LGUI` | |Swap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` | |Swap Right Alt and GUI |
|`MAGIC_NO_GUI` | |Disable the GUI key |
|`MAGIC_SWAP_GRAVE_ESC` | |Swap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap Backslash and Backspace |
|`MAGIC_HOST_NKRO` | |Force NKRO on |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` | |Unswap Left Control and Caps Lock |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` | |Stop treating CapsLock as Control |
|`MAGIC_UNSWAP_LALT_LGUI` | |Unswap Left Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` | |Unswap Right Alt and GUI |
|`MAGIC_UNNO_GUI` | |Enable the GUI key |
|`MAGIC_UNSWAP_GRAVE_ESC` | |Unswap <code>&#96;</code> and Escape|
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap Backslash and Backspace |
|`MAGIC_UNHOST_NKRO` | |Force NKRO off |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Left Alt and GUI |
|`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off |
Command is a feature that allows you to control different aspects of your keyboard. Command used to be called Magic. Command is typically accessed by holding Left and Right Shift at the same time, although that can be customized. While it shares some functionality with Bootmagic it also allows you to access functionality that Bootmagic does not. For more information see the (Command)[feature_command.md) documentation page.
## Enabling Bootmagic
## Bootmagc Hotkeys
Bootmagic is disabled by default. To use Bootmagic you need to enable it in your `rules.mk` file:
Use this by holding the SPACEBAR and the documented key while
plugging in the USB connection. e.g. to get into bootloader mode
hold `SPACE` and `B` while plugging in USB.
BOOTMAGIC_ENABLE = yes
## Bootmagic Hotkeys and Keycodes
|Key |Description |
|-----------|------------------------------------------------------------------------|
|`ESC` | Skip bootmagic and saved eeprom configuration |
|`B` | Enter bootloader instead of firmware |
|`BACKSPACE`| Clear the saved settings from flash |
|`LCTRL` | Swap `Control` and `Capslock` and save into flash |
|`CAPSLOCK` | Swap `Capslock` and `Control` and save into flash |
|`LALT` | Swap Left `Alt` and `GUI` and save into flash, e.g. for OSX Opt and Cmd|
|`RALT` | Swap Right `Alt` and `GUI` and save into flash |
|`LGUI` | Disable GUI key - e.g. disable Windows key during gaming |
|`GRAVE` | Swap &#39; and `ESC` and save into flash |
|`BACKSLASH`| Swap Blackslash and Backspace and save into flash |
|`N` | Enable NKRO (N Key Roll Over) |
|`0` | Make Layer 0 the default layer at bootup, e.g. switch to dvorak |
|`1` | Make Layer 1 the default layer at bootup |
|`2` | Make Layer 2 the default layer at bootup |
|`3` | Make Layer 3 the default layer at bootup |
|`4` | Make Layer 4 the default layer at bootup |
|`5` | Make Layer 5 the default layer at bootup |
|`6` | Make Layer 6 the default layer at bootup |
|`7` | Make Layer 7 the default layer at bootup |
This table describes the default Hotkeys for Bootmagic and the Keycodes for Magic. These may be overriden at the Keyboard or Keymap level. Some functionality is not available in both methods.
To use the Hotkey hold down `BOOTMAGIC_KEY_SALT` (`KC_SPACE` by default) and the Hotkey while plugging in your keyboard. To use the Keycode assign that keycode to a layer. For example, if you hold down Space+B while plugging in most keyboards, you will enter bootloader mode.
|Hotkey |Keycode |Description |
|-----------|----------------------------------|--------------------------------------------------------|
|`ESC` | |Skip bootmagic and saved eeprom configuration |
|`B` |`RESET` |Enter bootloader instead of firmware |
|`D` |`DEBUG` |Enable debugging (writes messages to serial) |
|`X` | |Enable matrix debugging |
|`K` | |Enable keyboard debugging |
|`M` | |Enable mouse debugging |
|`BACKSPACE`| |Clear the saved settings from flash |
|`CAPSLOCK` |`MAGIC_CAPSLOCK_TO_CONTROL` |Treat `Capslock` as `Control` |
| |`MAGIC_UNCAPSLOCK_TO_CONTROL` |Stop treating CapsLock as Control |
|`LCTRL` |`MAGIC_SWAP_CONTROL_CAPSLOCK` |Swap `Control` and `Capslock` |
| |`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |Unswap Left Control and Caps Lock |
| |`MAGIC_SWAP_ALT_GUI` |Swap Alt and GUI on both sides |
| |`MAGIC_UNSWAP_ALT_GUI` |Unswap Left Alt and GUI |
|`LALT` |`MAGIC_SWAP_LALT_LGUI` |Swap Left `Alt` and `GUI`, e.g. for OSX Opt and Cmd |
| |`MAGIC_UNSWAP_LALT_LGUI` |Unswap Left Alt and GUI |
|`RALT` |`MAGIC_SWAP_RALT_RGUI` |Swap Right `Alt` and `GUI` |
| |`MAGIC_UNSWAP_RALT_RGUI` |Unswap Right Alt and GUI |
|`LGUI` |`MAGIC_NO_GUI` |Disable GUI key - e.g. disable Windows key during gaming|
| |`MAGIC_UNNO_GUI` |Enable the GUI key |
|`GRAVE` |`MAGIC_SWAP_GRAVE_ESC` |Swap `\`~` and `ESC` |
| |`MAGIC_UNSWAP_GRAVE_ESC` |Unswap `\`~` and Escape |
|`BACKSLASH`|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |Swap Blackslash and Backspace |
| |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Unswap Backslash and Backspace |
|`N` |`MAGIC_HOST_NKRO` |Force N-Key Rollover (NKRO) on |
| |`MAGIC_UNHOST_NKRO` |Force NKRO off |
| |`MAGIC_TOGGLE_NKRO` |Toggle NKRO on or off |
|`0` |`DF(0)` |Make Layer 0 the default layer at bootup |
|`1` |`DF(1)` |Make Layer 1 the default layer at bootup |
|`2` |`DF(2)` |Make Layer 2 the default layer at bootup |
|`3` |`DF(3)` |Make Layer 3 the default layer at bootup |
|`4` |`DF(4)` |Make Layer 4 the default layer at bootup |
|`5` |`DF(5)` |Make Layer 5 the default layer at bootup |
|`6` |`DF(6)` |Make Layer 6 the default layer at bootup |
|`7` |`DF(7)` |Make Layer 7 the default layer at bootup |
## Bootmagic Configuration
When setting up your keyboard and/or keymap there are a number of `#define`s that control the behavior of Bootmagic. To use these put them in your `config.h`, either at the keyboard or keymap level.
|Define |Default|Description |
|-------|-------|------------|
|`BOOTMAGIC_KEY_SALT`|`KC_SPACE`|The key to hold down to trigger Bootmagic during initialization.|
|`BOOTMAGIC_KEY_SKIP`|`KC_ESC`|The Hotkey to ignore saved eeprom configuration.|
|`BOOTMAGIC_KEY_EEPROM_CLEAR`|`KC_BSPACE`|The hotkey to clear the saved eeprom configuration.|
|`BOOTMAGIC_KEY_BOOTLOADER`|`KC_B`|The hotkey to enter the bootloader.|
|`BOOTMAGIC_KEY_DEBUG_ENABLE`|`KC_D`|The hotkey to enable debug mode.|
|`BOOTMAGIC_KEY_DEBUG_MATRIX`|`KC_X`|The hotkey to enable matrix debugging mode.|
|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`|`KC_K`|The hotkey to enable keyboard debugging mode.|
|`BOOTMAGIC_KEY_DEBUG_MOUSE`|`KC_M`|The hotkey to enable mouse debugging mode.|
|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`|`KC_LCTRL`||
|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`|`KC_CAPSLOCK`||
|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`|`KC_LALT`||
|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`|`KC_RALT`||
|`BOOTMAGIC_KEY_NO_GUI`|`KC_LGUI`||
|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`|`KC_GRAVE`||
|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`||
|`BOOTMAGIC_HOST_NKRO`|`KC_N`||
|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`|`KC_0`|Hotkey to set Layer 0 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`|`KC_1`|Hotkey to set Layer 1 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`|`KC_2`|Hotkey to set Layer 2 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`|`KC_3`|Hotkey to set Layer 3 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`|`KC_4`|Hotkey to set Layer 4 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`|`KC_5`|Hotkey to set Layer 5 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`|`KC_6`|Hotkey to set Layer 6 as the default layer|
|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`|`KC_7`|Hotkey to set Layer 7 as the default layer|

52
docs/feature_command.md Normal file
View file

@ -0,0 +1,52 @@
# Command (Formerly known as Magic)
Command is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md). Whenever possible we encourage you to use that functionality instead of Command.
## Enabling Command
By default Command is disabled. You can enable it in your `rules.mk` file:
COMMAND_ENABLE = yes
## Usage
To use Command you hold down the key combination defined by `IS_COMMAND`. By default that combination is both shift keys. While holding the key combination press the key corresponding to the command you want.
For example, to write the current QMK version to the QMK Toolbox console, you can press `Left Shift`+`Right Shift`+`V`.
## Configuration
The following values can be defined in `config.h` to control the behavior of Command.
|Define |Default | Description |
|-------|--------|-------------|
|`IS_COMMAND()` |`(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`|Key combination to activate Command|
|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true` |Do layer switching with Function row|
|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true` |Do layer switching with number keys.|
|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false` |Do layer switching with custom keys (`MAGIC_KEY_LAYER0..9` below.)|
|`MAGIC_KEY_HELP1` |`H` |Show help.|
|`MAGIC_KEY_HELP2` |`SLASH` |Show help.|
|`MAGIC_KEY_DEBUG` |`D` |Turn on debug mode.|
|`MAGIC_KEY_DEBUG_MATRIX` |`X` |Turn on matrix debugging.|
|`MAGIC_KEY_DEBUG_KBD` |`K` |Turn on keyboard debugging.|
|`MAGIC_KEY_DEBUG_MOUSE` |`M` |Turn on mouse debugging.|
|`MAGIC_KEY_VERSION` |`V` |Write the QMK version to the console|
|`MAGIC_KEY_STATUS` |`S` |Show the current keyboard status|
|`MAGIC_KEY_CONSOLE` |`C` |Enable the Command Console|
|`MAGIC_KEY_LAYER0_ALT1` |`ESC` |Alternate access to layer 0|
|`MAGIC_KEY_LAYER0_ALT2` |`GRAVE` |Alternate access to layer 0|
|`MAGIC_KEY_LAYER0` |`0` |Change default layer to 0|
|`MAGIC_KEY_LAYER1` |`1` |Change default layer to 1|
|`MAGIC_KEY_LAYER2` |`2` |Change default layer to 2|
|`MAGIC_KEY_LAYER3` |`3` |Change default layer to 3|
|`MAGIC_KEY_LAYER4` |`4` |Change default layer to 4|
|`MAGIC_KEY_LAYER5` |`5` |Change default layer to 5|
|`MAGIC_KEY_LAYER6` |`6` |Change default layer to 6|
|`MAGIC_KEY_LAYER7` |`7` |Change default layer to 7|
|`MAGIC_KEY_LAYER8` |`8` |Change default layer to 8|
|`MAGIC_KEY_LAYER9` |`9` |Change default layer to 9|
|`MAGIC_KEY_BOOTLOADER` |`PAUSE` |Exit keyboard and enter bootloader|
|`MAGIC_KEY_LOCK` |`CAPS` |Lock the keyboard so nothing can be typed|
|`MAGIC_KEY_EEPROM` |`E` |Erase EEPROM settings|
|`MAGIC_KEY_NKRO` |`N` |Toggle NKRO on/off|
|`MAGIC_KEY_SLEEP_LED` |`Z` |Toggle LED when computer is sleeping on/off|

16
docs/hardware_keyboard_guidelines.md
View file

@ -16,6 +16,22 @@ In an effort to keep the repo size down, we're no longer accepting images of any
Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
## Keyboard Defaults
Given the amount of functionality that QMK exposes it's very easy to confuse new users. When putting together the default firmware for your keyboard we recommend limiting your enabled features and options to the minimal set needed to support your hardware. Recommendations for specific features follow.
### Bootmagic and Command
(Bootmagic)[feature_bootmagic.md) and (Command)[feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board.
By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in.
If your keyboard does not have 2 shift keys you should provide a working default for `IS_COMMAND`, even when you have set `COMMAND_ENABLE = no`. This will give your users a default to conform to if they do enable Command.
## Custom Keyboard Programming
As documented on (Customizing Functionality)[custom_quantum_functions.md] you can define custom functions for your keyboard. Please keep in mind that your users may want to customize that behavior as well, and make it possible for them to do that. If you are providing a custom function, for example `process_record_kb()`, make sure that your function calls the `_user()` version of the call too. You should also take into account the return value of the `_user()` version, and only run your custom code if the user returns `true`.
## Keyboard Metadata
As QMK grows so does the ecosystem surrounding QMK. To make it easier for projects in that ecosystem to tie into QMK as we make changes we are developing a metadata system to expose information about keyboards in QMK.