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 {% hint style='info' %}
  16 If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
  17
  18 Windows:
  19
  20     start .
  21
  22 macOS:
  23
  24     open .
  25 {% endhint %}
  26
  27 The firmware file always follows this naming format:
  28
  29     <keyboard_name>_<keymap_name>.{bin,hex}
  30
  31 For example, the `plank/rev5` with a `default` keymap will have this filename:
  32
  33     planck_rev5_default.hex
  34
  35 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.
  36
  37 ### Put Your Keyboard Into DFU (Bootloader) Mode
  38
  39 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.
  40
  41 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:
  42
  43 * Hold down both shift keys and press `Pause`
  44 * Hold down both shift keys and press `B`
  45 * 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
  46 * Press the physical `RESET` button on the bottom of the PCB
  47 * Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
  48
  49 When you are successful you will see a message similar to this in QMK Toolbox:
  50
  51 ```
  52 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  53 *** DFU device connected
  54 ```
  55
  56 ### Flash Your Keyboard
  57
  58 Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
  59
  60 ```
  61 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  62 *** DFU device connected
  63 *** Attempting to flash, please don't remove device
  64 >>> dfu-programmer atmega32u4 erase --force
  65     Erasing flash...  Success
  66     Checking memory from 0x0 to 0x6FFF...  Empty.
  67 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
  68     Checking memory from 0x0 to 0x55FF...  Empty.
  69     0%                            100%  Programming 0x5600 bytes...
  70     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  71     0%                            100%  Reading 0x7000 bytes...
  72     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  73     Validating...  Success
  74     0x5600 bytes written into 0x7000 bytes memory (76.79%).
  75 >>> dfu-programmer atmega32u4 reset
  76
  77 *** DFU device disconnected
  78 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
  79 ```
  80
  81 ## Flash your Keyboard from the Command Line
  82
  83 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.
  84
  85 You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
  86
  87 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.
  88
  89 ### DFU
  90
  91 For the DFU bootloader, when you're ready to compile and flash your firmware, open up your terminal window and run the built command:
  92
  93     make <my_keyboard>:<my_keymap>:dfu
  94
  95 For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
  96
  97     make planck/rev5:xyverz:dfu
  98
  99 Once it finishes compiling, it should output the following:
 100
 101 ```
 102 Linking: .build/planck_rev5_xyverz.elf                                                              [OK]
 103 Creating load file for flashing: .build/planck_rev5_xyverz.hex                                      [OK]
 104 Copying planck_rev5_xyverz.hex to qmk_firmware folder                                               [OK]
 105 Checking file size of planck_rev5_xyverz.hex
 106  * File size is fine - 18574/28672
 107  ```
 108
 109 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.
 110
 111     dfu-programmer: no device present.
 112     Error: Bootloader not found. Trying again in 5s.
 113
 114 Once it does this, you'll want to reset the controller.  It should then show output similiar to this:
 115
 116 ```
 117 *** Attempting to flash, please don't remove device
 118 >>> dfu-programmer atmega32u4 erase --force
 119     Erasing flash...  Success
 120     Checking memory from 0x0 to 0x6FFF...  Empty.
 121 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
 122     Checking memory from 0x0 to 0x55FF...  Empty.
 123     0%                            100%  Programming 0x5600 bytes...
 124     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 125     0%                            100%  Reading 0x7000 bytes...
 126     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 127     Validating...  Success
 128     0x5600 bytes written into 0x7000 bytes memory (76.79%).
 129 >>> dfu-programmer atmega32u4 reset
 130 ```
 131
 132 If you have any issues with this, you may need to this:
 133
 134     sudo make <my_keyboard>:<my_keymap>:dfu
 135
 136 ### Caterina
 137
 138 For Arduino boards and their close (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the built command:
 139
 140     make <my_keyboard>:<my_keymap>:avrdude
 141
 142 For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
 143
 144     make lets_split/rev2:xyverz:avrdude
 145
 146 Once the firmware finishes compiling, it will output something like this:
 147
 148 ```
 149 Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
 150 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
 151 Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
 152  * File size is fine - 27938/28672
 153 Detecting USB port, reset your controller now..............
 154 ```
 155
 156 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:
 157
 158 ```
 159 Detected controller on USB port at /dev/ttyS15
 160
 161 Connecting to programmer: .
 162 Found programmer: Id = "CATERIN"; type = S
 163     Software Version = 1.0; No Hardware Version given.
 164 Programmer supports auto addr increment.
 165 Programmer supports buffered memory access with buffersize=128 bytes.
 166
 167 Programmer supports the following devices:
 168     Device code: 0x44
 169
 170 avrdude.exe: AVR device initialized and ready to accept instructions
 171
 172 Reading | ################################################## | 100% 0.00s
 173
 174 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
 175 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
 176              To disable this feature, specify the -D option.
 177 avrdude.exe: erasing chip
 178 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
 179 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 180 avrdude.exe: writing flash (27938 bytes):
 181
 182 Writing | ################################################## | 100% 2.40s
 183
 184 avrdude.exe: 27938 bytes of flash written
 185 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
 186 avrdude.exe: load data flash data from 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: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
 189 avrdude.exe: reading on-chip flash data:
 190
 191 Reading | ################################################## | 100% 0.43s
 192
 193 avrdude.exe: verifying ...
 194 avrdude.exe: 27938 bytes of flash verified
 195
 196 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
 197
 198 avrdude.exe done.  Thank you.
 199 ```
 200 If you have any issues with this, you may need to this:
 201
 202     sudo make <my_keyboard>:<my_keymap>:avrdude
 203
 204 ## HalfKay
 205
 206 For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the built command:
 207
 208     make <my_keyboard>:<my_keymap>:teensy
 209
 210 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:
 211
 212     make erdogox_ez:xyverz:teensy
 213
 214 Once the firmware finishes compiling, it will output something like this:
 215
 216 ```
 217 Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
 218 Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
 219 Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
 220  * File size is fine - 25584/32256
 221  Teensy Loader, Command Line, Version 2.1
 222 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
 223 Waiting for Teensy device...
 224  (hint: press the reset button)
 225  ```
 226
 227  At this point, reset your board.  Once you've done that, you'll see output like this:
 228
 229  ```
 230  Found HalfKay Bootloader
 231 Read "./.build/ergodox_ez_drashna.hex": 28532 bytes, 88.5% usage
 232 Programming............................................................................................................................................................................
 233 ...................................................
 234 Booting
 235 ```
 236
 237
 238 ## Test It Out!
 239
 240 Congrats! Your custom firmware has been programmed to your keyboard!
 241
 242 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.