Crate rmk

Source

Expand description

A modern, easy-to-use, and 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 real-time keymap modifications through Vial, or its native Rynk protocol (experimental). 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, nRF54, esp32, Pi Pico W and SF32LB52 microcontrollers, tested on nRF52840, nRF54L15, nRF54LM20, esp32c3, esp32c6, esp32h2, 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

§User Documentation | API Reference | FAQs | Changelog

§Real-World Implementations

rmk-ble-keyboard	dactyl-lynx-rmk	sessile

Urchin	zx66	rmk-zsa-voyager

§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/rmk-rs/rmkit/releases/latest/download/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

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

Build the firmware

cd examples/use_rust/rp2040
cargo build --release

Flash using a debug probe

With a debug probe connected to your rp2040 board, simply run:
```
cd examples/use_rust/rp2040
cargo run --release
```

(Optional) Flash via USB

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

Install the tool: cargo install elf2uf2-rs

Modify examples/use_rust/rp2040/.cargo/config.toml to use elf2uf2:

- runner = "probe-rs run --chip RP2040"
+ runner = "elf2uf2-rs -d"

Connect your rp2040 board while holding the BOOTSEL button until the USB drive appears

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

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Feature flags

watchdog (enabled by default) — Enable hardware watchdog support
host (enabled by default) — Enable host configurator support
vial (enabled by default) — Enable vial support
dfu_lock — Experimental. Enable DFU lock feature — physical key unlock for DFU firmware download
host_lock (enabled by default) — Enable physical key unlock and matrix state tracking — the shared base of the lock features (dfu_lock and rynk imply it; combine with vial for the Vial lock).
rynk — Experimental. Enable Rynk protocol support (RMK-native protocol, mutually exclusive with vial). The wire protocol and host API can change in any release; vial is the stable default. Includes host_lock so the lock gate always has matrix-state tracking.
dongle — Enable dongle support. Both sides of a dongle setup enable it: the keyboard gets a bond slot of its own for the dongle plus the SwitchToDongle key, the dongle binary gets rmk::dongle. The dongle relays the keyboard’s host protocol: Rynk by default, or Vial when both binaries also enable vial.
storage (enabled by default) — Enable the storage. The storage is optional to save memory
defmt (enabled by default) — Enable defmt support
usb_log — Enable logging via usb
log — Use log, this feature cannot be enabled when defmt is enabled
std — Activate the embassy-time mock driver for deterministic, fast test timing. (Despite the historic name, this feature does NOT enable embassy-time/std — it swaps in the manually-advanced mock clock driven by rmk::test_support::test_block_on.)
display — Enable display support (traits + processor)
ssd1306 — Enable SSD1306 OLED driver
oled_async — Enable OLED drivers via oled_async (SH1106, SH1107, SH1108, SSD1309)
lcd_async — Enable TFT drivers via lcd-async (GC9107, GC9A01, ILI9225, ILI9341, ILI9342C, ILI9486, ILI9488, RM67162, ST7735, ST7789, ST7796).
async_matrix — Enable async matrix scanning
use_1m_phy — Use 1M PHY toward the host. The dongle link and the split link are unaffected: they always run at 2M.
split — Enable split keyboard support.
rp2040 — Enable feature to use rp2040 specific features, like PIO and bootrom
adafruit_bl — Enable feature if you’re using Adafruit nRF52 bootloader and want bootloader jumping key
zsa_voyager_bl — Enable feature if you’re using the ZSA Voyager ignition DFU bootloader
dfu — Experimental. Enable DFU firmware update support (USB DFU interface). The flash layout, config, and API can change in any release.
dfu_rp — Experimental. Enable RP2040-specific DFU with embassy-boot-rp (implies dfu and rp2040)
dfu_nrf — Experimental. Enable nRF DFU firmware update support (add a chip feature like nrf52840 too)
dfu_split — Experimental. Enable split firmware update support — forward firmware to peripherals over split link. Wired split only; see the guard in lib.rs for BLE.
steno — Enable Plover HID stenography support: adds the steno HID descriptor, the steno USB writer endpoint, and the Action::Steno variant.
_no_usb — Internal feature that indicates no USB is used, this feature will be auto-activated for some chips
_usb_high_speed — Internal marker for 480 Mbps USB chips; activates 512-byte bulk packets.
_no_saadc — Internal marker for chips without SAADC; compiles out NrfAdc.
subrating — Enable BLE connection subrating for split Connections
_no_subrating — Internal feature that indicates that subrating is not supported, this will be auto-activated for some chips

