Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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)
 
#define 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.
 
#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_handlermgmt_find_handler (uint16_t group_id, uint16_t command_id)
 Finds a registered command handler.
 
const struct mgmt_groupmgmt_find_group (uint16_t group_id)
 Finds a registered command group.
 
const struct mgmt_handlermgmt_get_handler (const struct mgmt_group *group, uint16_t command_id)
 Finds a registered command handler.
 

Detailed Description

MCUmgr mgmt API .

MCUmgr mgmt API .

Since
1.11
Version
1.0.0

Macro Definition Documentation

◆ MGMT_CTXT_RC_RSN

#define MGMT_CTXT_RC_RSN ( mc)

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

Value:
NULL

◆ MGMT_CTXT_SET_RC_RSN

#define MGMT_CTXT_SET_RC_RSN ( mc,
rsn )

◆ MGMT_HDR_SIZE

#define MGMT_HDR_SIZE   8

◆ MGMT_RETURN_CHECK

#define MGMT_RETURN_CHECK ( ok)

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

Value:
@ MGMT_ERR_EMSGSIZE
Response too large.
Definition mgmt_defines.h:119
@ MGMT_ERR_EOK
No error (success).
Definition mgmt_defines.h:98

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

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

#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_bufAn optional source buffer to copy user data from.
argOptional 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 <zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Group iteration callback.

Parameters
groupGroup
user_dataUser-supplied data
Returns
true to continue with the foreach callback, false to abort

◆ mgmt_handler_fn

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

#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
ctxtThe mcumgr context to use.
Returns
0 if a response was successfully encoded, mcumgr_err_t code on failure.

◆ mgmt_reset_buf_fn

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

#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
bufThe buffer to reset.
argOptional streamer argument.

Enumeration Type Documentation

◆ mcumgr_err_t

#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

#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

#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 <zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Finds a registered command group.

Parameters
group_idThe 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 <zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Finds a registered command handler.

Parameters
group_idThe group of the command to find.
command_idThe 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 <zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Finds a registered command handler.

Parameters
groupThe group of the command to find.
command_idThe 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 <zephyr/mgmt/mcumgr/mgmt/mgmt.h>

Iterate over groups.

Parameters
user_cbUser callback
user_dataUser-supplied data

◆ mgmt_register_group()

void mgmt_register_group ( struct mgmt_group * group)

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

Registers a full command group.

Parameters
groupThe group to register.

◆ mgmt_unregister_group()

void mgmt_unregister_group ( struct mgmt_group * group)

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

Unregisters a full command group.

Parameters
groupThe group to register.