Edit the Keymap

This HowTo changes what the keys do. There are two routes — pick by how permanent the change is and how deep it goes:

Route	Best for	Recompile?	Survives a reflash?
1. PolyKybdHost Layout Editor	Remapping individual keys, quickly	No	Yes — kept in the keyboard’s EEPROM*
2. QMK firmware source	Permanent keymaps, layers, macros — and behaviour beyond the keymap	Yes	Yes — it is the compiled default

Background on layers and the dynamic keymap is on Keymaps & Layers.

Caution

There is no QMK Configurator or keymap.json route for PolyKybd. The online Configurator only lists keyboards in mainline QMK, and PolyKybd is a fork, so it isn’t there. The keymap.json workflow doesn’t work either: qmk c2json can’t parse the firmware’s custom keycodes and layer names, and a JSON-built image would drop the per-variant g_led_config (RGB matrix) and encoder_map that live in the keymap. Use one of the two routes below.

Route 1 — PolyKybdHost Layout Editor (runtime)

The fastest route. Right-click the PolyKybdHost tray icon → Configure Keymap, click a key, pick a keycode, and it’s written to the keyboard over HID immediately — no recompile. It writes a single key at a time (ID_DYNAMIC_KEYMAP_SET_KEYCODE) and the change persists across power cycles.

Full walkthrough and limitations: Keymap Editor.

Note

* The Layout Editor writes to the keyboard’s EEPROM, which lives in a separate flash region from the firmware image — so your remaps persist across power cycles and survive a normal firmware reflash. The only time they revert to the compiled defaults is when a firmware update changes the on-keyboard EEPROM layout, or you explicitly clear the EEPROM. Reach for route 2 when you want the change to be the firmware default, or when you need behaviour beyond remapping single keys (new layers, macros, encoder logic).

Route 2 — QMK firmware source

Editing the firmware directly is the most powerful route: it does much more than remap keys — new layers, macros, tap-dance, encoder behaviour, and any custom QMK logic. It’s also the way to make your change the compiled default that ships with the firmware (rather than living only in the keyboard’s EEPROM), so it’s there on a fresh board and is what you share or upstream.

The keymap data — the keymaps[] array, g_led_config, and encoder_map[] — lives per-variant:

keyboards/polykybd/split72/keymaps/default/keymap.c
keyboards/polykybd/split42/keymaps/default/keymap.c

The shared keymap logic (rendering, HID handling, the QMK callbacks) is in keyboards/polykybd/poly_keymap.c. Both are in the qmk_firmware fork; see Keyboard Variants for why the logic is shared but the data is per-variant.

1. Start from a copy so you can fall back to the default:

   qmk new-keymap -kb polykybd/split72 -km my_keymap    # or /split42

2. Make the change in keymaps[] (each layer is a LAYOUT_left_right_stacked(...) of keycodes):

   Remap / add a layer

   Replace a keycode, or add another [n] = LAYOUT_left_right_stacked(...) entry (up to 9 layers) plus a key that reaches it — MO(n) (momentary) or TG(n) (toggle). QMK’s keycode reference is at docs.qmk.fm/keycodes.

   Macro / tap-dance / custom

   These need firmware logic, not just data — implement them via the QMK callbacks and reference them from keymaps[]. This is exactly what makes route 2 worth it. See Firmware Development.

3. Rebuild and flash per Build & Flash from Source:

   qmk compile -kb polykybd/split72 -km my_keymap

A keymap change lands on the per-key displays automatically — the firmware re-derives every legend from the active layer.

See Contributing if you want to upstream a keymap change.