1 # Flashing Your Keyboard
3 Now that you've built a custom firmware file you'll want to flash your keyboard.
5 ## Flashing Your Keyboard with QMK Toolbox
7 The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
9 However, the QMK Toolbox is only available for Windows and macOS currently. If you're using Linux (or just wish to flash the firmware from the command line), you'll have to use the [method outlined below](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
11 ### Load The File Into QMK Toolbox
13 Begin by opening the QMK Toolbox application. You'll want to locate the firmware file in Finder or Explorer. Your keyboard firmware may be in one of two formats- `.hex` or `.bin`. QMK tries to copy the appropriate one for your keyboard into the root `qmk_firmware` directory.
15 ?> If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
25 The firmware file always follows this naming format:
27 <keyboard_name>_<keymap_name>.{bin,hex}
29 For example, the `plank/rev5` with a `default` keymap will have this filename:
31 planck_rev5_default.hex
33 Once you have located your firmware file drag it into the "Local file" box in QMK Toolbox, or click "Open" and navigate to where your firmware file is stored.
35 ### Put Your Keyboard Into DFU (Bootloader) Mode
37 In order to flash your custom firmware you have to put your keyboard into a special flashing mode. While it is in this mode you will not be able to type or otherwise use your keyboard. It is very important that you do not unplug your keyboard or otherwise interrupt the flashing process while the firmware is being written.
39 Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK or TMK and you have not been given specific instructions try the following, in order:
41 * Hold down both shift keys and press `Pause`
42 * Hold down both shift keys and press `B`
43 * Unplug your keyboard, hold down the Spacebar and `B` at the same time, plug in your keyboard and wait a second before releasing the keys
44 * Press the physical `RESET` button on the bottom of the PCB
45 * Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
47 When you are successful you will see a message similar to this in QMK Toolbox:
50 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
51 *** DFU device connected
54 ### Flash Your Keyboard
56 Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
59 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
60 *** DFU device connected
61 *** Attempting to flash, please don't remove device
62 >>> dfu-programmer atmega32u4 erase --force
63 Erasing flash... Success
64 Checking memory from 0x0 to 0x6FFF... Empty.
65 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
66 Checking memory from 0x0 to 0x55FF... Empty.
67 0% 100% Programming 0x5600 bytes...
68 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
69 0% 100% Reading 0x7000 bytes...
70 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
72 0x5600 bytes written into 0x7000 bytes memory (76.79%).
73 >>> dfu-programmer atmega32u4 reset
75 *** DFU device disconnected
76 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
79 ## Flash your Keyboard from the Command Line
81 First thing you'll need to know is which bootloader that your keyboard uses. There are four main bootloaders that are used, usually. Pro-Micro and clones use CATERINA, and Teensy's use Halfkay, OLKB boards use QMK-DFU, and other atmega32u4 chips use DFU.
83 You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
85 If you know what bootloader that you're using, then when compiling the firmware, you can actually add some extra text to the `make` command to automate the flashing process.
89 For the DFU bootloader, when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
91 make <my_keyboard>:<my_keymap>:dfu
93 For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
95 make planck/rev5:xyverz:dfu
97 Once it finishes compiling, it should output the following:
100 Linking: .build/planck_rev5_xyverz.elf [OK]
101 Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
102 Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
103 Checking file size of planck_rev5_xyverz.hex
104 * File size is fine - 18574/28672
107 After it gets to this point, the build script will look for the DFU bootloader every 5 seconds. It will repeat the following until the device is found or you cancel it.
109 dfu-programmer: no device present.
110 Error: Bootloader not found. Trying again in 5s.
112 Once it does this, you'll want to reset the controller. It should then show output similiar to this:
115 *** Attempting to flash, please don't remove device
116 >>> dfu-programmer atmega32u4 erase --force
117 Erasing flash... Success
118 Checking memory from 0x0 to 0x6FFF... Empty.
119 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
120 Checking memory from 0x0 to 0x55FF... Empty.
121 0% 100% Programming 0x5600 bytes...
122 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
123 0% 100% Reading 0x7000 bytes...
124 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
125 Validating... Success
126 0x5600 bytes written into 0x7000 bytes memory (76.79%).
127 >>> dfu-programmer atmega32u4 reset
130 If you have any issues with this, you may need to this:
132 sudo make <my_keyboard>:<my_keymap>:dfu
136 There are a number of DFU commands that you can use to flash firmware to a DFU device:
138 * `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
139 * `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
140 * `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
141 * `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
146 For Arduino boards and their clones (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
148 make <my_keyboard>:<my_keymap>:avrdude
150 For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
152 make lets_split/rev2:xyverz:avrdude
154 Once the firmware finishes compiling, it will output something like this:
157 Linking: .build/lets_split_rev2_xyverz.elf [OK]
158 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK]
159 Checking file size of lets_split_rev2_xyverz.hex [OK]
160 * File size is fine - 27938/28672
161 Detecting USB port, reset your controller now..............
164 At this point, reset the board and then the script will detect the bootloader and then flash the board. The output should look something like this:
167 Detected controller on USB port at /dev/ttyS15
169 Connecting to programmer: .
170 Found programmer: Id = "CATERIN"; type = S
171 Software Version = 1.0; No Hardware Version given.
172 Programmer supports auto addr increment.
173 Programmer supports buffered memory access with buffersize=128 bytes.
175 Programmer supports the following devices:
178 avrdude.exe: AVR device initialized and ready to accept instructions
180 Reading | ################################################## | 100% 0.00s
182 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
183 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
184 To disable this feature, specify the -D option.
185 avrdude.exe: erasing chip
186 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
187 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
188 avrdude.exe: writing flash (27938 bytes):
190 Writing | ################################################## | 100% 2.40s
192 avrdude.exe: 27938 bytes of flash written
193 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
194 avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
195 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
196 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
197 avrdude.exe: reading on-chip flash data:
199 Reading | ################################################## | 100% 0.43s
201 avrdude.exe: verifying ...
202 avrdude.exe: 27938 bytes of flash verified
204 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
206 avrdude.exe done. Thank you.
208 If you have any issues with this, you may need to this:
210 sudo make <my_keyboard>:<my_keymap>:avrdude
213 Additionally, if you want to flash multiple boards, use the following command:
215 make <keyboard>:<keymap>:avrdude-loop
217 When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
222 For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
224 make <my_keyboard>:<my_keymap>:teensy
226 For example, if your keymap is named "xyverz" and you're building a keymap for an Ergodox or Ergodox EZ, you'll use this command:
228 make erdogox_ez:xyverz:teensy
230 Once the firmware finishes compiling, it will output something like this:
233 Linking: .build/ergodox_ez_xyverz.elf [OK]
234 Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK]
235 Checking file size of ergodox_ez_xyverz.hex [OK]
236 * File size is fine - 25584/32256
237 Teensy Loader, Command Line, Version 2.1
238 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
239 Waiting for Teensy device...
240 (hint: press the reset button)
243 At this point, reset your board. Once you've done that, you'll see output like this:
246 Found HalfKay Bootloader
247 Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
248 Programming............................................................................................................................................................................
249 ...................................................
255 For a majority of ARM boards (including the Proton C, Planck Rev 6, and Preonic Rev 3), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
257 make <my_keyboard>:<my_keymap>:dfu-util
259 For example, if your keymap is named "xyverz" and you're building a keymap for the Planck Revision 6 keyboard, you'll use this command and then reboot the keyboard to the bootloader (before it finishes compiling):
261 make planck/rev6:xyverz:dfu-util
263 Once the firmware finishes compiling, it will output something like this:
266 Linking: .build/planck_rev6_xyverz.elf [OK]
267 Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
268 Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
271 text data bss dec hex filename
272 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
274 Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
277 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
278 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
279 This program is Free Software and has ABSOLUTELY NO WARRANTY
280 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
282 Invalid DFU suffix signature
283 A valid DFU suffix will be required in a future dfu-util release!!!
284 Opening DFU capable USB device...
286 Run-time device DFU version 011a
287 Claiming USB DFU Interface...
288 Setting Alternate Setting #0 ...
289 Determining device status: state = dfuERROR, status = 10
290 dfuERROR, clearing status
291 Determining device status: state = dfuIDLE, status = 0
293 DFU mode device DFU version 011a
294 Device returned transfer size 2048
295 DfuSe interface name: "Internal Flash "
296 Downloading to address = 0x08000000, size = 41824
297 Download [=========================] 100% 41824 bytes
299 File downloaded successfully
300 Transitioning to dfuMANIFEST state
305 Congrats! Your custom firmware has been programmed to your keyboard!
307 Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about how to troubleshoot your custom functionality.