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 OS, 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 your keyboard to PC (depends on keyboard, but 99% works)
- Press the key mapped to RESET or QK_BOOT. You need to read manufacturer’s User Guide or Default Keymap to find that key
- ^ Just like above, but you (manually & actively) map a key to RESET (using VIA, VIAL, or any keymapping software that supports your keyboard), then press it
- 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 have tried all and end up with no result, time to ask for help.
If everything goes fine, there will be a 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 last 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. Tip: try the "Flash when ready" checkbox, it really helps.
- Pressing the physical RESET button does not work!
- Try double-tapping 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.