MCUmgr mgmt API

MCUmgr mgmt API. More...

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 mgmt 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.