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

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

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.

Rendering & fonts

thpoll83/adafruit-gfx-library — the GFX fork the firmware draws with, plus the fontconvert tool that builds the keycap fonts.

A fifth repository, thpoll83/polykybd-ctnd, is a Raspberry Pi hardware-in-the-loop rig that flashes and tests firmware on real hardware as part of CI. It is development infrastructure rather than something you need to use the keyboard — see Test Rig & CI.

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

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.