Struct MCUmgrClient 

pub struct MCUmgrClient { /* private fields */ }

A high-level client for Zephyr’s MCUmgr SMP protocol.

This struct is the central entry point of this crate.

Implementations

impl MCUmgrClient

pub fn new_from_serial<T: Send + Read + Write + ConfigurableTimeout + 'static>( serial: T, ) -> Self

Creates a Zephyr MCUmgr SMP client based on a configured and opened serial port.

let serial = serialport::new("COM42", 115200)
    .timeout(std::time::Duration::from_millis(10000))
    .open()
    .unwrap();

let mut client = MCUmgrClient::new_from_serial(serial);

pub fn new_from_usb_serial( identifier: impl AsRef<str>, baud_rate: u32, timeout: Duration, ) -> Result<Self, UsbSerialError>

Creates a Zephyr MCUmgr SMP client based on a USB serial port identified by VID:PID.

Useful for programming many devices in rapid succession, as Windows usually gives each one a different COMxx identifier.

Arguments

• identifier - A regex that identifies the device.
• baud_rate - The baud rate the port should operate at.
• timeout - The communication timeout.

Identifier examples

• 1234:89AB - Vendor ID 1234, Product ID 89AB. Will fail if product has multiple serial ports.
• 1234:89AB:12 - Vendor ID 1234, Product ID 89AB, Interface 12.
• 1234:.*:[2-3] - Vendor ID 1234, any Product Id, Interface 2 or 3.

pub fn set_frame_size(&self, smp_frame_size: usize)

Configures the maximum SMP frame size that we can send to the device.

Must not exceed MCUMGR_TRANSPORT_NETBUF_SIZE, otherwise we might crash the device.

pub fn use_auto_frame_size(&self) -> Result<(), ExecuteError>

Configures the maximum SMP frame size that we can send to the device automatically by reading the value of MCUMGR_TRANSPORT_NETBUF_SIZE from the device.

pub fn set_timeout(&self, timeout: Duration) -> Result<(), Report>

Changes the communication timeout.

When the device does not respond to packets within the set duration, an error will be raised.

pub fn check_connection(&self) -> Result<(), ExecuteError>

Checks if the device is alive and responding.

Runs a simple echo with random data and checks if the response matches.

Return

An error if the device is not alive and responding.

