Keysmith Firmware

Safety-gated QMK firmware for the Keychron Q3 Max ANSI encoder.
Inspect deeply. Prepare exactly one operation. Touch the keyboard to approve it.

Website · Host app · Keymap details · Protocol specification · Build it

Important

This repository publishes source, not a one-click firmware updater. It does not contain factory dumps, private configuration snapshots, pairing material, recovery images, or prebuilt .bin files. Building is automated; flashing is deliberately separate and attended.

Note

The public 0.3.0-candidate branch is build-validated in CI, not published as a firmware release and not yet validated on hardware as this exact commit. The reference keyboard installation documented by the host project came from an earlier source revision.

What this fork is

Keysmith extends Keychron's public QMK tree with a small Raw HID protocol at command 0xAC. The protocol makes useful keyboard state observable while keeping mutation behind a short-lived, plan-bound physical gate.

This is not a general remote-control backdoor and not a replacement for normal typing. USB, Bluetooth, and 2.4 GHz continue to carry ordinary keyboard input. Keysmith management uses USB only.

Why it exists

Goal	Firmware decision
Inspect without guessing	Versioned queries expose build, device, runtime, keymap, encoder, RGB, wireless, and macro metadata.
Preserve privacy	Macro contents and radio credentials are never returned.
Make changes reviewable	Every mutation is bound to an eight-byte plan tag and one complete target payload.
Require a human at the board	Esc + Space + Right Control must be held for three seconds after preparation.
Prevent reusable authorization	The gate applies once and relocks after success, error, timeout, disconnect, transport change, or reset.
Keep recovery independent	Bootloader entry, radio DFU, and STM32 flashing are outside the protocol.

The safety gate

The physical chord only arms the exact operation that was already prepared. It does not enable a global write mode. A mismatched commit fails closed.

Supported attended operations

• one dynamic keycode
• one complete RGB profile
• one encoder direction binding
• wireless backlight and sleep policy
• debounce algorithm and duration

Explicitly outside the boundary

• macro writes or macro-content reads
• Bluetooth pairing or host selection
• 2.4 GHz receiver provisioning
• per-key RGB and Snap Click writes without complete rollback state
• Keychron radio DFU, factory-test commands, and VIA bootloader jump
• STM32 firmware flashing
• browser, server, timer, background-agent, or remote apply

Legacy VIA and Keychron setters are denied before their normal dispatch. The keymap also undefines Keychron's VIA_INSECURE matrix reporting so ordinary Raw HID clients cannot poll live key presses.

Capability matrix

Capability	USB	Bluetooth	2.4 GHz
Normal typing, media, knob	Yes	Yes	Yes
Keysmith inspection	Yes	No	No
Prepare / status / cancel protocol	Yes	No	No
Physically confirmed bounded mutation	Yes	No	No
Keysmith pairing, radio provisioning, firmware flashing	No	No	No

Build it

The default branch is keysmith/q3-max-v3 and is based on Keychron's 2025q3 line. Clone submodules and compile the single validated target:

git clone --recurse-submodules https://github.com/karti-ai/keysmith-qmk.git
cd keysmith-qmk
git switch keysmith/q3-max-v3
make keychron/q3_max/ansi_encoder:keysmith

The result is keychron_q3_max_ansi_encoder_keysmith.bin in the repository root. Record its digest before any separate attended flashing procedure:

sha256sum keychron_q3_max_ansi_encoder_keysmith.bin

The Keysmith build workflow compiles this target on every relevant change. It intentionally does not upload the binary as a public artifact.

Caution

A successful compile is not permission to flash. Confirm the exact Q3 Max ANSI encoder target, take a fresh full-device readback, keep two verified recovery copies, review the candidate SHA-256, and approve that exact image at the local terminal. Never automate DFU.

Source tour

Path	Responsibility
keysmith_protocol.c	Protocol queries, prepared-operation state machine, physical chord, bounded apply, and relock behavior.
config.h	Protocol version, stable VIA EEPROM marker, and secure matrix-reporting policy.
keymap.c	Factory-compatible ANSI encoder layout.
keychron_raw_hid.c	Keyboard-level Raw HID policy hook and early command denial.
wireless.c	Bounded read-only wireless runtime visibility.
quantum/via.c	Stable, keymap-defined VIA EEPROM marker support.

The public branch changes firmware source/keymap files over the pinned Keychron base. The rest of this repository remains the upstream Keychron/QMK tree so the complete corresponding source and build inputs stay available.

Host-side project

The companion Keysmith application provides the Rust protocol core, keychronctl CLI, loopback-only API, and React control surface. Its browser and server remain read-only. Even keychronctl plan prepare is an offline packet compiler and never opens the keyboard.

Contributing safely

Changes to the transaction protocol should be small, reviewable, and fail closed. New mutation types need complete rollback evidence, bounded payload validation, deterministic host-side planning, explicit physical confirmation, readback, and a terminal relock path.

Do not submit device dumps, firmware binaries, pairing data, private snapshots, credentials, or machine-specific deployment records. Security reports that could bypass the physical gate should use GitHub private vulnerability reporting rather than a public issue.

Upstream and license

This fork is possible because Keychron publishes its QMK firmware source and device documentation. We are sincerely grateful for that openness and hope Keysmith contributes something useful back to the keyboard community.

This fork is based on Keychron QMK, which in turn tracks QMK Firmware. All upstream copyrights and license notices are preserved. The repository's source license is documented in LICENSE, and Keysmith additions are GPL-2.0-or-later. Combined ARM firmware also links GPLv3 ChibiOS; distributing such a binary requires GPLv3 terms plus complete corresponding source and build inputs.

Keysmith is an independent community project and is not affiliated with or endorsed by Keychron, QMK, or VIA.