embassy-boot-ch32 — an A/B bootloader (embassy-boot) for CH32V2/V3 on ch32-hal, serial + USB DFU

[alexxy]

Hi everyone. I've put together an adaptation of embassy-boot for the CH32 parts driven by ch32-hal: repo alexxy/embassy-boot-ch32, published on crates.io as embassy-boot-ch32 v0.3.0, docs on docs.rs. MIT OR Apache-2.0.

What it is. A NorFlash adapter over ch32-hal's flash driver, linker-script-driven partition maps, and a complete bootloader / application example pair. 20 parts across five families: CH32V203, V208, V303, V305, V307. Tested on real hardware — the nanoCH32V305 (CH32V305RBT6).

Two selectable update transports:

• Serial console (every part): the bootloader waits 3 seconds after reset; a key press opens a console with i (partition map / state) and d (update session). The protocol is deliberately trivial — f <len> plus raw bytes, acknowledged with a . after each 256-byte page — and a host script (tools/serial_update.py) ships with it.
• USB DFU 1.1 (ten parts): the bootloader is a DFU download device (dfu-util -a 0 -D app.bin), and the application exposes the DFU runtime interface, so dfu-util -e from a running application resets the board straight into the USB bootloader. Controllers covered: USBD (V208), OTG_FS (V305RBT6, V307), USBHS (V305FBP6/GBU6). Built on embassy-usb-dfu.

Under the hood:

• CoarseFlash hides the flash's 256-byte pages behind an 8 KiB erase granularity: the embassy-boot state partition stays at 8 KiB instead of ballooning to ~193 KiB, and the swap remains power-loss safe.
• Partition maps (BOOTLOADER 16K/32K + ACTIVE + DFU + STATE) are a single source of truth for both binaries via the __bootloader_* linker symbols — they can never disagree about the geometry.
• Rollback out of the box: until the application calls mark_booted(), the bootloader reverts the previous image on the next reset, so a bad image cannot brick the board.
• CI: a 60-build matrix (both examples × both transports × every supported part) plus static validation of the partition maps.

Quickstart (nanoCH32V305):

git clone https://github.com/alexxy/embassy-boot-ch32 && cd embassy-boot-ch32
# bootloader + application, default chip CH32V305RBT6, serial transport
(cd examples/bootloader && cargo build --release)
(cd examples/application && cargo build --release)
wchisp flash examples/bootloader/target/riscv32imfc-unknown-none-elf/release/bootloader
wchisp flash examples/application/target/riscv32imfc-unknown-none-elf/release/application

After the first ISP flash, updates need no debugger: d in the application console (or dfu-util -e in a USB build), then ship the new binary.

Limitations worth knowing:

• A runtime bootloader needs a working flash driver, which ch32-hal only has for the v3 flash IP: the CH32V2/V3 lines. V003 / X03x / L103 are not covered yet.
• CH32V203RBT6 is excluded: its TIM5 (the only 32-bit GP timer in V203) expands to TimerBits::Bits32, while that enum variant is gated #[cfg(any(ch32l1, ch32v208))] — the HAL simply does not compile for this part. It is a one-line upstream fix; the part comes back into the matrix as soon as it lands.
• 32 KiB flash parts are too small for two images plus a state partition.
• USB builds: 144 MHz HSI, busy-poll during the DFU session, demo VID/PID 0xc0de:0xcafe (replace before shipping), no MSOS descriptors — Windows needs the DFU driver assigned by hand.
• The examples need a nightly with rust-src (riscv32imfc is a JSON target); the crate itself is a plain cargo check, MSRV 1.87.

Roadmap:

• CAN bus firmware loading and updates — a third transport over the bxCAN controllers the V305/V307 carry, for boards where neither a serial cable nor a USB port is available in the field.
• Re-enabling CH32V203RBT6 once the upstream ch32-hal timer bug is fixed.

The full chip matrix, partition geometry, both protocols and the pairing rules are in the README; each example has its own README with the details (bootloader, application).

Feedback, issues and PRs welcome — especially tests on other parts and boards.

[holly-hacker]

Seems neat, but what benefits does this bring? WCH chips have a built-in bootloader that you can't overwrite, so it should theoretically be impossible to brick your chip. Automatic roll-backs are cool and all, but you're now paying a 3 second startup cost for a feature you already have, from what I can tell?
I'd love to heard what the human behind this thinks, rather than get an LLM's response :)

[Johannes-Zink-SSB-AG]

Hi there, not the human who wrote this, but I worked on some A/B updaters in my past jobs.

There is multiple advantages in the solution presented. You can, e.g. implement custom transports (think CAN, USB-DFU, Ethernet, ...) or force-boot into the old partition, which is required on some applications, e.g. if configuration data migration fails. A/B Updates will also prevent your board from becoming a brick if power fails during an update, since it will just fall back to the previous partition. In the field, it's not a very good idea for most applications to rely on builtin bootloaders, especially if they do not support A/B updating. Imagine your board is built into a device somewhere in a very remote location - would you like to drive there for several hours just to plug a usb cable into it for updating? You probably won't need this for a board while prototyping and to which you have physical access, but when building a real world product it's good practice to use A/B systems if you can afford the flash footprint.

Also with respect to the startup delay: in practise one would probably shorten this time, depending on the transport medium. Again: in contrast to the builtin rom-loader you can actually tailor the software to your needs. Maybe you do not want or need an updater in the bootloader itself, in this case you can just skip waiting the 3 seconds entirely and e.g. update the other partition just from your user application.

[holly-hacker]

Aah I see, that makes a lot of sense. Thanks for the clarification!