aboutsummaryrefslogtreecommitdiff
path: root/docs/flashing.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/flashing.md')
-rw-r--r--docs/flashing.md132
1 files changed, 111 insertions, 21 deletions
diff --git a/docs/flashing.md b/docs/flashing.md
index 3b4582f005..98841c1aac 100644
--- 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:
@@ -119,6 +142,73 @@ Flashing sequence:
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
+## USBasploader
+
+USBasploader is a bootloader developed by matrixstorm. It is used in some non-USB AVR chips such as the ATmega328P, which run V-USB.
+
+To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
+
+```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:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [avrdude](http://www.nongnu.org/avrdude/) with the `usbasp` programmer
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+Flashing sequence:
+
+1. Press the `RESET` keycode, or keep the boot pin shorted to GND while quickly shorting RST to GND
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## BootloadHID
+
+BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requires no kernel level driver on Windows and can therefore be run without installing any DLLs.
+
+To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
+
+```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:
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (recommended Windows GUI)
+* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` in QMK (recommended command line)
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+ * Tap the `RESET` keycode (may not work on all devices)
+ * Hold the salt key while plugging the keyboard in (usually documented within keyboard readme)
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+or:
+
+ make <keyboard>:<keymap>:bootloadHID
+
## STM32
All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.
@@ -146,7 +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.
-* `:dfu-util-wait` - This works like the default command, but it gives you a (configurable) 10 second timeout before it attempts to flash the firmware. You can use `TIME_DELAY=20` from the command line to change the timeout.
- * Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
+* `: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.