Flashing the Firmware

There are two ways to flash PolyKybd firmware. The recommended way is over HID directly from PolyKybdHost — no buttons, no bootloader drive. The UF2 bootloader drive method is kept as a recovery fallback.

Recommended: flash over HID from PolyKybdHost

PolyKybdHost includes a firmware updater (polyhost/device/hid_fw_up.py) that pushes a firmware image to the keyboard over the normal HID connection. No BOOT button is needed, and — importantly — it works even across protocol-version mismatches, so a keyboard running incompatible firmware can still be updated.

The deliverable for HID flashing is a raw .bin image (not the .uf2).

From the tray app
From the command line

Open PolyKybdHost (system-tray icon).
Use the firmware update action — either the release-update flow (which fetches a published keyboard-firmware release) or Flash firmware .bin… to pick a local .bin.
Confirm and let it transfer. Progress is shown as it streams the image to the keyboard.
Apply the update when prompted — the keyboard reboots into the new firmware.

The polyctl console tool can flash without the GUI:

polyctl fw flash path/to/firmware.bin --apply

fw flash streams progress to the terminal. Without --apply it stages the image; with --apply it stages and then applies (reboots into) the new firmware.

You can also check the running version first:

polyctl fw version

Official firmware releases are signed, and the keyboard verifies the signature against a key built into its firmware before applying an update.

The release-update flow in the tray app handles this for you — it downloads the release’s .bin.sig alongside the .bin, and stops with an explanation rather than flashing if the signature can’t be fetched. If you download a release by hand instead, take the .bin.sig too and put it in the same folder as the .bin: the host looks for it right there, and without it the keyboard treats the image as unsigned.

An unsigned image is not rejected, but it is not applied silently either: the keyboard blanks its keycaps except a big A / ACCEPT on the left half and R / REJECT on the right, states the question on the status OLED, and waits up to a minute for you to press one. That is expected for a firmware you built yourself. If the host instead reports that the signature does not match, the .bin and .sig are from different builds or one of them is damaged — re-download both.

If you build and sign your own firmware — or want to require signatures — see Firmware signing.

Fallback: UF2 bootloader drive

Use this if the keyboard can’t be reached over HID (e.g. a bad image left it unresponsive). It flashes the .uf2 build, not the .bin.

Entering bootloader mode

Hold down the BOOT button on the PCB.
While holding it, connect the USB-C cable to the half you’re flashing.
Release the button.
The keyboard mounts as a USB drive called RPI-RP2.

Copying the firmware

Download the latest .uf2 from the firmware repo releases (or build your own — see below) and copy it onto the RPI-RP2 drive. The drive unmounts automatically when flashing completes.

Building from source

To build your own firmware image, see Firmware Development for the full toolchain setup and build commands. In short:

qmk compile -kb polykybd/split72 -km default   # or /split42

The build produces a .uf2 (for the bootloader drive). For HID flashing, convert the ELF to a raw .bin:

arm-none-eabi-objcopy -O binary .build/<target>.elf .build/<target>.bin

Verifying the flash

After the update applies and the keyboard reboots:

Wait 1–2 seconds for the firmware to boot.
All per-key displays should show characters.
Press keys to confirm they respond, and check that both halves are active.