MCUmgr DFU/OTA

Overview

Zephyr uses the MCUmgr subsystem with the SMP protocol to perform DFU (Device Firmware Update). This takes advantage of the MCUboot upgrade management features and requires the target device to use an MCUboot application as the primary bootloader.

This subsystem provides CONFIG_ATM_MCUMGR which enables MCUmgr with image and OS management command groups and selects all required dependencies. Transport-specific defaults are also automatically applied based on whether you’re using Bluetooth or Serial/UART transport.

Tip

When using DFU it can be useful to version the images being flashed. Both the Atmosic mobile app and the MCUmgr utility will show the version of the application. The version can be set using CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION with the format "major.minor.revision+build", for example "2.1.0+0".

Usage

Basic Configuration

Enable MCUmgr and the desired transport in your prj.conf:

For Bluetooth OTA:

CONFIG_ATM_MCUMGR=y
CONFIG_MCUMGR_TRANSPORT_BT=y

For Serial DFU:

CONFIG_ATM_MCUMGR=y
CONFIG_MCUMGR_TRANSPORT_UART=y

The subsystem will automatically configure:

  • Core command groups (IMG_MANAGER, MCUMGR_GRP_IMG, MCUMGR_GRP_OS)

  • Reasonable stack sizes

  • Transport-specific settings (buffer sizes, reassembly, etc.)

  • Bluetooth packet sizes for efficient transfers

  • Storage erase command support

BLE DFU Security

The security level depends on whether CONFIG_BT_SMP is enabled:

  • BT_SMP enabled: Defaults to the highest security level (MCUMGR_TRANSPORT_BT_PERM_RW_AUTHEN). To lower the security level, set one of:

    # Encryption only (no authentication)
CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_ENCRYPT=y

# No security
CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW=y

  • BT_SMP disabled: Only MCUMGR_TRANSPORT_BT_PERM_RW is available (no security).

Serial DFU

UART Configuration

By default, Serial DFU is performed over UART0, which may be disabled. Enable it by adding to your board’s DTS file:

&uart0 {
    status = "okay";
};

Using mcumgr CLI

Install the mcumgr Golang utility:

go install github.com/apache/mynewt-mcumgr-cli/mcumgr@latest

Save connection parameters:

mcumgr conn add DEMO type="serial" connstring="dev=/dev/serial/by-id/usb-SEGGER_J-Link_<DEVICE_ID>-if00,baud=115200"

Test the connection:

mcumgr -c DEMO echo hello

Performing DFU

Upload and activate a new image:

mcumgr -c DEMO image upload /path/to/zephyr.signed.bin

OR for multiimage with image0 and image1

mcumgr -c DEMO image upload /path/to/zephyr.signed.bin --image 0
mcumgr -c DEMO image upload /path/to/zephyr.signed.bin --image 1

mcumgr -c DEMO image list

mcumgr -c DEMO image test <hash of Slot 1 image>

OR for multiimage with image0 and image1

mcumgr -c DEMO image test <hash of image0 Slot 1>
mcumgr -c DEMO image test <hash of image1 Slot 1>

mcumgr -c DEMO reset

  • image test <hash> - Boot new image once, then restore original on next boot

  • image confirm <hash> - Permanently switch to new image

Alternatively, call boot_write_img_confirmed() from within the application after self-test.

Building for DFU

When building an application that supports DFU, MCUboot must be built and flashed. Please see the platform specific instructions in the main README on how to build MCUboot.

External flash is always required for DFU operations. The secondary slot (slot1) for MCUboot is always located in external flash.