qmk

Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

feature_bootmagic.md (10879B)


      1 # Bootmagic
      2 
      3 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.
      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 
     11 On 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
     14 BOOTMAGIC_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 
     19 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:
     20 
     21 ```make
     22 BOOTMAGIC_ENABLE = lite
     23 ```
     24 
     25 ## Hotkeys
     26 
     27 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.
     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 |Backspace         |Clear the EEPROM                             |
     38 |Caps Lock         |Toggle treating Caps Lock as Left Control    |
     39 |Left Control      |Toggle swapping Caps Lock and Left Control   |
     40 |Left Alt          |Toggle swapping Left Alt and Left GUI        |
     41 |Right Alt         |Toggle swapping Right Alt and Right GUI      |
     42 |Left GUI          |Toggle the GUI keys (useful when gaming)     |
     43 |<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
     44 |`\`               |Toggle swapping `\` and Backspace            |
     45 |`N`               |Toggle N-Key Rollover (NKRO)                 |
     46 |`0`               |Make layer 0 the default layer               |
     47 |`1`               |Make layer 1 the default layer               |
     48 |`2`               |Make layer 2 the default layer               |
     49 |`3`               |Make layer 3 the default layer               |
     50 |`4`               |Make layer 4 the default layer               |
     51 |`5`               |Make layer 5 the default layer               |
     52 |`6`               |Make layer 6 the default layer               |
     53 |`7`               |Make layer 7 the default layer               |
     54 
     55 ## Keycodes
     56 
     57 |Keycode                           |Aliases  |Description                               |
     58 |----------------------------------|---------|------------------------------------------|
     59 |`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Left Control           |
     60 |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Left Control   |
     61 |`MAGIC_HOST_NKRO`                 |         |Force N-Key Rollover (NKRO) on            |
     62 |`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                            |
     63 |`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                       |
     64 |`MAGIC_NO_GUI`                    |         |Disable the GUI keys (useful when gaming) |
     65 |`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
     66 |`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
     67 |`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI                        |
     68 |`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap                   |
     69 |`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)|
     70 |`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI                       |
     71 |`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap                  |
     72 |`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
     73 |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
     74 |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
     75 |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock         |
     76 |`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape        |
     77 |`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape      |
     78 |`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and Left GUI                |
     79 |`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and Left GUI              |
     80 |`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and Right GUI              |
     81 |`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and Right GUI            |
     82 |`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and Left GUI            |
     83 |`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and Left GUI          |
     84 |`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and Right GUI          |
     85 |`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and Right GUI        |
     86 
     87 ## Configuration
     88 
     89 If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
     90 
     91 |Define                                  |Default      |Description                                        |
     92 |----------------------------------------|-------------|---------------------------------------------------|
     93 |`BOOTMAGIC_KEY_SALT`                    |`KC_SPACE`   |The Bootmagic key                                  |
     94 |`BOOTMAGIC_KEY_SKIP`                    |`KC_ESC`     |Ignore Bootmagic configuration in EEPROM           |
     95 |`BOOTMAGIC_KEY_EEPROM_CLEAR`            |`KC_BSPACE`  |Clear the EEPROM configuration                     |
     96 |`BOOTMAGIC_KEY_BOOTLOADER`              |`KC_B`       |Enter the bootloader                               |
     97 |`BOOTMAGIC_KEY_DEBUG_ENABLE`            |`KC_D`       |Toggle debugging over serial                       |
     98 |`BOOTMAGIC_KEY_DEBUG_MATRIX`            |`KC_X`       |Toggle matrix debugging                            |
     99 |`BOOTMAGIC_KEY_DEBUG_KEYBOARD`          |`KC_K`       |Toggle keyboard debugging                          |
    100 |`BOOTMAGIC_KEY_DEBUG_MOUSE`             |`KC_M`       |Toggle mouse debugging                             |
    101 |`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`   |`KC_LCTRL`   |Swap Left Control and Caps Lock                    |
    102 |`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`     |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control          |
    103 |`BOOTMAGIC_KEY_SWAP_LALT_LGUI`          |`KC_LALT`    |Toggle swapping Left Alt and Left GUI (for macOS)  |
    104 |`BOOTMAGIC_KEY_SWAP_RALT_RGUI`          |`KC_RALT`    |Toggle swapping Right Alt and Right GUI (for macOS)|
    105 |`BOOTMAGIC_KEY_NO_GUI`                  |`KC_LGUI`    |Toggle the GUI keys (useful when gaming)           |
    106 |`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`          |`KC_GRAVE`   |Toggle swapping <code>&#96;</code> and Escape      |
    107 |`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`  |Toggle swapping `\` and Backspace                  |
    108 |`BOOTMAGIC_HOST_NKRO`                   |`KC_N`       |Toggle N-Key Rollover (NKRO)                       |
    109 |`BOOTMAGIC_KEY_DEFAULT_LAYER_0`         |`KC_0`       |Make layer 0 the default layer                     |
    110 |`BOOTMAGIC_KEY_DEFAULT_LAYER_1`         |`KC_1`       |Make layer 1 the default layer                     |
    111 |`BOOTMAGIC_KEY_DEFAULT_LAYER_2`         |`KC_2`       |Make layer 2 the default layer                     |
    112 |`BOOTMAGIC_KEY_DEFAULT_LAYER_3`         |`KC_3`       |Make layer 3 the default layer                     |
    113 |`BOOTMAGIC_KEY_DEFAULT_LAYER_4`         |`KC_4`       |Make layer 4 the default layer                     |
    114 |`BOOTMAGIC_KEY_DEFAULT_LAYER_5`         |`KC_5`       |Make layer 5 the default layer                     |
    115 |`BOOTMAGIC_KEY_DEFAULT_LAYER_6`         |`KC_6`       |Make layer 6 the default layer                     |
    116 |`BOOTMAGIC_KEY_DEFAULT_LAYER_7`         |`KC_7`       |Make layer 7 the default layer                     |
    117 
    118 # Bootmagic Lite
    119 
    120 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.
    121 
    122 To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
    123 
    124 ```make
    125 BOOTMAGIC_ENABLE = lite
    126 ```
    127 
    128 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:
    129 
    130 ```c
    131 #define BOOTMAGIC_LITE_ROW 0
    132 #define BOOTMAGIC_LITE_COLUMN 1
    133 ```
    134 
    135 By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
    136 
    137 And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
    138 
    139 !> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
    140 
    141 ## Advanced Bootmagic Lite
    142 
    143 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.
    144 
    145 To replace the function, all you need to do is add something like this to your code:
    146 
    147 ```c
    148 void bootmagic_lite(void) {
    149     matrix_scan();
    150     wait_ms(DEBOUNCE * 2);
    151     matrix_scan();
    152 
    153     if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
    154       // Jump to bootloader.
    155       bootloader_jump();
    156     }
    157 }
    158 ```
    159 
    160 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.