Keyboard Builders' Digest / Advent Calendar
Why on earth should a keyboard do that?
Nick Brassel (@tzarc), one of QMK’s Directors, wasn’t satisfied with keyboards only having switches and an indicator LED or three.
Published December 23, 2022
Intro
In 2019, Nick Brassel (@tzarc) started a keyboard design in an attempt to convert something “simple” – in-game key repeat while held – from an AutoHotkey script into keyboard code. He found QMK, but for some silly reason decided to pick a fight with QMK-incompatible hardware… clearly the right choice.
QMK
If you've been living under a rock for some time, you may not know of an open-source project called QMK Firmware. Its aim is to allow people to write code for their keyboard – perhaps even one of their own design – allowing firmware-based features to be embedded into the keyboard itself.
There are also other satellite projects under the QMK umbrella, such as QMK Configurator, which allows end-users to configure their keyboard layout without needing a local development environment.
As it's an open-source project, QMK firmware inevitably stands on the shoulders of giants – the QMK community. It wouldn't be anywhere near where it is now without the tireless contribution of community members – the Discord server is where the bulk of the work gets done. I'd like to explicitly call out and thank the QMK collaborators team – the vast majority of the day-to-day grind is (usually) thanklessly handled by the donation of their time, so let's make it a little less thankless. :)
And a final shameless plug – QMK has an open collective for donations. Keeps the lights on!
Anyway, on to my personal journey of keyboard design…
Designing the Cyclone – a bit of history
As is the case with a lot of open-source projects, someone will usually get an itch and then decide, "hey, I can do something about that!"
In my case I had wrist pain – something a lot of us suffer from nowadays – so I'd originally wrote an AutoHotkey script that allowed me to hold down a key and get it to repeat. Normally this would be handled by the operating system, but for games… they usually only handle keydown and keyup. And I was playing a lot of games.
For most people, they'd write the script and they'd be done. For me… it wasn't enough.
The Cyclone was where my rabbit-hole started – I discovered custom keyboard design. Some people start out with handwiring, but I chose violence to design a keyboard PCB from scratch with an integrated USB hub. I was new to the scene and chose hardware first – something we need to do nowadays due to the component shortages – but at the time, it was a pretty stupid move.
Initial design complete, sent off to manufacturing… now, firmware.
Sigh… QMK does not support the microcontroller.
For ARM devices, QMK depends on a third-party library called ChibiOS to handle a lot of the low-level hardware. At the time, I was using a relatively new microcontroller – STM32L082KZ – which the older version of ChibiOS used by QMK did not support.
Hey, I can do something about that!
At the time, the ChibiOS upgrade had been attempted previously and failed. I eventually created a PR for ChibiOS 17->19 in December 2019, and it was merged in February 2020. Done, right?
Well no, we're never done, are we?
Using an Iris – a revelation
You'd note that the Cyclone was the left half of a "normal" layout keyboard. One of the other advent calendar writers, @bakingpy, produces a split keyboard called the Iris – and on a whim (well, after a suggestion from one of the QMK collaborators), I bought one.
Argh, how did I not know about split keyboards until now?
This was a revelation – I'd finally found something that helped with my wrist pain in general! After using it for a while, I realised I wanted certain keys to be physically present, and I missed some sort of visual feedback on the board itself – the display that the Cyclone had.
Hey, I can do something about that!
Argh, here we go again.
Designing the Djinn – fit for (my) use today?
Another itch – the Cyclone's OLED wasn't big enough. The microcontroller wasn't fast enough. I wanted safety mechanisms like current limiters. I wanted support for USBPD. I wanted encoders. I wanted audio. I wanted per-key RGB.
So I started a new design – the Djinn. You'd think I'd have learned from last time, but no – I'd chosen yet another microcontroller for which neither QMK nor ChibiOS had support. I'd chosen a display technology which QMK didn't support. Heck, at the time neither ARM split nor split RGB LEDs were supported by QMK.
Make no mistake, these choices were intentional. QMK needed to be closer to bleeding-edge, and this thing was going to be another vehicle to get there:
- A breadboard ratsnest evolved.
- ChibiOS gets upgraded again, this time from 19->20. Faster microcontroller supported, check.
- At the time, integrate in-flight PRs @zvecr created for ARM split. Working… check. Merged to QMK.
- At the time, integrate in-flight PRs @XScorpion2 created for split RGB. Uhoh, issues. Fixups sent, stability achieved. RGB all good… check. Merged to QMK.
- Now for the display… and the graphics library already present in QMK doesn't work with the hardware.
Hey, I can do something about that!
A new graphics subsystem is born within QMK – Quantum Painter – a set of generic drawing APIs which ended up taking 2 years to create and rewrite several times. The timespan was annoying but necessary when you've only got a limited time budget to spend.
The resulting code produced support for 7 different display panels, with more still inbound. It supports graphics primitives like lines, boxes, circles. It supports custom fonts, even unicode. It supports animations, and the QMK CLI can even convert animated gifs for playback.
So, two years after starting – June 2022 – I finally get the rest of the dependencies into QMK so that the Djinn can actually be PR'ed into QMK firmware. Done, right?
Well no, we're never done, are we?
Designing the Ghoul – a universal testbed?
As you can probably tell, there's a bit of a running theme going on – what new hardware capabilities would be cool for QMK firmware to pick up?
Rewinding back to October 2021, QMK firmware is starting to look like it'll finally get support for the Raspberry Pi Foundation's RP2040. @KarlK90 raises the PR and starts iterating. As a QMK collaborator, we try to have evaluation boards on-hand in order to verify functionality wherever possible – and I have a handful of Pi Pico's available for testing. Did I think that was that enough? Not even close.
SparkFun has the MicroMod ecosystem with a set of processor modules available. QMK already supported the STM32F405, and was soon to pick up support for the RP2040.
They also produce processor boards for Teensy 4, Nordic nRF52, and Atmel/Microchip SAMD51. Perfect – get things working with STM32F4, then do feature parity testing for RP2040. When we pick up support for the other microcontrollers, I'll have a testbed ready to go.
What else should I put on the Ghoul?
The number of available GPIOs on the MicroMod is actually quite low, if you look at the available GPIOs across the MicroMod processor boards. I guess I'll design a new low-pincount shift register based matrix.
We have basic ADC support within QMK firmware, what can I measure on the board to ensure ADCs work for each of the new microcontroller types? I guess I'll add USB voltage and current measurement.
EEPROM isn't really big enough for some of the future QMK firmware initiatives. I guess I'll add support for SPI NOR Flash.
Actually… I guess I'll add an SDcard socket too.
Separate bootloader reset switches are a pain in the backside to use, sometimes requiring opening up cases and the like. I guess I'll add the ability to reset the board using a 5-key hardware-based keyswitch combination.
Oh cool, a shiny new RGB OLED is available! Well, I guess I'll add support for that, too.
Turned out a treat, don't you think?
Future possibilities
Right now I'm sure you're thinking – @tzarc, what do you plan to do with all the currently-unsupported hardware on the Ghoul?
Well, QMK is headed to a much more dynamic future with QMK XAP in the pipeline – a new host<=>keyboard protocol which will allow for much greater customisability without recompiling and reflashing.
I've already gotten Lua running within QMK as a proof of concept, so ideas such as onboard scripting and display themes, uploaded through XAP and backed by Flash or SDcard isn't outside the realm of possiblity. Given a DAC, perhaps XAP audio uploads are feasible, too? Only needs someone in the community with an itch and the desire to scratch it!
Signing off
Obviously this has so far been purely through the lens of my own designs… but there are far more contributions to QMK by the community, both hardware- and firmware-wise.
As of the 23rd of December, QMK has support for 2,804 keyboards (!!!), up from 2,077 at the start of the year – an increase of 727 new keyboards, +35% in this year alone.
Also throughout this year, QMK has picked up firmware features such as:
- Autocorrection
- RP2040 support
- Caps word
- Encoder mapping
- Split pointing devices
- Board converters (from ProMicro into STM32 and RP2040 pin-compatible boards)
…to name a few, along with tons of cleanup and payback of technical debt.
Pure stats-wise, in 2022 QMK firmware has gone from 15,516 valuable commits up to 18,230 – an average of 7.6 PRs merged per day. A phenomenal effort from everyone involved.
Now, the more astute readers will have noticed that I'd never mentioned the key repeat code through my keyboard building journey. Did I ever actually rewrite it?
Well, yes… though it took me 18 months to stop messing with QMK internals for a while and do what I originally intended to do with my first custom keyboard.
But hey… going down the rabbit hole is the fun of it, right? It's what we do!
 | Nick Brassel (38)tzarc |
|---|---|
| Location | Sydney, Australia |
| Description | QMK Director |
| Occupation | Professional draftsman of interconnected lines, boxes, and clouds |
| Niche | Coaxing unwilling hardware to work with QMK |
| Fav. switch | Box Navies, or 98g spring-swapped versions everything he gets his hands on |
| Fav. keycap profile | DSA, MT3 |
| Other hobbies | You think there’s time for others?!?! |
| Links | https://github.com/tzarc, https://qmk.fm |
Published on Fri 23rd Dec 2022. Featured in KBD #109.
Related
Cyberpunk OLED glitch
A cool OLED glitch animation by Aleks with open-source firmware and bitmap frames.
Luna - a QMK keyboard pet
Luna is a QMK keyboard pet by HellSingCoder reacting to your typing speed and same layer states (video, git).
Partycrasher Micro & Xiao
Semickolon shared some updates to the FAK firmware, along with Partycrasher Micro, a Pro Micro drop-in replacement.
ZMK: A History
Pete Johanson sums up the early days of ZMK, everyone's favorite wireless first firmware, and looks into the future.