Dynamic Keyboard Firmware Lab

keyfw is a Go lab for dynamic mechanical keyboard firmware behavior: validated keymap configs, layered matrix scanning, tap-hold keys, macros, and a firmware-image artifact that can be flashed or transported by a real host tool later.

The MVP is hardware-free so it can run in CI, but the core model mirrors common keyboard firmware concepts used by QMK/ZMK-style projects.

Features

• JSON keymap configuration with matrix dimensions, layers, and actions.
• Validation for coordinates, unknown actions, missing layers, and action shape.
• Dynamic layer engine with base layer and momentary Fn layer.
• Tap-hold action simulation with configurable threshold.
• Macro sequence expansion.
• HID-style active key reports.
• Firmware image compiler with version, inventory, and SHA-256 config hash.
• Table, JSON, and Markdown simulation output.

Quick Start

go build -o keyfw ./cmd/keyfw

./keyfw validate --config examples/keymap.json
./keyfw compile --config examples/keymap.json --output firmware-image.json --version v0.1.0
./keyfw simulate --config examples/keymap.json --events examples/scan-events.jsonl --format table

Run the built-in demo:

./keyfw demo --format table

Commands

keyfw validate --config examples/keymap.json
keyfw compile --config examples/keymap.json --output firmware-image.json
keyfw simulate --config examples/keymap.json --events examples/scan-events.jsonl --format table
keyfw demo --format markdown
keyfw version

Keymap Model

The example keymap defines a 3x3 matrix:

• base layer keys: Q W E / A S D
• MO_FN: momentary Fn layer
• TH_TAB_CTRL: tap for TAB, hold for LCTRL
• MAC_HELLO: expands to H E L L O

The Fn layer remaps the top and home rows to navigation keys.

Firmware Image

keyfw compile writes a JSON image with:

• keyboard name and vendor
• build version and timestamp
• SHA-256 hash of the source keymap
• matrix, layers, actions, and inventory

That artifact is intentionally transport-neutral: a real board flasher could send it over serial, USB vendor endpoint, BLE, or a bootloader protocol.

Hardware Scope

This project does not flash a real board or emit USB HID reports to the OS. When adapting it to hardware, test on boards you own, keep a recovery keymap, and validate matrix wiring, debounce settings, and bootloader entry before enabling live reconfiguration.

Development

go test ./...
go vet ./...
go build -o keyfw ./cmd/keyfw

Project Status

MVP complete:

• Dynamic keymap validation.
• Layered matrix simulation.
• Tap-hold and macro actions.
• Firmware-image compiler.
• Examples, docs, tests, and CI.