MCUmgr Callbacks

Overview

MCUmgr has a customisable callback/notification system that allows application (and module) code to receive callbacks for MCUmgr events that they are interested in and react to them or return a status code to the calling function that provides control over if the action should be allowed or not. An example of this is with the fs_mgmt group, whereby file access can be gated, the callback allows the application to inspect the request path and allow or deny access to said file, or it can rewrite the provided path to a different path for transparent file redirection support.

Implementation

Enabling

The base callback/notification system can be enabled using CONFIG_MCUMGR_MGMT_NOTIFICATION_HOOKS which will compile the registration and notification system into the code. This will not provide any callbacks by default as the callbacks that are supported by a build must also be selected by enabling the Kconfig’s for the required callbacks (see Events for further details). A callback function with the mgmt_cb type definition can then be declared and registered by calling mgmt_callback_register() for the desired event inside of a :c:struct`mgmt_callback` structure. Handlers are called in the order that they were registered.

With the system enabled, a basic handler can be set up and defined in application code as per:

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

struct mgmt_callback my_callback;

enum mgmt_cb_return my_function(uint32_t event, enum mgmt_cb_return prev_status,
                                int32_t *rc, uint16_t *group, bool *abort_more,
                                void *data, size_t data_size)
{
    if (event == MGMT_EVT_OP_CMD_DONE) {
        /* This is the event we registered for */
    }

    /* Return OK status code to continue with acceptance to underlying handler */
    return MGMT_CB_OK;
}

int main()
{
    my_callback.callback = my_function;
    my_callback.event_id = MGMT_EVT_OP_CMD_DONE;
    mgmt_callback_register(&my_callback);
}

This code registers a handler for the MGMT_EVT_OP_CMD_DONE event, which will be called after a MCUmgr command has been processed and output generated, note that this requires that CONFIG_MCUMGR_SMP_COMMAND_STATUS_HOOKS be enabled to receive this callback.

Multiple callbacks can be setup to use a single function as a common callback, and many different functions can be used for each event by registering each group once, or all notifications for a whole group can be enabled by using one of the MGMT_EVT_OP_*_ALL events, alternatively a handler can setup for every notification by using MGMT_EVT_OP_ALL. When setting up handlers, events can be combined that are in the same group only, for example 5 img_mgmt callbacks can be setup with a single registration call, but to also setup a callback for an os_mgmt callback, this must be done as a separate registration. Group IDs are numerical increments, event IDs are bitmask values, hence the restriction.

As an example, the following registration is allowed, which will register for 3 SMP events with a single callback function in a single registration:

my_callback.callback = my_function;
my_callback.event_id = (MGMT_EVT_OP_CMD_RECV |
                        MGMT_EVT_OP_CMD_STATUS |
                        MGMT_EVT_OP_CMD_DONE);
mgmt_callback_register(&my_callback);

The following code is not allowed, and will cause undefined operation, because it mixes the IMG management group with the OS management group whereby the group is not a bitmask value, only the event is:

my_callback.callback = my_function;
my_callback.event_id = (MGMT_EVT_OP_IMG_MGMT_DFU_STARTED |
                        MGMT_EVT_OP_OS_MGMT_RESET);
mgmt_callback_register(&my_callback);

Events

Events can be selected by enabling their corresponding Kconfig option:

Actions

Some callbacks expect a return status to either allow or disallow an operation, an example is the fs_mgmt access hook which allows for access to files to be allowed or denied. With these handlers, the first non-OK error code returned by a handler will be returned to the MCUmgr client.

An example of selectively denying file access:

#include <zephyr/kernel.h>
#include <zephyr/mgmt/mcumgr/mgmt/mgmt.h>
#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>
#include <string.h>

struct mgmt_callback my_callback;

