From 71e9f8fc11f617278497611e169bf2ddccd2211c Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 24 Jul 2021 23:00:57 -0700 Subject: Update LUFA (18-07-2021) and add QMK-HID Bootloader support (#13588) Co-authored-by: Ryan --- docs/flashing.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'docs/flashing.md') diff --git a/docs/flashing.md b/docs/flashing.md index 83c97444e1..da3c64c4a4 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -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#bootmagic-lite), 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. -- cgit v1.2.3