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     start .
  20
  21 ?> macOS:
  22
  23     open .
  24
  25 The firmware file always follows this naming format:
  26
  27     <keyboard_name>_<keymap_name>.{bin,hex}
  28
  29 For example, the `plank/rev5` with a `default` keymap will have this filename:
  30
  31     planck_rev5_default.hex
  32
  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.
  34
  35 ### Put Your Keyboard Into DFU (Bootloader) Mode
  36
  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.
  38
  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:
  40
  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
  46
  47 When you are successful you will see a message similar to this in QMK Toolbox:
  48
  49 ```
  50 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  51 *** DFU device connected
  52 ```
  53
  54 ### Flash Your Keyboard
  55
  56 Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
  57
  58 ```
  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
  71     Validating...  Success
  72     0x5600 bytes written into 0x7000 bytes memory (76.79%).
  73 >>> dfu-programmer atmega32u4 reset
  74
  75 *** DFU device disconnected
  76 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
  77 ```
  78
  79 ## Flash your Keyboard from the Command Line
  80
  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.
  82
  83 You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
  84
  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.
  86
  87 ### DFU
  88
  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:
  90
  91     make <my_keyboard>:<my_keymap>:dfu
  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:dfu
  96
  97 Once it finishes compiling, it should output the following:
  98
  99 ```
 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
 105  ```
 106
 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.
 108
 109     dfu-programmer: no device present.
 110     Error: Bootloader not found. Trying again in 5s.
 111
 112 Once it does this, you'll want to reset the controller.  It should then show output similiar to this:
 113
 114 ```
 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
 128 ```
 129
 130 ?> If you have any issues with this - such as `dfu-programmer: no device present` - please see the [Frequently Asked Build Questions](faq_build.md).
 131
 132 #### DFU commands
 133
 134 There are a number of DFU commands that you can use to flash firmware to a DFU device:
 135
 136 * `: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.
 137 * `:dfu-ee` - This flashes an `eep` file instead of the normal hex.  This is uncommon.
 138 * `: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._
 139 * `: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._
 140
 141
 142 ### Caterina
 143
 144 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:
 145
 146     make <my_keyboard>:<my_keymap>:avrdude
 147
 148 For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
 149
 150     make lets_split/rev2:xyverz:avrdude
 151
 152 Once the firmware finishes compiling, it will output something like this:
 153
 154 ```
 155 Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
 156 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
 157 Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
 158  * File size is fine - 27938/28672
 159 Detecting USB port, reset your controller now..............
 160 ```
 161
 162 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:
 163
 164 ```
 165 Detected controller on USB port at /dev/ttyS15
 166
 167 Connecting to programmer: .
 168 Found programmer: Id = "CATERIN"; type = S
 169     Software Version = 1.0; No Hardware Version given.
 170 Programmer supports auto addr increment.
 171 Programmer supports buffered memory access with buffersize=128 bytes.
 172
 173 Programmer supports the following devices:
 174     Device code: 0x44
 175
 176 avrdude.exe: AVR device initialized and ready to accept instructions
 177
 178 Reading | ################################################## | 100% 0.00s
 179
 180 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
 181 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
 182              To disable this feature, specify the -D option.
 183 avrdude.exe: erasing chip
 184 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
 185 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 186 avrdude.exe: writing flash (27938 bytes):
 187
 188 Writing | ################################################## | 100% 2.40s
 189
 190 avrdude.exe: 27938 bytes of flash written
 191 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
 192 avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
 193 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 194 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
 195 avrdude.exe: reading on-chip flash data:
 196
 197 Reading | ################################################## | 100% 0.43s
 198
 199 avrdude.exe: verifying ...
 200 avrdude.exe: 27938 bytes of flash verified
 201
 202 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
 203
 204 avrdude.exe done.  Thank you.
 205 ```
 206 If you have any issues with this, you may need to this:
 207
 208     sudo make <my_keyboard>:<my_keymap>:avrdude
 209
 210
 211 Additionally, if you want to flash multiple boards, use the following command:
 212
 213     make <keyboard>:<keymap>:avrdude-loop
 214
 215 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.
 216
 217
 218 ## HalfKay
 219
 220 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:
 221
 222     make <my_keyboard>:<my_keymap>:teensy
 223
 224 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:
 225
 226     make erdogox_ez:xyverz:teensy
 227
 228 Once the firmware finishes compiling, it will output something like this:
 229
 230 ```
 231 Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
 232 Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
 233 Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
 234  * File size is fine - 25584/32256
 235  Teensy Loader, Command Line, Version 2.1
 236 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
 237 Waiting for Teensy device...
 238  (hint: press the reset button)
 239  ```
 240
 241  At this point, reset your board.  Once you've done that, you'll see output like this:
 242
 243  ```
 244  Found HalfKay Bootloader
 245 Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
 246 Programming............................................................................................................................................................................
 247 ...................................................
 248 Booting
 249 ```
 250
 251 ## STM32 (ARM)
 252
 253 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:
 254
 255     make <my_keyboard>:<my_keymap>:dfu-util
 256
 257 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):
 258
 259     make planck/rev6:xyverz:dfu-util
 260
 261 Once the firmware finishes compiling, it will output something like this:
 262
 263 ```
 264 Linking: .build/planck_rev6_xyverz.elf                                                             [OK]
 265 Creating binary load file for flashing: .build/planck_rev6_xyverz.bin                               [OK]
 266 Creating load file for flashing: .build/planck_rev6_xyverz.hex                                     [OK]
 267
 268 Size after:
 269    text    data     bss     dec     hex filename
 270       0   41820       0   41820    a35c .build/planck_rev6_xyverz.hex
 271
 272 Copying planck_rev6_xyverz.bin to qmk_firmware folder                                              [OK]
 273 dfu-util 0.9
 274
 275 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 276 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 277 This program is Free Software and has ABSOLUTELY NO WARRANTY
 278 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 279
 280 Invalid DFU suffix signature
 281 A valid DFU suffix will be required in a future dfu-util release!!!
 282 Opening DFU capable USB device...
 283 ID 0483:df11
 284 Run-time device DFU version 011a
 285 Claiming USB DFU Interface...
 286 Setting Alternate Setting #0 ...
 287 Determining device status: state = dfuERROR, status = 10
 288 dfuERROR, clearing status
 289 Determining device status: state = dfuIDLE, status = 0
 290 dfuIDLE, continuing
 291 DFU mode device DFU version 011a
 292 Device returned transfer size 2048
 293 DfuSe interface name: "Internal Flash  "
 294 Downloading to address = 0x08000000, size = 41824
 295 Download        [=========================] 100%        41824 bytes
 296 Download done.
 297 File downloaded successfully
 298 Transitioning to dfuMANIFEST state
 299 ```
 300
 301 ## Test It Out!
 302
 303 Congrats! Your custom firmware has been programmed to your keyboard!
 304
 305 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.