GOLEM — Build a keyboard with KMK & Adafruit KB2040

• Source: https://golem.hu/guide/kmk-firmware/
• Category: research — background knowledge; firmware fallback option only
• Role for KN-86: NOT the chosen firmware path. Per keyboard-decision.md the KN-86 will use QMK / Vial on the Ferris Sweep’s holykeebs RP2040, not KMK. Two specific pieces of this guide remain actively useful: the drag-drop CircuitPython workflow (as UX contrast for QMK flashing) and the documented NeoPixel diagnostic color vocabulary (as a deck-status-LED idea).
• License / caveats: GOLEM site content.

What it is

GOLEM’s end-to-end guide to running KMK firmware on an Adafruit KB2040 controller. The pipeline:

1. Drop CircuitPython onto the KB2040: hold BOOT while pressing RST; the board mounts as a generic mass-storage device; copy the CircuitPython .UF2 over; the board reboots and now presents as the CIRCUITPY USB drive.
2. Drop the KMK firmware directory onto CIRCUITPY along with a boot.py and the user’s code.py keymap.
3. The board now runs KMK; edit code.py directly on the drive to iterate the keymap. No compile step.

The guide includes a working 2×2 macropad example that demonstrates the minimal KMK keymap (scan matrix definition, key codes, the simplest possible main loop) and the NeoPixel diagnostic color codes — the built-in NeoPixel on the KB2040 surfaces system state through a documented color vocabulary.

Why this isn’t the actioned path

Per keyboard-decision.md “Firmware decision” section:

• KMK is on limited life support as of 2026 (“no longer actively maintained / limited life support” per the KMK firmware repo README)
• QMK is the dominant ecosystem for the Sweep family with active community keymaps and shipping defaults
• Vial gives us GUI-editable keymaps layered over QMK, which simplifies the 31-canonical-functions → 34-key + layers mapping work without firmware rebuilds

KN-86 is using QMK + Vial on the holykeebs RP2040. KMK is not the firmware.

What’s worth keeping from this guide

1. The drag-drop CircuitPython workflow — as UX contrast for QMK flashing

KMK’s flash UX is:

Hold BOOT + press RST → board appears as USB drive →
copy CircuitPython .UF2 → board reboots as CIRCUITPY →
drop KMK directory + code.py → done

This is dramatically friendlier than QMK’s compile-and-flash cycle, where the user typically:

Install QMK toolchain →
clone keymap repo or use Vial config → compile firmware →
hold BOOT + press RST → flash compiled .uf2 via qmk command or dfu-util

The lesson is the UX contrast, not the firmware choice. When we document the KN-86 owner’s firmware-flash experience, the bar to clear is “as approachable as KMK’s drag-drop.” Vial helps a lot here (no compile step needed for keymap iteration), but the cold-flash experience — initial firmware install on a new Sweep — still requires careful documentation so it doesn’t feel meaningfully harder than the KMK path.

2. NeoPixel diagnostic color codes — as a “deck status LED” idea

The KB2040 (and many similar RP2040-family boards) carries a single onboard NeoPixel that KMK uses to surface system state through a published color vocabulary:

State	NeoPixel pattern
Factory state (CircuitPython freshly installed)	Slow color-cycle rainbow
code.py has a syntax error	2 red flashes
No code.py present	Solid green
Code running normally	Off
File system in safe mode	Yellow
(and so on)

For KN-86 the lesson is not the specific color vocabulary — that’s KMK / CircuitPython’s, not ours — but the idea of a single onboard status LED with a documented color vocabulary as a deck-wide affordance. Worth scoping as a small KN-86 hardware addition:

• A single NeoPixel on the deck (likely on the Sweep half opposite the OLED, or alongside one of the controller daughterboards)
• A small documented color vocabulary published in the KN-86 owner’s manual: e.g., white = boot, amber = healthy / running, dim amber = sleep, red = error, flashing red = cart-format-error, flashing amber = update available, off = power off

The KN-86 vocabulary should be monochrome-amber-friendly to match the canonical AMBER aesthetic — use intensity / blink-rate / hue-shift to differentiate states rather than committing to a multi-color rainbow. The KMK vocabulary is the pattern; the KN-86 vocabulary is its own design downstream.

Image

No image downloaded. The GOLEM hub entry covers the source visually.

Notes

• Cross-link keyboard-decision.md — the decision context placing this entry in research/ as a non-actioned reference.
• Cross-link kmk-firmware.md — the firmware repo itself, with the “limited life support” caveat.
• Cross-link golem-hub.md — the parent index entry.
• Open promote item: the single-NeoPixel deck-status LED with documented amber-friendly color vocabulary as a small v0.1 hardware affordance. Worth scoping in an ADR or small spec entry.