diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/feature_bootmagic.md | 52 |
1 files changed, 51 insertions, 1 deletions
diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index 586b5d8370..20c76d9b74 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -11,7 +11,15 @@ There are three separate but related features that allow you to change the behav 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 = yes +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`) ideally 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 @@ -99,3 +107,45 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes |`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 + +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. + +To enable this version of Bootmagic, you need to enable it in your `rules.mk` with: + +```make +BOOTMAGIC_ENABLE = lite +``` + +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 +#define BOOTMAGIC_LITE_ROW 0 +#define BOOTMAGIC_LITE_COLUMN 1 +``` + +By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards. + +And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. + +## Advanced Bootmagic Lite + +The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed. + +To replace the function, all you need to do is add something like this to your code: + +```c +void bootmagic_lite(void) { + matrix_scan(); + wait_ms(DEBOUNCING_DELAY * 2); + matrix_scan(); + + if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) { + // Jump to bootloader. + bootloader_jump(); + } +} +``` + +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. |