Generate keyboard maps from QMK definitions #4

Merged

jwarykowski merged 1 commit from qmk-maps into main

2026-10-11 10:32:58 +00:00

jwarykowski commented

2026-10-11 10:27:39 +00:00

(Migrated from github.com)

Why

The Moonlander map has a gap at index 0 and a numbering that isn't the firmware's LED order, and new boards need a keybars find session. QMK's keyboards/<kb>/keyboard.json already knows every key's matrix position, physical x/y, and RGB LED order, so maps can be generated from it.

What

keybars gen KEYBOARD: a local keyboard.json, or a qmk_firmware path (zsa/voyager) fetched from GitHub.
- Default -order keymapp: Keymapp's API index — each half row by row in QMK layout order, thumb cluster last, index 0 a gap.
- -order firmware: QMK's rgb_matrix index, for a future backend that talks to the firmware directly (on the Moonlander this runs down each column).
- Thumbs and a split half's short inner column are left out, as in the hand-made maps; -inner keeps the inner column.
maps/voyager.txt: top-left 0 → -, matching the Moonlander and the generated map. If Keymapp returns failure for index 0, Frame would otherwise stop keybars with -height 4.
README documents gen under "Adding a keyboard".

Findings on index 0

Not keybars' encoding: fields() omits zero fields exactly as kontroll/prost do for proto3 int32 led = 1.
Not the firmware: ZSA's Oryx module writes webhid_leds[param[0]] for any index, and QMK says LED 0 is the top-left key on both boards.
So Keymapp drops it. kontroll set-rgb --led 0 would confirm before reporting it to ZSA.

Testing

TestKeymappMatchesBuiltinMaps: the map generated from QMK equals the hand-tested Moonlander map exactly, and the (now fixed) Voyager map.
Firmware order, inner columns, one-piece boards, and missing rgb_matrix are covered.
Run with Go 1.24 against local clones of the dependencies (the module proxy wasn't reachable from the session), so please run go test ./... on 1.25 before merging.

Notes

internal/qmk/testdata/*.json are trimmed copies of QMK's ZSA definitions (GPL-2.0-or-later), test-only; see its README. Drop them if you'd rather keep the repo strictly MIT.
Definitions that inherit from a parent info.json (e.g. the ErgoDox EZ) aren't followed yet; pass qmk info -kb … -f json output instead.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NLaq6YcfqSLfjkQq55MVpr

Generated by Claude Code

## Why The Moonlander map has a gap at index 0 and a numbering that isn't the firmware's LED order, and new boards need a `keybars find` session. QMK's `keyboards/<kb>/keyboard.json` already knows every key's matrix position, physical x/y, and RGB LED order, so maps can be generated from it. ## What - `keybars gen KEYBOARD`: a local `keyboard.json`, or a qmk_firmware path (`zsa/voyager`) fetched from GitHub. - Default `-order keymapp`: Keymapp's API index — each half row by row in QMK layout order, thumb cluster last, index 0 a gap. - `-order firmware`: QMK's `rgb_matrix` index, for a future backend that talks to the firmware directly (on the Moonlander this runs down each column). - Thumbs and a split half's short inner column are left out, as in the hand-made maps; `-inner` keeps the inner column. - `maps/voyager.txt`: top-left `0` → `-`, matching the Moonlander and the generated map. If Keymapp returns failure for index 0, `Frame` would otherwise stop keybars with `-height 4`. - README documents `gen` under "Adding a keyboard". ## Findings on index 0 - Not keybars' encoding: `fields()` omits zero fields exactly as kontroll/prost do for proto3 `int32 led = 1`. - Not the firmware: ZSA's Oryx module writes `webhid_leds[param[0]]` for any index, and QMK says LED 0 is the top-left key on both boards. - So Keymapp drops it. `kontroll set-rgb --led 0` would confirm before reporting it to ZSA. ## Testing - `TestKeymappMatchesBuiltinMaps`: the map generated from QMK equals the hand-tested Moonlander map exactly, and the (now fixed) Voyager map. - Firmware order, inner columns, one-piece boards, and missing `rgb_matrix` are covered. - Run with Go 1.24 against local clones of the dependencies (the module proxy wasn't reachable from the session), so please run `go test ./...` on 1.25 before merging. ## Notes - `internal/qmk/testdata/*.json` are trimmed copies of QMK's ZSA definitions (GPL-2.0-or-later), test-only; see its README. Drop them if you'd rather keep the repo strictly MIT. - Definitions that inherit from a parent `info.json` (e.g. the ErgoDox EZ) aren't followed yet; pass `qmk info -kb … -f json` output instead. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01NLaq6YcfqSLfjkQq55MVpr --- _Generated by [Claude Code](https://claude.ai/code/session_01NLaq6YcfqSLfjkQq55MVpr)_