From a03aa301def77c867ae6c6c840f7fc82b26d91d6 Mon Sep 17 00:00:00 2001
From: James Young <18669334+noroadsleft@users.noreply.github.com>
Date: Fri, 6 Aug 2021 23:59:56 -0700
Subject: Remove Full Bootmagic (#13846)
* disambiguate Bootmagic rules in keymaps
The files edited by this commit were added at a point in time where `BOOTMAGIC_ENABLE = yes` enabled full Bootmagic.
This commit edits the files to specify that full Bootmagic is intended.
* remove BOOTMAGIC_ENABLE=full setting
* unify commented BOOTMAGIC_ENABLE rules in keyboards
Explicitly sets `BOOTMAGIC_ENABLE = no` in keyboards where the rule was commented out.
Command:
```
find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;#[ \t]*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-zA-Z]\+\).*;\1 = no # Virtual DIP switch configuration;g' {} +
```
* remove commented Bootmagic rules from keymap/user level
Command:
```
find keyboards/ layouts/ users/ -type f -name 'rules.mk' -exec sed -i -e '/#.*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*/d' {} +
```
* update keyboard BOOTMAGIC_ENABLE rule formatting
Sets the formatting of BOOTMAGIC_ENABLE rules to `BOOTMAGIC_ENABLE = [value]`, without the inline comments (which will be replaced later).
Command:
```
find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' +
```
* update keyboards' BOOTMAGIC_ENABLE settings
Updates keyboard `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used.
Command:
```
find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = \)full;\1lite;g' '{}' +
```
* update keymap/user BOOTMAGIC_ENABLE settings
Updates keymap/user `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used.
Commands:
```
find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' +
find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' +
```
* remove and replace inline comments in keyboards and keymap/user files
Removes and replaces the inline comments, which have been updated to read `Enable Bootmagic Lite`.
Commands:
```
find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' +
find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' +
find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = lite\);\1 # Enable Bootmagic Lite;g' '{}' +
find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = yes\);\1 # Enable Bootmagic Lite;g' '{}' +
find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = no\);\1 # Enable Bootmagic Lite;g' '{}' +
```
* rename improperly named makefiles
Some files intended to be used as makefiles had improper names causing them to not be used as intended when building.
This commit corrects the filenames of the affected files.
* update renamed file with new rule formatting
* update QMK's template files
Updates QMK's `rules.mk` templates to use the new inline comment.
* update QMK Docs
- remove documentation of full Bootmagic
- update links to Bootmagic Lite doc
- add doc for Magic Keycodes
* rules.mk patch for coarse/ixora and coarse/vinta
---
docs/feature_bootmagic.md | 141 +++++-----------------------------------------
1 file changed, 13 insertions(+), 128 deletions(-)
(limited to 'docs/feature_bootmagic.md')
diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md
index 4c655d8e1c..6c66b00679 100644
--- a/docs/feature_bootmagic.md
+++ b/docs/feature_bootmagic.md
@@ -1,136 +1,15 @@
-# Bootmagic
-
-There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
-
-**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
-
-**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
-
-**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
-
-On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
-
-```make
-BOOTMAGIC_ENABLE = full
-```
-
-?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
-
-Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
-
-```make
-BOOTMAGIC_ENABLE = lite
-```
-
-## Hotkeys
-
-Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
-
-|Hotkey |Description |
-|------------------|---------------------------------------------|
-|Escape |Ignore Bootmagic configuration in EEPROM |
-|`B` |Enter the bootloader |
-|`D` |Toggle debugging over serial |
-|`X` |Toggle key matrix debugging |
-|`K` |Toggle keyboard debugging |
-|`M` |Toggle mouse debugging |
-|`L` |Set "Left Hand" for EE_HANDS handedness |
-|`R` |Set "Right Hand" for EE_HANDS handedness |
-|Backspace |Clear the EEPROM |
-|Caps Lock |Toggle treating Caps Lock as Left Control |
-|Left Control |Toggle swapping Caps Lock and Left Control |
-|Left Alt |Toggle swapping Left Alt and Left GUI |
-|Right Alt |Toggle swapping Right Alt and Right GUI |
-|Left GUI |Toggle the GUI keys (useful when gaming) |
-|`
|Toggle swapping `
and Escape|
-|`\` |Toggle swapping `\` and Backspace |
-|`N` |Toggle N-Key Rollover (NKRO) |
-|`0` |Make layer 0 the default layer |
-|`1` |Make layer 1 the default layer |
-|`2` |Make layer 2 the default layer |
-|`3` |Make layer 3 the default layer |
-|`4` |Make layer 4 the default layer |
-|`5` |Make layer 5 the default layer |
-|`6` |Make layer 6 the default layer |
-|`7` |Make layer 7 the default layer |
-
-## Keycodes :id=keycodes
-
-|Key |Aliases |Description |
-|----------------------------------|---------|--------------------------------------------------------------------------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
-|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
-|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
-|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
-|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
-|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
-|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
-|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
-|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
-|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
-|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
-|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
-|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
-|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
-|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
-|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
-|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
-|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
-|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap `
and Escape |
-|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap `
and Escape |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
-|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
-|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
-|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
-|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
-|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
-
-## Configuration
-
-If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
-
-|Define |Default |Description |
-|----------------------------------------|-------------|---------------------------------------------------|
-|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key |
-|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM |
-|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration |
-|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader |
-|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial |
-|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging |
-|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging |
-|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging |
-|`BOOTMAGIC_KEY_EE_HANDS_LEFT` |`KC_L` |Set "Left Hand" for EE_HANDS handedness |
-|`BOOTMAGIC_KEY_EE_HANDS_RIGHT` |`KC_R` |Set "Right Hand" for EE_HANDS handedness |
-|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock |
-|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control |
-|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) |
-|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)|
-|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) |
-|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping `
and Escape |
-|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace |
-|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer |
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer |
-
# Bootmagic Lite :id=bootmagic-lite
-In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+The Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button, giving you a way to jump into the bootloader
-To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
+On some keyboards Bootmagic Lite is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
```make
-BOOTMAGIC_ENABLE = lite
+BOOTMAGIC_ENABLE = yes
```
+?> You may see `lite` being used in place of `yes`.
+
Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
```c
@@ -142,7 +21,7 @@ By default, these are set to 0 and 0, which is usually the "ESC" key on a majori
And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
-!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
+!> Using Bootmagic Lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
## Split Keyboards
@@ -174,4 +53,10 @@ void bootmagic_lite(void) {
}
```
-You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
+You can additional feature here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
+
+## Addenda
+
+To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic.md).
+
+The Command feature, formerly known as Magic, also allows you to control different aspects of your keyboard. While it shares some functionality with Magic Keycodes, it also allows you to do things that Magic Keycodes cannot, such as printing version information to the console. For more information, see [Command](feature_command.md).
--
cgit v1.2.3