enum mgmt_cb_return my_function(uint32_t event, enum mgmt_cb_return prev_status,
                                int32_t *rc, uint16_t *group, bool *abort_more,
                                void *data, size_t data_size)
{
    /* Only run this handler if a previous handler has not failed */
    if (event == MGMT_EVT_OP_FS_MGMT_FILE_ACCESS && prev_status == MGMT_CB_OK) {
        struct fs_mgmt_file_access *fs_data = (struct fs_mgmt_file_access *)data;

        /* Check if this is an upload and deny access if it is, otherwise check the
         * the path and deny if is matches a name
         */
        if (fs_data->access == FS_MGMT_FILE_ACCESS_WRITE) {
            /* Return an access denied error code to the client and abort calling
             * further handlers
             */
            *abort_more = true;
            *rc = MGMT_ERR_EACCESSDENIED;

            return MGMT_CB_ERROR_RC;
        } else if (strcmp(fs_data->filename, "/lfs1/false_deny.txt") == 0) {
            /* Return a no entry error code to the client, call additional handlers
             * (which will have failed set to true)
             */
            *rc = MGMT_ERR_ENOENT;

            return MGMT_CB_ERROR_RC;
        }
    }

    /* Return OK status code to continue with acceptance to underlying handler */
    return MGMT_CB_OK;
}

int main()
{
    my_callback.callback = my_function;
    my_callback.event_id = MGMT_EVT_OP_FS_MGMT_FILE_ACCESS;
    mgmt_callback_register(&my_callback);
}

This code registers a handler for the MGMT_EVT_OP_FS_MGMT_FILE_ACCESS event, which will be called after a fs_mgmt file read/write command has been received to check if access to the file should be allowed or not, note that this requires that CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK be enabled to receive this callback. Two types of errors can be returned, the rc parameter can be set to an mcumgr_err_t error code and MGMT_CB_ERROR_RC can be returned, or a group error code (introduced with version 2 of the MCUmgr protocol) can be set by setting the group value to the group and rc value to the group error code and returning MGMT_CB_ERROR_ERR.

MCUmgr Command Callback Usage/Adding New Event Types

To add a callback to a MCUmgr command, mgmt_callback_notify() can be called with the event ID and, optionally, a data struct to pass to the callback (which can be modified by handlers). If no data needs to be passed back, NULL can be used instead, and size of the data set to 0.

An example MCUmgr command handler:

#include <zephyr/kernel.h>
#include <zcbor_common.h>
#include <zcbor_encode.h>
#include <zephyr/mgmt/mcumgr/smp/smp.h>
#include <zephyr/mgmt/mcumgr/mgmt/mgmt.h>
#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

#define MGMT_EVT_GRP_USER_ONE MGMT_EVT_GRP_USER_CUSTOM_START

enum user_one_group_events {
    /** Callback on first post, data is test_struct. */
    MGMT_EVT_OP_USER_ONE_FIRST  = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_USER_ONE, 0),

    /** Callback on second post, data is test_struct. */
    MGMT_EVT_OP_USER_ONE_SECOND = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_USER_ONE, 1),

    /** Used to enable all user_one events. */
    MGMT_EVT_OP_USER_ONE_ALL    = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_USER_ONE),
};

struct test_struct {
    uint8_t some_value;
};

static int test_command(struct mgmt_ctxt *ctxt)
{
    int rc;
    int err_rc;
    uint16_t err_group;
    zcbor_state_t *zse = ctxt->cnbe->zs;
    bool ok;
    struct test_struct test_data = {
        .some_value = 8,
    };

    rc = mgmt_callback_notify(MGMT_EVT_OP_USER_ONE_FIRST, &test_data,
                              sizeof(test_data), &err_rc, &err_group);

    if (rc != MGMT_CB_OK) {
        /* A handler returned a failure code */
        if (rc == MGMT_CB_ERROR_RC) {
            /* The failure code is the RC value */
            return err_rc;
        }

        /* The failure is a group and ID error value */
        ok = smp_add_cmd_err(zse, err_group, (uint16_t)err_rc);
        goto end;
    }

    /* All handlers returned success codes */
    ok = zcbor_tstr_put_lit(zse, "output_value") &&
         zcbor_int32_put(zse, 1234);

end:
    rc = (ok ? MGMT_ERR_EOK : MGMT_ERR_EMSGSIZE);

    return rc;
}

