Guide
Documentation
API doc
Guide
Documentation
API doc

Split keyboard

RMK supports multi-split keyboard, which contains one central board and unlimited peripheral boards. The host is connected to the central board via USB or BLE.

INFO

There are many examples for split keyboards in RMK examples folder.

Communication

RMK supports both wired and wireless communication.

Currently, the communication type indicates that how split central communicates with split peripherals. How the central talks with the host depends only on the central.

  • Wireless Split (BLE): The central connects to the host using BLE (Bluetooth Low Energy) or USB if the cable is plugged in.
  • Wired Split (Serial): The central connects to the host using USB only.

Wired split

RMK supports most existing opensource serial based split keyboard hardwares using UART, USART, PIO, etc.

DETAILS

RMK uses embedded-io-async as the abstract layer of wired communication. Any device that implements embedded-io-async::Read and embedded-io-async::Write traits can be used as RMK split central/peripheral. That unlocks many possibilities of RMK's split keyboard.

The most common implementations of those traits are serial ports(UART/USART), such as embassy_rp::uart::BufferedUart and embassy_stm32::usart::BufferedUart.

For keyboards connected using only a single wire, e.g. a 3-pole TRS cable, for the RP2040 only RMK implements a half-duplex UART serial port, rmk::split::rp::uart::BufferedUart, using one or both of the Programmable IO (PIO) blocks available on the RP2040 chip. The PIO serial port also supports full-duplex over two wires, and can be used when the central/peripheral connection does not use the pins connected to the chip's standard UART ports.

To use the RP2040's PIO UART driver, you need to enable the rp2040 feature gate in your Cargo.toml:

1rmk = { version = "...", features = [
2    "split",
3    "rp2040", # Enable PIO UART driver for rp2040
4] }

Wireless split

RMK supports BLE wireless split on nRF52, ESP32 and Pi Pico W right now. For BLE split, the central and peripheral parts are connected via BLE, and the host is connected to the central via USB or BLE.

TIP

storage feature is required for BLE split.

Split keyboard project

A project of split keyboard could be like:

src - bin - central.rs - peripheral.rs keyboard.toml Cargo.toml

In Cargo.toml, the split feature should be enabled, and the [[bin]] section should be added for both central and peripheral:

rmk = { version = "...", features = [
    "nrf52840_ble",
    "split", # Enable split keyboard feature
    "async_matrix",
] }

# ..
# ..

# Split keyboard entry files
[[bin]]
name = "central"
path = "src/central.rs"

[[bin]]
name = "peripheral"
path = "src/peripheral.rs"

# You can add more than one peripherals
[[bin]]
name = "peripheral2"
path = "src/peripheral2.rs"

Configuration

For the detailed configuration of split keyboards, refer to Split Keyboard Configuration documentation

ON THIS PAGE