newbs_flashing.md (6189B)
1 # Flashing Your Keyboard 2 3 Now 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 7 In 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 9 Different 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 18 If you've attempted all of the above to no avail, and the main chip on the board says `STM32` or `RP2-B1` on it, this may be a bit more complicated. Generally your best bet is to ask on [Discord](https://discord.gg/qmk) 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 20 Otherwise, 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 26 and this bootloader device will also be present in Device Manager, System Information.app, or `lsusb`. 27 28 ## Flashing Your Keyboard with QMK Toolbox 29 30 The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). 31 32 However, 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. 33 34 ::: tip 35 QMK Toolbox is not necessary for flashing [RP2040 devices](flashing#raspberry-pi-rp2040-uf2). 36 ::: 37 38 ### Load the File into QMK Toolbox 39 40 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. 41 42 If you are on Windows or macOS, there are commands you can use to easily open the current folder in Explorer or Finder. 43 44 ::::tabs 45 46 === Windows 47 48 ``` 49 start . 50 ``` 51 52 === macOS 53 54 ``` 55 open . 56 ``` 57 58 :::: 59 60 The firmware file always follows this naming format: 61 62 ``` 63 <keyboard>_<keymap>.{bin,hex} 64 ``` 65 66 For example, the `planck/rev5` with a `default` keymap will have this filename: 67 68 ``` 69 planck_rev5_default.hex 70 ``` 71 72 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. 73 74 ### Flash Your Keyboard 75 76 Click the `Flash` button in QMK Toolbox. You will see output similar to the following: 77 78 ``` 79 *** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) 80 *** Attempting to flash, please don't remove device 81 >>> dfu-programmer.exe atmega32u4 erase --force 82 Erasing flash... Success 83 Checking memory from 0x0 to 0x6FFF... Empty. 84 >>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex" 85 Checking memory from 0x0 to 0x3F7F... Empty. 86 0% 100% Programming 0x3F80 bytes... 87 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 88 0% 100% Reading 0x7000 bytes... 89 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 90 Validating... Success 91 0x3F80 bytes written into 0x7000 bytes memory (56.70%). 92 >>> dfu-programmer.exe atmega32u4 reset 93 94 *** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000) 95 ``` 96 97 ## Flash your Keyboard from the Command Line 98 99 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 flash command: 100 101 ```sh 102 qmk flash 103 ``` 104 105 If you did not configure your keyboard/keymap name in the CLI according to the [Configure your build environment](newbs_getting_started) section, or you have multiple keyboards, you can specify the keyboard and keymap: 106 107 ```sh 108 qmk flash -kb <my_keyboard> -km <my_keymap> 109 ``` 110 111 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. 112 113 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: 114 115 ``` 116 WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. 117 ``` 118 119 In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing) Guide for more details. 120 121 ::: warning 122 If your bootloader is not detected by `qmk flash`, try running `qmk doctor` for suggestions on how to fix common problems. 123 ::: 124 125 ## Test It Out! 126 127 Congrats! Your custom firmware has been programmed to your keyboard and you're ready to test it out! 128 129 With a little bit of luck everything will work perfectly, but if not there are steps that will help you figure out what's wrong. 130 Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK. 131 132 Still not working? Browse the FAQ topics for more information, or [chat with us on Discord](https://discord.gg/qmk).