flashing.md (21866B)
1 # Flashing Instructions and Bootloader Information 2 3 There are quite a few different types of bootloaders that keyboards use, and almost all of them use their own flashing method and tools. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to support as many of them as possible, but this article will describe the different types of bootloaders, and available methods for flashing them. 4 5 For AVR-based keyboards, QMK will automatically calculate if your `.hex` file is the right size to be flashed to the device based on the `BOOTLOADER` value set in `rules.mk`, and output the total size in bytes (along with the max). 6 7 You will also be able to use the CLI to flash your keyboard, by running: 8 ``` 9 $ qmk flash -kb <keyboard> -km <keymap> 10 ``` 11 See the [`qmk flash`](cli_commands#qmk-flash) documentation for more information. 12 13 ## Atmel DFU 14 15 Atmel's DFU bootloader comes on all USB AVRs by default (except for 16/32U4RC), and is used by many keyboards that have their own ICs on their PCBs (older OLKB boards, Clueboards). Some keyboards may also use LUFA's DFU bootloader, or QMK's fork of it (newer OLKB boards), that adds in additional features specific to that hardware. 16 17 To ensure compatibility with the DFU bootloader, make sure this block is present in your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead): 18 19 ```make 20 # Bootloader selection 21 BOOTLOADER = atmel-dfu 22 ``` 23 24 Compatible flashers: 25 26 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 27 * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` target in QMK (recommended command line) 28 ``` 29 dfu-programmer <mcu> erase --force 30 dfu-programmer <mcu> flash --force <filename> 31 dfu-programmer <mcu> reset 32 ``` 33 34 Flashing sequence: 35 36 1. Enter the bootloader using any of the following methods: 37 * Press the `QK_BOOT` keycode 38 * Press the `RESET` button on the PCB if available 39 * Short RST to GND quickly 40 2. Wait for the OS to detect the device 41 3. Erase the flash memory (will be done automatically if using the Toolbox or CLI/`make` command) 42 4. Flash a .hex file 43 5. Reset the device into application mode (will be done automatically as above) 44 45 ### QMK DFU 46 47 QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU) that additionally performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. To enable these features, add the following defines to your `config.h`: 48 49 ```c 50 #define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW 51 #define QMK_ESC_INPUT D5 // ROW pin if COL2ROW 52 // Optional: 53 //#define QMK_LED E6 54 //#define QMK_SPEAKER C6 55 ``` 56 Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic](features/bootmagic), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. 57 58 The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. 59 60 To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`. 61 62 ### `make` Targets 63 64 * `:dfu`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware. 65 * `:dfu-split-left` and `:dfu-split-right`: Flashes the firmware as with `:dfu`, but also sets the handedness setting in EEPROM. This is ideal for Elite-C-based split keyboards. 66 67 ## Caterina 68 69 Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) or a variant of it (any keyboard built with a Pro Micro or clone, and the Pololu A-Star), and uses the AVR109 protocol to communicate through virtual serial. 70 71 To ensure compatibility with the Caterina bootloader, make sure this block is present in your `rules.mk`: 72 73 ```make 74 # Bootloader selection 75 BOOTLOADER = caterina 76 ``` 77 78 Compatible flashers: 79 80 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 81 * [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) 82 * [avrdude](https://www.nongnu.org/avrdude/) with the `avr109` programmer / `:avrdude` target in QMK (recommended command line) 83 ``` 84 avrdude -p <mcu> -c avr109 -P <serialport> -U flash:w:<filename>:i 85 ``` 86 87 Flashing sequence: 88 89 1. Enter the bootloader using any of the following methods (you only have 7 seconds to flash once it enters; some variants may require you to reset twice within 750 milliseconds): 90 * Press the `QK_BOOT` keycode 91 * Press the `RESET` button on the PCB if available 92 * Short RST to GND quickly 93 2. Wait for the OS to detect the device 94 3. Flash a .hex file 95 4. Wait for the device to reset automatically 96 97 ### `make` Targets 98 99 * `:avrdude`: Checks every 5 seconds until a Caterina device is available (by detecting a new COM port), and then flashes the firmware. 100 * `:avrdude-loop`: Flashes the firmware as with `:avrdude`, but after each device is flashed, will attempt to flash again. This is useful for bulk flashing. Hit Ctrl+C to escape the loop. 101 * `:avrdude-split-left` and `:avrdude-split-right`: Flashes the firmware as with `:avrdude`, but also sets the handedness setting in EEPROM. This is ideal for Pro Micro-based split keyboards. 102 103 ## HalfKay 104 105 HalfKay is a super-slim bootloader developed by PJRC that presents itself as an HID device (which requires no additional driver), and comes preflashed on all Teensys, namely the 2.0. It is currently closed-source, and thus once overwritten (eg. via ISP flashing another bootloader), cannot be restored. 106 107 To ensure compatibility with the Halfkay bootloader, make sure this block is present in your `rules.mk`: 108 109 ```make 110 # Bootloader selection 111 BOOTLOADER = halfkay 112 ``` 113 114 Compatible flashers: 115 116 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 117 * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) 118 * [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / `:teensy` target in QMK (recommended command line) 119 ``` 120 teensy_loader_cli -v -mmcu=<mcu> <filename> 121 ``` 122 123 Flashing sequence: 124 125 1. Enter the bootloader using any of the following methods (you only have 7 seconds to flash once it enters): 126 * Press the `QK_BOOT` keycode 127 * Press the `RESET` button on the Teensy or PCB if available 128 * short RST to GND quickly 129 2. Wait for the OS to detect the device 130 3. Flash a .hex file 131 4. Reset the device into application mode (may be done automatically) 132 133 ## USBasploader 134 135 USBasploader is a bootloader originally by [Objective Development](https://www.obdev.at/products/vusb/usbasploader.html). It emulates a USBasp ISP programmer and is used in some non-USB AVR chips such as the ATmega328P, which run V-USB. 136 137 To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`: 138 139 ```make 140 # Bootloader selection 141 BOOTLOADER = usbasploader 142 ``` 143 144 Compatible flashers: 145 146 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 147 * [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) 148 * [avrdude](https://www.nongnu.org/avrdude/) with the `usbasp` programmer / `:usbasp` target in QMK (recommended command line) 149 ``` 150 avrdude -p <mcu> -c usbasp -U flash:w:<filename>:i 151 ``` 152 153 Flashing sequence: 154 155 1. Enter the bootloader using any of the following methods: 156 * Press the `QK_BOOT` keycode 157 * Keep the `BOOT` button held while quickly tapping the `RESET` button on the PCB 158 2. Wait for the OS to detect the device 159 3. Flash a .hex file 160 4. Press the `RESET` button on the PCB or short RST to GND 161 162 ## BootloadHID 163 164 BootloadHID is a USB bootloader for AVR microcontrollers. It presents itself as an HID input device, much like HalfKay, and can therefore be run without installing any driver on Windows. 165 166 To ensure compatibility with the bootloadHID bootloader, make sure this block is present in your `rules.mk`: 167 168 ```make 169 # Bootloader selection 170 BOOTLOADER = bootloadhid 171 ``` 172 173 Compatible flashers: 174 175 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 176 * [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) 177 * [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / `:bootloadhid` target in QMK (recommended command line) 178 ``` 179 bootloadHID -r <filename> 180 ``` 181 182 Flashing sequence: 183 184 1. Enter the bootloader using any of the following methods: 185 * Tap the `QK_BOOT` keycode 186 * Hold the salt key while plugging the keyboard in - for PS2AVRGB boards, this is usually the key connected to MCU pins A0 and B0, otherwise it will be documented in your keyboard's readme 187 2. Wait for the OS to detect the device 188 3. Flash a .hex file 189 4. Reset the device into application mode (may be done automatically) 190 191 ### QMK HID 192 193 QMK maintains [a fork of the LUFA HID bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/HID), which uses a USB HID Endpoint for flashing in the way that the PJRC's Teensy Loader flasher and HalfKay bootloader work. Additionally, it performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. 194 195 To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`: 196 197 ```make 198 # Bootloader selection 199 BOOTLOADER = qmk-hid 200 ``` 201 202 To enable the additional features, add the following defines to your `config.h`: 203 204 ```c 205 #define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW 206 #define QMK_ESC_INPUT D5 // ROW pin if COL2ROW 207 // Optional: 208 //#define QMK_LED E6 209 //#define QMK_SPEAKER C6 210 ``` 211 212 Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic](features/bootmagic), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. 213 214 The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. 215 216 To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`. 217 218 Compatible flashers: 219 220 * TBD 221 * Currently, you need to either use the [Python script](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), or compile [`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp), from the LUFA repo. Homebrew may (will) have support for this directly (via `brew install qmk/qmk/hid_bootloader_cli`). 222 223 Flashing sequence: 224 225 1. Enter the bootloader using any of the following methods: 226 * Press the `QK_BOOT` keycode 227 * Press the `RESET` button on the PCB if available 228 * short RST to GND quickly 229 2. Wait for the OS to detect the device 230 3. Flash a .hex file 231 4. Reset the device into application mode (may be done automatically) 232 233 ### `make` Targets 234 235 * `:qmk-hid`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware. 236 237 ## STM32/APM32 DFU 238 239 All USB-capable STM32 and APM32 MCUs, except for a small handful (such as STM32F103 -- see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted. 240 241 To ensure compatibility with the STM32-DFU bootloader, make sure this block is present in your `rules.mk` (optionally with `apm32-dfu` instead): 242 243 ```make 244 # Bootloader selection 245 BOOTLOADER = stm32-dfu 246 ``` 247 248 Compatible flashers: 249 250 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 251 * [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line) 252 ``` 253 dfu-util -a 0 -d 0483:DF11 -s 0x8000000:leave -D <filename> 254 ``` 255 256 Flashing sequence: 257 258 1. Enter the bootloader using any of the following methods: 259 * Tap the `QK_BOOT` keycode (may not work on STM32F042 devices) 260 * If a reset circuit is present, tap the `RESET` button on the PCB; some boards may also have a toggle switch that must be flipped 261 * Otherwise, you need to bridge `BOOT0` to VCC (via `BOOT0` button or jumper), short `RESET` to GND (via `RESET` button or jumper), and then let go of the `BOOT0` bridge 262 2. Wait for the OS to detect the device 263 3. Flash a .bin file 264 4. Reset the device into application mode (may be done automatically) 265 266 ### `make` Targets 267 268 * `:dfu-util`: Waits until an STM32 bootloader device is available, and then flashes the firmware. 269 * `:dfu-util-split-left` and `:dfu-util-split-right`: Flashes the firmware as with `:dfu-util`, but also sets the handedness setting in EEPROM. This is ideal for Proton-C-based split keyboards. 270 * `:st-link-cli`: Allows you to flash the firmware via the ST-Link CLI utility, rather than dfu-util. Requires an ST-Link dongle. 271 * `:st-flash`: Allows you to flash the firmware via the `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink), rather than dfu-util. Requires an ST-Link dongle. 272 273 ## STM32duino 274 275 This bootloader is used almost exclusively for STM32F103 boards, as they do not come with a USB DFU bootloader. The source code and prebuilt binaries can be found [here](https://github.com/rogerclarkmelbourne/STM32duino-bootloader). 276 277 To ensure compatibility with the STM32duino bootloader, make sure this block is present in your `rules.mk`: 278 279 ```make 280 # Bootloader selection 281 BOOTLOADER = stm32duino 282 ``` 283 284 Compatible flashers: 285 286 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 287 * [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line) 288 ``` 289 dfu-util -a 2 -d 1EAF:0003 -D <filename> 290 ``` 291 292 Flashing sequence: 293 294 1. Enter the bootloader using any of the following methods: 295 * Tap the `QK_BOOT` keycode 296 * If a reset circuit is present, tap the `RESET` button on the PCB 297 * Otherwise, you need to bridge `BOOT0` to VCC (via `BOOT0` button or jumper), short `RESET` to GND (via `RESET` button or jumper), and then let go of the `BOOT0` bridge 298 2. Wait for the OS to detect the device 299 3. Flash a .bin file 300 4. Reset the device into application mode (may be done automatically) 301 302 ## Kiibohd DFU 303 304 Keyboards produced by Input Club use NXP Kinetis microcontrollers rather than STM32, and come with their own [custom bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader), however the process and protocol is largely the same. 305 306 The `rules.mk` setting for this bootloader is `kiibohd`, but since this bootloader is limited to Input Club boards, it should not be necessary to set at keymap or user level. 307 308 Compatible flashers: 309 310 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) 311 * [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line) 312 ``` 313 dfu-util -a 0 -d 1C11:B007 -D <filename> 314 ``` 315 316 Flashing sequence: 317 318 1. Enter the bootloader using any of the following methods: 319 * Tap the `QK_BOOT` keycode 320 * Press the `RESET` button on the PCB 321 2. Wait for the OS to detect the device 322 3. Flash a .bin file 323 4. Reset the device into application mode (may be done automatically) 324 325 ## WB32 DFU 326 327 Some keyboards produced for several commercial brands (GMMK, Akko, MonsGeek, Inland) use this bootloader. The `wb32-dfu-updater` utility is bundled with [QMK MSYS](https://msys.qmk.fm/) and [Glorious's build of QMK Toolbox](https://www.gloriousgaming.com/blogs/guides-resources/gmmk-2-qmk-installation-guide). If neither of these flashing methods is available for your OS, you will likely need to [compile the CLI version from source](https://github.com/WestberryTech/wb32-dfu-updater). 328 329 The `info.json` setting for this bootloader is `wb32-dfu`. 330 331 Compatible flashers: 332 333 * [Glorious's build of QMK Toolbox](https://www.gloriousgaming.com/blogs/guides-resources/gmmk-2-qmk-installation-guide) (recommended GUI) 334 * [wb32-dfu-updater_cli](https://github.com/WestberryTech/wb32-dfu-updater) / `:flash` target in QMK (recommended command line) 335 ``` 336 wb32-dfu-updater_cli -t -s 0x8000000 -D <filename> 337 ``` 338 339 Flashing sequence: 340 341 1. Enter the bootloader using any of the following methods: 342 * Tap the `QK_BOOT` keycode 343 * Press the `RESET` button on the PCB 344 2. Wait for the OS to detect the device 345 3. Flash a .bin file 346 4. Reset the device into application mode (may be done automatically) 347 348 ## AT32 DFU 349 350 All AT32 MCUs come preloaded with a factory bootloader that cannot be modified nor deleted. 351 352 To ensure compatibility with the AT32-DFU bootloader, make sure this block is present in your `rules.mk`: 353 354 ```make 355 # Bootloader selection 356 BOOTLOADER = at32-dfu 357 ``` 358 359 Compatible flashers: 360 361 * [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line) 362 ``` 363 dfu-util -a 0 -d 2E3C:DF11 -s 0x8000000:leave -D <filename> 364 ``` 365 366 Flashing sequence: 367 368 1. Enter the bootloader using any of the following methods: 369 * Tap the `QK_BOOT` keycode 370 * If a reset circuit is present, tap the `RESET` button on the PCB; some boards may also have a toggle switch that must be flipped 371 * Otherwise, you need to bridge `BOOT0` to VCC (via `BOOT0` button or jumper), short `RESET` to GND (via `RESET` button or jumper), and then let go of the `BOOT0` bridge 372 2. Wait for the OS to detect the device 373 3. Flash a .bin file 374 4. Reset the device into application mode (may be done automatically) 375 376 ### `make` Targets 377 378 * `:dfu-util`: Waits until an AT32 bootloader device is available, and then flashes the firmware. 379 * `:dfu-util-split-left` and `:dfu-util-split-right`: Flashes the firmware as with `:dfu-util`, but also sets the handedness setting in EEPROM. 380 381 ## tinyuf2 382 383 Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on F303/F401/F411. 384 385 The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level. 386 387 To ensure compatibility with the tinyuf2 bootloader, make sure this block is present in your `rules.mk`: 388 389 ```make 390 # Bootloader selection 391 BOOTLOADER = tinyuf2 392 ``` 393 394 Compatible flashers: 395 396 * Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_. 397 398 Flashing sequence: 399 400 1. Enter the bootloader using any of the following methods: 401 * Tap the `QK_BOOT` keycode 402 * Double-tap the `nRST` button on the PCB. 403 2. Wait for the OS to detect the device 404 3. Copy the .uf2 file to the new USB disk 405 4. Wait for the keyboard to become available 406 407 or 408 409 CLI Flashing sequence: 410 411 1. Enter the bootloader using any of the following methods: 412 * Tap the `QK_BOOT` keycode 413 * Double-tap the `nRST` button on the PCB. 414 2. Wait for the OS to detect the device 415 3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/blackpill_f411_tinyuf2 --keymap default` 416 4. Wait for the keyboard to become available 417 418 ### `make` Targets 419 420 * `:uf2-split-left` and `:uf2-split-right`: Flashes the firmware but also sets the handedness setting in EEPROM by generating a side specific firmware. 421 422 ## uf2boot 423 424 Keyboards may opt into supporting the uf2boot bootloader. This is currently only supported on F103. 425 426 The `rules.mk` setting for this bootloader is `uf2boot`, and can be specified at the keymap or user level. 427 428 To ensure compatibility with the uf2boot bootloader, make sure this block is present in your `rules.mk`: 429 430 ```make 431 # Bootloader selection 432 BOOTLOADER = uf2boot 433 ``` 434 435 Compatible flashers: 436 437 * Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_. 438 439 Flashing sequence: 440 441 1. Enter the bootloader using any of the following methods: 442 * Tap the `QK_BOOT` keycode 443 * Double-tap the `nRST` button on the PCB. 444 2. Wait for the OS to detect the device 445 3. Copy the .uf2 file to the new USB disk 446 4. Wait for the keyboard to become available 447 448 or 449 450 CLI Flashing sequence: 451 452 1. Enter the bootloader using any of the following methods: 453 * Tap the `QK_BOOT` keycode 454 * Double-tap the `nRST` button on the PCB. 455 2. Wait for the OS to detect the device 456 3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/bluepill_uf2boot --keymap default` 457 4. Wait for the keyboard to become available 458 459 ### `make` Targets 460 461 * `:uf2-split-left` and `:uf2-split-right`: Flashes the firmware but also sets the handedness setting in EEPROM by generating a side specific firmware. 462 463 ## Raspberry Pi RP2040 UF2 464 465 The `rules.mk` setting for this bootloader is `rp2040`, and can be specified at the keymap or user level. 466 467 To ensure compatibility with the rp2040 bootloader, make sure this block is present in your `rules.mk`: 468 469 ```make 470 # Bootloader selection 471 BOOTLOADER = rp2040 472 ``` 473 474 Compatible flashers: 475 476 * Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_. 477 478 Flashing sequence: 479 480 1. Enter the bootloader using any of the following methods: 481 * Tap the `QK_BOOT` keycode 482 * Hold the `BOOTSEL` button on the PCB while plugin in the usb cable. 483 * Double-tap the `RESET` button on the PCB<sup>1</sup>. 484 2. Wait for the OS to detect the device 485 3. Copy the .uf2 file to the new USB disk 486 4. Wait for the keyboard to become available 487 488 or 489 490 CLI Flashing sequence: 491 492 1. Enter the bootloader using any of the following methods: 493 * Tap the `QK_BOOT` keycode 494 * Hold the `BOOTSEL` button on the PCB while plugin in the usb cable. 495 * Double-tap the `RESET` button on the PCB<sup>1</sup>. 496 2. Wait for the OS to detect the device 497 3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/rpi_pico --keymap default` 498 4. Wait for the keyboard to become available 499 500 <sup>1</sup>: This works only if the controller has been flashed with QMK Firmware with `RP2040_BOOTLOADER_DOUBLE_TAP_RESET` defined.