Keymaps & Layers

What are layers?

Layers work like the Shift key but for your entire layout. You can define multiple complete keymaps and switch between them with a dedicated key. PolyKybd’s per-key displays make layers instantly visible — every key shows its current function on the active layer.

PolyKybd uses QMK’s dynamic keymap with 8 host-remappable layers, so remaps can be written to the keyboard at runtime without recompiling. Remapping is done with the keymap editor built into PolyKybdHost — see Keymap Editor.

The utility and settings layers

Two layers hold the keyboard’s own controls, and which one a thing lives on follows a single rule: how often you reach for it.

Utility is what you touch while working — media and volume, the display brightness presets, legend size, mute, scroll lock. Nothing here changes how the keyboard is set up; it all changes what it is doing right now.

Settings is set-once or destructive — pinning the OS, picking a base layout, RGB, and the keys that reboot the board. Its everyday half is visible as soon as you open the layer: the OS pins and the five layout picks.

More…

The rest of the settings layer is blank and inert until you tap More… — the idle style and how long before it engages, the glyph script, the modifier and command legend modes, debug logging, the Eden replay, and Restart and Boot. Tap it once and that row appears; leave the layer and it hides itself again.

That is not decoration. Restart and Boot are one tap from a layer you open to change the OS pin, and neither is undoable from the keyboard — so they, and everything else on that row, take a deliberate second press to reach.

Note

Keys behind More… are inert as well as blank while hidden — a key that renders nothing but still reboots the board would be worse than a visible one.

Board info on the status display

Firmware v0.17.0+status-display board info

While More… is showing, the status display swaps from the usual layout/brightness panel to what the board is — the numbers you would otherwise have to ask the host for, or find in a log.

The numbers above are from a development board — yours will differ, and the firmware version shown is whatever that board happened to be running, not the one this screen needs.

Line	Means
FW 0.16.18	The firmware version running on this half.
P15 HW 0x0320	The HID protocol version the firmware speaks, and the hardware revision.
USB up 1:23:45	Whether this half is the one plugged into the computer (USB) or the one on the other end of the cable (LNK), and how long it has been powered. Past four days it switches to 3d 7h.
Lnk 0.4% 182k	Split-link health — see below.

Leave the settings layer and the display goes back to normal.

Note

On the split42 the status display is smaller, so it shows the first two lines only. Uptime and link health are split72.

Reading the link line

The two halves talk to each other over the cable, and the Lnk line is the only place that conversation is visible: the percentage is the share of messages that had to be retried or went unanswered, and the number beside it is how many have been sent.

It counts from power-on, and a handful of errors while the two halves find each other at boot is normal — so on a healthy board the percentage falls the longer you leave it running, as those first few are diluted by everything since. What matters is the direction: a number that climbs, or sits high on a board that has been up for hours, points at the cable or its connectors.

Two readings are not percentages at all:

• Lnk n/a on the half that is not plugged into the computer. Only the USB half starts these exchanges, so the other one has nothing to report — and showing it as 0.0% would look like a perfect link rather than no measurement.
• Lnk idle before anything has been sent yet.

Tip

This is the quickest way to answer “which firmware am I on?” with no computer attached — and the numbers to quote when reporting a problem if the host cannot see the keyboard at all.

Keys that name their own state

Several of these keycaps show what they are set to rather than what they do, so the layer can be read at a glance instead of pressed to find out: the idle-style and glyph-script keys carry a label over the current value (IDLE: / Eden), the layout picks show their name over a lit or unlit switch, and the modifier/command legend keys read Mods / Icon or Cmds / Text depending on which rendering is active.

The idle timeout key sits next to the idle-style one and follows the same rule, except that its top line is a small clock face rather than a word — two neighbours both reading IDLE: would be the one place this convention stopped helping. So it shows the clock over 2min, and each tap steps to the next preset.

The function layer

Firmware v0.15.14+one function layer, aligned F-row

Hold Fn and the number row becomes F1–F12. There is one function layer shared by every base layout, and the F-keys line themselves up with whichever layout you are using: F5 sits on the key that types 5, wherever that key is.

That matters because the layouts don’t agree on where the number row splits between the halves. Most carry 1–5 on the left and 6–0 on the right; one carries 1–6 on the left. The keyboard reads the active layout’s own number row and places the F-keys to match, rather than guessing.

