Programming Whitefox keyboard with QMK

This week I've finally received my order of Whitefox keyboard:

What's so special about this keyboard you ask? First of all, it is a mechanical keyboard. But more importantly is that keyboard has a programmable microcontroller. So the layout doesn't depend on the OS or drivers or 3rd party utilities anymore!

In fact, Whitefox was the only programmable keyboard that you can buy fully assembled in November 2017, when I did the research.

A common setup for programmable keyboards is to have several dedicated buttons for switching the layout, for example, CAPSLOCK or right CTRL. My idea was to use a spacebar: if spacebar is pressed along with another character then it will act as layer selector, otherwise, it will emit space character when the button is released. That allows using vim-like navigation without hands leaving the home row or stretching a pinky.

Kiibohd configurator

InputClub officially recommends this program (or the web version which is essentially the same app) to configure Whitefox. If all you need is to create a couple of virtual layers activated when a user presses or holds dedicated button - look no further. Unfortunately, the configurator doesn't allow you to easily go beyond the basics.

I have looked at how it represents and compiles a firmware and the path looks like:

config ui → kll file → kll compiler → binary → dfu-util → keyboard

KLL is short for "Keyboard Layout Language". It seems that this project tries to create some standard for defining keyboard layouts. At this moment kll-compiler supports version 0.3 of spec which is quite plain doesn't allow assigning "two roles" to one button. Maybe after a couple of years, this project will cover 95% of user needs. From my personal point of view, the need to maintain such niche domain-specific language only makes progress slower. And there is only one maintainer...

Fortunately for me, there is an alternative:

QMK

QMK is a successor/fork of pretty popular TMK firmware. It takes much straightforward approach: you modify several files in well-structured C-project and then compile them directly to binary.

As this project IS as a firmware, it's really easy to get direct access lower levels, down to matrix scan method. That's why there are tons of contributed features you can employ in your layout right away. And look, there is a one that covers my case:

LT(layer, kc) - momentary switch to layer when held, and kc when tapped.

If you're interested in my full layout build check my fork of QMK (make target is "whitefox:gem"). I would argue that one doesn't really need a UI if it's so easy to define it in a text file.

I can't commend QMK project enough: it's well maintained, builds smoothly, has awesome documentation and many contributors. I hope that InputClub will invest more in that project and will make it officially supported by QMK.

In conclusion

I like this new toy and really enjoy typing with it! As it's 65% keyboard, it will take some time to get used to missing buttons: enter is smaller, grave, F-keys, backspace or numpad are not where my hands look for them. These are things to consider before buying a non-standard keyboard. And don't forget to check if yours is supported by QMK ;)

Good luck!