From a2bc294e2cad004a728df7373341595b3d499c8e Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sun, 29 Oct 2017 18:36:38 -0400 Subject: [PATCH] adds flashing docs --- docs/_summary.md | 1 + docs/flashing.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 docs/flashing.md diff --git a/docs/_summary.md b/docs/_summary.md index b433181a6..fbfb0a549 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,6 +3,7 @@ * [Install Build Tools](getting_started_build_tools.md) * Alternative: [Vagrant Guide](getting_started_vagrant_guide.md) * [Build/Compile instructions](getting_started_make_guide.md) + * [Flashing instructions](flashing.md) * [Contributing to QMK](contributing.md) * [How to Use Github](getting_started_github.md) diff --git a/docs/flashing.md b/docs/flashing.md new file mode 100644 index 000000000..a61634d21 --- /dev/null +++ b/docs/flashing.md @@ -0,0 +1,74 @@ +# Flashing Intrustructions + +There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them. + +## DFU + +Atmel's DFU bootloader comes on all atmega32u4 chips by default, 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) (Newer OLKB boards) that adds in additional features specific to that hardware. + +These bootloaders are usually 4096 bytes for the atmega32u4 chip. + +Compatible flashers: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) +* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended commandline) +* [Atmel's Flip](http://www.atmel.com/tools/flip.aspx) (not recommended) + +Flashing sequence: + +1. Press the `RESET` keycode, or tap the RESET button (or short RST to GND). +2. Wait for the OS to detect the device +3. Erase the memory (may be done automatically) +4. Flash a .hex file +5. Reset the device into application mode (may be done automatically) + +or: + + make ::dfu + +## Caterina + +Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina. + +This block of code allows for Caterina compatibility in QMK: + + #define CATERINA_BOOTLOADER + +These bootloaders are usually 4096 bytes for the atmega32u4 chip. + +Compatible flashers: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) +* [avrdude](http://www.nongnu.org/avrdude/) with avr109 / `:avrdude` (recommended commandline) +* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) + +Flashing sequence: + +1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters) +2. Wait for the OS to detect the device +4. Flash a .hex file +5. Wait for the device to reset automatically + +or + + make ::avrdude + +## Halfkay + +Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0). + +This bootloader is 512 bytes. + +Compatible flashers: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) +* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) +* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) (recommended commandline) + +Flashing sequence: + +1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters) +2. Wait for the OS to detect the device +4. Flash a .hex file +5. Reset the device into application mode (may be done automatically) +