1
0
Fork 0

[Docs] Update flashing information to include :flash target (#6999)

* Update Newbs Flashing guide

For the newbs that want to start flashing

* Update flashing docs

* Misc flashing

* Attempt at flashing in french

Lets hope I didn't butcher this too badly with machine transations

* Update docs/feature_userspace.md

* Apply language suggestions from code review

* Apply suggestions from code review

* Apply additional fr lang suggestions from code review

* Apply suggestions from code review

Co-Authored-By: fauxpark <fauxpark@gmail.com>
Co-Authored-By: Noan Mousy <4sstylz@protonmail.ch>
Co-Authored-By: Xavier Hahn <xavier.hahn@gmail.com>
Co-Authored-By: Vincent LE GOFF <vince.legoff@gmail.com>
This commit is contained in:
Drashna Jaelre 2019-10-29 13:15:03 -07:00 committed by noroadsleft
parent 476f556613
commit 0e6f78547e
7 changed files with 145 additions and 107 deletions

View file

@ -211,15 +211,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT )
#endif
{ //
#if defined(__arm__) // only run for ARM boards
SEND_STRING(":dfu-util");
#elif defined(BOOTLOADER_DFU) // only run for DFU boards
SEND_STRING(":dfu");
#elif defined(BOOTLOADER_HALFKAY) // only run for teensy boards
SEND_STRING(":teensy");
#elif defined(BOOTLOADER_CATERINA) // only run for Pro Micros
SEND_STRING(":avrdude");
#endif // bootloader options
SEND_STRING(":flash");
}
if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) {
SEND_STRING(" -j8 --output-sync");
@ -244,7 +236,7 @@ endif
This 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.
Also, 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.
Also, 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.
And 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.

View file

@ -99,11 +99,16 @@ or
make <keyboard>:<keymap>:avrdude
or if you want to flash multiple boards, use the following command
make <keyboard>:<keymap>:avrdude-loop
#### Caterina commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `: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.
* `: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._
* `: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._
* `: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._
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.
## Halfkay
@ -231,7 +236,7 @@ Flashing sequence:
There are a number of DFU commands that you can use to flash firmware to a STM32 device:
* `:dfu-util` - The default command for flashing to STM32 devices.
* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader device is present.
* `: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.
* `: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.
* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.

View file

@ -99,11 +99,14 @@ ou, utilisez:
make <keyboard>:<keymap>:avrdude
ou, si vous vous voulez flasher plusieurs claviers, utilisez la commande suivante:
#### Commandes Caterina
make <keyboard>:<keymap>:avrdude-loop
Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU:
Quand 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.
* `: avrdude` - Il sagit de loption normale. Le script va attendre quun appareil Caterina soit disponible. Dès que cest le cas, il flash le firmware. Il attendra de détecter un nouveau port COM pour le flasher.
* `: 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_
* `: 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.
* `: 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.
## Halfkay
@ -230,7 +233,7 @@ Séquence pour flasher:
Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32:
* `:dfu-util` - La commande par défaut pour flasher un appareil STM32.
* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Le script attendra qu'un bootloader STM32 soit présent.
* `: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é.
* `: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é.
* `: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.

View file

@ -78,7 +78,23 @@ Appuyez sur le boutton `Flash` dans QMK Toolbox. Vous verrez un résultat simila
## Flashez votre clavier à l'aide de la ligne de commande
La 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.
C'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 :
make <my_keyboard>:<my_keymap>:flash
Par 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:
make planck/rev5:xyverz:flash
La commande va vérifier la configuration du clavier, puis tentera de le flasher en fonction du bootloader (chargeur damorç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.
Cependant, tout dépend du bootloader qui est installé sur le clavier. Si cette information nest pas configurée ou si vous tentez de flasher un clavier qui ne permet pas dêtre flashé alors vous obtiendrez cette erreur :
WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
Dans ce cas, vous devrez choisir le bootloader.
Il y a cinq bootloaders principaux. Les Pro-Micro et les clones utilisent Caterina, les Teensy utilisent Halfkay, les claviers AVR dOLKB utilisent QMK-DFU, certains controleurs atmega32u4 utilisent DFU et la plupart des controlleurs ARM utilisent ARM DFU.
Vous pouvez trouver plus d'information à propos des bootloaders sur la page [Instructions de flash et information sur le Bootloader](flashing.md).
@ -207,11 +223,14 @@ Si vous avez un soucis, essayez de faire ceci:
sudo make <my_keyboard>:<my_keymap>:avrdude
En addition, si vous voulez flasher plusieurs boards, utilisez la commande suivante:
#### Commandes Caterina
make <keyboard>:<keymap>:avrdude-loop
Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU:
Une 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.
* `: avrdude` - Il sagit de loption normale. Elle attend quun appareil Caterina soit disponible, puis tente de flasher le firmware. Il attendra de détecter un autre port COM, puis il flashera à nouveau.
* `: 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_
* `: 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.
* `: 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.
### HalfKay
@ -246,42 +265,6 @@ Programming.....................................................................
Booting
```
### BootloadHID
Pour 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:
make <my_keyboard>:<my_keymap>:bootloaderHID
Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, vous utilisez cette commande:
make jj40:xyverz:bootloaderHID
Une fois le firmware compilé, vous aurez cette sortie:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
A 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.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Une fois ce résultat atteint, réinitialisez le contrôleur. Il devrait afficher le résultat suivant:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
### STM32 (ARM)
Pour 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
Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device STM32:
* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32.
* `: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.
* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Elle attendra qu'un bootloader STM32 soit présent et tentera de lutiliser.
* `: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.
* `: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.
* `: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.
### BootloadHID
Pour 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 :
make <my_keyboard>:<my_keymap>:bootloaderHID
Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, utilisez cette commande:
make jj40:xyverz:bootloaderHID
Une fois le firmware compilé, vous aurez cette sortie:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
A 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 lappareil soit trouvé ou que vous annuliez l'opération```
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Une fois ce résultat obtenu, réinitialisez le contrôleur. Le résultat suivant devrait safficher :
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
## Faites l'essai!

View file

@ -145,7 +145,7 @@ util/docker_build.sh
There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
```bash
util/docker_build.sh keyboard:keymap:target
# For example: util/docker_build.sh planck/rev6:default:dfu-util
# For example: util/docker_build.sh planck/rev6:default:flash
```
If 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.

View file

@ -14,8 +14,8 @@ The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`,
The `<target>` means the following
* If no target is given, then it's the same as `all` below
* `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.
* `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.
* **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`.
* `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.
* **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`.
* `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.
You 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
* `make all:all` builds everything (all keyboard folders, all keymaps). Running just `make` from the `root` will also run this.
* `make ergodox_infinity:algernon:clean` will clean the build output of the Ergodox Infinity keyboard.
* `make planck/rev4:default:dfu COLOR=false` builds and uploads the keymap without color output.
* `make planck/rev4:default:flash COLOR=false` builds and uploads the keymap without color output.
## `rules.mk` Options

View file

@ -86,7 +86,23 @@ Click the `Flash` button in QMK Toolbox. You will see output similar to the foll
## Flash your Keyboard from the Command Line
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.
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:
make <my_keyboard>:<my_keymap>:flash
For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
make planck/rev5:xyverz:flash
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.
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:
WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
In this case, you'll have to fall back on specifying the bootloader.
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.
You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
@ -216,11 +232,14 @@ If you have any issues with this, you may need to this:
sudo make <my_keyboard>:<my_keymap>:avrdude
Additionally, if you want to flash multiple boards, use the following command:
#### Caterina commands
make <keyboard>:<keymap>:avrdude-loop
There are a number of DFU commands that you can use to flash firmware to a DFU device:
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.
* `: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.
* `: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._
* `: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._
* `: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._
### HalfKay
@ -256,42 +275,6 @@ Programming.....................................................................
Booting
```
### BootloadHID
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:
make <my_keyboard>:<my_keymap>:bootloaderHID
For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
make jj40:xyverz:bootloaderHID
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
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.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Once it does this, you'll want to reset the controller. It should then show output similar to this:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
### STM32 (ARM)
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:
@ -346,11 +329,47 @@ Transitioning to dfuMANIFEST state
There are a number of DFU commands that you can use to flash firmware to a STM32 device:
* `:dfu-util` - The default command for flashing to STM32 devices.
* `: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.
* Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader is present. .
* `: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.
* `: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.
* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
### BootloadHID
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:
make <my_keyboard>:<my_keymap>:bootloaderHID
For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
make jj40:xyverz:bootloaderHID
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
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.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Once it does this, you'll want to reset the controller. It should then show output similar to this:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
## Test It Out!