MCUmgr

Overview

The management subsystem allows remote management of Zephyr-enabled devices. The following management operations are available:

  • Image management

  • File System management

  • OS management

  • Settings (config) management

  • Shell management

  • Statistic management

  • Zephyr management

over the following transports:

  • BLE (Bluetooth Low Energy)

  • Serial (UART)

  • UDP over IP

The management subsystem is based on the Simple Management Protocol (SMP) provided by MCUmgr, an open source project that provides a management subsystem that is portable across multiple real-time operating systems.

The management subsystem is located in subsys/mgmt/ inside of the Zephyr tree.

Additionally, there is a sample server that provides management functionality over BLE and serial.

Tools/libraries

There are various tools and libraries available which enable usage of MCUmgr functionality on a device which are listed below. Note that these tools are not part of or related to the Zephyr project.

Tools and Libraries for MCUmgr

Name

OS support

Transports

Groups

Type

Language

License

Windows

Linux

mac

Mobile

Embedded

Serial

Bluetooth

UDP

OS

IMG

Stat

Settings

FS

Shell

Zephyr

AuTerm

✓

✓

✓

✕

✕

✓

✓

✓

✓

✓

✓

✓

✓

✓

✓

Application

C++ (Qt)

GPLv3

mcumgr-client

✓

✓

✓

✕

✕

✓

✕

✕

✕

✓

✕

✕

✕

✕

✕

Application

Rust

BSD

mcumgr-web

✓

✓

✓

✕

✕

✕

✓

✕

✕

✓

✕

✕

✕

✕

✕

Web page (chrome only)

Javascript

MIT

nRF Connect Device Manager:
Android and iOS

✕

✕

✕

✓

✕

✕

✓

✕

✓

✓

✓

✓

✓

✓

✓

Library and application

Java, Kotlin, Swift

Apache

Zephyr MCUmgr client (in-tree)

✕

✓

✕

✕

✓

✓

✓

✓

✓

✓

✕

✕

✕

✕

✕

Library

C

Apache

Note that a tick for a particular group indicates basic support for that group in the code, it is possible that not all commands/features of a group are supported by the implementation.

Bootloader Integration

The Device Firmware Upgrade subsystem integrates the management subsystem with the bootloader, providing the ability to send and upgrade a Zephyr image to a device.

Currently only the MCUboot bootloader is supported. See MCUboot for more information.

Discord channel

Developers welcome!

API Reference

group mcumgr_mgmt_api

MCUmgr mgmt API.

Since

1.11

Version

1.0.0

Defines

MGMT_CTXT_SET_RC_RSN(mc, rsn)
MGMT_CTXT_RC_RSN(mc)
MGMT_RETURN_CHECK(ok)

Used at end of MCUmgr handlers to return an error if the message size limit was reached, or OK if it was not.

MGMT_HDR_SIZE

Typedefs

typedef void *(*mgmt_alloc_rsp_fn)(const void *src_buf, void *arg)

Allocates a buffer suitable for holding a response.

If a source buf is provided, its user data is copied into the new buffer.

Param src_buf:

An optional source buffer to copy user data from.

Param arg:

Optional streamer argument.

Return:

Newly-allocated buffer on success NULL on failure.

typedef void (*mgmt_reset_buf_fn)(void *buf, void *arg)

Resets a buffer to a length of 0.

The buffer’s user data remains, but its payload is cleared.

Param buf:

The buffer to reset.

Param arg:

Optional streamer argument.

typedef int (*mgmt_handler_fn)(struct smp_streamer *ctxt)

Processes a request and writes the corresponding response.

A separate handler is required for each supported op-ID pair.

Param ctxt:

The mcumgr context to use.

Return:

0 if a response was successfully encoded, mcumgr_err_t code on failure.

Enums

enum mcumgr_op_t

Opcodes; encoded in first byte of header.

Values:

enumerator MGMT_OP_READ = 0

Read op-code.

enumerator MGMT_OP_READ_RSP

Read response op-code.

enumerator MGMT_OP_WRITE

Write op-code.

enumerator MGMT_OP_WRITE_RSP

Write response op-code.

enum mcumgr_group_t

MCUmgr groups.

