Keyboard shortcuts

Press ← or β†’ to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

RMK provides an easy and accessible way to set up the keyboard with a toml config file, even without Rust code!

Usage

A toml file named keyboard.toml is used as the configuration file of RMK. The following is the spec of toml if you're unfamiliar with toml:

RMK provides a proc-macro to load the keyboard.toml at your projects root: #[rmk_keyboard], add it to your main.rs like:

#![allow(unused)]
fn main() {
use rmk::macros::rmk_keyboard;

#[rmk_keyboard]
mod my_keyboard {}
}

And, that's it! The #[rmk_keyboard] macro would load your keyboard.toml config and create everything that's needed for creating a RMK keyboard instance.

If you don't want any other customizations beyond the keyboard.toml, #[rmk_keyboard] macro will just work. For the examples, please check the example/use_config folder.

What's in the config file?

The config file contains almost EVERYTHING to customize a keyboard. For the full reference of keyboard.toml, please refer to this doc. Also, we have pre-defined default configurations for chips, at rmk-macro/src/default_config folder. We're going to add default configurations for more chips, contributions are welcome!

The following are the available tables and related documentaion available in keyboard.toml:

  • Keyboard and matrix: basic information and physical key matrix definition of the keyboard
  • Layout: layout and default keymap configuration of the keyboard
  • Split keyboard: split keyboard configuration
  • Storage: configuration for storage, which is used for on-board config and keymap
  • Behavior: configuration for advanced keyboard behaviors, such as one-shot key, tri-layer, tap-hold(including HRM mode), etc.
  • Input device: configuration for input devices, such as rotary encoder, joystick, etc.
  • Wireless/Bluetooth: configuration for wireless/bluetooth
  • Light: configuration for lights
  • RMK config: internal configurations of RMK, such as length of communication channels, number of allowed macros, etc
  • Appendix: full spec and references of the keyboard.toml

TODOs:

  • read vial.json and check whether vial.json is consist of keyboard.toml