docs/newbs_flashing.md

   1 # Flashing Your Keyboard
   2
   3 Now that you've built a custom firmware file you'll want to flash your keyboard.
   4
   5 ## Flashing Your Keyboard with QMK Toolbox
   6
   7 The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
   8
   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).
  10
  11 ### Load The File Into QMK Toolbox
  12
  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.
  14
  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.
  16
  17 #### Windows
  18
  19 ```
  20 start .
  21 ```
  22
  23 #### macOS
  24
  25 ```
  26 open .
  27 ```
  28
  29 The firmware file always follows this naming format:
  30
  31 ```
  32 <keyboard_name>_<keymap_name>.{bin,hex}
  33 ```
  34
  35 For example, the `planck/rev5` with a `default` keymap will have this filename:
  36
  37 ```
  38 planck_rev5_default.hex
  39 ```
  40
  41 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.
  42
  43 ### Put Your Keyboard Into DFU (Bootloader) Mode
  44
  45 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.
  46
  47 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:
  48
  49 * Hold down both shift keys and press `Pause`
  50 * Hold down both shift keys and press `B`
  51 * 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
  52 * Press the physical `RESET` button on the bottom of the PCB
  53 * Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
  54
  55 When you are successful you will see a message similar to this in QMK Toolbox:
  56
  57 ```
  58 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  59 *** DFU device connected
  60 ```
  61
  62 ### Flash Your Keyboard
  63
  64 Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
  65
  66 ```
  67 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  68 *** DFU device connected
  69 *** Attempting to flash, please don't remove device
  70 >>> dfu-programmer atmega32u4 erase --force
  71     Erasing flash...  Success
  72     Checking memory from 0x0 to 0x6FFF...  Empty.
  73 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
  74     Checking memory from 0x0 to 0x55FF...  Empty.
  75     0%                            100%  Programming 0x5600 bytes...
  76     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  77     0%                            100%  Reading 0x7000 bytes...
  78     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  79     Validating...  Success
  80     0x5600 bytes written into 0x7000 bytes memory (76.79%).
  81 >>> dfu-programmer atmega32u4 reset
  82
  83 *** DFU device disconnected
  84 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
  85 ```
  86
  87 ## Flash your Keyboard from the Command Line
  88
  89 This has been made pretty simple compared to what it used to be.  When you are ready to compile and flash your firmware, open up your terminal window and run the build command:
  90
  91     make <my_keyboard>:<my_keymap>:flash
  92
  93 For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
  94
  95     make planck/rev5:xyverz:flash
  96
  97 This will check the keyboard's configuration, and then attempt to flash it based on the specified bootloader.  This means that you don't need to know which bootloader that your keyboard uses.  Just run the command, and let the command do the heavy lifting.
  98
  99 However, this does rely on the bootloader being set by the keyboard.  If this information is not configured, or you're using a board that doesn't have a supported target to flash it, you will see this error:
 100
 101     WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
 102
 103 In this case, you'll have to fall back on specifying the bootloader.
 104
 105 There are five main bootloaders that are used. Pro Micro and clones use Caterina, Teensys use HalfKay, OLKB's AVR boards use QMK-DFU, other ATmega32U4 boards use DFU, and most ARM boards use ARM DFU.
 106
 107 You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
 108
 109 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.
 110
 111 ### DFU
 112
 113 For the DFU bootloader, when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
 114
 115     make <my_keyboard>:<my_keymap>:dfu
 116
 117 For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
 118
 119     make planck/rev5:xyverz:dfu
 120
 121 Once it finishes compiling, it should output the following:
 122
 123 ```
 124 Linking: .build/planck_rev5_xyverz.elf                                                              [OK]
 125 Creating load file for flashing: .build/planck_rev5_xyverz.hex                                      [OK]
 126 Copying planck_rev5_xyverz.hex to qmk_firmware folder                                               [OK]
 127 Checking file size of planck_rev5_xyverz.hex
 128  * File size is fine - 18574/28672
 129  ```
 130
 131 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.
 132
 133     dfu-programmer: no device present.
 134     Error: Bootloader not found. Trying again in 5s.
 135
 136 Once it does this, you'll want to reset the controller.  It should then show output similar to this:
 137
 138 ```
 139 *** Attempting to flash, please don't remove device
 140 >>> dfu-programmer atmega32u4 erase --force
 141     Erasing flash...  Success
 142     Checking memory from 0x0 to 0x6FFF...  Empty.
 143 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
 144     Checking memory from 0x0 to 0x55FF...  Empty.
 145     0%                            100%  Programming 0x5600 bytes...
 146     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 147     0%                            100%  Reading 0x7000 bytes...
 148     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 149     Validating...  Success
 150     0x5600 bytes written into 0x7000 bytes memory (76.79%).
 151 >>> dfu-programmer atmega32u4 reset
 152 ```
 153
 154 ?> If you have any issues with this - such as `dfu-programmer: no device present` - please see the [Frequently Asked Build Questions](faq_build.md).
 155
 156 #### DFU commands
 157
 158 There are a number of DFU commands that you can use to flash firmware to a DFU device:
 159
 160 * `: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.
 161 * `:dfu-ee` - This flashes an `eep` file instead of the normal hex.  This is uncommon.
 162 * `: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._
 163 * `: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._
 164
 165
 166 ### Caterina
 167
 168 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:
 169
 170     make <my_keyboard>:<my_keymap>:avrdude
 171
 172 For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
 173
 174     make lets_split/rev2:xyverz:avrdude
 175
 176 Once the firmware finishes compiling, it will output something like this:
 177
 178 ```
 179 Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
 180 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
 181 Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
 182  * File size is fine - 27938/28672
 183 Detecting USB port, reset your controller now..............
 184 ```
 185
 186 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:
 187
 188 ```
 189 Detected controller on USB port at /dev/ttyS15
 190
 191 Connecting to programmer: .
 192 Found programmer: Id = "CATERIN"; type = S
 193     Software Version = 1.0; No Hardware Version given.
 194 Programmer supports auto addr increment.
 195 Programmer supports buffered memory access with buffersize=128 bytes.
 196
 197 Programmer supports the following devices:
 198     Device code: 0x44
 199
 200 avrdude.exe: AVR device initialized and ready to accept instructions
 201
 202 Reading | ################################################## | 100% 0.00s
 203
 204 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
 205 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
 206              To disable this feature, specify the -D option.
 207 avrdude.exe: erasing chip
 208 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
 209 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 210 avrdude.exe: writing flash (27938 bytes):
 211
 212 Writing | ################################################## | 100% 2.40s
 213
 214 avrdude.exe: 27938 bytes of flash written
 215 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
 216 avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
 217 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 218 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
 219 avrdude.exe: reading on-chip flash data:
 220
 221 Reading | ################################################## | 100% 0.43s
 222
 223 avrdude.exe: verifying ...
 224 avrdude.exe: 27938 bytes of flash verified
 225
 226 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
 227
 228 avrdude.exe done.  Thank you.
 229 ```
 230 If you have any issues with this, you may need to this:
 231
 232     sudo make <my_keyboard>:<my_keymap>:avrdude
 233
 234
 235 #### Caterina commands
 236
 237 There are a number of DFU commands that you can use to flash firmware to a DFU device:
 238
 239 * `:avrdude` - This is the normal option which waits until a Caterina device is available (by detecting a new COM port), and then flashes the firmware.
 240 * `:avrdude-loop` - This runs the same command as `:avrdude`, but after each device is flashed, it will attempt to flash again.  This is useful for bulk flashing. _This requires you to manually escape the loop by hitting Control+C._
 241 * `:avrdude-split-left` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
 242 * `:avrdude-split-right` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
 243
 244
 245 ### HalfKay
 246
 247 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:
 248
 249     make <my_keyboard>:<my_keymap>:teensy
 250
 251 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:
 252
 253     make ergodox_ez:xyverz:teensy
 254
 255 Once the firmware finishes compiling, it will output something like this:
 256
 257 ```
 258 Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
 259 Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
 260 Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
 261  * File size is fine - 25584/32256
 262  Teensy Loader, Command Line, Version 2.1
 263 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
 264 Waiting for Teensy device...
 265  (hint: press the reset button)
 266  ```
 267
 268  At this point, reset your board.  Once you've done that, you'll see output like this:
 269
 270  ```
 271  Found HalfKay Bootloader
 272 Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
 273 Programming............................................................................................................................................................................
 274 ...................................................
 275 Booting
 276 ```
 277
 278 ### STM32 (ARM)
 279
 280 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:
 281
 282     make <my_keyboard>:<my_keymap>:dfu-util
 283
 284 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):
 285
 286     make planck/rev6:xyverz:dfu-util
 287
 288 Once the firmware finishes compiling, it will output something like this:
 289
 290 ```
 291 Linking: .build/planck_rev6_xyverz.elf                                                             [OK]
 292 Creating binary load file for flashing: .build/planck_rev6_xyverz.bin                               [OK]
 293 Creating load file for flashing: .build/planck_rev6_xyverz.hex                                     [OK]
 294
 295 Size after:
 296    text    data     bss     dec     hex filename
 297       0   41820       0   41820    a35c .build/planck_rev6_xyverz.hex
 298
 299 Copying planck_rev6_xyverz.bin to qmk_firmware folder                                              [OK]
 300 dfu-util 0.9
 301
 302 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 303 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 304 This program is Free Software and has ABSOLUTELY NO WARRANTY
 305 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 306
 307 Invalid DFU suffix signature
 308 A valid DFU suffix will be required in a future dfu-util release!!!
 309 Opening DFU capable USB device...
 310 ID 0483:df11
 311 Run-time device DFU version 011a
 312 Claiming USB DFU Interface...
 313 Setting Alternate Setting #0 ...
 314 Determining device status: state = dfuERROR, status = 10
 315 dfuERROR, clearing status
 316 Determining device status: state = dfuIDLE, status = 0
 317 dfuIDLE, continuing
 318 DFU mode device DFU version 011a
 319 Device returned transfer size 2048
 320 DfuSe interface name: "Internal Flash  "
 321 Downloading to address = 0x08000000, size = 41824
 322 Download        [=========================] 100%        41824 bytes
 323 Download done.
 324 File downloaded successfully
 325 Transitioning to dfuMANIFEST state
 326 ```
 327
 328 #### STM32 Commands
 329
 330 There are a number of DFU commands that you can use to flash firmware to a STM32 device:
 331
 332 * `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader is present. .
 333 * `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
 334 * `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
 335 * `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
 336
 337
 338 ### BootloadHID
 339
 340 For Bootmapper Client(BMC)/bootloadHID/ATmega32A based boards, when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
 341
 342     make <my_keyboard>:<my_keymap>:bootloaderHID
 343
 344 For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
 345
 346     make jj40:xyverz:bootloaderHID
 347
 348 Once the firmware finishes compiling, it will output something like this:
 349
 350 ```
 351 Linking: .build/jj40_default.elf                                                                   [OK]
 352 Creating load file for flashing: .build/jj40_default.hex                                           [OK]
 353 Copying jj40_default.hex to qmk_firmware folder                                                    [OK]
 354 Checking file size of jj40_default.hex                                                             [OK]
 355  * The firmware size is fine - 21920/28672 (6752 bytes free)
 356 ```
 357
 358 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.
 359
 360 ```
 361 Error opening HIDBoot device: The specified device was not found
 362 Trying again in 5s.
 363 ```
 364
 365 Once it does this, you'll want to reset the controller.  It should then show output similar to this:
 366
 367 ```
 368 Page size   = 128 (0x80)
 369 Device size = 32768 (0x8000); 30720 bytes remaining
 370 Uploading 22016 (0x5600) bytes starting at 0 (0x0)
 371 0x05580 ... 0x05600
 372 ```
 373
 374 ## Test It Out!
 375
 376 Congrats! Your custom firmware has been programmed to your keyboard!
 377
 378 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.