How dreamy-jy/rmk works
Project type and purpose
• This is a multi-crate Rust firmware project (“rmk”) for building feature-rich keyboard firmware on a variety of microcontrollers.
• It includes:
• A core firmware library (rmk)
• A configuration-generation tool (rmk-config)
• A procedural-macro crate (rmk-macro)
• A shared-types crate (rmk-types)
• Dozens of example applications (one per MCU family)
• Documentation site (VitePress under docs/)
• CI/CD workflows and helper scripts
File-structure analysis
• Top-level crates & folders:
• rmk-config (CPU-agnostic TOML → Rust code generator)
• rmk-macro (proc macros to wire up drivers, matrix, USB/BLE stacks)
• rmk-types (common enums/structs: keycodes, protocols)
• rmk (core runtime: matrix scanning, debouncing, layers, host protocols)
• examples/… (each example is a Cargo project targeting a specific MCU)
• docs/ (VitePress site source + theme)
• .github/workflows/ (CI: build, test, lint, docs deploy)
• scripts/ (automation: check_all, clean_all, via2rmk.py)
• rmk Cargo workspace: shared toolchain, rustfmt, build.rs scripts that invoke codegen or embed build metadata.
Key README insights
• Supports broad MCU families via Embassy + embedded-HAL
• Native Vial support (wireless keymap editing) over BLE or USB HID
• Advanced keyboard features baked in (layers, combos, mouse, media)
• Build is driven by a single keyboard.toml, or extended via Rust code
1. Developer tools
– keyboard.toml + Cargo project
– rmk-config CLI (codegen)
– rmk-macro (proc macro expansion)
2. Build system & CI/CD
– Cargo workspace
– build.rs scripts
– GitHub Actions + scripts/
3. Crate dependency graph
– rmk-types → rmk → examples
– rmk-macro → rmk (compile-time only)
– rmk-config → examples (codegen)
4. Generated firmware
– Monolithic binary per example
5. Runtime modules (inside rmk)
– Matrix scanning → Debouncer → Keymap → Controller → HID over USB or BLE
– Async executor (embassy)
– Storage (flash) / lighting / wireless reconnection
6. Hardware & external systems
– MCU (GPIO, ADC, SPI, USB peripheral, BLE radio)
– Host PC or mobile (USB HID host, Vial host over BLE)
– keyboard.toml → rmk-config → generated Rust modules → Cargo build
– Cargo build invokes rmk-macro (proc macros) → expands to driver/stack code
– Build.rs scripts (per crate) may embed metadata or call codegen
– Final binary flashes to MCU
– At runtime:
• Keyboard matrix → rmk matrix scanner
• Debounced events → keymap lookup → HID events
• HID events → USB endpoint or BLE GATT → Host
• Host → Vial UI (optional wireless keymap updates)
c. Architectural patterns & design principles
– Cargo workspace for multi-crate modularity
– Code-first configuration with TOML + codegen
– Compile-time macros for zero-cost abstractions
– Feature flags per MCU & per capability (async_matrix, wireless)
– Clear separation: hardware drivers, core logic, host protocol
d. Key technologies & frameworks
– Rust, Cargo, Proc‐Macros, build.rs
– embassy (async runtime)
– embedded‐HAL drivers
– usb‐device, Bluetooth GATT stacks
– VitePress for docs
– GitHub Actions for CI/CD