feat(dfu): revisit docs, small corrections

Signed-off-by: Pascal Jäger <pascal.jaeger@leimstift.de>

Author: Schievel1

docs/docs/main/docs/configuration/bootloader.mdx

@@ -4,12 +4,12 @@ RMK supports DFU firmware updates via [embassy-boot](https://github.com/embassy-
 
 A pre-built bootloader called **bootymcbootface** is available for both platforms. The partition formula is identical:
 
-```rust
-// bootloader+state = 28K (fixed)
-// storage = 128K (fixed — 32 sectors × 4K for persistent keymap storage)
-// remaining = flash_size - 28K - 128K
-// ACTIVE    = (remaining - 4K) / 2
-// DFU       = ACTIVE + 4K
+```text
+bootloader+state = 28K (fixed)
+storage = 128K (fixed — 32 sectors × 4K for persistent keymap storage)
+remaining = flash_size - 28K - 128K
+ACTIVE    = (remaining - 4K) / 2
+DFU       = ACTIVE + 4K
 ```
 
 See the [flashing guide](../user_guide/flash_firmware/use_embassy_boot.mdx) for step-by-step instructions.
@@ -40,17 +40,17 @@ led = "PIN_25"
 unlock_keys = [[0, 0], [1, 1]]
 
 # ── (Optional) Manual overrides (only if auto-calculation is not suitable) ──
-# state_offset = 0x6000
-# state_size   = 0x1000
-# dfu_offset   = 0x87000
-# dfu_size     = 528384
+state_offset = 0x6000
+state_size   = 0x1000
+dfu_offset   = 0x87000
+dfu_size     = 528384
 ```
 
 </Tab>
 <Tab label={<Rust />}>
 
 ```rust title="main.rs"
-/ Flash layout using the bootymcbootface formula:
+// Flash layout using the bootymcbootface formula:
 //   state at 0x6000 (4K), active from 0x7000 (size: (flash_size - 28K (= BOOT2 size + embassy-boot + embassy-boot state) - STORAGE_SIZE (= 128K) - page_size (= 4K)) / 2),
 //   dfu follows active (active_size + page_size (= 4K))
 //
@@ -75,8 +75,7 @@ let active_size: u32 = (remaining - PAGE_SIZE) / 2; // DFU = ACTIVE + 1 page (em
 let dfu_size: u32 = active_size + PAGE_SIZE; // embassy-boot needs that extra page for swap info
 let dfu_offset: u32 = ACTIVE_OFFSET + active_size; // dfu after active
 let storage_offset: u32 = dfu_offset + dfu_size; // storage after active + dfu
-let storage_size: u32 = STORAGE_SIZE;
-assert!(storage_offset + storage_size == FLASH_SIZE); // sanity check that we fit everything in flash
+assert!(storage_offset + STORAGE_SIZE == FLASH_SIZE); // sanity check that we fit everything in flash
 
 info!(
     "Flash layout: state @ 0x{:04X} ({}K), active @ 0x{:04X} ({}K), dfu @ 0x{:04X} ({}K), storage @ 0x{:04X} ({}K)",
@@ -87,13 +86,13 @@ info!(
     dfu_offset,
     dfu_size / 1024,
     storage_offset,
-    storage_size / 1024
+    STORAGE_SIZE / 1024
 );
 
 let flash = async_flash_wrapper(rmk::dfu::init_flash(
     p.FLASH,
     storage_offset,
-    storage_size,
+    STORAGE_SIZE,
     STATE_OFFSET,
     STATE_SIZE,
     dfu_offset,
@@ -144,14 +143,10 @@ led = "P0_15"
 unlock_keys = [[0, 0], [1, 1]]
 
 # ── (Optional) Manual overrides (only if auto-calculation is not suitable) ──
-# state_offset = 0x6000
-# state_size   = 0x1000
-# dfu_offset   = 0x87000
-# dfu_size     = 528384
-
-# (Optional) BLE + DFU simultaneously
-[ble]
-enabled = true
+state_offset = 0x6000
+state_size   = 0x1000
+dfu_offset   = 0x87000
+dfu_size     = 528384
 ```
 
 </Tab>
@@ -181,8 +176,7 @@ let active_size: u32 = (remaining - PAGE_SIZE) / 2;
 let dfu_size: u32 = active_size + PAGE_SIZE;
 let dfu_offset: u32 = ACTIVE_OFFSET + active_size;
 let storage_offset: u32 = dfu_offset + dfu_size;
-let storage_size: u32 = STORAGE_SIZE;
-assert!(storage_offset + storage_size == FLASH_SIZE);
+assert!(storage_offset + STORAGE_SIZE == FLASH_SIZE);
 
 info!(
     "Flash layout: state @ 0x{:04X} ({}K), active @ 0x{:04X} ({}K), dfu @ 0x{:04X} ({}K), storage @ 0x{:04X} ({}K)",
@@ -193,13 +187,13 @@ info!(
     dfu_offset,
     dfu_size / 1024,
     storage_offset,
-    storage_size / 1024
+    STORAGE_SIZE / 1024
 );
 
 let flash = async_flash_wrapper(rmk::dfu::init_flash(
     p.NVMC,
     storage_offset,
-    storage_size,
+    STORAGE_SIZE,
     STATE_OFFSET,
     STATE_SIZE,
     dfu_offset,
@@ -233,13 +227,13 @@ run_all!(
 
 The bootloader divides flash into regions. The defaults follow the [bootymcbootface](https://codeberg.org/Schievel/bootymcbootface/) convention and are automatically calculated from `flash_size`:
 
-| Region          | Offset       | Size                         |
-|-----------------|--------------|------------------------------|
-| Bootloader      | `0x0000000`  | 28 KB                        |
-| Boot state      | `0x6000`     | 4 KB                         |
-| Active firmware | `0x7000`     | `(flash_size - 28K - 128K - 4K) / 2` |
-| DFU download    | follows active | `active_size + 4K`        |
-| Storage         | follows DFU  | 128 KB                       |
+| Region          | Offset         | Size                                 |
+|-----------------|----------------|--------------------------------------|
+| Bootloader(s)   | `0x0000000`    | 28 KB                                |
+| Boot state      | `0x6000`       | 4 KB                                 |
+| Active firmware | `0x7000`       | `(flash_size - 28K - 128K - 4K) / 2` |
+| DFU download    | follows active | `active_size + 4K`                   |
+| Storage         | follows DFU    | 128 KB                               |
 
 The DFU partition size follows embassy-boot guidelines, the additional page is used for status information during flashing.
 

docs/docs/main/docs/user_guide/flash_firmware/use_embassy_boot.mdx

@@ -8,12 +8,12 @@ RMK supports DFU for **RP2040** (via `dfu_rp`) and **nRF52840** (via `dfu_nrf`).
 
 RMK and bootymcbootface use an **identical partition formula** so the layout always fits perfectly:
 
-```rust
-// bootloader+state = 28K (fixed)
-// storage = 128K (fixed — 32 sectors × 4K for persistent keymap storage)
-// remaining = flash_size - 28K - 128K
-// ACTIVE    = (remaining - 4K) / 2
-// DFU       = ACTIVE + 4K  (1 page delta required by embassy-boot swap)
+```text
+bootloader+state = 28K (fixed)
+storage = 128K (fixed — 32 sectors × 4K for persistent keymap storage)
+remaining = flash_size - 28K - 128K
+ACTIVE    = (remaining - 4K) / 2
+DFU       = ACTIVE + 4K  (1 page delta required by embassy-boot swap)
 ```
 
 The 4K page delta is an **invariant of embassy-boot's swap algorithm**: the DFU slot must always be exactly one erase page larger than the ACTIVE slot. Storage is reserved at the end of flash and **cannot be reconfigured** when using bootymcbootface — it is always 128K (32 sectors × 4K).
@@ -26,8 +26,9 @@ The 4K page delta is an **invariant of embassy-boot's swap algorithm**: the DFU
 | Storage     | 128K (0x20000)    | 128K (0x20000)    | 128K (0x20000)    | 128K (0x20000)    | 128K (0x20000)   |
 
 The size of the ACTIVE Region is what you need to plug in as the flash size in `memory.x`. 
+(see also the examples `memory.x` in `rmk/examples/use_rust/rp2040_embassy_boot/` for RP2040 or `rmk/examples/use_rust/nrf52840_embassy_boot/` for nRF)
 
-If you override `flash_size` in your `keyboard.toml`'s `[dfu]` section, RMK's auto-calc recomputes the layout on the fly. You never need to manually set `dfu_offset` or `dfu_size` when using bootymcbootface.
+If you override `flash_size` in your `keyboard.toml`'s `[dfu]` section, RMK's auto-calc recomputes the layout on the fly. You never need to manually set the addresses like `dfu_offset` or `dfu_size` when using bootymcbootface.
 
 ## Prerequisites
 
@@ -41,11 +42,13 @@ You need the [bootymcbootface](https://codeberg.org/Schievel/bootymcbootface/) b
 - `bootymcbootface-rp204o-8mb.uf2` – for 8 MB flash
 - `bootymcbootface-rp204o-16mb.uf2` – for 16 MB flash
 
+::: tip
+The **2 MB version works with larger flash chips too** (e.g. 4 MB or 8 MB), using only the first 2 MB. On 2 MB you get 944K of ACTIVE space, which is ample for most RMK firmwares. If you need more room (e.g. with large keymaps, displays, RGB, or many features), pick the matching flash size variant — see the table above for exact slot sizes.
+:::
+
 **nRF52840:**
 - `bootymcbootface-nrf52840.uf2` – for 1 MB flash
-- or build with `cargo make build-nrf` / `cargo make uf2-nrf`
-
-The **2 MB version works with larger flash chips too** (e.g. 4 MB or 8 MB), using only the first 2 MB. On 2 MB you get 944K of ACTIVE space, which is ample for most RMK firmwares. If you need more room (e.g. with large keymaps, Vial, or many features), pick the matching flash size variant — see the table above for exact slot sizes.
+- `bootymcbootface-nrf52840.elf` – for 1 MB flash, for direct flashing via probe-rs
 
 ::: warning
 When using the nRF52840 with the **Adafruit UF2 bootloader**, flashing bootymcbootface **overwrites** the Adafruit bootloader (even when flashing via UF2). Subsequent UF2 uploads won't work.
@@ -64,10 +67,10 @@ If configuring manually, ensure:
 - `keyboard.toml` has `[dfu]` section
 - The flash partitioning in `memory.x` matches your bootloader and flash size (see `rmk/examples/use_rust/rp2040_embassy_boot/` for RP2040 or `rmk/examples/use_rust/nrf52840_embassy_boot/` for nRF)
 
-**Important:** For RP2040 the bootymcbootface version (2MB, 4MB, ...) and the RMK settings must use the **same flash size**. Example: bootymcbootface 2 MB → RMK with 2 MB flash configuration.
+**Important:** For RP2040 the bootymcbootface version (2MB, 4MB, ...) and the RMK settings must use the **same flash size**. Example: bootymcbootface 2 MB → RMK with 2 MB flash configuration. So that means, if you have a RP2040 with bigger flash, you can always use a bootymcbootface and a memory.x in your firmware for a smaller flash size, but the both must be for the same flash size.
 
 ::: tip
-You can still flash firmware via UF2 or probe-rs — as long as it was built with the correct `memory.x` for the embassy-boot partition layout (i.e. with `dfu_rp` or `dfu_nrf` feature), it will land in the active firmware slot and leave bootymcbootface untouched.
+You can still flash firmware via UF2 (when using RP2040, on nRF52840 the UF2 bootloader was overwritten by bootymcbootface) or probe-rs — as long as it was built with the correct `memory.x` for the embassy-boot partition layout (i.e. with `dfu_rp` or `dfu_nrf` feature), it will land in the active firmware slot and leave bootymcbootface untouched.
 
 If you flash a RMK firmware built with a **normal** `memory.x` (without embassy-boot), it will start at flash address `0x0` and **overwrite bootymcbootface**.
 :::
@@ -102,6 +105,8 @@ The first time, you need to flash the bootloader first, then RMK.
 
 **Via debug probe (probe-rs):**
 ```shell
+# in the bootymcbootface directory
+cargo build --relese
 # RP2040
 probe-rs run --chip RP2040 target/thumbv6m-none-eabi/release/bootymcbootface
 # nRF52840
@@ -121,18 +126,19 @@ Now flash the actual RMK firmware. The bootloader stays in place.
 
 **Method B – via debug probe (probe-rs):**
 ```shell
+# in your RMK firmware directory
 # RP2040
 probe-rs run --chip RP2040 target/thumbv6m-none-eabi/release/your-firmware
 # nRF52840
 probe-rs run --chip nRF52840_xxAA target/thumbv7em-none-eabihf/release/your-firmware
 
-# or for both
+# or (for both RP2040 and nRF52840)
 cargo run --release
 ```
 
 ### All subsequent updates via DFU
 
-Once bootymcbootface and the RMK firmware have been flashed once, all future updates can be done **easily over USB via DFU**.
+Once bootymcbootface and the RMK firmware have been flashed once, all future updates can be done **easily over USB via DFU**. (but as stated above, as long as the `memory.x` of your firmware fits, you can still use probe-rs (RP2040 and nRF52840) or the UF2 bootloader (RP2040))
 
 #### Generate the .bin file
 
@@ -150,17 +156,17 @@ rust-objcopy -O binary target/thumbv7em-none-eabihf/release/your-firmware your-f
 ```shell
 cargo make bin --release
 ```
-(Requires a `Makefile.toml` with a `bin` task — the generated template from `rmkit` and the examples already include one.)
+(Requires a `Makefile.toml` with a `bin` task — the generated template from `rmkit` and the examples already include one or see embassy-boot examples.)
 
 #### Flash via dfu-util
 
 ```shell
 dfu-util -D your-firmware.bin -R 
 ```
 
-Or with a device ID if multiple devices are connected:
+Or with a device ID if multiple DFU devices are connected:
 ```shell
-dfu-util -d 1209:1234 -D your-firmware.bin
+dfu-util -d 4c4b:4643 -D your-firmware.bin
 ```
 
 Find your device's VID:PID via `lsusb` on Linux or Device Manager (under "Universal Serial Bus devices") on Windows.
@@ -188,10 +194,20 @@ If you don't press the unlock keys within the first 10 seconds, the window close
 
 If an LED pin is configured in `keyboard.toml` (default PIN_25, if not `[dfu] led = "none"`):
 
-| State | LED behavior |
-|---|---|---|
-| Unlock window open (waiting for keys) | Solid on |
-| DFU unlocked (ready for dfu-util) | Blinks Morse "D F U" |
-| DFU download started | On |
-| Writing data blocks | Toggles on each block (flickers) |
-| DFU finished / system reset | Off |
+| State                                 | LED behavior                     |
+|---------------------------------------|----------------------------------|
+| Unlock window open (waiting for keys) | Solid on                         |
+| DFU unlocked (ready for dfu-util)     | Blinks Morse "D F U"             |
+| DFU download started                  | On                               |
+| Writing data blocks                   | Toggles on each block (flickers) |
+| DFU finished / system reset           | Off                              |
+
+Additionally the bootymcbootface bootloader has blinking codes using PIN_25 (RP2040) / P0_15 (nRF52840) as well:
+| State                                                                                                      | LED behavior                       |
+|------------------------------------------------------------------------------------------------------------|------------------------------------|
+| Normal boot — bootloader ran and jumped to ACTIVE                                                          | 2 short blinks (≈2 Hz)             |
+| Bootloader detected a pending DFU→ACTIVE swap and is about to copy                                         | 1 s solid on                       |
+| Previous forward swap completed but the new app did not call =mark_booted()= — reverting to the old ACTIVE | 3 short blinks (50 ms)             |
+| Successful DFU→ACTIVE copy; about to jump                                                                  | 5 short blinks (50 ms)             |
+| Bootloader itself panicked (e.g. flash read error, invalid state partition)                                | Morse SOS (... --- ...), repeating |
+

examples/use_config/nrf52840_embassy_boot/keyboard.toml

@@ -36,13 +36,28 @@ enabled = true
 [ble]
 enabled = true
 
+# DFU partition layout — must match your bootloader's memory.x
+#
+# By default RMK uses the bootymcbootface formula with flash_size from the
+# chip default (1 MB for nRF52840).
+# Calculation: 
+# 2 * 1024 * 1024;    // 2 MB (default)
+# 4 * 1024 * 1024;    // 4 MB
+# and so on
+# the addresses for the state, dfu, active and storage partitions are then automatically calculated.
+# Uncomment and adjust to override:
+# [dfu]
+# flash_size = 2097152   # total flash (default: 1 MB)
+#
+# To set addresses manually, uncomment and edit the values below.
+# Doing so disables the auto-calculation:
+# state_offset = 0x6000
+# state_size = 0x1000
+# dfu_offset = 0x87000
+# dfu_size = 528384
+
 [dfu]
-led = "P0_15"
+led = "P0_15" # default P0_15, to not use set to "none"
 # Optional DFU lock — physical keys to press simultaneously to unlock DFU firmware download.
 # Requires the `dfu_lock` Cargo feature (not enabled by default).
-# unlock_keys = [[0, 0], [1, 1]]
-
-# [storage]
-# enabled = false
-# start_addr = 0xA0000
-# num_sectors = 32
+# unlock_keys = [[0, 0], [1, 1]]

examples/use_config/nrf52840_embassy_boot/memory.x

@@ -4,9 +4,6 @@ Flash layout matching bootymcbootface nRF layout:
   ACTIVE (this firmware): 432K at 0x7000
   DFU: 436K at 0x73000
   storage: 128K at 0xE0000
-
-ACTIVE size depends on the default [storage] num_sectors (32 = 128K).
-If you change num_sectors, adjust LENGTH accordingly.
 */
 MEMORY {
 	FLASH : ORIGIN = 0x00007000, LENGTH = 432K

examples/use_config/rp2040_embassy_boot/keyboard.toml

@@ -29,9 +29,6 @@ keymap = [
     ],
 ]
 
-[storage]
-enabled = true
-
 # DFU partition layout — must match your bootloader's memory.x
 #
 # By default RMK uses the bootymcbootface formula with flash_size from the
@@ -51,15 +48,9 @@ enabled = true
 # state_size = 0x1000
 # dfu_offset = 0x87000
 # dfu_size = 528384
-# Optional DFU activity LED (lit during firmware download)
-# led = "PIN_25"
 
 [dfu]
 led = "PIN_16"
 # Optional DFU lock — physical keys to press simultaneously to unlock DFU firmware download.
 # Requires the `dfu_lock` Cargo feature (not enabled by default).
 unlock_keys = [[0, 0], [1, 1]]
-
-[rmk]
-morse_max_num = 8
-max_patterns_per_key = 8

examples/use_config/rp2040_embassy_boot/memory.x

@@ -1,8 +1,13 @@
 /*
 This memory.x is for the RP2040 with 2MB flash.
-For different flash sizes see docs. 
+For different flash sizes uncomment below. 
+Be aware you need to change [dfu] flash_size in keyboard.toml accordingly
+and flash the matching bootloader.
 */
 MEMORY {
 	FLASH : ORIGIN = 0x10007000, LENGTH = 944K
+	/* 4MB: FLASH : ORIGIN = 0x10007000, LENGTH = 1968K */
+	/* 8MB: FLASH : ORIGIN = 0x10007000, LENGTH = 4016K */
+	/* 16MB: FLASH : ORIGIN = 0x10007000, LENGTH = 8112K */
 	RAM   : ORIGIN = 0x20000000, LENGTH = 256K
 }