The first 64 groups are reserved for system level mcumgr commands. Per-user commands are then defined after group 64.

Values:

enumerator MGMT_GROUP_ID_OS = 0

OS (operating system) group.

enumerator MGMT_GROUP_ID_IMAGE

Image management group, used for uploading firmware images.

enumerator MGMT_GROUP_ID_STAT

Statistic management group, used for retieving statistics.

enumerator MGMT_GROUP_ID_SETTINGS

Settings management (config) group, used for reading/writing settings.

enumerator MGMT_GROUP_ID_LOG

Log management group (unused)

enumerator MGMT_GROUP_ID_CRASH

Crash group (unused)

enumerator MGMT_GROUP_ID_SPLIT

Split image management group (unused)

enumerator MGMT_GROUP_ID_RUN

Run group (unused)

enumerator MGMT_GROUP_ID_FS

FS (file system) group, used for performing file IO operations.

enumerator MGMT_GROUP_ID_SHELL

Shell management group, used for executing shell commands.

enumerator MGMT_GROUP_ID_PERUSER = 64

User groups defined from 64 onwards.

enumerator ZEPHYR_MGMT_GRP_BASIC = (MGMT_GROUP_ID_PERUSER - 1)

Zephyr-specific groups decrease from PERUSER to avoid collision with upstream and user-defined groups.

Zephyr-specific: Basic group

enum mcumgr_err_t

MCUmgr error codes.

Values:

enumerator MGMT_ERR_EOK = 0

No error (success).

enumerator MGMT_ERR_EUNKNOWN

Unknown error.

enumerator MGMT_ERR_ENOMEM

Insufficient memory (likely not enough space for CBOR object).

enumerator MGMT_ERR_EINVAL

Error in input value.

enumerator MGMT_ERR_ETIMEOUT

Operation timed out.

enumerator MGMT_ERR_ENOENT

No such file/entry.

enumerator MGMT_ERR_EBADSTATE

Current state disallows command.

enumerator MGMT_ERR_EMSGSIZE

Response too large.

enumerator MGMT_ERR_ENOTSUP

Command not supported.

enumerator MGMT_ERR_ECORRUPT

Corrupt.

enumerator MGMT_ERR_EBUSY

Command blocked by processing of other command.

enumerator MGMT_ERR_EACCESSDENIED

Access to specific function, command or resource denied.

enumerator MGMT_ERR_UNSUPPORTED_TOO_OLD

Requested SMP MCUmgr protocol version is not supported (too old)

enumerator MGMT_ERR_UNSUPPORTED_TOO_NEW

Requested SMP MCUmgr protocol version is not supported (too new)

enumerator MGMT_ERR_EPERUSER = 256

User errors defined from 256 onwards.

Functions

void mgmt_register_group(struct mgmt_group *group)

Registers a full command group.

Parameters:

  • group – The group to register.

void mgmt_unregister_group(struct mgmt_group *group)

Unregisters a full command group.

Parameters:

  • group – The group to register.

const struct mgmt_handler *mgmt_find_handler(uint16_t group_id, uint16_t command_id)

Finds a registered command handler.

Parameters:

  • group_id – The group of the command to find.

  • command_id – The ID of the command to find.

Returns:

The requested command handler on success; NULL on failure.

const struct mgmt_group *mgmt_find_group(uint16_t group_id)

Finds a registered command group.

Parameters:

  • group_id – The group id of the command group to find.

Returns:

The requested group on success; NULL on failure.

const struct mgmt_handler *mgmt_get_handler(const struct mgmt_group *group, uint16_t command_id)

Finds a registered command handler.

Parameters:

  • group – The group of the command to find.

  • command_id – The ID of the command to find.

Returns:

The requested command handler on success; NULL on failure.

struct mgmt_handler
#include <mgmt.h>

Read handler and write handler for a single command ID.

Set use_custom_payload to true when using a user defined payload type

struct mgmt_group
#include <mgmt.h>

A collection of handlers for an entire command group.

Public Members

sys_snode_t node

Entry list node.

const struct mgmt_handler *mg_handlers

Array of handlers; one entry per command ID.

uint16_t mg_group_id

The numeric ID of this group.