summaryrefslogtreecommitdiff
path: root/docs/flashing.md
diff options
context:
space:
mode:
authorNick Brassel <nick@tzarc.org>2021-08-29 08:20:25 +1000
committerNick Brassel <nick@tzarc.org>2021-08-29 08:20:25 +1000
commitf061ca497464fe85284906fb163a33eaee7a91ef (patch)
tree33ef1bfb529aed382e8526c607c4e18717f92571 /docs/flashing.md
parentff65185dec6f97be1eb49f17cea526a0d0bbf3d6 (diff)
parent4bad375d7c09d949a9dcdd4feba147c9c7a67ec6 (diff)
Breaking changes develop merge to master, 2021Q3 edition. (#14196)
Diffstat (limited to 'docs/flashing.md')
-rw-r--r--docs/flashing.md50
1 files changed, 48 insertions, 2 deletions
diff --git a/docs/flashing.md b/docs/flashing.md
index 83c97444e1..7b7fe956f3 100644
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -48,7 +48,7 @@ QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tr
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```
-Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
+Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
@@ -171,6 +171,52 @@ Flashing sequence:
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
+### QMK HID
+
+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.
+
+To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`:
+
+```make
+# Bootloader selection
+BOOTLOADER = qmk-hid
+```
+
+To enable the additional features, add the following defines to your `config.h`:
+
+```c
+#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
+#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
+// Optional:
+//#define QMK_LED E6
+//#define QMK_SPEAKER C6
+```
+
+Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
+
+The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
+
+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`.
+
+Compatible flashers:
+
+* TBD
+ * 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`).
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+ * Press the `RESET` keycode
+ * Press the `RESET` button on the PCB if available
+ * short RST to GND quickly
+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)
+
+### `make` Targets
+
+* `:qmk-hid`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware.
+
## STM32/APM32 DFU
All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted.
@@ -252,7 +298,7 @@ Flashing sequence:
## tinyuf2
-Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F411 blackpill.
+Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F401/F411 blackpill.
The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level.