pub fn firmware_update( &self, firmware: impl AsRef<[u8]>, checksum: Option<[u8; 32]>, params: FirmwareUpdateParams, progress: Option<&mut FirmwareUpdateProgressCallback<'_>>, ) -> Result<(), FirmwareUpdateError>

High-level firmware update routine.

Arguments

• firmware - The firmware image data.
• checksum - SHA256 of the firmware image. Optional.
• params - Configurable parameters.
• progress - A callback that receives progress updates.

pub fn os_echo(&self, msg: impl AsRef<str>) -> Result<String, ExecuteError>

Sends a message to the device and expects the same message back as response.

This can be used as a sanity check for whether the device is connected and responsive.

pub fn os_task_statistics( &self, ) -> Result<HashMap<String, TaskStatisticsEntry>, ExecuteError>

Queries live task statistics

Note

Converts stkuse and stksiz to bytes. Zephyr originally reports them as number of 4 byte words.

Return

A map of task names with their respective statistics

pub fn os_set_datetime( &self, datetime: NaiveDateTime, ) -> Result<(), ExecuteError>

Sets the RTC of the device to the given datetime.

pub fn os_get_datetime(&self) -> Result<NaiveDateTime, ExecuteError>

Retrieves the device RTC’s datetime.

pub fn os_system_reset( &self, force: bool, boot_mode: Option<u8>, ) -> Result<(), ExecuteError>

Issues a system reset.

Arguments

• force - Issues a force reset.
• boot_mode - Overwrites the boot mode.

Known boot_mode values:

• 0 - Normal system boot
• 1 - Bootloader recovery mode

Note that boot_mode only works if MCUMGR_GRP_OS_RESET_BOOT_MODE is enabled.

pub fn os_mcumgr_parameters( &self, ) -> Result<MCUmgrParametersResponse, ExecuteError>

Fetch parameters from the MCUmgr library

pub fn os_application_info( &self, format: Option<&str>, ) -> Result<String, ExecuteError>

Fetch information on the running image

Similar to Linux’s uname command.

Arguments

• format - Format specifier for the returned response

For more information about the format specifier fields, see the SMP documentation.

pub fn os_bootloader_info(&self) -> Result<BootloaderInfo, ExecuteError>

Fetch information on the device’s bootloader

pub fn image_get_state(&self) -> Result<Vec<ImageState>, ExecuteError>

Obtain a list of images with their current state.

pub fn image_set_state( &self, hash: Option<[u8; 32]>, confirm: bool, ) -> Result<Vec<ImageState>, ExecuteError>

Modify the current image state

Arguments

• hash - the SHA256 id of the image.
• confirm - mark the given image as ‘confirmed’

If confirm is false, perform a test boot with the given image and revert upon hard reset.

If confirm is true, boot to the given image and mark it as confirmed. If hash is omitted, confirm the currently running image.

Note that hash will not be the same as the SHA256 of the whole firmware image, it is the field in the MCUboot TLV section that contains a hash of the data which is used for signature verification purposes.

pub fn image_upload( &self, data: impl AsRef<[u8]>, image: Option<u32>, checksum: Option<[u8; 32]>, upgrade_only: bool, progress: Option<&mut dyn FnMut(u64, u64) -> bool>, ) -> Result<(), ImageUploadError>

Upload a firmware image to an image slot.

Arguments

• data - The firmware image data
• image - Selects target image on the device. Defaults to 0.
• checksum - The SHA256 checksum of the image. If missing, will be computed from the image data.
• upgrade_only - If true, allow firmware upgrades only and reject downgrades.
• progress - A callback that receives a pair of (transferred, total) bytes and returns false on error.

pub fn image_erase(&self, slot: Option<u32>) -> Result<(), ExecuteError>

Erase image slot on target device.

Arguments

• slot - The slot ID of the image to erase. Slot 1 if omitted.

pub fn image_slot_info(&self) -> Result<Vec<SlotInfoImage>, ExecuteError>

Obtain a list of available image slots.

pub fn fs_file_download<T: Write>( &self, name: impl AsRef<str>, writer: T, progress: Option<&mut dyn FnMut(u64, u64) -> bool>, ) -> Result<(), FileDownloadError>

Load a file from the device.

Arguments

• name - The full path of the file on the device.
• writer - A Write object that the file content will be written to.
• progress - A callback that receives a pair of (transferred, total) bytes.

Performance

Downloading files with Zephyr’s default parameters is slow. You want to increase MCUMGR_TRANSPORT_NETBUF_SIZE to maybe 4096 or larger.

pub fn fs_file_upload<T: Read>( &self, name: impl AsRef<str>, reader: T, size: u64, progress: Option<&mut dyn FnMut(u64, u64) -> bool>, ) -> Result<(), FileUploadError>

Write a file to the device.

Arguments

• name - The full path of the file on the device.
• reader - A Read object that contains the file content.
• size - The file size.
• progress - A callback that receives a pair of (transferred, total) bytes and returns false on error.

Performance

Uploading files with Zephyr’s default parameters is slow. You want to increase MCUMGR_TRANSPORT_NETBUF_SIZE to maybe 4096 and then enable larger chunking through either MCUmgrClient::set_frame_size or MCUmgrClient::use_auto_frame_size.

pub fn fs_file_status( &self, name: impl AsRef<str>, ) -> Result<FileStatusResponse, ExecuteError>

Queries the file status

pub fn fs_file_checksum( &self, name: impl AsRef<str>, algorithm: Option<impl AsRef<str>>, offset: u64, length: Option<u64>, ) -> Result<FileChecksumResponse, ExecuteError>

Computes the hash/checksum of a file

For available algorithms, see fs_supported_checksum_types().

Arguments

• name - The absolute path of the file on the device
• algorithm - The hash/checksum algorithm to use, or default if None
• offset - How many bytes of the file to skip
• length - How many bytes to read after offset. None for the entire file.

pub fn fs_supported_checksum_types( &self, ) -> Result<HashMap<String, FileChecksumProperties>, ExecuteError>

Queries which hash/checksum algorithms are available on the target

pub fn fs_file_close(&self) -> Result<(), ExecuteError>

Close all device files MCUmgr has currently open

pub fn shell_execute( &self, argv: &[String], ) -> Result<(i32, String), ExecuteError>

Run a shell command.

Arguments

• argv - The shell command to be executed.

Return

A tuple of (returncode, stdout) produced by the command execution.

pub fn zephyr_erase_storage(&self) -> Result<(), ExecuteError>

Erase the storage_partition flash partition.

pub fn raw_command<T: McuMgrCommand>( &self, command: &T, ) -> Result<T::Response, ExecuteError>

Execute a raw commands::McuMgrCommand.

Only returns if no error happened, so the user does not need to check for an rc or err field in the response.