#Bootloader Configuration (embassy-boot)

embassy-boot is a library of the embassy framework that is used to build bootloaders. RMK supports DFU firmware updates via embassy-boot for RP2040 and nRF52840 / nRF52833. An embassy-boot based bootloader splits flash into ACTIVE and DFU slots, providing safe updates with automatic rollback on failure. This is an optional feature of RMK, the default bootloaders of the devices can still be used as usual without runtime updates via USB DFU.

An embassy-boot based bootloader for both platforms lives in rmk-boot. RMK integrates with it through a memory.x file that the bootloader generates: build rmk-boot for your chip and it writes its matching rmk-memory.x into the rmk-boot project directory. Rename that file to memory.x and place it next to your project's Cargo.toml, so the firmware and the bootloader agree on the partition layout.

At runtime RMK reads partition offsets from linker symbols embedded in memory.x — you never compute or hardcode partition addresses yourself.

See the flashing guide for step-by-step instructions on getting the bootloader and RMK flashed.

#RP2040

Add a [dfu] section to your keyboard.toml or use the Rust API directly.

[dfu]
# (Optional) DFU activity LED pin, default "PIN_25".
led = "PIN_25"
# led = "none" to omit DFU LED

# (Optional) Unlock keys for dfu_lock (physical matrix positions).
# Only works with dfu_lock feature enabled in Cargo.toml.
unlock_keys = [[0, 0], [1, 1]]

use core::cell::RefCell;
use rmk::dfu::{FlashMutex, FlashDfuHandler, partitions_from_linkerscript};

// Flash partitions come from the DFU symbols in memory.x.
let flash_mutex = FlashMutex::new(RefCell::new(Flash::new_blocking(p.FLASH)));
let (storage_partition, state_partition, dfu_partition) = partitions_from_linkerscript(&flash_mutex);

// Optional: assign a DFU activity LED
let mut dfu_led_processor =
    rmk::processor::builtin::dfu_led::DfuLedProcessor::new(Output::new(p.PIN_25, Level::Low), false);

// Optional: DFU lock with physical key unlock. Requires the `dfu_lock` Cargo feature.
let unlock_keys: &[(u8, u8)] = &[(0, 0), (1, 1)];
let mut dfu_lock = ::rmk::dfu::DfuLock::new(unlock_keys, &keymap);

// Build the USB transport. The DFU interface is registered internally by the
// transport and flashes through the DFU task; add the interface to run_all!().
let mut dfu_iface = FlashDfuHandler::new(dfu_partition, state_partition);
let mut usb_transport = UsbTransport::new(driver, rmk_config.device_config);

run_all!(
	// other processors ...
	usb_transport,
	dfu_iface,
	dfu_led_processor,
	dfu_lock,
)

#nRF52840 / nRF52833

Add a [dfu] section to your keyboard.toml or use the Rust API directly.

[dfu]
# (Optional) Flash page size in bytes (4096 for nRF52840 / nRF52833).
page_size = 4096

# (Optional) DFU activity LED pin, default "P0_15".
led = "P0_15"
# led = "none" to omit DFU LED

# (Optional) Unlock keys for dfu_lock (physical matrix positions).
# Only works with dfu_lock feature enabled in Cargo.toml.
unlock_keys = [[0, 0], [1, 1]]

use core::cell::RefCell;
use embassy_nrf::nvmc::Nvmc;
use rmk::dfu::{FlashMutex, FlashDfuHandler, partitions_from_linkerscript};

// Flash partitions come from the DFU symbols in memory.x.
let flash_mutex = FlashMutex::new(RefCell::new(Nvmc::new(p.NVMC)));
let (storage_partition, state_partition, dfu_partition) = partitions_from_linkerscript(&flash_mutex);

// Optional: assign a DFU activity LED
let mut dfu_led_processor = rmk::processor::builtin::dfu_led::DfuLedProcessor::new(
    Output::new(p.P0_15, Level::Low, OutputDrive::Standard),
    false,
);

// Optional: DFU lock with physical key unlock. Requires the `dfu_lock` Cargo feature.
let unlock_keys: &[(u8, u8)] = &[(0, 0), (1, 1)];
let mut dfu_lock = ::rmk::dfu::DfuLock::new(unlock_keys, &keymap);

