Crate rmk

source ·
Expand description

§RMK

Crates.io Docs Build Discord

中文

A feature-rich Rust keyboard firmware.

§Features

  • Support a wide range of microcontrollers: Powered by embassy, RMK supports a wide range of microcontrollers, such as stm32/nrf/rp2040/esp32
  • Real-time keymap editing: RMK has built-in vial support, the keymap can be changed on-the-fly
  • Advanced keyboard features: Many advanced keyboard features are available by default in RMK, such as layer switch, media control, system control, mouse control, etc
  • Wireless: (Experimental) BLE wireless support with auto-reconnection/multiple devices feature for nrf52 and esp32 microcontrollers, tested on nrf52840 and esp32c3
  • Easy configuration: RMK provides a simple way to build your keyboard: a keyboard.toml is all you need! For experienced Rust user, you can still customize your firmware easily using RMK

§User Documentation | API Reference | FAQs

§News

  • [2024.05.01] RMK’s new configuration system is available at main branch! This new feature brings a totally new way to build your keyboard firmware: using a config file keyboard.toml. The document can be found here, you can also check out the examples folder for both config way and rust way to use RMK.

  • [2024.04.07] BLE support for esp32 is available now on main branch, you can try the example at examples/use_rust/esp32c3_ble and examples/use_rust/esp32s3_ble. It will be released to crates.io soon, after some additional testing.

Click to check out more news

  • [2024.03.07] BLE support with auto-reconnection/multiple devices feature for nrf52840/nrf52832 has been added to RMK! Checkout examples/use_rust/nrf52840_ble and examples/use_rust/nrf52832_ble for details.

  • [2024.02.18] Version 0.1.4 is just released! This release contains a new build script for generating vial config, minor API update and a brand-new user documentation page.

  • [2024.01.26] 🎉rmk-template is released! Now you can create your own keyboard firmware with a single command: cargo generate --git https://github.com/HaoboGu/rmk-template

  • [2024.01.18] RMK just released version 0.1.0! By migrating to Embassy, RMK now has better async support, more supported MCUs and much easier usages than before. For examples, check examples folder!

§Real World Examples

§rmk-ble-keyboard

§Usage

§Option 1: Initialize from template

You can use rmk-template to initialize your project.

cargo install cargo-generate
cargo generate --git https://github.com/HaoboGu/rmk-template

Then follow the steps in generated README.md. Check RMK’s User Guide for details.

§Option 2: Try built-in examples

Example can be found at examples. The following is a simple step-to-step instruction for rp2040. For other microcontrollers, the steps should be identical with a debug probe.

§rp2040

  1. Install probe-rs

    cargo install probe-rs --features cli

  2. Build the firmware

    cd examples/use_rust/rp2040
cargo build

  3. Flash using debug probe

    If you have a debug probe connected to your rp2040 board, flashing is quite simple: run the following command to automatically compile and flash RMK firmware to the board:

    cd examples/use_rust/rp2040
cargo run

  4. (Optional) Flash using USB

    If you don’t have a debug probe, you can use elf2uf2-rs to flash your firmware via USB. There are several additional steps you have to do:

    1. Install elf2uf2-rs: cargo install elf2uf2-rs
    2. Update examples/use_rust/rp2040/.cargo/config.toml, use elf2uf2 as the flashing tool
      - runner = "probe-rs run --chip RP2040"
+ runner = "elf2uf2-rs -d"
    3. Connect your rp2040 board holding the BOOTSEL key, ensure that rp’s USB drive appears
    4. Flash
      cd examples/use_rust/rp2040
cargo run
      Then, you will see logs like if everything goes right:
      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

§Roadmap

Current roadmap of RMK can be found here.

§Minimum Supported Rust Version (MSRV)

This crate requires stable Rust 1.77 and up.

§License

RMK is licensed under either of

at your option.

§Feature flags

  • col2row (enabled by default) — If your PCB diode’s direction is col2row, enable this feature. If it’s row2col, disable this feature.
  • async_matrix — Enable async matrix scan
  • rapid_debouncer (enabled by default) — Use rapid debouncer
§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.
  • nrf52832_ble — Enable feature if you want to use nRF52832 with BLE.
  • esp32c3_ble — Enable feature if you want to use ESP32C3 with BLE.
  • esp32s3_ble — Enable feature if you want to use ESP32S3 with BLE.

Re-exports§

Modules§

Macros§

  • a
    Create a normal action: KeyAction
  • 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.
  • osl
    Create an oneshot layer key in keymap
  • tg
    Create a layer toggle action
  • tt
    Create a layer activate or tap toggle action

Functions§