If no response is required for the callback, the function call be called and casted to void.

Migration

If there is existing code using the previous callback system(s) in Zephyr 3.2 or earlier, then it will need to be migrated to the new system. To migrate code, the following callback registration functions will need to be migrated to register for callbacks using mgmt_callback_register() (note that CONFIG_MCUMGR_MGMT_NOTIFICATION_HOOKS will need to be set to enable the new notification system in addition to any migrations):

API Reference

group mcumgr_callback_api

MCUmgr callback API.

Defines

MGMT_EVT_GET_GROUP(event)

Get group from event.

MGMT_EVT_GET_ID(event)

Get event ID from event.

MGMT_CB_ERROR_RET

Typedefs

typedef enum mgmt_cb_return (*mgmt_cb)(uint32_t event, enum mgmt_cb_return prev_status, int32_t *rc, uint16_t *group, bool *abort_more, void *data, size_t data_size)

Function to be called on MGMT notification/event.

This callback function is used to notify an application or system about a MCUmgr mgmt event.

Param event:

mcumgr_op_t.

Param prev_status:

mgmt_cb_return of the previous handler calls, if it is an error then it will be the first error that was returned by a handler (i.e. this handler is being called for a notification only, the return code will be ignored).

Param rc:

If prev_status is MGMT_CB_ERROR_RC then this is the SMP error that was returned by the first handler that failed. If prev_status is MGMT_CB_ERROR_ERR then this will be the group error rc code returned by the first handler that failed. If the handler wishes to raise an SMP error, this must be set to the mcumgr_err_t status and MGMT_CB_ERROR_RC must be returned by the function, if the handler wishes to raise a ret error, this must be set to the group ret status and MGMT_CB_ERROR_ERR must be returned by the function.

Param group:

If prev_status is MGMT_CB_ERROR_ERR then this is the group of the ret error that was returned by the first handler that failed. If the handler wishes to raise a ret error, this must be set to the group ret status and MGMT_CB_ERROR_ERR must be returned by the function.

Param abort_more:

Set to true to abort further processing by additional handlers.

Param data:

Optional event argument.

Param data_size:

Size of optional event argument (0 if no data is provided).

Return:

mgmt_cb_return indicating the status to return to the calling code (only checked when this is the first failure reported by a handler).

Enums

enum mgmt_cb_return

MGMT event callback return value.

Values:

enumerator MGMT_CB_OK

No error.

enumerator MGMT_CB_ERROR_RC

SMP protocol error and err_rc contains the mcumgr_err_t error code.

enumerator MGMT_CB_ERROR_ERR

Group (application-level) error and err_group contains the group ID that caused the error and err_rc contians the error code of that group to return.

enum mgmt_cb_groups

MGMT event callback group IDs.

Note that this is not a 1:1 mapping with mcumgr_group_t values.

Values:

enumerator MGMT_EVT_GRP_ALL = 0
enumerator MGMT_EVT_GRP_SMP
enumerator MGMT_EVT_GRP_OS
enumerator MGMT_EVT_GRP_IMG
enumerator MGMT_EVT_GRP_FS
enumerator MGMT_EVT_GRP_SETTINGS
enumerator MGMT_EVT_GRP_USER_CUSTOM_START = MGMT_GROUP_ID_PERUSER
enum smp_all_events

MGMT event opcodes for all command processing.

Values:

enumerator MGMT_EVT_OP_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_ALL)

Used to enable all events.

enum smp_group_events

MGMT event opcodes for base SMP command processing.

Values:

enumerator MGMT_EVT_OP_CMD_RECV = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 0)

Callback when a command is received, data is mgmt_evt_op_cmd_arg().

enumerator MGMT_EVT_OP_CMD_STATUS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 1)

Callback when a a status is updated, data is mgmt_evt_op_cmd_arg().

enumerator MGMT_EVT_OP_CMD_DONE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 2)

Callback when a command has been processed, data is mgmt_evt_op_cmd_arg().

enumerator MGMT_EVT_OP_CMD_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_SMP)

