# haobogu/rmk architecture

> Architecture diagram of the GitHub repository haobogu/rmk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haobogu/rmk
- Repository: https://github.com/haobogu/rmk

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time
    keyboardToml["keyboard.toml"]:::build
    ExampleApp["Example Application"]:::build
    rmkConfig["rmk-config"]:::build
    rmkMacro["rmk-macro"]:::build
    rmkTypes["rmk-types"]:::core
    buildRS["build.rs"]:::build
    rustc["Rust Compiler"]:::build

    %% Runtime
    rmkCore["rmk (core)"]:::core
    embassyHAL["embassy HAL"]:::core
    Driver["MCU Drivers"]:::core
    Matrix["Keyboard Matrix & Peripherals"]:::hw
    MCU["MCU Hardware"]:::hw
    HostPC["Host PC / Vial Client"]:::external

    %% Build-time flows
    keyboardToml -->|input to| rmkConfig
    ExampleApp -->|invokes| rmkConfig
    rmkConfig -->|generates config code| buildRS
    buildRS -->|calls proc-macro| rmkMacro
    rmkConfig -->|provides definitions| rmkTypes
    rmkMacro -->|depends on| rmkTypes
    rmkCore -->|uses types| rmkTypes
    rmkConfig -->|feeds into| rustc
    rmkMacro -->|expands code into| rustc
    rustc -->|compiles| rmkCore

    %% Runtime flows
    rmkCore -->|uses| embassyHAL
    embassyHAL -->|drives| Driver
    Driver -->|interfaces with| Matrix
    Driver -->|interfaces with| MCU
    rmkCore -->|USB/BLE HID GATT| MCU
    MCU -->|USB/BLE traffic| HostPC

    %% Click Events
    click rmkTypes "https://github.com/haobogu/rmk/tree/main/rmk-types/src"
    click rmkMacro "https://github.com/haobogu/rmk/tree/main/rmk-macro/src"
    click rmkConfig "https://github.com/haobogu/rmk/tree/main/rmk-config/src"
    click rmkCore "https://github.com/haobogu/rmk/tree/main/rmk/src"
    click buildRS "https://github.com/haobogu/rmk/blob/main/rmk/build.rs"
    click ExampleApp "https://github.com/haobogu/rmk/tree/main/examples/use_config"

    %% Styles
    classDef build fill:#f9f,stroke:#333;
    classDef core fill:#9f9,stroke:#333;
    classDef hw fill:#ff9,stroke:#333;
    classDef external fill:#ccf,stroke:#333,stroke-dasharray: 5 5;
```
