Obviously I used QMK.

Repository containing the custom keyboard definition for my hardware is here: https://github.com/SkUrRiEr/qmk_firmware/tree/skurrier_aek_usb_custom

Sounds simple, right? Not really, getting here was an adventure.

1. What even is QMK?

The most simplistic answer is a cross-platform firmware for custom keyboards.

Which is correct, in the highest level view, but really, QMK is an "application" for ChibiOS which is a somewhat cross-platform hardware abstraction layer / kernel / operating system for microcontrollers.

So ultimately this means that QMK works on any microcontroller that ChibiOS supports, which means that a lot of microcontrollers work out-of-the-box, but there's also a few which are supported only through third-party code, which is kinda quasi-supported: QMK ships it, but that's it.

The Teensy family of microcontrollers fall into that latter category.

Ultimately I would probably have had a better experience with a different microcontroller, but I bought a Teensy LC for this project before I knew that, so I persisted.

2. How to QMK?

That's an interesting question to answer.

There's at least two different projects out there to help you go from your custom keyboard to a firmware for it's microcontroller.

• QMK's official configurator is excellent, if your keyboard is already supported. It doesn't appear to have any direct support for building firmware for your 100% custom keyboard.
• kbfirmware.com (I think that's where I got it from) is a way to turn a keyboard-layout-editor.com layout into firmware, and when I used it (over a year ago) it appeared to give me an ancient (even at the time) version of QMK configured with my keyboard's layout.

Neither of these are really a good path forwards if you have something truly custom. In my case, my keyboard is 100% custom, has a very simple layout (I'm not doing complicated stuff like layers, non-traditional modifiers, etc.) and has a weird matrix due to it's history as the Frankenstein monster of a random USB controller mixed with an Apple Keyboard.

So I went the most manual route, downloaded the official QMK firmware and associated tool, and did it all manually.

3. So how did that go?

I was able to rescue most of the layout work done by kbfirmware.com to make the layout bits work, however that was very much written from a "layout follows matrix" perspective which didn't really help me verify and modify the layout, so I ended up building my own custom layout macros and stuff so I could understand the layout files.

Then came the adventure of actually getting it compiled for the MKL26Z64 on the Teensy.

This is where the documentation dried up, and what had been a relatively straight-forward process became complicated.

I ended up copying all the files I needed from one of the other MKL26Z64 powered keyboards and that worked fine in my testing, but that doesn't seem to be the process one would expect. I'd expect to have some tutorial somewhere explain to me what I'm doing, what the values in the files I copied do, why they're there and why those values are "correct".

I can't find that documentation, I can't find any documentation on how this is supposed to work. The MKL26Z64 is one of the "not really supported but works" microcontrollers supported through the third-party code shipped with QMK. I can't find any useful documentation, and the tool you're "supposed" to use to manage these files doesn't seem to be documented.

I took my working firmware, flashed it, made some tweaks (hold a key to boot to the bootloader, fixed some mistakes in the layout) and I'm calling it done.

4. Conclusion

QMK really is the path forwards: even if you do it 100% manually like I did, it's pretty easy to go from some switches wired to a supported microcontroller to a working keyboard (if somewhat time consuming) and it has loads of fancy features around it to let you add some bling to your keyboard.

But ultimately, it's an open source project, focused on a small number of commercial keyboards who's companies employ the core developers. Everything, literally everything else is community supported and therefore anything outside the well beaten path is poorly documented, if it's documented at all.

I am more than happy with my keyboard and it's firmware, but I feel like it could have been better.

Maybe I'll end up with something more satisfying if I build the super-ergonomic split keyboard I've been thinking about...