// Build the USB transport. The DFU interface is registered internally by the
// transport and flashes through the DFU task; add the interface to run_all!().
let mut dfu_iface = FlashDfuHandler::new(dfu_partition, state_partition);
let mut usb_transport = UsbTransport::new(driver, rmk_config.device_config);

run_all!(
	// other processors ...
	usb_transport,
	dfu_iface,
	dfu_led_processor,
	dfu_lock,
)

#Partition layout

The bootloader divides flash into regions. All offsets and sizes come from linker symbols in the memory.x file from rmk-boot. The default layout with rmk-boot (2MB RP2040, 32K storage) is:

The DFU partition size follows embassy-boot guidelines, the additional page is used for status information during flashing.

The [dfu] section is optional and configures only DFU behaviour (LED, unlock keys). Partition offsets are read at link time from memory.x — you do not set state_offset, dfu_offset, or flash_size in keyboard.toml.

#Custom bootloader

If you built your own embassy-boot bootloader, add these eight symbols with matching values to your memory.x (all values are flash-relative offsets):

__bootloader_state_start   = 0x6000;   /* boot state start */
__bootloader_state_end     = 0x7000;   /* boot state end */
__bootloader_active_start  = 0x7000;   /* active (booted) slot start */
__bootloader_active_end    = 0xF3000;  /* active (booted) slot end */
__bootloader_dfu_start     = 0xF3000;  /* DFU download slot start */
__bootloader_dfu_end       = 0x1E0000; /* DFU download slot end */
__bootloader_storage_start = 0x1E0000; /* storage partition start */
__bootloader_storage_end   = 0x200000; /* storage partition end */

Make sure FLASH : ORIGIN in your MEMORY block starts at your ACTIVE partition. RMK's partitions_from_linkerscript() picks up the symbols at runtime.

#DFU LED (optional)

A GPIO pin for the DFU LED.

See the LED behavior table for the full state machine.

#DFU lock (optional, feature dfu_lock)

Physical key positions that unlock DFU firmware downloads. Requires the dfu_lock Cargo feature. Keys are identified by matrix position (row, col), not by keycode.

See the DFU lock section for the unlock workflow.

#External Flash DFU (optional, feature dfu_ext)

When your firmware grows too large for the internal DFU/ACTIVE partition split, you can move the DFU download slot to an external SPI NOR flash chip. With dfu_ext active, the internal DFU partition is removed entirely — the ACTIVE region expands to fill the freed space, giving you roughly double the space for your firmware. The DFU image is written to and read from the external chip.

Requirements:

• A 25-series SPI NOR flash chip with JEDEC‑standard commands (Winbond W25Q64JV, Macronix MX25R, ISSI IS25LP, etc.)
• A matching dfu_ext build of rmk-boot for your chip
• The dfu_ext Cargo feature in your RMK firmware

#Partition layout with dfu_ext

All internal flash regions stay at fixed offsets. The DFU download slot moves entirely to the external chip.

The active size is flash_size - bootloader - state - storage (no DFU partition is carved out of the internal flash).

#Default SPI pins

The bootloader hard‑codes default SPI pins. Match them in your keyboard.toml (or change the bootloader source for a custom board):

#Configuration

[dfu.external_flash]
# Flash chip driver: "w25q" (built-in) or "custom"
driver = "w25q"
# Total flash size in bytes (8 MB = 8388608)
flash_size = 8388608

[dfu.external_flash.spi]
instance = "SPI0"
sck = "PIN_18"
mosi = "PIN_19"
miso = "PIN_16"
cs = "PIN_17"
tx_dma = "DMA_CH3"   # required for async SPI on RP2040
rx_dma = "DMA_CH4"   # required for async SPI on RP2040

[dependencies.rmk]
features = ["rp2040", "dfu_rp", "dfu_ext"]

use core::cell::RefCell;
use embassy_embedded_hal::flash::partition::BlockingPartition;
use embassy_rp::flash::Flash;
use embassy_rp::gpio::Output;
use embassy_rp::spi::{self, Spi};
use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::blocking_mutex::Mutex;
use rmk::dfu::{FlashMutex, FlashDfuHandler, partitions_from_linkerscript};
use rmk::driver::w25q::W25qNorFlash;