Used to enable all smp_group events.

enum fs_mgmt_group_events

MGMT event opcodes for filesystem management group.

Values:

enumerator MGMT_EVT_OP_FS_MGMT_FILE_ACCESS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_FS, 0)

Callback when a file has been accessed, data is fs_mgmt_file_access().

enumerator MGMT_EVT_OP_FS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_FS)

Used to enable all fs_mgmt_group events.

enum img_mgmt_group_events

MGMT event opcodes for image management group.

Values:

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 0)

Callback when a client sends a file upload chunk, data is img_mgmt_upload_check().

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_STOPPED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 1)

Callback when a DFU operation is stopped.

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_STARTED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 2)

Callback when a DFU operation is started.

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_PENDING = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 3)

Callback when a DFU operation has finished being transferred.

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_CONFIRMED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 4)

Callback when an image has been confirmed.

enumerator MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK_WRITE_COMPLETE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 5)

Callback when an image write command has finished writing to flash.

enumerator MGMT_EVT_OP_IMG_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_IMG)

Used to enable all img_mgmt_group events.

enum os_mgmt_group_events

MGMT event opcodes for operating system management group.

Values:

enumerator MGMT_EVT_OP_OS_MGMT_RESET = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 0)

Callback when a reset command has been received, data is os_mgmt_reset_data.

enumerator MGMT_EVT_OP_OS_MGMT_INFO_CHECK = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 1)

Callback when an info command is processed, data is os_mgmt_info_check.

enumerator MGMT_EVT_OP_OS_MGMT_INFO_APPEND = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 2)

Callback when an info command needs to output data, data is os_mgmt_info_append.

enumerator MGMT_EVT_OP_OS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_OS)

Used to enable all os_mgmt_group events.

enum settings_mgmt_group_events

MGMT event opcodes for settings management group.

Values:

enumerator MGMT_EVT_OP_SETTINGS_MGMT_ACCESS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SETTINGS, 0)

Callback when a setting is read/written/deleted.

enumerator MGMT_EVT_OP_SETTINGS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_SETTINGS)

Used to enable all settings_mgmt_group events.

Functions

uint8_t mgmt_evt_get_index(uint32_t event)

Get event ID index from event.

Parameters:

  • event – Event to get ID index from.

Returns:

Event index.

enum mgmt_cb_return mgmt_callback_notify(uint32_t event, void *data, size_t data_size, int32_t *err_rc, uint16_t *err_group)

This function is called to notify registered callbacks about mcumgr notifications/events.

Parameters:

  • event – mcumgr_op_t.

  • data – Optional event argument.

  • data_size – Size of optional event argument (0 if none).

  • err_rc – Pointer to rc value.

  • err_group – Pointer to group value.

Returns:

mgmt_cb_return either MGMT_CB_OK if all handlers returned it, or MGMT_CB_ERROR_RC if the first failed handler returned an SMP error (in which case err_rc will be updated with the SMP error) or MGMT_CB_ERROR_ERR if the first failed handler returned a ret group and error (in which case err_group will be updated with the failed group ID and err_rc will be updated with the group-specific error code).

void mgmt_callback_register(struct mgmt_callback *callback)

Register event callback function.

Parameters:

  • callback – Callback struct.

void mgmt_callback_unregister(struct mgmt_callback *callback)

Unregister event callback function.

Parameters:

  • callback – Callback struct.

struct mgmt_callback
#include <callbacks.h>

MGMT callback struct.

Public Members

sys_snode_t node

Entry list node.

mgmt_cb callback

Callback that will be called.

uint32_t event_id

MGMT_EVT_[…] Event ID for handler to be called on.

This has special meaning if MGMT_EVT_OP_ALL is used (which will cover all events for all groups), or MGMT_EVT_OP_*_MGMT_ALL (which will cover all events for a single group). For events that are part of a single group, they can be or’d together for this to have one registration trigger on multiple events, please note that this will only work for a single group, to register for events in different groups, they must be registered separately.

struct mgmt_evt_op_cmd_arg
#include <callbacks.h>

