Crate rmk

Source

Expand description

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

§sessile

§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

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

host (enabled by default) — Enable host configurator support
vial (enabled by default) — Enable vial support
vial_lock (enabled by default) — Enable vial lock feature
storage (enabled by default) — Enable the storage. The storage is optional to save memory
col2row — 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 support
usb_log — Enable logging via usb
log — Use log, this feature cannot be enabled when defmt is enabled
std — Add std feature for testing
async_matrix — Enable async matrix scanning
controller — Enable to use controllers to control other hardwares on the board or peripheral
split — Enable split keyboard support.

The split peripheral is regarded as a controller subscriber, so the split feature requires controller feature.
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
_no_usb — Internal feature that indicates no USB is used, this feature 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.

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;
pub use rmk_types as types;

Modules§

appearance: The representation of the external appearance of the device.
ble
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.
combo
config
controller: Controller module for RMK
debounce
declarations: UUIDs for the declarations module.
descriptor
descriptors: UUIDs for the descriptors module.
direct_pin
driver
event
fork
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.
morse
object_types: UUIDs for the object types module.
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

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)
ltp: Create a layer activate action or tap key(tap/hold) with profile
macros
mo: Create a layer activate action. For example, mo!(1) activates layer 1.
morse: Create a Morse(index) action (in Vial it will appear as “Tap Dance”)
mt: Create a modifier-tap-hold action
mtp: Create a modifier-tap-hold action with profile
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.
ser_storage_variant: Macro to serialize standard variants: key + postcard-serialized data Used by both StorageData and KeymapData
shifted: Create a shifted key
td: Create a Morse(index) action (in Vial its simplest form is known as “Tap Dance”, so td name is used)
tg: Create a layer toggle action
th: Create a tap-hold action
thp: Create a tap-hold action with profile
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
ttp: Create a layer activate or tap toggle action with profile
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 normal key with modifier action

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
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.
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.
CccdTable: A table of CCCD values.
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.
ConnectConfig: Connection configuration.
ConnectParams: Connection parameters.
Connection: Handle to a BLE connection.
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.
Host: Host components.
HostMetrics: Host metrics
HostResources: HostResources holds the resources used by the host.
Identity: Identity of a peer device
IdentityResolvingKey: Identity Resolving Key.
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.
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.
LeAdvReportsIter: An iterator for advertising reports.
LeExtAdvReportsIter: An iterator for extended advertising reports.
LongTermKey: LE Secure Connections Long Term Key.
Notification: A notification payload.
NotificationListener: Notification listener for GATT client.
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.
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
SerialTransport: HCI transport layer for a split serial bus using the UART transport layer protocol 📖
Service: A GATT service.
ServiceBuilder: Builder for constructing GATT service definitions.
ServiceHandle: Handle for a GATT service.
Stack: Contains the host stack
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
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 GAP_SERVICE: 1 ├── DEVICE_NAME: 2 └── APPEARANCE: 2 GATT_SERVICE: + 1 — = 6
LE_GENERAL_DISCOVERABLE: Discoverable flag.
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_encoder_keymap
initialize_encoder_keymap_and_storage
initialize_keymap
initialize_keymap_and_storage
run_rmk

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

§News

§User Documentation | API Reference | FAQs | Changelog

§Real-World Implementations

§rmk-ble-keyboard

§dactyl-lynx-rmk

§sessile

§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