[Keyboard] Add hand swap config matrix for preonic rev 3 (#7460)

[qmk_firmware.git] / docs / flashing.md

diff --git a/docs/flashing.md b/docs/flashing.md
index b47a5ebf8e14c79c5cc6e365c906b124372af2c6..98841c1aacd70f2418b04abc53400df42dc90369 100644 (file)
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -10,11 +10,17 @@ Atmel's DFU bootloader comes on all atmega32u4 chips by default, and is used by
 
 To ensure compatibility with the DFU bootloader, make sure this block is present your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead):
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = atmel-dfu
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
 
 Compatible flashers:
 
@@ -64,11 +70,17 @@ Arduino boards and their clones use the [Caterina bootloader](https://github.com
 
 To ensure compatibility with the Caterina bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = caterina
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
 
 Compatible flashers:
 
@@ -87,11 +99,16 @@ or
 
     make <keyboard>:<keymap>:avrdude
 
-or if you want to flash multiple boards, use the following command
 
-    make <keyboard>:<keymap>:avrdude-loop
+#### Caterina commands
+
+There are a number of DFU commands that you can use to flash firmware to a DFU device:
+
+* `:avrdude` - This is the normal option which waits until a Caterina device is available (by detecting a new COM port), and then flashes the firmware.
+* `:avrdude-loop` - This runs the same command as `:avrdude`, but after each device is flashed, it will attempt to flash again.  This is useful for bulk flashing. _This requires you to manually escape the loop by hitting Ctrl+C._
+* `:avrdude-split-left` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
+* `:avrdude-split-right` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
 
-When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
 
 
 ## Halfkay
@@ -100,11 +117,17 @@ Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on al
 
 To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = halfkay
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
 
 Compatible flashers:
 
@@ -125,11 +148,17 @@ USBasploader is a bootloader developed by matrixstorm. It is used in some non-US
 
 To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = USBasp
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
 
 Compatible flashers:
 
@@ -150,11 +179,17 @@ BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requ
 
 To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = bootloadHID
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
 
 Compatible flashers:
 
@@ -201,5 +236,7 @@ Flashing sequence:
 
 There are a number of DFU commands that you can use to flash firmware to a STM32 device:
 
-* `:dfu-util` - The default command for flashing to STM32 devices.
-* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
+* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader device is present.
+* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
+* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
+* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.