Crate rmk

Source
Expand description

Logo

A feature-rich keyboard firmware written in Rust.

👉 Join our Discord server for discussions, support, and community collaboration!

中文

§Features

  • Broad microcontroller compatibility: Leveraging embassy, RMK supports a comprehensive range of microcontrollers, including stm32, nRF, rp2040(w), esp32, etc
  • Dynamic keymap customization: RMK offers native Vial support, enabling real-time keymap modifications. You can even edit keymaps over BLE connections wirelessly
  • Advanced keyboard functionality: RMK comes with lots of advanced keyboard features by default, including layer switching, media controls, system commands, mouse control, and more
  • Wireless connectivity: BLE wireless support with automatic reconnection and multi-device capabilities for nRF52 and esp32 microcontrollers, tested on nRF52840, esp32c3, esp32s3, Pi Pico W
  • Easy configuration: RMK simplifies keyboard development through a single keyboard.toml configuration file. For Rust enthusiasts, the firmware remains highly customizable using Rust code
  • Optimized performance: RMK achieves approximately 2ms latency in wired mode and 10ms in wireless mode. With the async_matrix feature enabled, power consumption is significantly reduced—a 2000mAh battery can power your keyboard for several months

§News

  • 2025-06-04: v0.7.0 is released! Check out the migration guide to upgrade!

§User Documentation | API Reference | FAQs | Changelog

§Real-World Implementations

§rmk-ble-keyboard

§dactyl-lynx-rmk

§Getting Started

§Option 1: Start with a Template

Quickly bootstrap your project using rmkit and the official RMK project template.

cargo install rmkit flip-link
# If you encounter installation issues on Windows, try this alternative command:
# powershell -ExecutionPolicy ByPass -c "irm https://github.com/haobogu/rmkit/releases/download/v0.0.13/rmkit-installer.ps1 | iex"
rmkit init

For comprehensive guidance, refer to the User Guide.

§Option 2: Explore Built-in Examples

Browse the examples in the examples directory. Below are step-by-step instructions for rp2040 development. The process is similar for other microcontrollers when using a debug probe.

§rp2040 Setup

  1. Install probe-rs

    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-tools-installer.sh | sh

  2. Build the firmware

    cd examples/use_rust/rp2040
cargo build --release

  3. Flash using a debug probe

    With a debug probe connected to your rp2040 board, simply run:

    cd examples/use_rust/rp2040
cargo run --release

  4. (Optional) Flash via USB

    Without a debug probe, you can use elf2uf2-rs to flash via USB:

    1. Install the tool: cargo install elf2uf2-rs
    2. Modify examples/use_rust/rp2040/.cargo/config.toml to use elf2uf2:
      - runner = "probe-rs run --chip RP2040"
+ runner = "elf2uf2-rs -d"
    3. Connect your rp2040 board while holding the BOOTSEL button until the USB drive appears
    4. Flash the firmware:
      cd examples/use_rust/rp2040
cargo run --release
      Upon successful completion, you’ll see output similar to:
      Finished release [optimized + debuginfo] target(s) in 0.21s
Running `elf2uf2-rs -d 'target\thumbv6m-none-eabi\release\rmk-rp2040'`
Found pico uf2 disk G:\
Transfering program to pico
173.00 KB / 173.00 KB [=======================] 100.00 % 193.64 KB/s

§Development Roadmap

Current roadmap of RMK can be found here.

§Minimum Supported Rust Version (MSRV)

RMK is developed against the latest stable Rust release. While other versions may work, they are not fully tested.

§License

RMK is licensed under either of

at your option.

§Feature flags

  • storage (enabled by default) — the storage is optional to save memory
  • col2row (enabled by default) — If your PCB diode’s direction is col2row, enable this feature. If it’s row2col, disable this feature by default-features = false.
  • defmt (enabled by default) — Enable defmt feature
  • std — Add std feature for testing
  • async_matrix — Enable async matrix scan
  • rapid_debouncer — Use rapid debouncer
  • split — Feature for split keyboard
  • controller — Feature for controller devices
  • _no_usb — Internal feature that indicates no USB is used, this feature will be auto-activated for some chips
  • rp2040_pio — Enable feature if you want to use RP2040 PIO UART
  • rp2040_bl — Enable feature if you want rp2040 bootloader jumping key
  • adafruit_bl — Enable feature if you’re using Adafruit nRF52 bootloader and want bootloader jumping key

§BLE feature flags

⚠️ Due to the limitation of docs.rs, functions gated by BLE features won’t show in docs.rs. You have to head to examples folder of RMK repo for their usages.

  • nrf52840_ble — Enable feature if you want to use nRF52840 with BLE.
  • nrf52833_ble — Enable feature if you want to use nRF52833 with BLE.
  • nrf52832_ble — Enable feature if you want to use nRF52832 with BLE.
  • nrf52811_ble — Enable feature if you want to use nRF52811 with BLE.
  • nrf52810_ble — Enable feature if you want to use nRF52810 with BLE.
  • esp32c3_ble — Enable feature if you want to use ESP32C3 with BLE.
  • esp32c6_ble — Enable feature if you want to use ESP32C6 with BLE.
  • esp32s3_ble — Enable feature if you want to use ESP32S3 with BLE.
  • pico_w_ble — Enable feature if you want to use RP2040W with BLE.
  • _ble — Enable feature if you want to use trouble BLE stack

Re-exports§

pub use embassy_futures;
pub use futures;
pub use heapless;
pub use rmk_macro as macros;

Modules§

action
channel
Exposed channels which can be used to share data across devices & processors
combo
config
debounce
descriptor
direct_pin
event
fork
hid
hid_state
input_device
Input device module for RMK
keyboard
keyboard_macros
keycode
keymap
layout_macro
light
matrix
split
state
storage
tap_dance
tap_hold
usb
via

Macros§

a
Create a normal action: KeyAction
bind_device_and_processor_and_run
Macro to bind input devices and an input processor directly.
df
create a switch default layer action, n is the layer number
encoder
Create an encoder action, the first argument is the clockwise action, the second is the counter-clockwise action
join_all
Helper macro for joining all futures
k
Create a normal key. For example, k!(A) represents KeyAction::Single(Action::Key(KeyCode::A))
layer
Create a layer in keymap
lm
Create a layer activate with modifier action
lt
Create a layer activate action or tap key(tap/hold)
mo
Create a layer activate action. For example, mo!(1) activates layer 1.
mt
Create a modifier-tap-hold action
osl
Create an oneshot layer key in keymap
osm
Create an oneshot modifier key in keymap
read_storage
Helper macro for reading storage config
run_devices
Macro to bind input devices to event channels and run all of them.
run_processor_chain
Macro for binding input processor chain to event channel and running them.
shifted
Create a shifted key
tg
Create a layer toggle action
th
Create a tap-hold action
to
Create a layer toggle only action (activate layer n and deactivate all other layers), n is the layer number
tt
Create a layer activate or tap toggle action
wm
Create a normal key with modifier action

Functions§

initialize_encoder_keymap
initialize_encoder_keymap_and_storage
initialize_keymap
initialize_keymap_and_storage
run_rmk