Skip to content
PolyKybd

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

  • 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

PolyKybd is a heavily customised QMK fork maintained on the PolyKybd branch:

github.com/thpoll83/qmk_firmware — branch: PolyKybd

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

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

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.

Further reading