§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.

nrf54lm20_ble — Enable feature if you want to use nRF54LM20 with BLE.
nrf54l15_ble — Enable feature if you want to use nRF54L15 with BLE.
nrf52840_ble — Enable feature if you want to use nRF52840 with BLE.
nrf52833_ble — Enable feature if you want to use nRF52833 with BLE.
nrf52820_ble — Enable feature if you want to use nRF52820 with BLE. The chip has no SAADC, so NrfAdc is unavailable.
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.
esp32h2_ble — Enable feature if you want to use ESP32H2 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.
sf32lb52x_ble — Enable feature if you want to use SF32LB52x with BLE.
passkey_entry — Enable passkey entry support for BLE pairing
_ble — Enable feature if you want to use trouble BLE stack

Re-exports§

pub use keymap::KeymapData;
pub use embassy_futures;
pub use embassy_time;
pub use futures;
pub use heapless;
pub use rmk_macro as macros;
pub use rmk_types as types;

Modules§

ad_types: UUIDs for the ad types module.
appearance: The representation of the external appearance of the device.
ble
boot
browse_group_identifiers: UUIDs for the browse group identifiers module.
channel: Exposed channels which can be used to share data across devices & processors
characteristic: UUIDs for the characteristic module.
config
core_traits
debounce
declarations: UUIDs for the declarations module.
descriptors: UUIDs for the descriptors module.
driver
event: Event system for RMK
helper_macro
hid
host
input_device: Input device module for RMK
keyboard
keyboard_macros
keymap
layout_macro
light
matrix
mesh_profile: UUIDs for the mesh profile module.
object_types: UUIDs for the object types module.
processor: Runtime traits for event consumers in RMK.
protocol_identifiers: UUIDs for the protocol identifiers module.
service: UUIDs for the service module.
service_class: UUIDs for the service class module.
split
state
storage
units: UUIDs for the units module.
usb
watchdog

Macros§

a: Create a KeyAction variant directly.
df: Create a default layer switch action.
encoder: Create a rotary encoder action.
join_all: Helper macro for joining all futures
k: Create a normal key action.
kbctrl: Create a keyboard control action.
layer: Create a layer in keymap.
light: Create a light control action.
lm: Create a layer activation with modifier action.
lt: Create a layer-tap action (tap/hold behavior).
ltp: Create a layer-tap action with custom timing profile.
macros: Create a macro trigger action.
mo: Create a momentary layer activation action.
morse: Create a Morse action (alias for tap dance).
mt: Create a modifier-tap action (tap/hold behavior).
mtp: Create a modifier-tap action with custom timing profile.
osl: Create a one-shot layer action.
osm: Create a one-shot modifier action.
pdf: Create a persistent default layer switch action.
run_all: Run multiple tasks concurrently by calling each task’s run method.
select_biased_with_feature: Wrapper for select_biased! with feature-gated arms
shifted: Create a shifted key action.
special: Create a special key action.
td: Create a tap dance action (Morse action).
tg: Create a layer toggle action.
th: Create a dual-key tap-hold action.
thp: Create a dual-key tap-hold action with custom timing profile.
to: Create a “to layer” action (exclusive layer activation).
tt: Create a layer tap-toggle action.
ttp: Create a layer tap-toggle action with custom timing profile.
user: Create a user key action with given index.
uuid: Create a UUID object from a string or other convertible literal, similar to how UUIDs can be specified in a gatt_service derivation.
with_feature
wm: Create a key action with modifier combination.

