auri.ee
keyboard stuff
1# Flashing Instructions and Bootloader Information
2
3There 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
5For 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
7You will also be able to use the CLI to flash your keyboard, by running:
8```
9$ qmk flash -kb <keyboard> -km <keymap>
10```
11See the [`qmk flash`](cli_commands#qmk-flash) documentation for more information.
12
13## Atmel DFU
14
15Atmel'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
17To 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
21BOOTLOADER = atmel-dfu
22```
23
24Compatible 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
34Flashing sequence:
35
361. 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
402. Wait for the OS to detect the device
413. Erase the flash memory (will be done automatically if using the Toolbox or CLI/`make` command)
424. Flash a .hex file
435. Reset the device into application mode (will be done automatically as above)
44
45### QMK DFU
46
47QMK 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```
56Currently 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
58The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
59
60To 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
69Arduino 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
71To ensure compatibility with the Caterina bootloader, make sure this block is present in your `rules.mk`:
72
73```make
74# Bootloader selection
75BOOTLOADER = caterina
76```
77
78Compatible 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
87Flashing sequence:
88
891. 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
932. Wait for the OS to detect the device
943. Flash a .hex file
954. 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
105HalfKay 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
107To ensure compatibility with the Halfkay bootloader, make sure this block is present in your `rules.mk`:
108
109```make
110# Bootloader selection
111BOOTLOADER = halfkay
112```
113
114Compatible 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
123Flashing sequence:
124
1251. 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
1292. Wait for the OS to detect the device
1303. Flash a .hex file
1314. Reset the device into application mode (may be done automatically)
132
133## USBasploader
134
135USBasploader 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
137To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
138
139```make
140# Bootloader selection
141BOOTLOADER = usbasploader
142```
143
144Compatible 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
153Flashing sequence:
154
1551. 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
1582. Wait for the OS to detect the device
1593. Flash a .hex file
1604. Press the `RESET` button on the PCB or short RST to GND
161
162## BootloadHID
163
164BootloadHID 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
166To ensure compatibility with the bootloadHID bootloader, make sure this block is present in your `rules.mk`:
167
168```make
169# Bootloader selection
170BOOTLOADER = bootloadhid
171```
172
173Compatible 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
182Flashing sequence:
183
1841. 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
1872. Wait for the OS to detect the device
1883. Flash a .hex file
1894. Reset the device into application mode (may be done automatically)
190
191### QMK HID
192
193QMK 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
195To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`:
196
197```make
198# Bootloader selection
199BOOTLOADER = qmk-hid
200```
201
202To 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
212Currently 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
214The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
215
216To 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
218Compatible 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
223Flashing sequence:
224
2251. 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
2292. Wait for the OS to detect the device
2303. Flash a .hex file
2314. 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
239All 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
241To 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
245BOOTLOADER = stm32-dfu
246```
247
248Compatible 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
256Flashing sequence:
257
2581. 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
2622. Wait for the OS to detect the device
2633. Flash a .bin file
2644. 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
275This 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
277To ensure compatibility with the STM32duino bootloader, make sure this block is present in your `rules.mk`:
278
279```make
280# Bootloader selection
281BOOTLOADER = stm32duino
282```
283
284Compatible 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
292Flashing sequence:
293
2941. 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
2982. Wait for the OS to detect the device
2993. Flash a .bin file
3004. Reset the device into application mode (may be done automatically)
301
302## Kiibohd DFU
303
304Keyboards 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
306The `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
308Compatible 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
316Flashing sequence:
317
3181. Enter the bootloader using any of the following methods:
319 * Tap the `QK_BOOT` keycode
320 * Press the `RESET` button on the PCB
3212. Wait for the OS to detect the device
3223. Flash a .bin file
3234. Reset the device into application mode (may be done automatically)
324
325## WB32 DFU
326
327Some 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
329The `info.json` setting for this bootloader is `wb32-dfu`.
330
331Compatible 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
339Flashing sequence:
340
3411. Enter the bootloader using any of the following methods:
342 * Tap the `QK_BOOT` keycode
343 * Press the `RESET` button on the PCB
3442. Wait for the OS to detect the device
3453. Flash a .bin file
3464. Reset the device into application mode (may be done automatically)
347
348## AT32 DFU
349
350All AT32 MCUs come preloaded with a factory bootloader that cannot be modified nor deleted.
351
352To ensure compatibility with the AT32-DFU bootloader, make sure this block is present in your `rules.mk`:
353
354```make
355# Bootloader selection
356BOOTLOADER = at32-dfu
357```
358
359Compatible 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
366Flashing sequence:
367
3681. 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
3722. Wait for the OS to detect the device
3733. Flash a .bin file
3744. 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
383Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on F303/F401/F411.
384
385The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level.
386
387To ensure compatibility with the tinyuf2 bootloader, make sure this block is present in your `rules.mk`:
388
389```make
390# Bootloader selection
391BOOTLOADER = tinyuf2
392```
393
394Compatible flashers:
395
396* Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_.
397
398Flashing sequence:
399
4001. Enter the bootloader using any of the following methods:
401 * Tap the `QK_BOOT` keycode
402 * Double-tap the `nRST` button on the PCB.
4032. Wait for the OS to detect the device
4043. Copy the .uf2 file to the new USB disk
4054. Wait for the keyboard to become available
406
407or
408
409CLI Flashing sequence:
410
4111. Enter the bootloader using any of the following methods:
412 * Tap the `QK_BOOT` keycode
413 * Double-tap the `nRST` button on the PCB.
4142. Wait for the OS to detect the device
4153. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/blackpill_f411_tinyuf2 --keymap default`
4164. 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
424Keyboards may opt into supporting the uf2boot bootloader. This is currently only supported on F103.
425
426The `rules.mk` setting for this bootloader is `uf2boot`, and can be specified at the keymap or user level.
427
428To ensure compatibility with the uf2boot bootloader, make sure this block is present in your `rules.mk`:
429
430```make
431# Bootloader selection
432BOOTLOADER = uf2boot
433```
434
435Compatible flashers:
436
437* Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_.
438
439Flashing sequence:
440
4411. Enter the bootloader using any of the following methods:
442 * Tap the `QK_BOOT` keycode
443 * Double-tap the `nRST` button on the PCB.
4442. Wait for the OS to detect the device
4453. Copy the .uf2 file to the new USB disk
4464. Wait for the keyboard to become available
447
448or
449
450CLI Flashing sequence:
451
4521. Enter the bootloader using any of the following methods:
453 * Tap the `QK_BOOT` keycode
454 * Double-tap the `nRST` button on the PCB.
4552. Wait for the OS to detect the device
4563. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/bluepill_uf2boot --keymap default`
4574. 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
465The `rules.mk` setting for this bootloader is `rp2040`, and can be specified at the keymap or user level.
466
467To ensure compatibility with the rp2040 bootloader, make sure this block is present in your `rules.mk`:
468
469```make
470# Bootloader selection
471BOOTLOADER = rp2040
472```
473
474Compatible flashers:
475
476* Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_.
477
478Flashing sequence:
479
4801. 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>.
4842. Wait for the OS to detect the device
4853. Copy the .uf2 file to the new USB disk
4864. Wait for the keyboard to become available
487
488or
489
490CLI Flashing sequence:
491
4921. 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>.
4962. Wait for the OS to detect the device
4973. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/rpi_pico --keymap default`
4984. 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.