快速入门

环境准备与配置

1. PC 主机安装 MCUmgr 命令行工具

您可以从 Apache Mynewt 官网下载对应平台的 newtmgr 工具包：

Windows 64-bit： apache-mynewt-newtmgr-bin-windows-1.14.0.tgz
Linux 64-bit： apache-mynewt-newtmgr-bin-linux-1.14.0.tgz

将解压后的 newtmgr 工具包路径添加至对应平台的环境变量中，命令行执行 newtmgr --help，若显示全局选项即配置成功。

2. Zephyr 设备端的工程配置

示例路径： zephyr/samples/subsys/mgmt/mcumgr/smp_svr。

Flash 分区（前提条件）

smp_svr 示例的板级 DTS 必须包含以下三个分区：boot_partition（存放 MCUboot）、slot0_partition（主槽，运行固件）、slot1_partition（次槽，接收新固件）。编译时指定 //mcuboot build type 即可自动使用对应的 MCUboot 板级 DTS 配置。各板分区地址详见 Flash Layout。

MCUboot 与 SMP 配置

本文以 UART 作为 MCUmgr 与 PC 主机之间的传输方式为例。您需要确保 smp_svr 示例的配置文件（如 prj.conf 或板卡特定的配置文件）中包含以下关键配置：

# 启用 MCUboot 引导程序
CONFIG_BOOTLOADER_MCUBOOT=y

# 启用 MCUmgr 和 SMP 服务
CONFIG_MCUMGR=y
CONFIG_MCUMGR_TRANSPORT_UART=y                              # 使用 UART 作为传输层

# 使能 MCUmgr 必要的命令组
CONFIG_MCUMGR_GRP_IMG=y                                     # 固件管理命令组
CONFIG_MCUMGR_GRP_OS=y                                      # 基本 OS 命令组
CONFIG_MCUMGR_GRP_IMG_ALLOW_CONFIRM_NON_ACTIVE_IMAGE_ANY=y  # 允许对非运行固件进行确认

# 配置 UART 缓冲区与 MTU（最大传输单元）
CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=1024
CONFIG_MCUMGR_TRANSPORT_UART_MTU=1024                       # UART 上收发的 SMP 帧最大长度
CONFIG_UART_MCUMGR_RX_BUF_SIZE=1024                         # UART 接收缓冲区大小，需能容纳一帧完整的 SMP 数据

您需要在应用程序的 sysbuild 配置文件 sysbuild.conf 中指定升级方式；不指定时默认采用 swap_using_offset 方式。

# 配置升级方式
SB_CONFIG_MCUBOOT_MODE_SWAP_USING_OFFSET=y

UART 传输层配置

您需要在 overlay 文件中指定所用的 UART 引脚，并确保该 UART 端口已正确配置并启用（下例以 uart2 为例）。

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

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

编译命令

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

设备上电/复位后，打开串口终端，确认示例已启动并打印初始化日志：

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

升级流程

假设设备已运行包含 smp_svr 示例的固件，并且选定的 UART 端口已连接到 PC 。

建立 MCUmgr 连接

配置连接

命令格式： newtmgr conn add <连接名> type=<类型> connstring="<key=value[,key=value...]>"

示例：

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

备注

波特率配置需要与设备树中的设定一致。MTU 配置需要与板端 CONFIG_MCUMGR_TRANSPORT_UART_MTU 保持一致，且不超过 CONFIG_UART_MCUMGR_RX_BUF_SIZE 。
newtmgr conn 配置其他传输方式，请参考官网说明。

查看固件列表

命令格式： newtmgr image list -c <connection_profile>

示例：

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

参数说明

image:

固件编号，当前 smp_svr 示例只有一个固件，故始终为 0 。

slot:

槽位（0=主槽，1=次槽）

version/hash:

版本号与哈希

bootable:

该槽位是否存在有效固件（固件头部正确且可校验）

flags:

active 表示是正在运行的固件槽位
pending 表示在下次 reset 时 MCUboot 会测试该固件槽位
confirmed 表示该固件槽位已确认，不会回滚

备注

编译新固件时，可修改版本号 CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION，方便版本管理和查询。

上传新固件

使用 image upload 命令将新编译好的、已签名的固件发送到设备。

命令格式： newtmgr image upload <image-file> -c <conn_profile> [-n <image_int>]

示例：

$ 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

参数说明

-n:: 指定固件编号，缺省时表示固件 0 。

标记为待测试

传输成功后，新固件将存放在对应固件的次槽分区中。通过以下命令标记新固件为 test ，MCUboot 会在下次启动时尝试运行它。

命令格式： newtmgr -c <conn_profile> image test <hex-image-hash>

示例：

$ 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)

备注

标记为 test 的固件槽位信息中可以看到： flags: pending。

重启设备

可以通过 MCUmgr 工具发送重启命令，或手动复位设备。

触发 reset 后，MCUboot 检测到次槽被标记为 test，根据配置的升级机制，决定是否执行主/次槽交换；采用 swap_using_xxx 策略时会在应用启动前完成交换。

命令格式： newtmgr reset -c <conn_profile>

示例：

$ newtmgr -c myConn reset
Done

确认新固件

设备重启并成功运行新固件后，必须执行确认操作，Zephyr 提供了两种确认方式：

应用程序自行确认

设备在启动并验证新固件成功后，由应用程序主动调用 MCUboot 提供的确认接口 boot_write_img_confirmed()，将当前固件标记为 confirmed。

通过 MCUmgr 工具下发确认命令

命令格式： newtmgr image confirm [hex-image-hash] -c <conn_profile>

示例：

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

备注

确认后的固件槽位信息中可以看到： flags: confirmed。
当前 smp_svr 示例采用第二种确认方式。