Management

MCUmgr Management API. More...

Modules
	Enumeration Management
	MCUmgr Enumeration Management API.
	File System Management
	MCUmgr File System Management API.
	Image Management
	MCUmgr Image Management API.
	OS Management
	MCUmgr OS Management API.
	Settings Management
	MCUmgr Settings Management API.
	Shell Management
	MCUmgr Shell Management API.
	Statistics Management
	MCUmgr Statistics Management API.
	Zephyr Basic Management
	MCUmgr Zephyr Basic Management API.

Data Structures
struct	mgmt_handler
	Read handler and write handler for a single command ID. More...
struct	mgmt_group
	A collection of handlers for an entire command group. More...

Macros
#define	MGMT_CTXT_SET_RC_RSN(mc, rsn)
#define	MGMT_CTXT_RC_RSN(mc)   NULL
#define	MGMT_RETURN_CHECK(ok)   ok ? MGMT_ERR_EOK : MGMT_ERR_EMSGSIZE
	Used at end of MCUmgr handlers to return an error if the message size limit was reached, or OK if it was not.
#define	MGMT_HDR_SIZE   8

Typedefs
typedef void *(*	mgmt_alloc_rsp_fn) (const void *src_buf, void *arg)
	Allocates a buffer suitable for holding a response.
typedef void(*	mgmt_reset_buf_fn) (void *buf, void *arg)
	Resets a buffer to a length of 0.
typedef int(*	mgmt_handler_fn) (struct smp_streamer *ctxt)
	Processes a request and writes the corresponding response.
typedef bool(*	mgmt_groups_cb_t) (const struct mgmt_group *group, void *user_data)
	Group iteration callback.

Enumerations
enum	mcumgr_op_t { MGMT_OP_READ = 0 , MGMT_OP_READ_RSP , MGMT_OP_WRITE , MGMT_OP_WRITE_RSP }
	Opcodes; encoded in first byte of header. More...
enum	mcumgr_group_t {   MGMT_GROUP_ID_OS = 0 , MGMT_GROUP_ID_IMAGE , MGMT_GROUP_ID_STAT , MGMT_GROUP_ID_SETTINGS ,   MGMT_GROUP_ID_LOG , MGMT_GROUP_ID_CRASH , MGMT_GROUP_ID_SPLIT , MGMT_GROUP_ID_RUN ,   MGMT_GROUP_ID_FS , MGMT_GROUP_ID_SHELL , MGMT_GROUP_ID_ENUM , MGMT_GROUP_ID_PERUSER = 64 ,   ZEPHYR_MGMT_GRP_BASIC = (MGMT_GROUP_ID_PERUSER - 1) }
	MCUmgr groups. More...
enum	mcumgr_err_t {   MGMT_ERR_EOK = 0 , MGMT_ERR_EUNKNOWN , MGMT_ERR_ENOMEM , MGMT_ERR_EINVAL ,   MGMT_ERR_ETIMEOUT , MGMT_ERR_ENOENT , MGMT_ERR_EBADSTATE , MGMT_ERR_EMSGSIZE ,   MGMT_ERR_ENOTSUP , MGMT_ERR_ECORRUPT , MGMT_ERR_EBUSY , MGMT_ERR_EACCESSDENIED ,   MGMT_ERR_UNSUPPORTED_TOO_OLD , MGMT_ERR_UNSUPPORTED_TOO_NEW , MGMT_ERR_EPERUSER = 256 }
	MCUmgr error codes. More...

Functions
void	mgmt_register_group (struct mgmt_group *group)
	Registers a full command group.
void	mgmt_unregister_group (struct mgmt_group *group)
	Unregisters a full command group.
void	mgmt_groups_foreach (mgmt_groups_cb_t user_cb, void *user_data)
	Iterate over groups.
const struct mgmt_handler *	mgmt_find_handler (uint16_t group_id, uint16_t command_id)
	Finds a registered command handler.
const struct mgmt_group *	mgmt_find_group (uint16_t group_id)
	Finds a registered command group.
const struct mgmt_handler *	mgmt_get_handler (const struct mgmt_group *group, uint16_t command_id)
	Finds a registered command handler.

Detailed Description

MCUmgr Management API.

Since

1.11

Version

1.0.0

Macro Definition Documentation

MGMT_CTXT_RC_RSN

#define MGMT_CTXT_RC_RSN

(

mc

)

NULL

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

MGMT_CTXT_SET_RC_RSN

#define MGMT_CTXT_SET_RC_RSN	(		mc,
			rsn
	)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

MGMT_HDR_SIZE

#define MGMT_HDR_SIZE   8

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>

MGMT_RETURN_CHECK

#define MGMT_RETURN_CHECK