// External DFU flash via SPI
type ExternalFlash = W25qNorFlash<spi::Spi<'static, peripherals::SPI0, spi::Blocking>, Output<'static>>;
type ExternalPartition<'a> = BlockingPartition<'a, CriticalSectionRawMutex, ExternalFlash>;

let spi = Spi::new_blocking(p.SPI0, p.PIN_18, p.PIN_19, p.PIN_16, Config::default());
let cs = Output::new(p.PIN_17, Level::High);
let ext_flash = ExternalFlash::new(spi, cs, 8_388_608);

let dfu_mutex = Mutex::new(RefCell::new(ext_flash));
// The whole external chip (offset 0) is the DFU download partition.
let dfu_partition = ExternalPartition::new(&dfu_mutex, 0, 2 * 1024 * 1024);

// Internal flash provides the boot state and storage partitions — the
// internal DFU partition from the linkerscript layout is discarded.
let flash_mutex = FlashMutex::new(RefCell::new(Flash::new_blocking(p.FLASH)));
let (storage_partition, state_partition, _) = partitions_from_linkerscript(&flash_mutex);

let mut dfu_iface = rmk::dfu::FlashDfuHandler::new(dfu_partition, state_partition);
let mut usb_transport = UsbTransport::new(driver, rmk_config.device_config);

run_all!(
	// other processors ...
	usb_transport,
	dfu_iface,
)

#driver = "custom"

If you use a different flash chip or want to provide your own driver, set driver = "custom" and point init_fn to a function in your crate:

[dfu.external_flash]
driver = "custom"
init_fn = "crate::my_flash::init"
flash_size = 8388608

[dfu.external_flash.spi]
instance = "SPI0"
sck = "PIN_18"
mosi = "PIN_19"
miso = "PIN_16"
cs = "PIN_17"
tx_dma = "DMA_CH3"   # required for async SPI on RP2040
rx_dma = "DMA_CH4"   # required for async SPI on RP2040

The function must have the signature:

fn init(spi: impl SpiBus, cs: impl OutputPin, flash_size: u32) -> impl NorFlash

RMK only requires NorFlash from your driver — the DFU download partition and its erase/size handling are built on top by RMK, so you don't need to slice the chip yourself.

#Building the bootloader

Build rmk-boot with the dfu_ext feature and your board's flash size:

# RP2040 4 MB
cargo build --release --target thumbv6m-none-eabi --features rp2040-4mb,dfu_ext

# nRF52840
cargo build --release --target thumbv7em-none-eabihf --features nrf52840,dfu_ext

# nRF52833
cargo build --release --target thumbv7em-none-eabihf --features nrf52833,dfu_ext

If you need different SPI pins, edit src/rp2040.rs or src/nrf52840.rs of rmk-boot and change the pin assignments before building. The EXT_FLASH_SIZE constant (default 8 MB) lives in src/main.rs.

#No-swap bootloader (rmk-boot noswap)

If your firmware no longer fits into the ACTIVE partition but you don't need USB DFU updates, build rmk-boot with the noswap feature. It removes the DFU download partition entirely and grows ACTIVE to fill the whole remaining flash:

The bootloader then becomes a minimal "jump to ACTIVE" loader: no swap, no automatic rollback, and no USB DFU interface in RMK. (But for nRF528xx rmk-boot itself has a USB DFU mode in the bootloader)

Trade-offs:

• Firmware updates via DFU are not possible in RMK's runtime. (but the board can still be flashed via RP2040's built in UF2 bootloader or via USB DFU mode of rmk-boot on nRF528xx)
• No rollback on a failed boot

Build:

cargo make uf2-rp2040-2mb-noswap    # → rmk-boot-rp2040-2mb-noswap.uf2  (or uf2-rp2040-4mb-noswap / uf2-rp2040-8mb-noswap / uf2-rp2040-16mb-noswap)
cargo make uf2-nrf52840-noswap      # → rmk-boot-nrf52840-noswap.uf2
cargo make uf2-nrf52833-noswap      # → rmk-boot-nrf52833-noswap.uf2

Rename the generated rmk-memory.x to memory.x as usual and build your RMK firmware without the DFU features (dfu_rp / dfu_nrf) — no [dfu] section in keyboard.toml is needed. Also activate the set-vtor feature of cortex-m-rt in your projects Cargo.toml.

cortex-m-rt = { version = "0.7.5", features = ["set-vtor"] }