MCUmgr

MCUmgr is a device management library designed to be OS and hardware agnostic. It originates from Newt Manager (newtmgr), which is an application for managing remote devices running the Mynewt operating system. MCUmgr builds on newtmgr's concepts but has distinct differences.

Key Features of MCUmgr

  1. Pluggable Transport and Encoding:

    • MCUmgr is designed to work with multiple transport and encoding schemes.
    • It operates independently of the underlying operating system or hardware, relying on hardware abstraction layers of the operating system it is implemented on.

  2. Compatibility:

    • Currently, MCUmgr supports Apache Mynewt and Zephyr operating systems.

Comparison: Newtmgr vs. MCUmgr

  • Newtmgr supports two wire formats:

    • NMP (Newtmgr Protocol)
    • OMP (CoAP Newtmgr Protocol)

  • MCUmgr only supports NMP, referred to as SMP (Simple Management Protocol) in MCUmgr.

Although a request yields the same effect on the recipient device regardless of the protocol, OMP integrates more seamlessly with systems using CoAP.

MCUmgr Stack Structure

+---------------------+---------------------+
|             <command handlers>            |
+---------------------+---------------------+
|                   mgmt                    |
+---------------------+---------------------+
|           <transfer encoding(s)>          |
+---------------------+---------------------+
|               <transport(s)>              |
+---------------------+---------------------+

Components

  1. Command Handlers:

    • Process incoming MCUmgr requests and generate appropriate responses.
    • Handle pairing and combining related commands.

  2. Mgmt:

    • The core of MCUmgr.
    • Facilitates communication between generic command handlers, physical transport, and transfer encoding layers.

  3. Transfer Encoding:

    • Defines how MCUmgr requests and responses are encoded over the wire.

  4. Transport:

    • Enables the transmission and reception of MCUmgr packets over specific mediums.

Each transport is configured with a single transfer encoding.

Example Application Setup

  • Command Handlers:

    • Image management (img_mgmt)
    • File system management (fs_mgmt)
    • Log management (log_mgmt)
    • OS management (os_mgmt)

  • Transport and Encoding Protocols:

    • SMP/Bluetooth
    • SMP/Shell

Extended Stack

+----------+----------+----------+----------+
| img_mgmt |  fs_mgmt | log_mgmt |  os_mgmt |
+----------+----------+----------+----------+
|                   mgmt                    |
+---------------------+---------------------+
|         SMP         |         SMP         |
+---------------------+---------------------+
|      Bluetooth      |        Shell        |
+---------------------+---------------------+

Command Definition

An MCUmgr request and response consist of:

  1. MCUmgr Header
  2. CBOR Key-Value Map

The encoding and parsing of these components depend on the transfer encoding. The content of the CBOR key-value map is defined by the command type.

SMP (Simple Management Protocol)

SMP is used for transmitting MCUmgr packets in frames of 0–126 bytes (127 bytes total), including header, CRC, and newline. Only the last frame includes a CRC.

Initial Frame Format

offset 0:    0x06 0x09
=== Begin Base64 Encoding ===
offset 2:    <16-bit packet-length>
offset ?:    <body>
offset ?:    <crc16> (if final frame)
=== End Base64 Encoding ===
offset ?:    0x0a (newline)

Continuation Frame Format

offset 0:    0x04 0x14
=== Begin Base64 Encoding ===
offset 2:    <body>
offset ?:    <crc16> (if final frame)
=== End Base64 Encoding ===
offset ?:    0x0a (newline)

Packet Field Definitions

Field Description
0x06 0x09 Byte pair indicating the start of a packet.
0x04 0x14 Byte pair indicating the start of a continuation frame.
Packet Length Combined total length of the unencoded body.
Body Actual SMP data (8-byte header and CBOR key-value map).
CRC16 A CRC16 of the unencoded body of the entire packet. Present only in the final frame.
Newline A 0x0a byte; terminates a frame.

CRC16 Configuration

Field Value
Polynomial 0x1021
Initial Value 0

Example Image Upload Command

$ mcumgr --conntype serial --connstring "/dev/ttyACM0,baud=115200" image upload firmware.img

Using MCUmgr with Mynewt OS

  1. Add MCUmgr to project.ym:
repository.mynewt-mcumgr:
    type: git
    vers: 0-latest
    url: 'git@github.com:apache/mynewt-mcumgr.git'
  1. Create a target using newt:
$ newt target create smp_svr-nrf52dk
  1. Set up SMP (e.g., for NRF52):
$ newt target set smp_svr-nrf52dk app=@mynewt-mcumgr/samples/smp_svr/apache \
                                  bsp=@apache-mynewt-core/hw/bsp/nrf52dk    \
                                  build_profile=debug
  1. Build, upload, and run:
$ newt run smp_svr-nrf52dk

Common MCUmgr Commands

# 1. Query the device for its current image list.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' image list

# 2. Upload a new image to the device.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' image upload <filename>

# 3. Test the new image on the next boot.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' image test <image-hash>

# 4. Reboot the device.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' reset

# 5. Verify the new image is running.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' image list

# 6. Make the image swap permanent.
$ mcumgr --conntype ble --connstring 'peer_name=Zephyr' image confirm