aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRyan <fauxpark@gmail.com>2020-05-22 02:24:39 +1000
committerGitHub <noreply@github.com>2020-05-21 09:24:39 -0700
commit9c8f61dfa0dfb3a500ffd12b4a2d1a906a7b669f (patch)
tree6851e5b67d3461d803c58a81e4a4b33cb0b8e5be
parentd1df576ece12a7627a18e1581eed482cda2dbed5 (diff)
downloadqmk_firmware-9c8f61dfa0dfb3a500ffd12b4a2d1a906a7b669f.tar.gz
qmk_firmware-9c8f61dfa0dfb3a500ffd12b4a2d1a906a7b669f.zip
[Docs] newbs_flashing.md: place bootloader instructions before Toolbox intro (#9077)
* newbs_flashing.md: place bootloader instructions before Toolbox intro * Update docs/newbs_flashing.md * More wordsmithing, point ARM users at Discord if all else fails * Link Discord
-rw-r--r--docs/newbs_flashing.md82
1 files changed, 42 insertions, 40 deletions
diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md
index dc81efd21..04c7c55ae 100644
--- a/docs/newbs_flashing.md
+++ b/docs/newbs_flashing.md
@@ -1,18 +1,41 @@
1# Flashing Your Keyboard 1# Flashing Your Keyboard
2 2
3Now that you've built a custom firmware file you'll want to flash your keyboard. 3Now that you've built a custom firmware file you'll want to flash your keyboard.
4
5## Put Your Keyboard into DFU (Bootloader) Mode
6
7In order to flash your custom firmware you must first 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 the keyboard or otherwise interrupt the flashing process while the firmware is being written.
8
9Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK, TMK, or PS2AVRGB (Bootmapper Client) and you have not been given specific instructions, try the following, in order:
10
11* Hold down both shift keys and press `Pause`
12* Hold down both shift keys and press `B`
13* 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
14* Unplug your keyboard, hold down the top or bottom left key (usually Escape or Left Control) and plug in your keyboard
15* Press the physical `RESET` button, usually located on the underside of the PCB
16* Locate header pins on the PCB labeled `RESET` and `GND`, and short them together while plugging your PCB in
17
18If you've attempted all of the above to no avail, and the main chip on the board says `STM32` on it, this may be a bit more complicated. Generally your best bet is to ask on [Discord](https://discord.gg/Uq7gcHh) for assistance. It's likely some photos of the board will be asked for -- if you can get them ready beforehand it'll help move things along!
19
20Otherwise, you should see a message in yellow, similar to this in QMK Toolbox:
21
22```
23*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
24```
25
26and this bootloader device will also be present in Device Manager, System Information.app, or `lsusb`.
4 27
5## Flashing Your Keyboard with QMK Toolbox 28## Flashing Your Keyboard with QMK Toolbox
6 29
7The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). 30The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
8 31
9However, 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), proceed down to [Flash Your Keyboard From The Command Line](#flash-your-keyboard-from-the-command-line). 32However, the Toolbox is currently only available for Windows and macOS. If you're using Linux (or just wish to flash the firmware from the command line), skip to the [Flash your Keyboard from the Command Line](#flash-your-keyboard-from-the-command-line) section.
10 33
11### Load The File Into QMK Toolbox 34### Load the File into QMK Toolbox
12 35
13Begin 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. 36Begin 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 37
15If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder. 38If you are on Windows or macOS, there are commands you can use to easily open the current folder in Explorer or Finder.
16 39
17#### Windows 40#### Windows
18 41
@@ -38,65 +61,44 @@ For example, the `planck/rev5` with a `default` keymap will have this filename:
38planck_rev5_default.hex 61planck_rev5_default.hex
39``` 62```
40 63
41Once 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. 64Once 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.
42
43### Put Your Keyboard Into DFU (Bootloader) Mode
44
45In 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.
46
47Different 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:
48
49* Hold down both shift keys and press `Pause`
50* Hold down both shift keys and press `B`
51* 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
52* Press the physical `RESET` button on the bottom of the PCB
53* Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
54
55When you are successful you will see a message similar to this in QMK Toolbox:
56
57```
58*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
59*** DFU device connected
60```
61 65
62### Flash Your Keyboard 66### Flash Your Keyboard
63 67
64Click the `Flash` button in QMK Toolbox. You will see output similar to the following: 68Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
65 69
66``` 70```
67*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 71*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
68*** DFU device connected
69*** Attempting to flash, please don't remove device 72*** Attempting to flash, please don't remove device
70>>> dfu-programmer atmega32u4 erase --force 73>>> dfu-programmer.exe atmega32u4 erase --force
71 Erasing flash... Success 74 Erasing flash... Success
72 Checking memory from 0x0 to 0x6FFF... Empty. 75 Checking memory from 0x0 to 0x6FFF... Empty.
73>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex 76>>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex"
74 Checking memory from 0x0 to 0x55FF... Empty. 77 Checking memory from 0x0 to 0x3F7F... Empty.
75 0% 100% Programming 0x5600 bytes... 78 0% 100% Programming 0x3F80 bytes...
76 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 79 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
77 0% 100% Reading 0x7000 bytes... 80 0% 100% Reading 0x7000 bytes...
78 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 81 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
79 Validating... Success 82 Validating... Success
80 0x5600 bytes written into 0x7000 bytes memory (76.79%). 83 0x3F80 bytes written into 0x7000 bytes memory (56.70%).
81>>> dfu-programmer atmega32u4 reset 84>>> dfu-programmer.exe atmega32u4 reset
82 85
83*** DFU device disconnected 86*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)
84*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
85``` 87```
86 88
87## Flash your Keyboard from the Command Line 89## Flash your Keyboard from the Command Line
88 90
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 flash command: 91This 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 flash command:
90 92
91 qmk flash 93 qmk flash
92 94
93If you have not configured your keyboard/keymap name, or you have multiple keyboards, you can specify the keyboard and keymap: 95If you have not configured your keyboard/keymap name in the CLI, or you have multiple keyboards, you can specify the keyboard and keymap:
94 96
95 qmk flash -kb <my_keyboard> -km <my_keymap> 97 qmk flash -kb <my_keyboard> -km <my_keymap>
96 98
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. 99This 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 100
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: 101However, 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 102
101 WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. 103 WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
102 104