The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
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).
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.
The firmware file always follows this naming format:
<keyboard_name>_<keymap_name>.{bin,hex}
For example, the `plank/rev5` with a `default` keymap will have this filename:
planck_rev5_default.hex
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.
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.
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:
* Hold down both shift keys and press `Pause`
* Hold down both shift keys and press `B`
* 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
* Press the physical `RESET` button on the bottom of the PCB
* Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
When you are successful you will see a message similar to this in QMK Toolbox:
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.
You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
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.
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:dfu
Once it finishes compiling, it should output the following:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex
* File size is fine - 18574/28672
```
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.
dfu-programmer: no device present.
Error: Bootloader not found. Trying again in 5s.
Once it does this, you'll want to reset the controller. It should then show output similiar to this:
```
*** Attempting to flash, please don't remove device
There are a number of DFU commands that you can use to flash firmware to a DFU device:
*`:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
*`:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
*`:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
*`:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
For Arduino boards and their clones (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
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:
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:
make <my_keyboard>:<my_keymap>:dfu-util
For example, if your keymap is named "xyverz" and you're building a keymap for the Planck Revision 6 keyboard, you'll use this command and then reboot the keyboard to the bootloader (before it finishes compiling):
make planck/rev6:xyverz:dfu-util
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/planck_rev6_xyverz.elf [OK]
Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
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.
*`: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.
Congrats! Your custom firmware has been programmed to your keyboard!
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.
