Crate mcumgr_toolkit

Source

Expand description

§MCUmgr Client for Zephyr

This crate provides a full Rust-based software suite for Zephyr’s MCUmgr protocol.

It might be compatible with other MCUmgr/SMP-based systems, but it is developed with Zephyr in mind.

Specifically, it provides:

mcumgrctl, a CLI tool for running MCUmgr actions via command line
A Rust library that supports all Zephyr MCUmgr commands
A Python interface for the library

Its primary design goals are:

Completeness
- cover all use cases of Zephyr’s MCUmgr
- for implementation progress, see this tracking issue
Performance
- use static memory and large buffers to prioritize performance over memory footprint
- see further down for more information regarding performance optimizations required on Zephyr side

§Usage Example

use mcumgr_toolkit::MCUmgrClient;
use std::time::Duration;

fn main() {
    let serial = serialport::new("COM42", 115200).open().unwrap();

    let mut client = MCUmgrClient::new_from_serial(serial);
    client.use_auto_frame_size().unwrap();

    println!("{:?}", client.os_echo("Hello world!").unwrap());
}

"Hello world!"

§Installation as command line tool

cargo install mcumgr-toolkit-cli

§Usage examples

List all available USB serial ports:

$ mcumgrctl --usb-serial

Available USB serial ports:

 - 2fe3:0004:0 (/dev/ttyACM0) - Zephyr Project CDC ACM serial backend

[!TIP] 2fe3:0004 is the default VID/PID of Zephyr samples.

Run a simple connection test:

$ mcumgrctl --usb-serial 2fe3:0004
Device alive and responsive.

You can even use a regular expression if you want:

$ mcumgrctl --usb-serial "2fe3:.*"
Device alive and responsive.

Or a normal serial port descriptor:

$ mcumgrctl --serial COM42
Device alive and responsive.

Perform a firmware update:

$ mcumgrctl -u 2fe3:0004 firmware update zephyr.signed.encrypted.bin
Detecting bootloader ...
Found bootloader: MCUboot
Parsing firmware image ...
Querying device state ...
Update: 1.2.3.4-f0a745b8 -> 1.2.3.5-79f50793
Uploading new firmware ...
Activating new firmware ...
Triggering device reboot ...
Success.
Device should reboot with new firmware.

Or show device information:

$ mcumgrctl -u 2fe3:0004 os application-info

OS/Application Info:
    Kernel name:       Zephyr
    Node name:         unknown
    Kernel release:    v4.3.0-3-gc87e528897ea
    Kernel version:    4.3.0
    Build time:        Sat Jan 24 10:39:08 2026
    Machine:           arm
    Processor:         cortex-m4
    Hardware platform: nrf52840dongle/nrf52840/bare
    Operating system:  Zephyr

For more information, run mcumgrctl --help.

§Usage as a library

To use this library in your project, enter your project directory and run:

cargo add mcumgr-toolkit

§Performance

Zephyr’s default buffer sizes are quite small and reduce the read/write performance drastically.

The central most important setting is MCUMGR_TRANSPORT_NETBUF_SIZE. Its default of 384 bytes is very limiting, both for performance and as cutoff for large responses, like os task_statistics or some shell commands.

Be aware that changing this value also requires an increase of MCUMGR_TRANSPORT_WORKQUEUE_STACK_SIZE to prevent overflow crashes.

In practice, I found that the following values work quite well (on i.MX RT1060) and give me 410 KB/s read and 120 KB/s write throughput, which is an order of magnitude faster than the default settings.

CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=4096
CONFIG_MCUMGR_TRANSPORT_WORKQUEUE_STACK_SIZE=8192

If the experience differs on other chips, please open an issue and let me know.

§Contributions

Contributions are welcome!

I primarily wrote this crate for myself, so any ideas for improvements are greatly appreciated.

Re-exports§

pub use client::MCUmgrClient;

Modules§

bootloader: Bootloader related definitions
client: A high-level client for Zephyr’s MCUmgr SMP functionality
commands: MCUmgr command group definitions
connection: SMP protocol layer implementation
mcuboot: MCUboot specific algorithms
smp_errors: Zephyr SMP error definitions
transport: SMP transport layer implementation

Enums§

Errno: See errno.h.
MCUmgrGroup: See enum mcumgr_group_t.