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 sends the firmware image to the keyboard over its normal USB connection. No BOOT button is needed, and it works even when the keyboard’s protocol version does not match the host, so a keyboard on incompatible firmware can still be updated.

The image goes over the keyboard’s fast link (a USB serial port next to the HID interface) when the firmware and the host both have it (firmware 1.9.4 and host 1.17.28 or newer), which transfers a full image in about 11 s, and over HID otherwise, about 50 s. The tray tooltip names the link in use. Details: Firmware Update over USB.

HID flashing uses a raw .bin image (not the .uf2).

From the tray app

1. Open PolyKybdHost (system-tray icon).
2. 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.
3. Confirm and let it transfer. Progress is shown as it streams the image to the keyboard.
4. Apply the update when prompted — the keyboard reboots into the new firmware.

From the command line

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

Note

While the image transfers, the keycap legends do not change. Holding Shift, toggling Caps Lock or holding a layer key does not repaint them. The keys themselves still work, so you can keep typing. The legends update when the transfer ends, and applying the image reboots the keyboard into the new firmware.

Caution

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 also not applied without asking: 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

1. Hold down the BOOT button on the PCB.
2. While holding it, connect the USB-C cable to the half you’re flashing.
3. Release the button.
4. 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.

Note

You only need to connect one half at a time. Repeat the process for the second half if needed.

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:

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

Caution

If displays stay blank after multiple attempts, check the FPC cable connections — see the Step-by-Step Build Guide.