#Dongle

A dongle is a small USB board that stays plugged into your computer and relays a wireless keyboard's reports to it. The keyboard talks Bluetooth to the dongle, the dongle talks USB to the host.

Use one when the host's own Bluetooth isn't an option: a machine with no Bluetooth at all, a BIOS or bootloader that can't see BLE keyboards, a locked-down work computer, or a desk where BLE reconnection is slow enough to be annoying. The keyboard stays wireless either way.

#How it works

The keyboard keeps a bond slot of its own for the dongle, separate from the BLE host profiles. Profile cycling never lands on it, so switching between your laptop and your phone doesn't disturb the dongle link, and pairing a new host doesn't cost you the dongle.

The dongle bonds exactly one keyboard. Once bonded, it only ever reconnects that keyboard, and it drops the bond only when the keyboard rejects its key. Replacing the keyboard needs no host involvement and no reflashing: set the new keyboard seeking and power-cycle the dongle, which opens one pairing window at power-on (see Pairing).

The dongle also relays the host configurator protocol, so Vial and Rynk work through the dongle exactly as they do over a direct connection — the dongle passes those frames through untouched.

#Hardware

A dongle build needs a chip with both a BLE controller and a USB device peripheral. RMK's example targets nRF; other BLE chips with USB use the same API, but are untested.

The keyboard side works on any BLE keyboard, unibody or split. On a split, only the central talks to the dongle.

#Building the firmware

Both sides enable the dongle Cargo feature — it means "this build is part of a dongle setup", and what it turns on depends on which side you're building.

The keyboard gets the extra bond slot and the SwitchToDongle key:

rmk = { path = "...", default-features = false, features = [
    "defmt",
    "storage",
    "vial",       # or "rynk"
    "dongle",
    "split",      # only if the keyboard is a split
    "nrf52840_ble",
] }

The dongle gets rmk::dongle:

rmk = { path = "...", default-features = false, features = [
    "defmt",
    "storage",
    "dongle",
    "nrf52840_ble",
] }

The dongle binary is short — a USB transport, the dongle itself, and storage for the bond, wired together by a shared router:

use rmk::dongle::{Dongle, DongleRouter};

// Shared by the two tasks that relay: the dongle's BLE link and the USB host sessions.
let router = DongleRouter::new();
let mut dongle = Dongle::new(sdc, ble_addr(), &router);
let mut usb_transport = UsbTransport::new(driver, device_config).with_dongle_router(&router);

run_all!(usb_transport, dongle, storage).await;

The dongle has no matrix, no keymap, and no storage of your layout — it only stores which keyboard it is bonded to.

#Pairing

1. Flash both boards and plug the dongle in. A dongle with no bonded keyboard opens a pairing window and repeats it until a keyboard shows up.
2. Press the SwitchToDongle key on the keyboard. The keyboard switches to its dongle slot and starts seeking; the scanning dongle picks it up and pairs.
3. From then on both sides reconnect on their own. A bonded dongle opens the pairing window exactly once, at power-on, and afterwards only reconnects its bonded keyboard.

SwitchToDongle is User(N+5), where N is the number of BLE profiles — see Wireless for the full list of profile keycodes. It exists only in builds with the dongle feature.

To move the keyboard to a different dongle, hold SwitchToDongle for 5 seconds. That clears the keyboard's dongle bond and sends it seeking again.

The pairing window length is configurable:

[rmk]
# Seconds per pairing window, default 30. Dongle builds only.
dongle_pairing_window_secs = 30

The dongle binary is written in Rust, so this setting only takes effect if the dongle crate points KEYBOARD_TOML_PATH (in its .cargo/config.toml) at a keyboard.toml that sets it. The nrf_dongle example has no such file and uses the default of 30 seconds.

#Example

examples/use_rust/nrf_dongle is a complete three-board setup: a split BLE keyboard (central + peripheral) relayed to the host by a USB dongle, with Rynk reaching the central's keymap through the dongle. Its README walks through the bring-up order.