Firmware Overview
The PolyKybd runs QMK firmware — the most widely used open-source keyboard firmware, with excellent documentation and a large community.
What QMK gives you
Section titled “What QMK gives you”- Layers — define completely different keymaps activated by a hold or tap
- Macros — send multi-key sequences with a single keypress
- Tap-dance — different actions based on how many times a key is tapped
- Unicode input — send emoji and international characters on any OS
- Per-key display control — PolyKybd extends QMK with display rendering via the custom Adafruit GFX fork
A customised QMK fork
Section titled “A customised QMK fork”PolyKybd is a heavily customised QMK fork maintained on the PolyKybd branch:
github.com/thpoll83/qmk_firmware — branch: PolyKybd
Upstream base: QMK 0.33.13 (as of PolyKybd firmware v0.11.6). The fork tracks
upstream QMK’s stable release tags rather than its moving master, and is
re-based onto a newer tag periodically — so everything in the QMK documentation
for 0.33.x applies to your keyboard, alongside the PolyKybd additions described
here. The fork’s own master branch is kept as an untouched mirror of upstream,
which is what makes the difference between “stock QMK” and “PolyKybd” easy to see.
The keyboard-specific files live at:
keyboards/polykybd/The shared keymap logic — display rendering, the HID command handler, language selection,
idle/suspend, split synchronisation — lives in poly_keymap.c and is compiled for every variant.
The hardware it targets
Section titled “The hardware it targets”PolyKybd is custom hardware, not a stock board:
- MCU: Raspberry Pi RP2040 — dual-core ARM Cortex-M0+, running at 200 MHz since firmware v0.11.0 (the operating point Raspberry Pi certified for the chip; earlier firmware ran at 125 MHz). QMK runs on core 0; core 1 is used for RLE decompression of overlay images. See System clock.
- Flash: 8 MB external QSPI flash (not the stock 2 MB), partitioned into:
- 0–2 MB — the running firmware
- 2–4 MB — firmware-update staging
- 4–6 MB — the font pack (independently-versioned glyph bundles)
- 6–8 MB — additional resource packs
- Displays: up to 72 per-keycap OLEDs (72×40 px monochrome, SPI-driven) plus a status OLED.
- Split: a left + right half connected over UART, with CRC32-validated state and overlay sync.
There are two hardware variants, split72 and split42, sharing one firmware codebase — see Keyboard Variants.
Host communication
Section titled “Host communication”The firmware talks to the host application (PolyKybdHost) over a
custom 64-byte raw HID report protocol. Each report is [report id, command id, payload…], and
responses are prefixed P\xNN. (ACK) or P\xNN! (NACK). A PROTOCOL_VERSION reported in the
device’s identity string gates host features, and the host connects only on an exact version
match. See the HID Protocol Reference for the command surface and the
per-version feature history.