aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorJames Young <18669334+noroadsleft@users.noreply.github.com>2021-08-06 23:59:56 -0700
committerGitHub <noreply@github.com>2021-08-06 23:59:56 -0700
commita03aa301def77c867ae6c6c840f7fc82b26d91d6 (patch)
treea6bc1e2ce769edfd3ce3e25c86ece48d1ca14853 /docs
parent0bc9090b1f98038b2bf4f648618d6143dcd93c82 (diff)
downloadqmk_firmware-a03aa301def77c867ae6c6c840f7fc82b26d91d6.tar.gz
qmk_firmware-a03aa301def77c867ae6c6c840f7fc82b26d91d6.zip
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
Diffstat (limited to 'docs')
-rw-r--r--docs/_summary.md3
-rw-r--r--docs/custom_quantum_functions.md2
-rw-r--r--docs/driver_installation_zadig.md4
-rw-r--r--docs/faq_keymap.md2
-rw-r--r--docs/feature_bootmagic.md141
-rw-r--r--docs/feature_command.md2
-rw-r--r--docs/flashing.md4
-rw-r--r--docs/hardware_keyboard_guidelines.md4
-rw-r--r--docs/keycodes.md72
-rw-r--r--docs/keycodes_magic.md35
-rw-r--r--docs/ref_functions.md2
-rw-r--r--docs/syllabus.md2
12 files changed, 97 insertions, 176 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 6c39aeda0..7e6c06213 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -60,6 +60,7 @@
60 * [Language-Specific Keycodes](reference_keymap_extras.md) 60 * [Language-Specific Keycodes](reference_keymap_extras.md)
61 * [Modifier Keys](feature_advanced_keycodes.md) 61 * [Modifier Keys](feature_advanced_keycodes.md)
62 * [Quantum Keycodes](quantum_keycodes.md) 62 * [Quantum Keycodes](quantum_keycodes.md)
63 * [Magic Keycodes](keycodes_magic.md)
63 64
64 * Advanced Keycodes 65 * Advanced Keycodes
65 * [Command](feature_command.md) 66 * [Command](feature_command.md)
@@ -103,7 +104,7 @@
103 * [RGB Matrix](feature_rgb_matrix.md) 104 * [RGB Matrix](feature_rgb_matrix.md)
104 * [Audio](feature_audio.md) 105 * [Audio](feature_audio.md)
105 * [Bluetooth](feature_bluetooth.md) 106 * [Bluetooth](feature_bluetooth.md)
106 * [Bootmagic](feature_bootmagic.md) 107 * [Bootmagic Lite](feature_bootmagic.md)
107 * [Custom Matrix](custom_matrix.md) 108 * [Custom Matrix](custom_matrix.md)
108 * [DIP Switch](feature_dip_switch.md) 109 * [DIP Switch](feature_dip_switch.md)
109 * [Encoders](feature_encoders.md) 110 * [Encoders](feature_encoders.md)
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index 30c637bb4..494e76996 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -382,7 +382,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
382 } 382 }
383} 383}
384``` 384```
385And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. 385And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic Lite](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued.
386 386
387```c 387```c
388void eeconfig_init_user(void) { // EEPROM is getting reset! 388void eeconfig_init_user(void) { // EEPROM is getting reset!
diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md
index e4db069f1..137ec8ad6 100644
--- a/docs/driver_installation_zadig.md
+++ b/docs/driver_installation_zadig.md
@@ -8,8 +8,8 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have
8 8
9## Installation 9## Installation
10 10
11Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in. 11Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
12Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure. 12Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
13 13
14To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button. 14To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
15Alternatively, hold `BOOT` while inserting the USB cable. 15Alternatively, hold `BOOT` while inserting the USB cable.
diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md
index c30e17990..3de4cd240 100644
--- a/docs/faq_keymap.md
+++ b/docs/faq_keymap.md
@@ -31,7 +31,7 @@ QMK has two features, Bootmagic and Command, which allow you to change the behav
31 31
32As 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: 32As 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:
33 33
34* [Bootmagic](feature_bootmagic.md) 34* [Bootmagic Lite](feature_bootmagic.md)
35* [Command](feature_command.md) 35* [Command](feature_command.md)
36 36
37## The Menu Key Isn't Working 37## The Menu Key Isn't Working
diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md
index 4c655d8e1..6c66b0067 100644
--- a/docs/feature_bootmagic.md
+++ b/docs/feature_bootmagic.md
@@ -1,136 +1,15 @@
1# Bootmagic
2
3There 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.
4
5**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.
6
7**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.
8
9**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).
10
11On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
12
13```make
14BOOTMAGIC_ENABLE = full
15```
16
17?> 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.
18
19Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
20
21```make
22BOOTMAGIC_ENABLE = lite
23```
24
25## Hotkeys
26
27Hold 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.
28
29|Hotkey |Description |
30|------------------|---------------------------------------------|
31|Escape |Ignore Bootmagic configuration in EEPROM |
32|`B` |Enter the bootloader |
33|`D` |Toggle debugging over serial |
34|`X` |Toggle key matrix debugging |
35|`K` |Toggle keyboard debugging |
36|`M` |Toggle mouse debugging |
37|`L` |Set "Left Hand" for EE_HANDS handedness |
38|`R` |Set "Right Hand" for EE_HANDS handedness |
39|Backspace |Clear the EEPROM |
40|Caps Lock |Toggle treating Caps Lock as Left Control |
41|Left Control |Toggle swapping Caps Lock and Left Control |
42|Left Alt |Toggle swapping Left Alt and Left GUI |
43|Right Alt |Toggle swapping Right Alt and Right GUI |
44|Left GUI |Toggle the GUI keys (useful when gaming) |
45|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
46|`\` |Toggle swapping `\` and Backspace |
47|`N` |Toggle N-Key Rollover (NKRO) |
48|`0` |Make layer 0 the default layer |
49|`1` |Make layer 1 the default layer |
50|`2` |Make layer 2 the default layer |
51|`3` |Make layer 3 the default layer |
52|`4` |Make layer 4 the default layer |
53|`5` |Make layer 5 the default layer |
54|`6` |Make layer 6 the default layer |
55|`7` |Make layer 7 the default layer |
56
57## Keycodes :id=keycodes
58
59|Key |Aliases |Description |
60|----------------------------------|---------|--------------------------------------------------------------------------|
61|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
62|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
63|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
64|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
65|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
66|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
67|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
68|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
69|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
70|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
71|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
72|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
73|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
74|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
75|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
76|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
77|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
78|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
79|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
80|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
81|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
82|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
83|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
84|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
85|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
86|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
87|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
88|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
89|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
90
91## Configuration
92
93If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
94
95|Define |Default |Description |
96|----------------------------------------|-------------|---------------------------------------------------|
97|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key |
98|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM |
99|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration |
100|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader |
101|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial |
102|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging |
103|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging |
104|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging |
105|`BOOTMAGIC_KEY_EE_HANDS_LEFT` |`KC_L` |Set "Left Hand" for EE_HANDS handedness |
106|`BOOTMAGIC_KEY_EE_HANDS_RIGHT` |`KC_R` |Set "Right Hand" for EE_HANDS handedness |
107|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock |
108|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control |
109|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) |
110|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)|
111|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) |
112|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping <code>&#96;</code> and Escape |
113|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace |
114|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) |
115|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer |
116|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer |
117|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer |
118|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer |
119|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer |
120|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer |
121|`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer |
122|`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer |
123
124# Bootmagic Lite :id=bootmagic-lite 1# Bootmagic Lite :id=bootmagic-lite
125 2
126In 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. 3The 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
127 4
128To enable this version of Bootmagic, you need to enable it in your `rules.mk` with: 5On some keyboards Bootmagic Lite is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
129 6
130```make 7```make
131BOOTMAGIC_ENABLE = lite 8BOOTMAGIC_ENABLE = yes
132``` 9```
133 10
11?> You may see `lite` being used in place of `yes`.
12
134Additionally, 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: 13Additionally, 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:
135 14
136```c 15```c
@@ -142,7 +21,7 @@ By default, these are set to 0 and 0, which is usually the "ESC" key on a majori
142 21
143And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. 22And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
144 23
145!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved. 24!> Using Bootmagic Lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
146 25
147## Split Keyboards 26## Split Keyboards
148 27
@@ -174,4 +53,10 @@ void bootmagic_lite(void) {
174} 53}
175``` 54```
176 55
177You 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. 56You 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.
57
58## Addenda
59
60To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic.md).
61
62The 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).
diff --git a/docs/feature_command.md b/docs/feature_command.md
index a4ce3f5ae..830006613 100644
--- a/docs/feature_command.md
+++ b/docs/feature_command.md
@@ -1,6 +1,6 @@
1# Command 1# Command
2 2
3Command, formerly known as Magic, 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#keycodes). Wherever possible we encourage you to use that feature instead of Command. 3Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic Lite](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Magic Keycodes](keycodes_magic.md). Wherever possible we encourage you to use that feature instead of Command.
4 4
5On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`: 5On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:
6 6
diff --git a/docs/flashing.md b/docs/flashing.md
index da3c64c4a..fae9c5d1c 100644
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -48,7 +48,7 @@ QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tr
48//#define QMK_LED E6 48//#define QMK_LED E6
49//#define QMK_SPEAKER C6 49//#define QMK_SPEAKER C6
50``` 50```
51Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. 51Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
52 52
53The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. 53The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
54 54
@@ -192,7 +192,7 @@ To enable the additional features, add the following defines to your `config.h`:
192//#define QMK_SPEAKER C6 192//#define QMK_SPEAKER C6
193``` 193```
194 194
195Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. 195Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
196 196
197The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. 197The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
198 198
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index 4f3271504..7630b44e0 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -189,9 +189,9 @@ Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm re
189 189
190Given 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. 190Given 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.
191 191
192### Bootmagic and Command 192### Magic Keycodes and Command
193 193
194[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. 194[Magic Keycodes](keycodes_magic.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.
195 195
196By 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. 196By 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.
197 197
diff --git a/docs/keycodes.md b/docs/keycodes.md
index 85988f185..a134c5a1b 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -257,42 +257,6 @@ See also: [Backlighting](feature_backlight.md)
257|`BL_DEC` |Decrease the backlight level | 257|`BL_DEC` |Decrease the backlight level |
258|`BL_BRTG`|Toggle backlight breathing | 258|`BL_BRTG`|Toggle backlight breathing |
259 259
260## Bootmagic :id=bootmagic
261
262See also: [Bootmagic](feature_bootmagic.md)
263
264|Key |Aliases |Description |
265|----------------------------------|---------|--------------------------------------------------------------------------|
266|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
267|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
268|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
269|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
270|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
271|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
272|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
273|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
274|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
275|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
276|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
277|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
278|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
279|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
280|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
281|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
282|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
283|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
284|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
285|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
286|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
287|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
288|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
289|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
290|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
291|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
292|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
293|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
294|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
295
296## Bluetooth :id=bluetooth 260## Bluetooth :id=bluetooth
297 261
298See also: [Bluetooth](feature_bluetooth.md) 262See also: [Bluetooth](feature_bluetooth.md)
@@ -354,6 +318,42 @@ See also: [Leader Key](feature_leader_key.md)
354|---------|------------------------| 318|---------|------------------------|
355|`KC_LEAD`|Begins a leader sequence| 319|`KC_LEAD`|Begins a leader sequence|
356 320
321## Magic Keycodes :id=magic-keycodes
322
323See also: [Magic Keycodes](keycodes_magic.md)
324
325|Key |Aliases |Description |
326|----------------------------------|---------|--------------------------------------------------------------------------|
327|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
328|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
329|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
330|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
331|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
332|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
333|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
334|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
335|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
336|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
337|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
338|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
339|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
340|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
341|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
342|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
343|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
344|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
345|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
346|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
347|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
348|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
349|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
350|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
351|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
352|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
353|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
354|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
355|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
356
357## MIDI :id=midi 357## MIDI :id=midi
358 358
359See also: [MIDI](feature_midi.md) 359See also: [MIDI](feature_midi.md)
diff --git a/docs/keycodes_magic.md b/docs/keycodes_magic.md
new file mode 100644
index 000000000..719d82031
--- /dev/null
+++ b/docs/keycodes_magic.md
@@ -0,0 +1,35 @@
1# Magic Keycodes :id=magic-keycodes
2
3**Magic Keycodes** are prefixed with `MAGIC_`, and allow you to access the functionality of the deprecated Bootmagic feature *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
4
5|Key |Aliases |Description |
6|----------------------------------|---------|--------------------------------------------------------------------------|
7|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
8|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
9|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
10|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
11|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
12|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
13|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
14|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
15|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
16|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
17|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
18|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
19|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
20|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
21|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
22|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
23|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
24|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
25|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
26|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
27|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
28|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
29|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
30|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
31|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
32|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
33|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
34|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
35|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
diff --git a/docs/ref_functions.md b/docs/ref_functions.md
index 27ae95aa9..c6185c870 100644
--- a/docs/ref_functions.md
+++ b/docs/ref_functions.md
@@ -93,7 +93,7 @@ And to do so, add `reset_keyboard()` to your function or macro, and this will re
93 93
94## Wiping the EEPROM (Persistent Storage) 94## Wiping the EEPROM (Persistent Storage)
95 95
96If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so. 96If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic Lite](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so.
97 97
98To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default. 98To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default.
99 99
diff --git a/docs/syllabus.md b/docs/syllabus.md
index b33bd9e72..ccb382c5d 100644
--- a/docs/syllabus.md
+++ b/docs/syllabus.md
@@ -54,7 +54,7 @@ Everything below here requires a lot of foundational knowledge. Besides being ab
54* **Advanced Features** 54* **Advanced Features**
55 * [Unicode](feature_unicode.md) 55 * [Unicode](feature_unicode.md)
56 * [API](api_overview.md) 56 * [API](api_overview.md)
57 * [Bootmagic](feature_bootmagic.md) 57 * [Bootmagic Lite](feature_bootmagic.md)
58* **Hardware** 58* **Hardware**
59 * [How Keyboards Work](how_keyboards_work.md) 59 * [How Keyboards Work](how_keyboards_work.md)
60 * [How A Keyboard Matrix Works](how_a_matrix_works.md) 60 * [How A Keyboard Matrix Works](how_a_matrix_works.md)
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-05 23:22:23 +0000