How it works
MCUmgr speaks SMP (Simple Management Protocol) over BLE, UART, or USB. This tool implements the BLE transport using the Web Bluetooth API, no host tools, no cable, just Chrome or Edge.
SMP messages are CBOR-encoded with an 8-byte header carrying the group ID (OS=0, Image=1), command ID, sequence number, and payload length. BLE responses may arrive across multiple notifications. The tool reassembles fragments by comparing received bytes against the declared payload length in the header.
MCUboot slot mechanics
MCUboot splits flash into two image slots:
- Slot 0 (primary): running image
- Slot 1 (secondary): staging area for new firmware
Full DFU sequence:
- Erase slot 1 — takes 30–60 s on most MCUs. Flash sectors are large and slow.
- Upload — firmware written in chunks over BLE. Chunk size controls throughput.
- Confirm — sends
{"hash": <sha256_of_slot1>, "confirm": true}, marking slot 1 for boot. On reset, MCUboot swaps it into slot 0. - Reset — device reboots, MCUboot performs the swap, new image runs.
To test a new image before committing, turn Auto-confirm OFF and confirm manually after verifying the device behaves correctly.
Chunk size vs. transfer speed
Chunk size is the raw firmware bytes per BLE write. Larger chunks mean fewer round trips, but the chunk plus SMP overhead must fit in the negotiated ATT MTU and the device’s CONFIG_MCUMGR_BUF_SIZE.
| Chunk size | BLE 4.2 (23B ATT MTU) | BLE 5.0 + DLE (251B ATT MTU) | ~200 KB firmware |
|---|---|---|---|
| 64 B | works | works | ~3 min |
| 128 B | works | works | ~1.5 min |
| 244 B | may fail | works | ~52 s |
Default is 128 B, safe on all BLE versions. The tool auto-tunes chunk size on first upload by halving on timeout until the device responds.
BLE requirements
Your Zephyr app needs one of these, depending on version:
# Zephyr 3.3+
CONFIG_MCUMGR_TRANSPORT_BLE=y# Zephyr < 3.3
CONFIG_MCUMGR_TRANSPORT_BT=yWithout this the SMP GATT service won’t appear and the connection will fail.
The tool scans for any BLE device and connects to the SMP service UUID 8d53dc1d-1db7-4cd3-868b-8a527460aa84.
Browser support: Chrome and Edge on desktop only. Firefox and Safari do not implement the Web Bluetooth API. Chrome on Android works but has not been tested with this tool.
WebAssembly: SMP packet encoding and CBOR parsing run in a Rust WASM module compiled with wasm-pack. No server involved — everything runs locally in your browser.
Supported devices
Any MCU running Zephyr RTOS with MCUboot and BLE SMP transport enabled:
- Nordic nRF52 series (nRF52840, nRF52833, nRF52832)
- Nordic nRF91 series (nRF9160-DK via external BLE)
- STM32WB series (STM32WB55, STM32WB35)
- ESP32-C3 / ESP32-S3 (with Zephyr port)
- Raspberry Pi RP2040 (with Zephyr + Bluetooth module)
Common issues
Erase timeout. On MCUs with larger flash sectors, erase can take over 60 s. If you see SMP timeout during erase, go to Advanced Settings and raise the erase timeout to 90–120 s.
Upload stuck at 0 %. Slot 1 was not erased first, or the MCU ran out of flash write buffers. Erase before uploading.
Confirm fails with “No image in slot 1”. Confirm reads the image list to get slot 1’s SHA-256 hash. If the upload was incomplete or the hash field is missing from the response, it has nothing to confirm. Re-erase and re-upload.
Device disconnects on reset. The BLE connection drops when the device reboots. That’s the reset working. The tool ignores this on the Reset operation.