aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/feature_userspace.md12
-rw-r--r--docs/flashing.md13
-rw-r--r--docs/fr-FR/flashing.md11
-rw-r--r--docs/fr-FR/newbs_flashing.md103
-rw-r--r--docs/getting_started_build_tools.md2
-rw-r--r--docs/getting_started_make_guide.md6
-rw-r--r--docs/newbs_flashing.md105
7 files changed, 145 insertions, 107 deletions
diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
index 1cc8ca742..e162d423c 100644
--- a/docs/feature_userspace.md
+++ b/docs/feature_userspace.md
@@ -211,15 +211,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
211 if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT ) 211 if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT )
212 #endif 212 #endif
213 { // 213 { //
214 #if defined(__arm__) // only run for ARM boards 214 SEND_STRING(":flash");
215 SEND_STRING(":dfu-util");
216 #elif defined(BOOTLOADER_DFU) // only run for DFU boards
217 SEND_STRING(":dfu");
218 #elif defined(BOOTLOADER_HALFKAY) // only run for teensy boards
219 SEND_STRING(":teensy");
220 #elif defined(BOOTLOADER_CATERINA) // only run for Pro Micros
221 SEND_STRING(":avrdude");
222 #endif // bootloader options
223 } 215 }
224 if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) { 216 if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) {
225 SEND_STRING(" -j8 --output-sync"); 217 SEND_STRING(" -j8 --output-sync");
@@ -244,7 +236,7 @@ endif
244 236
245This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time. 237This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
246 238
247Also, holding `shift` will add the appropriate flashing command (`:dfu`, `:teensy`, `:avrdude`, `:dfu-util`) for a majority of keyboards. Holding `control` will add some commands that will speed up compiling time by processing multiple files at once. 239Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once.
248 240
249And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap. 241And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap.
250 242
diff --git a/docs/flashing.md b/docs/flashing.md
index 18ae6364d..98841c1aa 100644
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -99,11 +99,16 @@ or
99 99
100 make <keyboard>:<keymap>:avrdude 100 make <keyboard>:<keymap>:avrdude
101 101
102or if you want to flash multiple boards, use the following command
103 102
104 make <keyboard>:<keymap>:avrdude-loop 103#### Caterina commands
104
105There are a number of DFU commands that you can use to flash firmware to a DFU device:
106
107* `: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.
108* `: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 Ctrl+C._
109* `: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._
110* `: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._
105 111
106When 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.
107 112
108 113
109## Halfkay 114## Halfkay
@@ -231,7 +236,7 @@ Flashing sequence:
231 236
232There are a number of DFU commands that you can use to flash firmware to a STM32 device: 237There are a number of DFU commands that you can use to flash firmware to a STM32 device:
233 238
234* `:dfu-util` - The default command for flashing to STM32 devices. 239* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader device is present.
235* `: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. 240* `: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.
236* `: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. 241* `: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.
237* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util. 242* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
diff --git a/docs/fr-FR/flashing.md b/docs/fr-FR/flashing.md
index f4379189a..1aa04af5f 100644
--- a/docs/fr-FR/flashing.md
+++ b/docs/fr-FR/flashing.md
@@ -99,11 +99,14 @@ ou, utilisez :
99 99
100 make <keyboard>:<keymap>:avrdude 100 make <keyboard>:<keymap>:avrdude
101 101
102ou, si vous vous voulez flasher plusieurs claviers, utilisez la commande suivante : 102#### Commandes Caterina
103 103
104 make <keyboard>:<keymap>:avrdude-loop 104Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU:
105 105
106Quand vous avez fini de flasher vos claviers, vous aurez besoin d'utiliser Ctrl + C ou alors la touche ayant la fonction similaire sur votre OS pour sortir de la boucle. 106* `: avrdude` - Il s’agit de l’option normale. Le script va attendre qu’un appareil Caterina soit disponible. Dès que c’est le cas, il flash le firmware. Il attendra de détecter un nouveau port COM pour le flasher.
107* `: avrdude-loop` - Cela fonctionne de la même manière que`: avrdude`, mais une fois que chaque périphérique est flashé, il tentera de flasher à nouveau. Cela peut être utile pour flasher plusieurs claviers à la suite. _Cela implique de sortir manuellement de la boucle en appuyant sur Ctrl + C, Cmd + C ou un raccourci équivalent selon votre OS_
108* `: avrdude-split-left` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté gauche de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro.
109* `: avrdude-split-right` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté droite de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro.
107 110
108## Halfkay 111## Halfkay
109 112
@@ -230,7 +233,7 @@ Séquence pour flasher:
230 233
231Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32  : 234Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32  :
232 235
233* `:dfu-util` - La commande par défaut pour flasher un appareil STM32. 236* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Le script attendra qu'un bootloader STM32 soit présent.
234* `:dfu-util-split-left` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté gauche des paramètres EEPROM sur un clavier scindé. 237* `:dfu-util-split-left` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté gauche des paramètres EEPROM sur un clavier scindé.
235* `:dfu-util-split-right` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté droit des paramètres EEPROM sur un clavier scindé. 238* `:dfu-util-split-right` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté droit des paramètres EEPROM sur un clavier scindé.
236* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util. 239* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util.
diff --git a/docs/fr-FR/newbs_flashing.md b/docs/fr-FR/newbs_flashing.md
index 401c524ac..267cf3add 100644
--- a/docs/fr-FR/newbs_flashing.md
+++ b/docs/fr-FR/newbs_flashing.md
@@ -78,7 +78,23 @@ Appuyez sur le boutton `Flash` dans QMK Toolbox. Vous verrez un résultat simila
78 78
79## Flashez votre clavier à l'aide de la ligne de commande 79## Flashez votre clavier à l'aide de la ligne de commande
80 80
81La première chose que vous devez savoir c'est quel bootloader utilise votre clavier. Il y a quatre bootloaders principaux. Pro-Micro et les clones, utilisent CATERINA, les Teensy utilisent Halfkay, les OLKB utilisent QMK-DFU et les autres chips atmega32u4 utilisent DFU. 81C'est désormais relativement simple. Lorsque vous êtes prêt à compiler et à flasher votre firmware, ouvrez la fenêtre de votre terminal et exécutez la commande de build :
82
83 make <my_keyboard>:<my_keymap>:flash
84
85Par exemple, si votre keymap s'appelle "xyverz" et que vous fabriquez une keymap pour un clavier `planck` de version `rev5` vous devrez utiliser cette commande:
86
87 make planck/rev5:xyverz:flash
88
89La commande va vérifier la configuration du clavier, puis tentera de le flasher en fonction du bootloader (chargeur d’amorçage) spécifié. Cela signifie que vous n'avez pas besoin de savoir quel bootloader votre clavier utilise. Exécutez simplement la commande et laissez-le faire le gros du travail.
90
91Cependant, tout dépend du bootloader qui est installé sur le clavier. Si cette information n’est pas configurée ou si vous tentez de flasher un clavier qui ne permet pas d’être flashé alors vous obtiendrez cette erreur :
92
93 WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
94
95Dans ce cas, vous devrez choisir le bootloader.
96
97Il y a cinq bootloaders principaux. Les Pro-Micro et les clones utilisent Caterina, les Teensy utilisent Halfkay, les claviers AVR d’OLKB utilisent QMK-DFU, certains controleurs atmega32u4 utilisent DFU et la plupart des controlleurs ARM utilisent ARM DFU.
82 98
83Vous pouvez trouver plus d'information à propos des bootloaders sur la page [Instructions de flash et information sur le Bootloader](flashing.md). 99Vous pouvez trouver plus d'information à propos des bootloaders sur la page [Instructions de flash et information sur le Bootloader](flashing.md).
84 100
@@ -207,11 +223,14 @@ Si vous avez un soucis, essayez de faire ceci:
207 223
208 sudo make <my_keyboard>:<my_keymap>:avrdude 224 sudo make <my_keyboard>:<my_keymap>:avrdude
209 225
210En addition, si vous voulez flasher plusieurs boards, utilisez la commande suivante: 226#### Commandes Caterina
211 227
212 make <keyboard>:<keymap>:avrdude-loop 228Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU:
213 229
214Une fois que vous avez terminé de flasher des boards, vous devrez appuyer sur Ctrl + C, ou les touches correspondantes pour votre système d'exploitation pour arrêter la boucle. 230* `: avrdude` - Il s’agit de l’option normale. Elle attend qu’un appareil Caterina soit disponible, puis tente de flasher le firmware. Il attendra de détecter un autre port COM, puis il flashera à nouveau.
231* `: avrdude-loop` - Cela fonctionne de la même manière que `: avrdude`, mais une fois que chaque périphérique est flashé, il tentera de flasher à nouveau. Cela peut être utile pour flasher plusieurs claviers à la suite. _Cela implique de sortir manuellement de la boucle en appuyant sur Ctrl + C, Cmd + C ou un raccourci équivalent selon votre OS_
232* `: avrdude-split-left` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté gauche de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro.
233* `: avrdude-split-right` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté droite de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro.
215 234
216### HalfKay 235### HalfKay
217 236
@@ -246,42 +265,6 @@ Programming.....................................................................
246Booting 265Booting
247``` 266```
248 267
249### BootloadHID
250
251Pour les boards basée sur Bootmapper Client(BMC)/bootloadHID/ATmega32A, une fois prêt à compiler et flasher le firmware, ouvrez votre fenêtre de terminal et lancez la commande suivante:
252
253 make <my_keyboard>:<my_keymap>:bootloaderHID
254
255Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, vous utilisez cette commande:
256
257 make jj40:xyverz:bootloaderHID
258
259Une fois le firmware compilé, vous aurez cette sortie:
260
261```
262Linking: .build/jj40_default.elf [OK]
263Creating load file for flashing: .build/jj40_default.hex [OK]
264Copying jj40_default.hex to qmk_firmware folder [OK]
265Checking file size of jj40_default.hex [OK]
266 * The firmware size is fine - 21920/28672 (6752 bytes free)
267```
268
269A ce stade, le script de build va chercher le bootloader DFU toutes les 5 secondes. Il va répéter la sortie suivante jusqu'à ce que le dispositif soit trouvé ou que vous l'annuliez.
270
271```
272Error opening HIDBoot device: The specified device was not found
273Trying again in 5s.
274```
275
276Une fois ce résultat atteint, réinitialisez le contrôleur. Il devrait afficher le résultat suivant:
277
278```
279Page size = 128 (0x80)
280Device size = 32768 (0x8000); 30720 bytes remaining
281Uploading 22016 (0x5600) bytes starting at 0 (0x0)
2820x05580 ... 0x05600
283```
284
285### STM32 (ARM) 268### STM32 (ARM)
286 269
287Pour la majorité des boards ARM (incluant les Proton C, Planck Rev 6, et Preonic Rev 3), lorsque vous êtes prêt à compiler et flasher votre firmware,ouvrez la fenêtre de terminal et lancez la commande de compilation: 270Pour la majorité des boards ARM (incluant les Proton C, Planck Rev 6, et Preonic Rev 3), lorsque vous êtes prêt à compiler et flasher votre firmware,ouvrez la fenêtre de terminal et lancez la commande de compilation:
@@ -336,10 +319,46 @@ Transitioning to dfuMANIFEST state
336 319
337Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device STM32: 320Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device STM32:
338 321
339* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. 322* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Elle attendra qu'un bootloader STM32 soit présent et tentera de l’utiliser.
340* `:dfu-util-wait` - Ceci fonctionne comme la commande standard, mais permet de d'avoir une pause (configurable( de 10 secondes avant de flasher le fimrware. Vous pouvez utiliser `TIME_DELAY=20` à la ligne de commande pour changer le délai.
341* `:dfu-util-left` - Ceci flasher le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flasher aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés. 323* `:dfu-util-left` - Ceci flasher le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flasher aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés.
342* `:dfu-util-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés. 324* `:dfu-util-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés.
325* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util.
326
327### BootloadHID
328
329Pour les claviers basés sur Bootmapper Client(BMC)/bootloadHID/ATmega32A, si vous êtes prêts à compiler et flasher le firmware, ouvrez votre fenêtre de terminal et lancez la commande suivante :
330
331 make <my_keyboard>:<my_keymap>:bootloaderHID
332
333Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, utilisez cette commande:
334
335 make jj40:xyverz:bootloaderHID
336
337Une fois le firmware compilé, vous aurez cette sortie:
338
339```
340Linking: .build/jj40_default.elf [OK]
341Creating load file for flashing: .build/jj40_default.hex [OK]
342Copying jj40_default.hex to qmk_firmware folder [OK]
343Checking file size of jj40_default.hex [OK]
344 * The firmware size is fine - 21920/28672 (6752 bytes free)
345```
346
347A ce stade, le script de build va chercher le bootloader DFU toutes les 5 secondes. Il répétera l ’affichage de ce message jusqu'à ce que l’appareil soit trouvé ou que vous annuliez l'opération```
348
349```
350Error opening HIDBoot device: The specified device was not found
351Trying again in 5s.
352```
353
354Une fois ce résultat obtenu, réinitialisez le contrôleur. Le résultat suivant devrait s’afficher :
355
356```
357Page size = 128 (0x80)
358Device size = 32768 (0x8000); 30720 bytes remaining
359Uploading 22016 (0x5600) bytes starting at 0 (0x0)
3600x05580 ... 0x05600
361```
343 362
344## Faites l'essai! 363## Faites l'essai!
345 364
diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md
index 268cc94c3..a55e903a6 100644
--- a/docs/getting_started_build_tools.md
+++ b/docs/getting_started_build_tools.md
@@ -145,7 +145,7 @@ util/docker_build.sh
145There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well: 145There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
146```bash 146```bash
147util/docker_build.sh keyboard:keymap:target 147util/docker_build.sh keyboard:keymap:target
148# For example: util/docker_build.sh planck/rev6:default:dfu-util 148# For example: util/docker_build.sh planck/rev6:default:flash
149``` 149```
150If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead. 150If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
151 151
diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md
index d1ecf6f5a..d2596b2e2 100644
--- a/docs/getting_started_make_guide.md
+++ b/docs/getting_started_make_guide.md
@@ -14,8 +14,8 @@ The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`,
14The `<target>` means the following 14The `<target>` means the following
15* If no target is given, then it's the same as `all` below 15* If no target is given, then it's the same as `all` below
16* `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck. 16* `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck.
17* `dfu`, `teensy`, `avrdude`, `dfu-util` or `bootloadHID`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme. 17* `flash`, `dfu`, `teensy`, `avrdude`, `dfu-util`, or `bootloadHID` compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
18 * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:dfu`. 18 * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:flash`.
19* `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems. 19* `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems.
20 20
21You can also add extra options at the end of the make command line, after the target 21You can also add extra options at the end of the make command line, after the target
@@ -31,7 +31,7 @@ Here are some examples commands
31 31
32* `make all:all` builds everything (all keyboard folders, all keymaps). Running just `make` from the `root` will also run this. 32* `make all:all` builds everything (all keyboard folders, all keymaps). Running just `make` from the `root` will also run this.
33* `make ergodox_infinity:algernon:clean` will clean the build output of the Ergodox Infinity keyboard. 33* `make ergodox_infinity:algernon:clean` will clean the build output of the Ergodox Infinity keyboard.
34* `make planck/rev4:default:dfu COLOR=false` builds and uploads the keymap without color output. 34* `make planck/rev4:default:flash COLOR=false` builds and uploads the keymap without color output.
35 35
36## `rules.mk` Options 36## `rules.mk` Options
37 37
diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md
index 9c76f5592..428e698e2 100644
--- a/docs/newbs_flashing.md
+++ b/docs/newbs_flashing.md
@@ -86,7 +86,23 @@ Click the `Flash` button in QMK Toolbox. You will see output similar to the foll
86 86
87## Flash your Keyboard from the Command Line 87## Flash your Keyboard from the Command Line
88 88
89First 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. 89This 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
93For 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
97This 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
99However, 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
103In this case, you'll have to fall back on specifying the bootloader.
104
105There 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.
90 106
91You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page. 107You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
92 108
@@ -216,11 +232,14 @@ If you have any issues with this, you may need to this:
216 sudo make <my_keyboard>:<my_keymap>:avrdude 232 sudo make <my_keyboard>:<my_keymap>:avrdude
217 233
218 234
219Additionally, if you want to flash multiple boards, use the following command: 235#### Caterina commands
220 236
221 make <keyboard>:<keymap>:avrdude-loop 237There are a number of DFU commands that you can use to flash firmware to a DFU device:
222 238
223When 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. 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._
224 243
225 244
226### HalfKay 245### HalfKay
@@ -256,42 +275,6 @@ Programming.....................................................................
256Booting 275Booting
257``` 276```
258 277
259### BootloadHID
260
261For 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:
262
263 make <my_keyboard>:<my_keymap>:bootloaderHID
264
265For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
266
267 make jj40:xyverz:bootloaderHID
268
269Once the firmware finishes compiling, it will output something like this:
270
271```
272Linking: .build/jj40_default.elf [OK]
273Creating load file for flashing: .build/jj40_default.hex [OK]
274Copying jj40_default.hex to qmk_firmware folder [OK]
275Checking file size of jj40_default.hex [OK]
276 * The firmware size is fine - 21920/28672 (6752 bytes free)
277```
278
279After 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.
280
281```
282Error opening HIDBoot device: The specified device was not found
283Trying again in 5s.
284```
285
286Once it does this, you'll want to reset the controller. It should then show output similar to this:
287
288```
289Page size = 128 (0x80)
290Device size = 32768 (0x8000); 30720 bytes remaining
291Uploading 22016 (0x5600) bytes starting at 0 (0x0)
2920x05580 ... 0x05600
293```
294
295### STM32 (ARM) 278### STM32 (ARM)
296 279
297For 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: 280For 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:
@@ -346,11 +329,47 @@ Transitioning to dfuMANIFEST state
346 329
347There are a number of DFU commands that you can use to flash firmware to a STM32 device: 330There are a number of DFU commands that you can use to flash firmware to a STM32 device:
348 331
349* `:dfu-util` - The default command for flashing to STM32 devices. 332* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader is present. .
350* `:dfu-util-wait` - This works like the default command, but it gives you a (configurable) 10 second timeout before it attempts to flash the firmware. You can use `TIME_DELAY=20` from the command line to change the timeout.
351 * Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
352* `: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. 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.
353* `: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. 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
340For 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
344For 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
348Once the firmware finishes compiling, it will output something like this:
349
350```
351Linking: .build/jj40_default.elf [OK]
352Creating load file for flashing: .build/jj40_default.hex [OK]
353Copying jj40_default.hex to qmk_firmware folder [OK]
354Checking file size of jj40_default.hex [OK]
355 * The firmware size is fine - 21920/28672 (6752 bytes free)
356```
357
358After 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```
361Error opening HIDBoot device: The specified device was not found
362Trying again in 5s.
363```
364
365Once it does this, you'll want to reset the controller. It should then show output similar to this:
366
367```
368Page size = 128 (0x80)
369Device size = 32768 (0x8000); 30720 bytes remaining
370Uploading 22016 (0x5600) bytes starting at 0 (0x0)
3710x05580 ... 0x05600
372```
354 373
355## Test It Out! 374## Test It Out!
356 375