]> git.donarmstrong.com Git - qmk_firmware.git/blob - docs/newbs_flashing.md
Keyboard: Initial 6lit port (#4355)
[qmk_firmware.git] / 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 built 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, you may need to this: 
131
132     sudo make <my_keyboard>:<my_keymap>:dfu
133
134 ### Caterina 
135
136 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: 
137
138     make <my_keyboard>:<my_keymap>:avrdude
139
140 For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
141
142     make lets_split/rev2:xyverz:avrdude
143
144 Once the firmware finishes compiling, it will output something like this: 
145
146 ```
147 Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
148 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
149 Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
150  * File size is fine - 27938/28672
151 Detecting USB port, reset your controller now..............
152 ```
153
154 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: 
155
156 ```
157 Detected controller on USB port at /dev/ttyS15
158
159 Connecting to programmer: .
160 Found programmer: Id = "CATERIN"; type = S
161     Software Version = 1.0; No Hardware Version given.
162 Programmer supports auto addr increment.
163 Programmer supports buffered memory access with buffersize=128 bytes.
164
165 Programmer supports the following devices:
166     Device code: 0x44
167
168 avrdude.exe: AVR device initialized and ready to accept instructions
169
170 Reading | ################################################## | 100% 0.00s
171
172 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
173 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
174              To disable this feature, specify the -D option.
175 avrdude.exe: erasing chip
176 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
177 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
178 avrdude.exe: writing flash (27938 bytes):
179
180 Writing | ################################################## | 100% 2.40s
181
182 avrdude.exe: 27938 bytes of flash written
183 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
184 avrdude.exe: load data flash data from 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: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
187 avrdude.exe: reading on-chip flash data:
188
189 Reading | ################################################## | 100% 0.43s
190
191 avrdude.exe: verifying ...
192 avrdude.exe: 27938 bytes of flash verified
193
194 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
195
196 avrdude.exe done.  Thank you.
197 ```
198 If you have any issues with this, you may need to this: 
199
200     sudo make <my_keyboard>:<my_keymap>:avrdude
201
202 ## HalfKay
203
204 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: 
205
206     make <my_keyboard>:<my_keymap>:teensy
207
208 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:
209
210     make erdogox_ez:xyverz:teensy
211
212 Once the firmware finishes compiling, it will output something like this: 
213
214 ```
215 Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
216 Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
217 Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
218  * File size is fine - 25584/32256
219  Teensy Loader, Command Line, Version 2.1
220 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
221 Waiting for Teensy device...
222  (hint: press the reset button)
223  ```
224
225  At this point, reset your board.  Once you've done that, you'll see output like this: 
226
227  ```
228  Found HalfKay Bootloader
229 Read "./.build/ergodox_ez_drashna.hex": 28532 bytes, 88.5% usage
230 Programming............................................................................................................................................................................
231 ...................................................
232 Booting
233 ```
234
235
236 ## Test It Out!
237
238 Congrats! Your custom firmware has been programmed to your keyboard!
239
240 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.