If your F-keys used to be one key off

On Colemak and Workman the F-keys from F6 up previously sat one position to the left of their matching number — F6 over the - or ` key, F7 over 6, and so on. That is fixed. Qwerty, Neo and the 1–6 layout are unchanged.

Editing the function layer switches the alignment off

The function layer is remappable like any other, so you can change it in the keymap editor. But the editor shows what is stored, and the alignment happens on the keyboard as it draws — so the two would disagree if both were active at once.

They can’t be. The moment you change any key on the Fn number row, the alignment stops for that whole row and the keyboard uses exactly what you stored. Editor and keyboard agree again, which is what you want while you are editing. Reset the keymap and the alignment comes back.

Home row mods on Workman

Firmware v0.24.0+Workman base layout only

Pick the Workman base layout and its home row doubles as your modifiers: tap a key for the letter, hold it for the modifier.

	Left hand	Right hand
GUI (Win/Cmd)	a	i
Alt	s	o
Ctrl	h	e
Shift	t	n

The order is the Miryoku GACS arrangement — outside in, mirrored across the two halves — so the two strongest fingers carry Ctrl and Shift.

The keycaps tell you. A key that carries a held modifier draws a small badge in its corner, so you can see which finger holds what instead of memorising the table above.

Only Workman — the base layout is the on/off switch

These exist only on the Workman layer. Qwerty, Colemak, Neo and Stag are untouched, and so is their typing feel: there is no setting to find and nothing to turn off, you just pick a different base layout on the settings layer.

Right ring is Alt, not AltGr

The literal Miryoku arrangement puts AltGr on the right ring finger. PolyKybd uses plain Alt there instead, because AltGr on this keyboard is a deliberate separate function with its own keycap legends — a home row mod that quietly started producing accented characters would be a nasty surprise.

If a hold ever fires when you meant to type, that is what the tap-hold tuning is for: the keyboard uses a 200 ms tapping term together with QMK’s chordal hold and Flow Tap, which between them suppress a modifier on ordinary fast rolls. Settling as held on any other keypress is deliberately switched off.

Workman’s bottom row also gained its missing < / \ key, which had been a second B by mistake.

Where the keymap lives

The shared keymap logic (rendering, HID handling, language selection, and the QMK callbacks) is in:

keyboards/polykybd/poly_keymap.c

Each variant’s default keymap data — the keymaps[] array and encoder_map[] — is in its own variant directory:

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

Both live in the PolyKybd firmware repo. See Keyboard Variants for why the logic is shared.

Customizing with PolyKybdHost

Updating to v0.15.14 clears a customised keymap, once

This version merged two near-identical function layers into one, which shifts the internal numbering of every layer above it. The keyboard stores your remaps by layer number, so it clears them once on the first boot after the update rather than serving them on the wrong layers. Any custom layout needs re-applying — after that, updates leave it alone as usual. The layout editor also now offers eight remappable layers instead of nine, since one of the two it merged is gone.

The easiest way to remap keys is through the PolyKybdHost keymap editor, which writes changes directly to the keyboard’s dynamic keymap without needing to recompile firmware:

1. Open PolyKybdHost (system tray icon → Configure Keymap)
2. Click any key to select it
3. Choose the new keycode from the browser
4. The change is written immediately to the keyboard

This is also where you assign dual-function keys — a key that types a letter on a tap and acts as a modifier (or switches layer) when held. The keycap keeps its letter and shows the held modifier as a small corner mark. See Keymap Editor for details.

Customizing in QMK source

For deeper changes (new layers, macros, tap-dance), edit the variant’s keymap.c directly. The keymaps[] array is data only:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT(
        KC_ESC,  KC_1,  KC_2,  /* ... */
    ),
    [1] = LAYOUT(
        /* function layer */
    ),
};

Then rebuild and flash the firmware (target polykybd/split72 or /split42).

QMK’s full keycode reference is at docs.qmk.fm/keycodes. Everything documented there works on PolyKybd.

Layer indicator on the status display

The status OLED shows the current active layer, along with other status information like the unicode input mode and host OS selection.

Tip

Adding a new keymap without modifying the default is the safest way to experiment. Use qmk new-keymap -kb polykybd/split72 -km my_keymap (or /split42) to get started.