Structs§

AdStructureIter: Iterator over advertisement structures.
AddrKind: AddrKind
Address: A BLE address. Every BLE device is identified by a unique Bluetooth Device Address, which is a 48-bit identifier similar to a MAC address. BLE addresses are categorized into two main types: Public and Random.
AdvChannelMap: AdvChannelMap
AdvHandle: AdvHandle
AdvSet: AdvSet
AdvertisementParameters: Parameters for an advertisement.
AdvertisementSet: Configuriation for a single advertisement set.
Advertiser: Handle to an active advertiser which can accept connections.
AttErrorCode: Attribute Error Code
AttPermissions: Attribute permissions
Attribute: Attribute metadata.
AttributeIterator: Iterator over attributes.
AttributeServer: A GATT server capable of processing the GATT protocol using the provided table of attributes.
AttributeTable: A table of attributes.
AttributeValue: A value of an attribute.
AutoMouseLayerRunner: Runnable for the auto mouse layer task.
BdAddr: BdAddr
BluetoothUuid16: A 16-bit Bluetooth UUID
BluetoothUuid32: A 32-bit Bluetooth UUID
BluetoothUuid128: A 128-bit Bluetooth UUID
BondInformation: Bond Information
CCCD: CCCD flag.
Central: A type implementing the BLE central role.
CentralConfig: Configuration for a central device GAP Service.
Characteristic: A characteristic in the attribute table.
CharacteristicBuilder: Builder for characteristics.
CharacteristicPropertiesHandle: Attribute handle for a characteristic’s properties
CharacteristicProps: Properties of a characteristic.
ClientAttTable: A compact, fixed-size map of client-specific attribute values (e.g. CCCDs).
ClientAttTableBuilder: A builder for ClientAttTable.
ClientAttTableView: A read-only view over a serialized ClientAttTable.
ConnParams: Current parameters for a connection.
ConnectConfig: Connection configuration.
ConnectRateParams: Connection rate parameters.
Connection: Handle to a BLE connection.
ConnectionParamsRequest: A connection parameters update request
ControlRunner: The control part of the host runner.
Descriptor: Characteristic descriptor handle.
ExternalController: An external Bluetooth controller with communication via Transport type T.
GattClient: A GATT client capable of using the GATT protocol.
GattConnection: Used to manage a GATT connection with a client.
GattData: A GATT payload ready for processing.
HostMetrics: Host metrics
HostResources: HostResources holds the resources used by the host.
Identity: Identity of a peer device
IdentityResolvingKey: Identity Resolving Key.
InvalidHandle: Invalid handle value
InvalidLengthError: An error returned when a byte slice has an invalid length for a Bluetooth UUID.
L2capChannel: Handle representing an L2CAP channel.
L2capChannelConfig: Configuration for an L2CAP channel.
L2capChannelListener: A listener for incoming L2CAP connection requests on a specific connection.
L2capChannelReader: Handle representing an L2CAP channel write endpoint.
L2capChannelRef: Handle to an L2CAP channel for checking it’s state.
L2capChannelWriter: Handle representing an L2CAP channel write endpoint.
L2capPendingConnection: A pending incoming L2CAP connection that can be inspected, then accepted or rejected.
LeAdvReportsIter: An iterator for advertising reports.
LeExtAdvReportsIter: An iterator for extended advertising reports.
LongTermKey: LE Secure Connections Long Term Key.
NotAllowedEvent: Other event returned while processing GATT requests (neither read, nor write).
Notification: A notification payload.
NotificationListener: Notification listener for GATT client.
OobData: OOB data for BLE pairing, exchanged via an out-of-band channel.
OtherEvent: Other event returned while processing GATT requests (neither read, nor write).
Peripheral: Type which implements the BLE peripheral role.
PeripheralConfig: Configuration for a peripheral device GAP Service.
PhyMask: PhyMask
ReadEvent: A characteristic read event returned while processing GATT requests.
Reply: A reply to a gatt request.
RequestedConnParams: Requested parameters for a connection.
Runner: Runs the host with the given controller.
RxRunner: The receiver part of the host runner.
ScanConfig: Scan/connect configuration.
ScanSession: Handle to an active advertiser which can accept connections.
Scanner: A scanner that wraps a central to provide additional functionality around BLE scanning.
Sdu: Service Data Unit
Service: A GATT service.
ServiceBuilder: Builder for constructing GATT service definitions.
ServiceHandle: Handle for a GATT service.
Stack: Contains the host stack
StackBuilder: Builder for configuring the BLE stack before use.
SubratingParams: Connection subrating parameters
TxRunner: The transmit part of the host runner.
WriteEvent: A characteristic write event returned while processing GATT requests.

