Quick Start

Environment Setup and Configuration

1. Install MCUmgr Command Line Tool on PC Host

You can download the corresponding platform’s newtmgr tool package from the Apache Mynewt official website:

Add the extracted newtmgr tool package path to the environment variable of the corresponding platform. Execute newtmgr –help in the command line. If global options are displayed, the configuration is successful.

2. Zephyr Device-side Project Configuration

Sample path: zephyr/samples/subsys/mgmt/mcumgr/smp_svr.

Flash Partition (Prerequisite)

The board-level DTS for the smp_svr sample must include three partitions: boot_partition (holds MCUboot), slot0_partition (primary slot, running firmware), and slot1_partition (secondary slot, receives new firmware). Building with the //mcuboot build type automatically applies the corresponding MCUboot board-level DTS configuration. For partition addresses of each board, see Flash Layout.

MCUboot and SMP Configuration

This guide uses UART as the transport between MCUmgr and the PC host as an example. You need to ensure that the smp_svr sample’s configuration file (such as prj.conf or board-specific configuration file) contains the following key configurations:

# Enable MCUboot bootloader
CONFIG_BOOTLOADER_MCUBOOT=y

# Enable MCUmgr and SMP services
CONFIG_MCUMGR=y
CONFIG_MCUMGR_TRANSPORT_UART=y                              # Use UART as transport layer

# Enable MCUmgr necessary command groups
CONFIG_MCUMGR_GRP_IMG=y                                     # Firmware management command group
CONFIG_MCUMGR_GRP_OS=y                                      # Basic OS command group
CONFIG_MCUMGR_GRP_IMG_ALLOW_CONFIRM_NON_ACTIVE_IMAGE_ANY=y  # Allow confirmation of non-running firmware

# Configure UART buffer and MTU (Maximum Transmission Unit)
CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=1024
CONFIG_MCUMGR_TRANSPORT_UART_MTU=1024                       # Maximum SMP frame size sent/received over UART
CONFIG_UART_MCUMGR_RX_BUF_SIZE=1024                         # UART RX buffer size, must fit one full SMP frame

You need to specify the upgrade method in the application’s sysbuild configuration file sysbuild.conf; if you do not specify it, the build defaults to the swap_using_offset method.

# Configure upgrade method
SB_CONFIG_MCUBOOT_MODE_SWAP_USING_OFFSET=y

UART Transport Layer Configuration

You need to specify the UART pins in overlay file and ensure the UART port is properly configured and enabled (the example below uses uart2).

/ {
   chosen {
      zephyr,uart-mcumgr = &uart2;
   };
};

&uart2 {
   pinctrl-0 = <&uart2_default>;
   pinctrl-names = "default";
   current-speed = <115200>;
   status = "okay";
};

Build Command

./nuwa.py build -b <BOARD>//mcuboot zephyr/samples/subsys/mgmt/mcumgr/smp_svr --sysbuild -p

After device power-on/reset, open a serial terminal and confirm that the sample has started and printed initialization logs:

*** Booting Zephyr OS build f50378385a85 ***
<inf> smp_sample: build time: Jan  7 2026 11:52:35

Upgrade Process

Assume the device is already running firmware containing the smp_svr sample, and the selected UART port is connected to the PC.

Establish MCUmgr Connection

Configure Connection

Command format: newtmgr conn add <connection_name> type=<type> connstring="<key=value[,key=value...]>"

Example:

$ newtmgr conn add myConn type=serial connstring="dev=<COM3>,baud=115200,mtu=1024"
Connection profile myConn successfully added

Note

  • Baud rate configuration needs to be consistent with the setting in device tree. MTU configuration needs to match the board’s CONFIG_MCUMGR_TRANSPORT_UART_MTU, and must not exceed CONFIG_UART_MCUMGR_RX_BUF_SIZE.

  • For other transport methods of newtmgr conn configuration, please refer to official documentation.

View Firmware List

Command format: newtmgr image list -c <connection_profile>

Example:

$ newtmgr image list -c myConn
Images:
image=0 slot=0
   version: 0.0.0
   bootable: true
   flags: active confirmed
   hash: d0d1fe6e6f39a65d2442009e6a620736ea88e437c7bd297abdd9e9eaf1e3e257

Parameter Description

image:

Firmware number; the smp_svr sample has only one firmware, so this is always 0.

slot:

Slot (0=primary slot, 1=secondary slot)

version/hash:

Version number and hash

bootable:

Whether the slot contains valid firmware (firmware header is correct and verifiable)

flags:

  • active indicates the currently running firmware slot

  • pending indicates MCUboot will test this firmware slot on next reset

  • confirmed indicates this firmware slot has been confirmed and will not roll back

Note

When building new firmware, you can modify the version number CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION for easier version management and querying.

Upload New Firmware

Use the image upload command to send the newly compiled and signed firmware to the device.

Command format: newtmgr image upload <image-file> -c <conn_profile> [-n <image_int>]

Example:

$ newtmgr -c myConn image upload -n 0 /path/to/your/image_0.bin
77.55 KiB / 77.55 KiB [=======================================================================] 100.00% 4.38 KiB/s 17s
Done

Parameter Description

-n:

Specify firmware number, defaults to firmware 0 when omitted.

Mark as Pending Test

After successful transfer, the new firmware will be stored in the secondary slot partition of the corresponding firmware. Use the following command to mark the new firmware as test, and MCUboot will try to run it on the next boot.

Command format: newtmgr -c <conn_profile> image test <hex-image-hash>

Example:

$ newtmgr -c myConn image test 99bb5f0867744a238693f522b31be146a74fca2ad587d878feebef70b7d1e812
Images:
image=0 slot=0
   version: 0.0.0
   bootable: true
   flags: active confirmed
   hash: d0d1fe6e6f39a65d2442009e6a620736ea88e437c7bd297abdd9e9eaf1e3e257
image=0 slot=1
   version: 0.0.1
   bootable: true
   flags: pending
   hash: 99bb5f0867744a238693f522b31be146a74fca2ad587d878feebef70b7d1e812
Split status: N/A (0)

Note

You can see in the information of the firmware slot specified for testing: flags: pending.

Reset Device

You can send a reset command through the MCUmgr tool, or manually reset the device.

After triggering reset, MCUboot detects that the secondary slot is marked as test, and based on the configured Upgrade Mechanism , decides whether to perform primary/secondary slot swap; when using swap_using_xxx strategy, the swap will be completed before the application starts.

Command format: newtmgr reset -c <conn_profile>

Example:

$ newtmgr -c myConn reset
Done

Confirm New Firmware

After the device restarts and successfully runs the new firmware, you must perform a confirmation operation. Zephyr provides two confirmation methods:

  1. Application self-confirmation

    After the device boots and verifies the new firmware successfully, the application actively calls the confirmation interface boot_write_img_confirmed() provided by MCUboot to mark the current firmware as confirmed.

  2. Send confirmation command through MCUmgr tool

    Command format: newtmgr image confirm [hex-image-hash] -c <conn_profile>

    Example:

    $ newtmgr -c myConn image confirm 99bb5f0867744a238693f522b31be146a74fca2ad587d878feebef70b7d1e812
Images:
image=0 slot=0
   version: 0.0.1
   bootable: true
   flags: active confirmed
   hash: 99bb5f0867744a238693f522b31be146a74fca2ad587d878feebef70b7d1e812

Note

  • You can see in the confirmed firmware slot information: flags: confirmed.

  • The current smp_svr sample uses the second confirmation method.