Guide
Documentation
API doc
Guide
Documentation
API doc

Vial support

RMK uses Vial as the default keymap editor. Vial allows you to change your keymapping in real-time, no additional firmware flashing is required.

Vial requires the

storage feature to persist your keymap data. Without storage feature enabled, any changes to your keymap will be lost after the keyboard reboots.

Port Vial

To use Vial with RMK, you need a keyboard definition file named vial.json. Vial provides detailed documentation on how to generate this file: https://get.vial.today/docs/porting-to-via.html.

When creating your

vial.json, it is essential that you use the exact same layout definition as your RMK firmware's internal keymap, which is defined in either src/keymap.rs or keyboard.toml.

It's important to understand the difference:

  • vial.json: Defines the keyboard layout recognized by Vial, which specifies the position of each key that Vial sets.
  • src/keymap.rs / keyboard.toml: Defines the actual layout and keymap in the firmware, which specifies the action for each key press.

Once you have your vial.json file, simply place it in the root directory of your RMK firmware project. RMK will automatically handle the rest.

Disable Vial

Vial support requires additional Flash and RAM. If you want to minimize binary size and memory usage, you can disable Vial support.

When using keyboard.toml, you can disable Vial by setting vial_enabled to false under the [host] section. To completely remove Vial from the build, also disable the vial feature in your Cargo.toml by turning off the default features:

keyboard.toml
[host]
vial_enabled = false
Cargo.toml
rmk = { version = "...", default-features = false }

Configure Unlock Keys

For security purposes, you can configure unlock keys that must be pressed simultaneously to unlock Vial configuration in Vial. This prevents accidental keymap changes.

keyboard.toml
[host]
# Unlock combination: simultaneous press of specified keys
# Format: [[row, col], [row, col], ...]
unlock_keys = [[0, 0], [0, 1]]  # Keys at (row=0,col=0) and (row=0,col=1)
The unlock keys use the physical matrix position (row, column), not the keycode. Make sure

to use keys that are easy to press simultaneously but not commonly pressed together accidentally.

ON THIS PAGE