(

ok

)

ok ? MGMT_ERR_EOK : MGMT_ERR_EMSGSIZE

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>

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

Typedef Documentation

mgmt_alloc_rsp_fn

mgmt_alloc_rsp_fn

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Allocates a buffer suitable for holding a response.

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

Parameters

src_buf	An optional source buffer to copy user data from.
arg	Optional streamer argument.

Returns

Newly-allocated buffer on success NULL on failure.

mgmt_groups_cb_t

typedef bool(* mgmt_groups_cb_t) (const struct mgmt_group *group, void *user_data)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Group iteration callback.

Parameters

group	Group
user_data	User-supplied data

Returns

true to continue with the foreach callback, false to abort

mgmt_handler_fn

mgmt_handler_fn

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Processes a request and writes the corresponding response.

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

Parameters

ctxt	The mcumgr context to use.

Returns

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

mgmt_reset_buf_fn

mgmt_reset_buf_fn

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Resets a buffer to a length of 0.

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

Parameters

buf	The buffer to reset.
arg	Optional streamer argument.

Enumeration Type Documentation

mcumgr_err_t

enum mcumgr_err_t

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>

MCUmgr error codes.

Enumerator
MGMT_ERR_EOK	No error (success).
MGMT_ERR_EUNKNOWN	Unknown error.
MGMT_ERR_ENOMEM	Insufficient memory (likely not enough space for CBOR object).
MGMT_ERR_EINVAL	Error in input value.
MGMT_ERR_ETIMEOUT	Operation timed out.
MGMT_ERR_ENOENT	No such file/entry.
MGMT_ERR_EBADSTATE	Current state disallows command.
MGMT_ERR_EMSGSIZE	Response too large.
MGMT_ERR_ENOTSUP	Command not supported.
MGMT_ERR_ECORRUPT	Corrupt.
MGMT_ERR_EBUSY	Command blocked by processing of other command.
MGMT_ERR_EACCESSDENIED	Access to specific function, command or resource denied.
MGMT_ERR_UNSUPPORTED_TOO_OLD	Requested SMP MCUmgr protocol version is not supported (too old)
MGMT_ERR_UNSUPPORTED_TOO_NEW	Requested SMP MCUmgr protocol version is not supported (too new)
MGMT_ERR_EPERUSER	User errors defined from 256 onwards.

mcumgr_group_t

enum mcumgr_group_t

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>

MCUmgr groups.

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

Enumerator
MGMT_GROUP_ID_OS	OS (operating system) group.
MGMT_GROUP_ID_IMAGE	Image management group, used for uploading firmware images.
MGMT_GROUP_ID_STAT	Statistic management group, used for retrieving statistics.
MGMT_GROUP_ID_SETTINGS	Settings management (config) group, used for reading/writing settings.
MGMT_GROUP_ID_LOG	Log management group (unused)
MGMT_GROUP_ID_CRASH	Crash group (unused)
MGMT_GROUP_ID_SPLIT	Split image management group (unused)
MGMT_GROUP_ID_RUN	Run group (unused)
MGMT_GROUP_ID_FS	FS (file system) group, used for performing file IO operations.
MGMT_GROUP_ID_SHELL	Shell management group, used for executing shell commands.
MGMT_GROUP_ID_ENUM	Enumeration management group, used for listing supported command groups.
MGMT_GROUP_ID_PERUSER	User groups defined from 64 onwards.
ZEPHYR_MGMT_GRP_BASIC	Zephyr-specific groups decrease from PERUSER to avoid collision with upstream and user-defined groups. Zephyr-specific: Basic group

mcumgr_op_t

enum mcumgr_op_t

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>

Opcodes; encoded in first byte of header.

Enumerator
MGMT_OP_READ	Read op-code.
MGMT_OP_READ_RSP	Read response op-code.
MGMT_OP_WRITE	Write op-code.
MGMT_OP_WRITE_RSP	Write response op-code.

Function Documentation

mgmt_find_group()

const struct mgmt_group * mgmt_find_group

(

uint16_t

group_id

)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

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.

mgmt_find_handler()

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

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

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.

mgmt_get_handler()

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

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

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.

mgmt_groups_foreach()

void mgmt_groups_foreach	(	mgmt_groups_cb_t	user_cb,
		void *	user_data
	)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Iterate over groups.

Parameters

user_cb	User callback
user_data	User-supplied data

mgmt_register_group()

void mgmt_register_group

(

struct mgmt_group *

group

)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Registers a full command group.

Parameters

group

The group to register.

mgmt_unregister_group()

void mgmt_unregister_group

(

struct mgmt_group *

group

)

#include <include/zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Unregisters a full command group.

Parameters

group

The group to register.