Flashing Firmware To Your Keyboard
as easy as it always be
* This tutorial is only for keyboards those powered by QMK Firmware. If you are not sure if your keyboard is running QMK or not, please contact manufacturer/maker before continue.
Step 0: Preparing
In order to flash a firmware to your keyboard, you need:
A keyboard which will be re-flashed
(sound reasonable, right?)
A firmware file
Should be a file with .hex or .bin suffix (for example: kiwikey_kawii9_via.hex)
Regarding products of KiwiKey, please go to Download section.
QMK Toolbox
It is a software that upload the firmware file into keyboard.
Download: https://github.com/qmk/qmk_toolbox/releases
Tip: QMK.Toolbox.pkg is for Mac, qmk_toolbox_install.exe is for Windows
Step 1: Put keyboard into "ready to flash" mode
The keyboard must run into a special mode to be flashed, called “DFU” or “Bootloader” mode.
There are several ways to do so, if you are not sure what to do, try one of the following ways:
- Press the physical Reset button on the underside of your PCB
- Unplug your keyboard, hold the top left key (usually ESC), then plug in your keyboard (depends on keyboard, but 99% works)
- Press the key mapped to RESET or QK_BOOT. You need to see manufacturer’s user guide to find that key
- ^ Just like above, but you (actively) map a key to RESET, and press it (only if your keyboard is detected by VIA)
- Hardcore & dangerous way: find the RESET and GND pins of the microcontroller on the PCB, and short them together (mostly used with keyboard powered by Pro-Micro controller) – highly not recommended
If you tried all and end up with no result, time to ask for help.
If everything goes fine, there will be a yellow message in QMK Toolbox, says something is “connected”:
Step 2: Setting up the QMK Toolbox
(1) Clicking Open and navigate to the firmware file
Tip: if you already downloaded the file, try looking at your Downloads folder
(2) Under “MCU (AVR only)” label, click the drop-down menu and select correct MCU (controller chip)
Tips: just choose atmega32u4, in most cases it works
(3) Make sure the yellow message in QMK Toolbox is still “connected”, if not, do Step 1 again
Step 3: Flash your keyboard
Click the Flash button in QMK Toolbox, some miracle lines appear, just let the magic do its work.
If you can see these “Success” texts in QMK Toolbox, everything is good:
Warning: do not unplug your keyboard during flashing, or it can be bricked (could be fixed, but tricky and need some special tools).
Step 4: Test it and enjoy it!
Test some basic functions (typing, LED lighting,…). Please note that there are keyboards with several versions/revisions, make sure the firmware version match the PCB version.
Tips:
- If you use a VIA-supported firmware, your keyboard should be detected by VIA (with or without loading JSON file into VIA)
- If you have done all steps with no error, but the keyboard does not work at all, it is high chance that you chose wrong firmware file. No worries, just do this tutorial all over again, with the correct file.
FAQ
- I can put the keyboard into bootloader mode, but it automatically disconnected after that, what's wrong?
- This usually happens to ProMicro-controlled keyboards. After 5 seconds in bootloader mode, it exits and returns to default program. You need to do fast between step-1 and step-2
- Pressing the physical RESET button does not work!
- Try double-tap it, or hold it while plugging into PC.
- I pressed RESET but QMK Toolbox does not recognize my keyboard!
- Try re-install drivers: in QMK Toolbox, choose Tools>Install Drivers... Make sure that when doing step-1, you can hear the sound of device disconnected, following by sound of device connected
- I accidentally unplug the keyboard while uploading firmware. The keyboard seems to be bricked now.
- Yes it is bricked. To fix this you need to burn a fresh "bootloader firmware" into it. You better contact the manufacturer/maker or anyone who has experience with this.