Skip to content
PolyKybd

Architecture & Ecosystem

PolyKybd is not a single program — it is a small stack of open-source projects that each own one layer of the system. Understanding how they connect makes the rest of these docs easier to navigate.

The big picture

Section titled “The big picture”
flowchart TB
    apps["Your apps<br/>(active window)"] --> host
    host["<b>PolyKybdHost</b> — Python, daemon + tray<br/>• tracks the active window<br/>• renders per-app key overlays<br/>• exposes a polyctl CLI + control socket"]
    host -- "USB HID (64-byte reports)" --> master
    master["<b>QMK firmware</b> — RP2040, branch PolyKybd<br/>Master half (USB)<br/>• draws each key's 72×40 OLED<br/>• decompresses overlays (core1)"]
    master -- "full-duplex serial (CRC32)" --> slave
    slave["<b>QMK firmware</b> — same image, slave role<br/>Slave half<br/>• mirrors state + overlays to its keys"]

The two keyboard halves run the same firmware image; which half is master is decided at runtime (the half with USB power). They stay in sync over a CRC32-validated full-duplex serial link.

The repositories

Section titled “The repositories”

Hardware

thpoll83/PolyKybd — KiCad PCBs, aluminium plates, 3D-printable case and key stems, and the build documentation source.

Firmware

thpoll83/qmk_firmware (branch PolyKybd) — a customised QMK fork for the RP2040. Two variants, split72 and split42, share one keymap codebase.

Host software

thpoll83/PolyKybdHost — the Python app that drives the displays. Runs as a background daemon with a tray GUI client and a polyctl command-line tool.

Those four are the stack itself. Four more repositories support it without being a layer of it:

  • thpoll83/polykybd-ctnd — a Raspberry Pi hardware-in-the-loop rig that flashes and tests firmware on real hardware as part of CI. Development infrastructure rather than something you need to use the keyboard; see Test Rig & CI.
  • thpoll83/wincompose — a maintained fork of Sam Hocevar’s WinCompose, kept alive because compose-key unicode input on Windows is a hard dependency for PolyKybd.
  • thpoll83/gnome-wayland-winreader — a read-only GNOME Shell extension that reports the focused window over D-Bus. On GNOME/Wayland, Mutter does not expose the active window over X11/EWMH, so the usual window-tracking libraries cannot see native Wayland windows.
  • thpoll83/polykybd-docs — this documentation site.

How the layers talk

Section titled “How the layers talk”
Link Transport Notes
Host ⇄ keyboard USB HID, 64-byte reports Command protocol with a versioned PROTOCOL_VERSION; see the HID Protocol Reference
Master ⇄ slave half Full-duplex serial (UART/PIO) CRC32-validated split transactions carry state and overlay data
Firmware ⇄ displays SPI + shift-register mux One 72×40 OLED per key, plus a status OLED per half
Host ⇄ host (multi-machine) TCP A forwarder relays the active window from a second computer — see Multi-Machine Setup

What works without the host

Section titled “What works without the host”

The keyboard is a complete QMK keyboard on its own: every key types, layers work, and the displays show the static labels baked into the firmware. PolyKybdHost is what makes the displays dynamic — context overlays, live language switching, adaptive brightness and the keymap editor. You can also flash firmware straight from the host over HID, with no bootloader button.