Enums§

AdStructure: Advertisement data structure.
AdvFilterPolicy: AdvFilterPolicy
Advertisement: Advertisement payload depending on which advertisement kind requested.
AdvertisementDataError: Error encoding advertisement data.
BleHostError: Errors returned by the host.
BluetoothUuid: A Bluetooth UUID of any valid length (16, 32, or 128 bits).
CCCDFlag: CCCD flag values.
CharacteristicProp: Characteristic properties
ConnectionEvent: A connection event.
CreditFlowPolicy: Control how credits are issued by the receiving end.
Error: Errors related to Host.
GapConfig: Configuration for the GAP Service.
GattConnectionEvent: A GATT connection event.
GattEvent: An event returned while processing GATT requests.
IoCapabilities: Device I/O capabilities
LeCreditConnResultCode: Result code for an LE Credit Based Connection Response.
PairingFailedReason: Pairing Failed Reason
PermissionLevel: Attribute permissions
PhyKind: PhyKind
PhySet: PHYs to scan on.
Role: LeConnRole
SecurityLevel: Security level of a connection
TxPower: Transmit power levels.
Uuid: A 16-bit or 128-bit UUID.

Constants§

AD_FLAG_LE_LIMITED_DISCOVERABLE: Le advertisement.
BR_EDR_NOT_SUPPORTED: BR/EDR not supported.
GAP_SERVICE_ATTRIBUTE_COUNT: The number of attributes added by the GAP and GATT services (with security)
LE_GENERAL_DISCOVERABLE: Discoverable flag.
MAX_SMALL_DATA_SIZE: The maximum size in bytes of an attribute using inline small data storage.
SIMUL_LE_BR_CONTROLLER: Simultaneous LE and BR/EDR to same device capable (controller).
SIMUL_LE_BR_HOST: Simultaneous LE and BR/EDR to same device capable (Host).

Traits§

AsGatt: Trait to allow conversion of a type to gatt bytes
AttributeHandle: A type which holds a handle to an attribute in the attribute table
Controller: Trait that defines the controller implementation required by the host.
DynamicAttributeServer: Type erased attribute server
EventHandler: Event handler.
FixedGattValue: Trait to allow conversion of a fixed size type to and from a byte slice
FromGatt: Trait to allow conversion of gatt bytes into a type
Packet: A Packet is a byte buffer for packet data. Similar to a Vec<u8> it has a length and a capacity.
PacketPool: A Packet Pool that can allocate packets of the desired size.

Functions§

initialize_keymap
initialize_keymap_and_storage

Type Aliases§

DefaultPacketPool: Global default packet pool.
HeaplessString: A fixed capacity String.

Attribute Macros§

gatt_server: Gatt Service attribute macro.
gatt_service: Gatt Service attribute macro.

Crate rmk

Crate rmk Copy item path

§Features

§User Documentation | API Reference | FAQs | Changelog

§Real-World Implementations

§Getting Started

§Option 1: Start with a Template

§Option 2: Explore Built-in Examples

§rp2040 Setup

§Development Roadmap

§Minimum Supported Rust Version (MSRV)

§License

§Feature flags

§BLE feature flags

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate rmk