Arguments for MGMT_EVT_OP_CMD_RECV, MGMT_EVT_OP_CMD_STATUS and MGMT_EVT_OP_CMD_DONE.

Public Members

uint16_t group

mcumgr_group_t

uint8_t id

Message ID within group.

int err

mcumgr_err_t, used in MGMT_EVT_OP_CMD_DONE

int status

img_mgmt_id_upload_t, used in MGMT_EVT_OP_CMD_STATUS

MCUmgr fs_mgmt callback API.

Enums

enum fs_mgmt_file_access_types

The type of operation that is being requested for a given file access callback.

Values:

enumerator FS_MGMT_FILE_ACCESS_READ

Access to read file (file upload).

enumerator FS_MGMT_FILE_ACCESS_WRITE

Access to write file (file download).

enumerator FS_MGMT_FILE_ACCESS_STATUS

Access to get status of file.

enumerator FS_MGMT_FILE_ACCESS_HASH_CHECKSUM

Access to calculate hash or checksum of file.

struct fs_mgmt_file_access
#include <fs_mgmt_callbacks.h>

Structure provided in the MGMT_EVT_OP_FS_MGMT_FILE_ACCESS notification callback: This callback function is used to notify the application about a pending file read/write request and to authorise or deny it.

Access will be allowed so long as all notification handlers return MGMT_ERR_EOK, if one returns an error then access will be denied.

Public Members

enum fs_mgmt_file_access_types access

Specifies the type of the operation that is being requested.

char *filename

Path and filename of file be accesses, note that this can be changed by handlers to redirect file access if needed (as long as it does not exceed the maximum path string size).

MCUmgr img_mgmt callback API.

struct img_mgmt_upload_check
#include <img_mgmt_callbacks.h>

Structure provided in the MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK notification callback: This callback function is used to notify the application about a pending firmware upload packet from a client and authorise or deny it.

Upload will be allowed so long as all notification handlers return MGMT_ERR_EOK, if one returns an error then the upload will be denied.

Public Members

struct img_mgmt_upload_action *action

Action to take.

struct img_mgmt_upload_req *req

Upload request information.

MCUmgr os_mgmt callback API.

struct os_mgmt_reset_data
#include <os_mgmt_callbacks.h>

Structure provided in the MGMT_EVT_OP_OS_MGMT_RESET notification callback: This callback function is used to notify the application about a pending device reboot request and to authorise or deny it.

Public Members

bool force

Contains the value of the force parameter.

MCUmgr settings_mgmt callback API.

Enums

enum settings_mgmt_access_types

Values:

enumerator SETTINGS_ACCESS_READ
enumerator SETTINGS_ACCESS_WRITE
enumerator SETTINGS_ACCESS_DELETE
enumerator SETTINGS_ACCESS_COMMIT
enumerator SETTINGS_ACCESS_LOAD
enumerator SETTINGS_ACCESS_SAVE
struct settings_mgmt_access
#include <settings_mgmt_callbacks.h>

Structure provided in the MGMT_EVT_OP_SETTINGS_MGMT_ACCESS notification callback: This callback function is used to notify the application about a pending setting read/write/delete/load/save/commit request and to authorise or deny it.

Access will be allowed so long as no handlers return an error, if one returns an error then access will be denied.

Public Members

enum settings_mgmt_access_types access

Type of access.

char *name

Key name for accesses (only set for SETTINGS_ACCESS_READ, SETTINGS_ACCESS_WRITE and SETTINGS_ACCESS_DELETE).

Note that this can be changed by handlers to redirect settings access if needed (as long as it does not exceed the maximum setting string size) if CONFIG_MCUMGR_GRP_SETTINGS_BUFFER_TYPE_STACK is selected, of maximum size CONFIG_MCUMGR_GRP_SETTINGS_NAME_LEN.

Note: This string must be NULL terminated.

const uint8_t *val

Data provided by the user (only set for SETTINGS_ACCESS_WRITE)

const size_t *val_length

Length of data provided by the user (only set for SETTINGS_ACCESS_WRITE)