Flashing QMK on a WhiteFox Mechanical Keyboard
February 5, 2020
Awhile back I had this itch of wanting to try a different firmware for my then recent mechanical keyboard. By that time I was also completely new to the mechanical keyboard world. To get some new layout for the keyboard I had to jump into a website, select my keyboard layout and start putting things together, it was very straight forward. Some time after I started wondering if I could put a different firmware on the keyboard. I found TMK and the fork with wider adoption QMK.
Intro to QMK
The first time I compiled QMK for the WhiteFox I remember doing things that were not documented and had to do some research here and there, this was around late 2017… Fast forward to just a few weeks ago that I came back to upgrade the firmware and to my surprise I’ve found myself in a way more mature ecosystem, good docs and some build tools like Docker and the QMK Toolbox if you don’t want to do the native install.
Using and Flashing the QMK firmware
Clone the project
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
We will use the following script for compiling the firmware as we are using Docker:
If you look inside the util/docker_build.sh you’ll see that it
uses the qmkfm/base_container. Running the above command with
keyboard:keymap of your preference this will output build data in a
.build directory and the compiled
.bin in the root of the project.
Now it’s time to open the QMK Toolbox open the
.bin file put
your keyboard in DFU mode this is done by pressing the button at the bottom of
the keyboard and then pressing the flash button in the QMK Toolbox GUI.
I use a custom layout inside my fork, and use the following command to build:
Once you know all these details you are mostly good to go.
For the WhiteFox there was no Vanilla layout so I had to made my own. Once I knew it was working I contributed back to the QMK project. The process of adding a new layout was a bit confusing but not impossible to solve. Here is the Pull Request where one can see the layout getting added.
All this process of using a custom firmware that has so many options is very cool and useful. The community around the project is huge. I still haven’t messed around with mouse buttons, LED layouts, macros, and other features that I want to test. Either way I think it’s a fun project and I’m eager to keep testing QMK features.