How haobogu/rmk works
Project type and purpose
• This is an open-source, modular Rust framework (“RMK”) for building keyboard firmware targeting a wide range of microcontrollers.
• It consists of several Rust crates (core runtime, types, macros, config generator) plus examples, docs, and build scripts.
File structure
• Top-level crates:
• rmk-types: defines keycodes, actions, protocols.
• rmk-macro: a procedural-macro crate that transforms user config/DSL into Rust code.
• rmk-config: a CLI tool for generating default TOML configs and embedding them.
• rmk: the core library implementing scanning, debouncing, HID, BLE, USB, host protocols, event loop, split support.
• Examples folder: many per-MCU sample applications, each with its own Cargo.toml, keyboard.toml, build.rs, and source.
• Build scripts, CI workflows, and helper scripts under scripts/.
README for additional insights
• Emphasizes broad MCU support (embassy-based async), Vial/host integration for live remapping, advanced features (layers, combos, macros), wireless BLE support, and low power.
• Mentions a single keyboard.toml for configuration plus optional Rust‐level customization.
Main components
a. User-level:
• keyboard.toml (configuration)
• Example application (Cargo project + build.rs)
b. Build time:
• rmk-config CLI (generates default configs, merges user TOML)
• rmk-macro (procedural macros expand config and DSL into Rust code)
• rmk-types (shared definitions)
c. Core firmware crates:
• rmk (async runtime, matrix scanning, debouncing, event loop, HID stack, USB & BLE drivers, split keyboard comms)
d. Hardware abstraction:
• embassy HAL + embassy-driver crates for target MCU peripherals (GPIO, USB, BLE radio)
e. Target hardware:
• MCU (stm32, nRF52, rp2040, esp32, etc.)
• Keyboard matrix, LEDs, input devices (encoders, joysticks), storage
f. External services:
• Host PC via USB HID or BLE (Vial protocol for live remapping)
• Vial host application or native OS keyboard driver
Relationships and interactions
• At build time, user’s keyboard.toml is read by rmk-config → merged into source via build.rs → rmk-macro expands it into concrete Rust code.
• rmk-types provides shared data definitions to both rmk-macro and rmk core.
• The rmk crate uses embassy HAL to talk to the MCU peripherals (GPIO, USB, BLE).
• The firmware binary is flashed to the MCU.
• At runtime, the event loop in rmk polls matrix, processes debouncing & layers, and drives USB HID endpoint or BLE GATT service.
• Over USB/BLE, the host PC Vial client can query/update keymap live via the Vial protocol.
Architectural patterns and principles
• Modular crate structure separating type definitions, macro codegen, config generation, and core runtime.
• Build-time codegen (proc macros + build scripts) to transform declarative configs into efficient firmware.
• Async Reactor pattern (embassy) for non-blocking matrix scanning and BLE/USB.
• Dependency-inversion: host protocols (USB, BLE) abstracted behind traits.
• Single Source of Truth: keyboard.toml drives both codegen and runtime behavior.