https://github.com/fuchskurt/keychron_q1_pro_rmk
Custom RMK firmware for the Keychron Q1 Pro ISO in Rust
https://github.com/fuchskurt/keychron_q1_pro_rmk
embassy firmware keyboard keychron rmk rust stm32
Last synced: 2 months ago
JSON representation
Custom RMK firmware for the Keychron Q1 Pro ISO in Rust
- Host: GitHub
- URL: https://github.com/fuchskurt/keychron_q1_pro_rmk
- Owner: fuchskurt
- License: apache-2.0
- Created: 2026-01-10T11:19:58.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T15:39:03.000Z (3 months ago)
- Last Synced: 2026-03-31T17:31:07.009Z (3 months ago)
- Topics: embassy, firmware, keyboard, keychron, rmk, rust, stm32
- Language: Rust
- Homepage: https://fuchskurt.github.io/keychron_q1_pro_rmk/
- Size: 166 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# Keychron Q1 Pro ISO — RMK Firmware
[](https://fuchskurt.github.io/keychron_q1_pro_rmk/rmk_q1_pro_iso/)
[](https://github.com/fuchskurt/keychron_q1_pro_rmk/releases)
[](#license)
Custom firmware for the Keychron Q1 Pro ISO, written in Rust using the
[RMK](https://github.com/HaoboGu/rmk) keyboard framework and
[Embassy](https://embassy.dev) async runtime. Replaces the stock QMK firmware
with a fully open, Rust-native implementation that retains Vial compatibility
for keymap editing.
| | |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Keyboard Maintainer** | [Kurt Fuchs](https://github.com/fuchskurt) |
| **Hardware** | Keychron Q1 Pro ISO |
| **MCU** | STM32L432KB (Cortex-M4F, 80 MHz, 128K Flash, 64K RAM) |
| **Availability** | [Keychron Q1 Pro QMK/VIA Wireless Custom Mechanical Keyboard](https://www.keychron.com/products/keychron-q1-pro-qmk-custom-mechanical-keyboard-iso-layout-collection) |
---
## Table of Contents
- [How it works](#how-it-works)
- [Building](#building)
- [Flashing](#flashing)
- [Keymap editing](#keymap-editing)
- [Project structure](#project-structure)
- [License](#license)
---
## How it works
### Matrix scanning
The Q1 Pro uses a standard mechanical switch matrix. Column selection is driven
by a 74HC595 shift register clocked via GPIO bit-bang, with 6 row inputs read
as active-low GPIO EXTI pins. For each column the firmware:
1. Shifts out a 16-bit mask via the HC595, driving the selected column low
2. Waits a short settle delay for the signal lines to stabilise
3. Reads all 6 row pins
4. Passes each reading through a debouncer before emitting a key event
### Debouncing
Key state transitions are filtered through RMK's built-in `DefaultDebouncer`
before a `KeyboardEvent` is emitted. Scanning resumes from the last recorded
position after an event is returned, so no transitions are missed while the
event is being processed upstream.
### Backlight
RGB backlighting is driven by two CKLED2001 LED driver chips over I²C, each
controlling half the keyboard. The firmware applies gamma 2.2 correction and
brightness scaling to all LED writes. The Caps Lock indicator is driven as a
distinct colour via an async channel from the key event processor to the
backlight task.
### Layers and input devices
The firmware supports two layers (Mac and Windows base layers) switchable via
a physical panel toggle switch. A rotary encoder provides volume control. Both
use async edge-interrupt input with debouncing.
---
## Building
Requires a nightly Rust toolchain and the `thumbv7em-none-eabihf` target.
```sh
rustup toolchain install nightly
rustup target add thumbv7em-none-eabihf
rustup component add rust-src
cargo install flip-link
```
Build the firmware:
```sh
cargo build --release
```
Produce a `.bin` artifact:
```sh
cargo make objcopy
```
---
## Flashing
### DFU (recommended)
Put the keyboard into DFU mode by holding the reset button, then:
```sh
dfu-util -l # note the serial number
dfu-util -a 0 -s 0x08000000:mass-erase:force:leave \
-D rmk.bin \
-S
```
### probe-rs (debug probe)
```sh
probe-rs run --chip STM32L432KB target/thumbv7em-none-eabihf/release/rmk-q1_pro
```
---
## Keymap editing
The firmware is Vial-compatible. Download [Vial](https://get.vial.today) and
connect the keyboard to remap keys and configure behaviour without reflashing.
---
## Project structure
```
src/
├── main.rs # Entry point, peripheral init, task startup
├── keymap.rs # Default keymap and encoder map
├── vial.rs # Generated Vial keyboard definition
├── matrix/
│ ├── hc595_cols.rs # 74HC595 shift register column driver
│ ├── shiftreg_matrix.rs # Shift register matrix scanner
│ └── layer_toggle.rs # Physical layer toggle switch
├── backlight/
│ ├── init.rs # Backlight task and soft-start ramp
│ ├── gamma_correction.rs # Gamma 2.2 LUT
│ ├── lock_indicator.rs # Caps lock indicator processor
│ └── mapping/
│ └── iso_knob.rs # LED index to CKLED channel mapping
└── ckled2001/
├── driver.rs # CKLED2001 I²C driver
├── led_address.rs # LED channel address constants
└── registers.rs # CKLED2001 register definitions
```
---
## License
Licensed under either of [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE) at your option.