services/device_mgmt/smp_groups/smp_group_0.html · services/device_mgmt/smp_groups/smp_group_0.rst 공식 원문 ↗

Zephyr 3.7.0 · SMP Groups

SMP Group 0 · OS Management

Group ID 0 하나로 system 진단, 시간 설정, reset 정책, runtime 정보와 MCUboot mode를 원격 관리합니다.

Official pathservices/device_mgmt/smp_groups/smp_group_0.html
Source fileservices/device_mgmt/smp_groups/smp_group_0.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

아홉 command ID의 지원 상태와 request OP, task/stack 단위, date-time format, reset hook, uname형 format specifier와 MCUboot downgrade policy를 설명합니다.

Group ID

0

Commands

9 IDs

Scope

Diagnostics · reset · bootloader

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 D554DC00E953B374C153CB9706E371486C5C6012C0FFC7B018BA734E052245AD
.. _mcumgr_smp_group_0:

Default/OS Management Group
###########################

OS management group defines following commands:

.. table::
    :align: center

    +-------------------+-----------------------------------------------+
    | ``Command ID``    | Command description                           |
    +===================+===============================================+
    | ``0``             | Echo                                          |
    +-------------------+-----------------------------------------------+
    | ``1``             | Console/Terminal echo control;                |
    |                   | unimplemented by Zephyr                       |
    +-------------------+-----------------------------------------------+
    | ``2``             | Task Statistics                               |
    +-------------------+-----------------------------------------------+
    | ``3``             | Memory pool statistics                        |
    +-------------------+-----------------------------------------------+
    | ``4``             | Date-time string                              |
    +-------------------+-----------------------------------------------+
    | ``5``             | System reset                                  |
    +-------------------+-----------------------------------------------+
    | ``6``             | MCUMGR parameters                             |
    +-------------------+-----------------------------------------------+
    | ``7``             | OS/Application info                           |
    +-------------------+-----------------------------------------------+
    | ``8``             | Bootloader information                        |
    +-------------------+-----------------------------------------------+

Echo command
************

Echo command responses by sending back string that it has received.

Echo request
============

Echo request header fields:

.. table::
    :align: center

    +--------------------+--------------+----------------+
    | ``OP``             | ``Group ID`` | ``Command ID`` |
    +====================+==============+================+
    | ``0`` or ``2``     | ``0``        |  ``0``         |
    +--------------------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str)"d" : (str)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "d"                   | string to be replied by echo service.             |
    +-----------------------+---------------------------------------------------+

Echo response
=============

Echo response header fields:

.. table::
    :align: center

    +--------+--------------+----------------+----------------------------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` | Note                             |
    +========+==============+================+==================================+
    | ``1``  | ``0``        |  ``0``         | When request ``OP`` was ``0``    |
    +--------+--------------+----------------+----------------------------------+
    | ``3``  | ``0``        |  ``0``         | When request ``OP`` was ``2``    |
    +--------+--------------+----------------+----------------------------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"r"        : (str)
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "r"              | replying echo string.                                                   |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

Task statistics command
***********************

The command responds with some system statistics.

Task statistics request
=======================

Task statistics request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``2``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data.


Task statistics response
========================

Task statistics response header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``2``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"tasks" : {
            (str)<task_name> : {
                (str)"prio"         : (uint)
                (str)"tid"          : (uint)
                (str)"state"        : (uint)
                (str)"stkuse"       : (uint)
                (str)"stksiz"       : (uint)
                (str)"cswcnt"       : (uint)
                (str)"runtime"      : (uint)
                (str)"last_checkin" : (uint)
                (str)"next_checkin" : (uint)
            }
            ...
        }
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | <task_name>      | string identifying task.                                                |
    +------------------+-------------------------------------------------------------------------+
    | "prio"           | task priority.                                                          |
    +------------------+-------------------------------------------------------------------------+
    | "tid"            | numeric task ID.                                                        |
    +------------------+-------------------------------------------------------------------------+
    | "state"          | numeric task state.                                                     |
    +------------------+-------------------------------------------------------------------------+
    | "stkuse"         | task's/thread's stack usage.                                            |
    +------------------+-------------------------------------------------------------------------+
    | "stksiz"         | task's/thread's stack size.                                             |
    +------------------+-------------------------------------------------------------------------+
    | "cswcnt"         | task's/thread's context switches.                                       |
    +------------------+-------------------------------------------------------------------------+
    | "runtime"        | task's/thread's runtime in "ticks".                                     |
    +------------------+-------------------------------------------------------------------------+
    | "last_checkin"   | set to 0 by Zephyr.                                                     |
    +------------------+-------------------------------------------------------------------------+
    | "next_checkin"   | set to 0 by Zephyr.                                                     |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

.. note::
    The unit for "stkuse" and "stksiz" is system dependent and in case of Zephyr
    this is number of 4 byte words.

Memory pool statistics
**********************

The command is used to obtain information on memory pools active in running
system.

Memory pool statistic request
=============================

Memory pool statistics request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``3``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data.

Memory pool statistics response
===============================

Memory pool statistics response header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``3``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)<pool_name> {
            (str)"blksiz"   : (int)
            (str)"nblks"    : (int)
            (str)"nfree"    : (int)
            (str)"min'      : (int)
        }
        ...
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | <pool_name>      | string representing the pool name, used as a key for dictionary with    |
    |                  | pool statistics data.                                                   |
    +------------------+-------------------------------------------------------------------------+
    | "blksiz"         | size of the memory block in the pool.                                   |
    +------------------+-------------------------------------------------------------------------+
    | "nblks"          | number of blocks in the pool.                                           |
    +------------------+-------------------------------------------------------------------------+
    | "nfree"          | number of free blocks.                                                  |
    +------------------+-------------------------------------------------------------------------+
    | "min"            | lowest number of free blocks the pool reached during run-time.          |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

Date-time command
*****************

The command allows to obtain string representing current time-date on a device
or set a new time to a device.
The time format used, by both set and get operations, is:

    "yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ"

Date-time get
=============

The command allows to obtain date-time from a device.

Date-time get request
---------------------

Date-time request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``4``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data.

Date-time get response
----------------------

Date-time get response header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``4``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"datetime" : (str)
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "datetime"       | String in format: ``yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ``.                |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+


Date-time set
=============

The command allows to set date-time to a device.

Date-time set request
---------------------

Date-time set request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``2``  | ``0``        |  ``4``         |
    +--------+--------------+----------------+

CBOR data of response:

.. code-block:: none

    {
        (str)"datetime" : (str)
    }

where:

.. table::
    :align: center

    +---------------+----------------------------------------------------------+
    | "datetime"    | String in format: ``yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ``. |
    +---------------+----------------------------------------------------------+

Date-time set response
----------------------

Date-time set response header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``3``  | ``0``        |  ``4``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data if successful. In case of error the
CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

System reset
************

Performs reset of system. The device should issue response before resetting so
that the SMP client could receive information that the command has been
accepted. By default, this command is accepted in all conditions, however if
the :kconfig:option:`CONFIG_MCUMGR_GRP_OS_RESET_HOOK` is enabled and an
application registers a callback, the callback will be called when this command
is issued and can be used to perform any necessary tidy operations prior to the
module rebooting, or to reject the reset request outright altogether with an
error response. For details on this functionality, see `ref:`mcumgr_callbacks`.

System reset request
====================

System reset request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``2``  | ``0``        |  ``5``         |
    +--------+--------------+----------------+

Normally the command sends an empty CBOR map as data, but if a previous reset
attempt has responded with "rc" equal to :c:enumerator:`MGMT_ERR_EBUSY` then the
following map may be sent to force a reset:

.. code-block:: none

    {
        (opt)"force"       : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "force"               | Force reset if value > 0, optional if 0.          |
    +-----------------------+---------------------------------------------------+


System reset response
=====================

System reset response header fields

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``3``  | ``0``        |  ``5``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data if successful. In case of error the
CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

MCUmgr Parameters
*****************

Used to obtain parameters of mcumgr library.

MCUmgr Parameters Request
=========================

MCUmgr parameters request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``6``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data.

MCUmgr Parameters Response
==========================

MCUmgr parameters response header fields

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``6``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"buf_size"     : (uint)
        (str)"buf_count"    : (uint)
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "buf_size"       | Single SMP buffer size, this includes SMP header and CBOR payload.      |
    +------------------+-------------------------------------------------------------------------+
    | "buf_count"      | Number of SMP buffers supported.                                        |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

.. _mcumgr_os_application_info:

OS/Application Info
*******************

Used to obtain information on running image, similar functionality to the linux
uname command, allowing details such as kernel name, kernel version, build
date/time, processor type and application-defined details to be returned. This
functionality can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_OS_INFO`.

OS/Application Info Request
===========================

OS/Application info request header fields:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``7``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str,opt)"format"      : (str)
    }

where:

.. table::
    :align: center

    +----------+-------------------------------------------------------------------+
    | "format" | Format specifier of returned response, fields are appended in     |
    |          | their natural ascending index order, not the order of             |
    |          | characters that are received by the command. Format               |
    |          | specifiers: |br|                                                  |
    |          | * ``s`` Kernel name |br|                                          |
    |          | * ``n`` Node name |br|                                            |
    |          | * ``r`` Kernel release |br|                                       |
    |          | * ``v`` Kernel version |br|                                       |
    |          | * ``b`` Build date and time (requires                             |
    |          | :kconfig:option:`CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME`) |br| |
    |          | * ``m`` Machine |br|                                              |
    |          | * ``p`` Processor |br|                                            |
    |          | * ``i`` Hardware platform |br|                                    |
    |          | * ``o`` Operating system |br|                                     |
    |          | * ``a`` All fields (shorthand for all above options) |br|         |
    |          | If this option is not provided, the ``s`` Kernel name option      |
    |          | will be used.                                                     |
    +----------+-------------------------------------------------------------------+

OS/Application Info Response
============================

OS/Application info response header fields

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``7``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"output"       : (str)
    }

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "output"         | Text response including requested parameters.                           |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

Bootloader Information
**********************

Allows retrieving information about the on-board bootloader and its parameters.

Bootloader Information Request
==============================

Bootloader information request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``0``        |  ``8``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str,opt)"query"  : (str)
    }

where:

.. table::
    :align: center

    +--------------+-----------------------------------------------+
    | "query"      | Is string representing query for parameters,  |
    |              | with no restrictions how the query looks like |
    |              | as processing of query is left for bootloader |
    |              | backend.                                      |
    |              | If there is no query, then response will      |
    |              | return string identifying the bootloader.     |
    +--------------+-----------------------------------------------+

Bootloader Information Response
===============================

Bootloader information response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``0``        |  ``8``         |
    +--------+--------------+----------------+

In case when no "query" has been provided in request,
CBOR data of response:

.. code-block:: none

    {
        (str)"bootloader"      : (str)
    }

where:

.. table::
    :align: center

    +--------------+-----------------------------------------------+
    | "bootloader" | String representing bootloader name           |
    +--------------+-----------------------------------------------+

In case when "query" is provided:

.. code-block:: none

    {
        (str,opt)<response>   : ()
	...
    }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | <response>       | Response to "query". This is optional and may be left out in case when  |
    |                  | query yields no response, SMP version 2 error code of                   |
    |                  | `OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER` is expected.                       |
    |                  | Response may have more than one parameter reported back or it may be    |
    |                  | a map, that is dependent on bootloader backednd and query.              |
    +------------------+-------------------------------------------------------------------------+
    | ...              | Parameter characteristic information.                                   |
    +------------------+-------------------------------------------------------------------------+

Parameter may be accompanied by additional, parameter specific, information keywords with
assigned values.

In case of error the CBOR data takes the form:

.. tabs::

   .. group-tab:: SMP version 2

      .. code-block:: none

          {
              (str)"err" : {
                  (str)"group"    : (uint)
                  (str)"rc"       : (uint)
              }
          }

   .. group-tab:: SMP version 1 (and non-group SMP version 2)

      .. code-block:: none

          {
              (str)"rc"       : (int)
          }

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
    |                  | appears if an error is returned when using SMP version 2.               |
    +------------------+-------------------------------------------------------------------------+
    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
    |                  | non-zero (error condition) when using SMP version 2.                    |
    +------------------+-------------------------------------------------------------------------+
    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
    +------------------+-------------------------------------------------------------------------+

Bootloader Information: MCUboot
===============================

In case when MCUboot is application bootloader, empty request will
be responded with:

.. code-block:: none

    {
        (str)"bootloader"      : (str)"MCUboot"
    }

Currently "MCUboot" supports querying for mode of operation:

.. code-block:: none

    {
        (str)"query"           : (str)"mode"
    }

Response to "mode" is:

.. code-block:: none

    {
        (str)"mode"                     : (int)
        (str,opt)"no-downgrade"         : (bool)
    }

where "mode" is one of:

.. table::
    :align: center

    +-----+-----------------------------------------------------+
    | -1  | Unknown mode of MCUboot.                            |
    +-----+-----------------------------------------------------+
    |  0  | MCUboot is in single application mode.              |
    +-----+-----------------------------------------------------+
    |  1  | MCUboot is in swap using scratch partition mode.    |
    +-----+-----------------------------------------------------+
    |  2  | MCUboot is in overwrite (upgrade-only) mode.        |
    +-----+-----------------------------------------------------+
    |  3  | MCUboot is in swap without scratch mode.            |
    +-----+-----------------------------------------------------+
    |  4  | MCUboot is in DirectXIP without revert mode.        |
    +-----+-----------------------------------------------------+
    |  5  | MCUboot is in DirectXIP with revert mode.           |
    +-----+-----------------------------------------------------+
    |  6  | MCUboot is in RAM loader mode.                      |
    +-----+-----------------------------------------------------+

The ``no-downgrade`` field is a flag, which is always sent when true, indicating that MCUboot has
downgrade prevention enabled; downgrade prevention means that if the uploaded image has a lower
version than the currently running application, it will not be used for an update by MCUboot.

MCUmgr may reject images with a lower version in this configuration.

Part 3

한국어 전문 번역

OS management group은 다음 command를 정의합니다.

OS management command
Command IDCommand description
0Echo
1Console/Terminal echo control (Zephyr에서는 구현되지 않음)
2Task statistics
3Memory pool statistics
4Date-time string
5System reset
6MCUmgr parameter
7OS/Application info
8Bootloader information

Echo command

Echo command는 받은 string을 그대로 되돌려 response합니다.

Echo request

Echo request header field는 다음과 같습니다.

Echo request header
OPGroup IDCommand ID
0 또는 200

Request의 CBOR data는 다음과 같습니다.

{
    (str)"d" : (str)
}

Request field의 의미는 다음과 같습니다.

Echo request field
dEcho service가 되돌려줄 string입니다.

Echo response

Echo response header는 request OP에 따라 다음과 같습니다.

Echo response header
OPGroup IDCommand IDNote
100Request OP가 0일 때
300Request OP가 2일 때

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)"r"        : (str)
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

Echo response field
r되돌려주는 echo string입니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Task statistics command

이 command는 일부 system statistics를 response합니다.

Task statistics request

Task statistics request header field는 다음과 같습니다.

Task statistics request header
OPGroup IDCommand ID
002

이 command는 data로 빈 CBOR map을 보냅니다.

Task statistics response

Task statistics response header field는 다음과 같습니다.

Task statistics response header
OPGroup IDCommand ID
102

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)"tasks" : {
        (str)<task_name> : {
            (str)"prio"         : (uint)
            (str)"tid"          : (uint)
            (str)"state"        : (uint)
            (str)"stkuse"       : (uint)
            (str)"stksiz"       : (uint)
            (str)"cswcnt"       : (uint)
            (str)"runtime"      : (uint)
            (str)"last_checkin" : (uint)
            (str)"next_checkin" : (uint)
        }
        ...
    }
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

Task statistics response field
<task_name>Task를 식별하는 string입니다.
prioTask priority입니다.
tid숫자 task ID입니다.
state숫자 task state입니다.
stkuseTask/thread의 stack usage입니다.
stksizTask/thread의 stack size입니다.
cswcntTask/thread의 context switch 횟수입니다.
runtimeTick 단위 task/thread runtime입니다.
last_checkinZephyr에서는 0으로 설정됩니다.
next_checkinZephyr에서는 0으로 설정됩니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Memory pool statistics

이 command는 실행 중인 system에서 활성화된 memory pool 정보를 가져옵니다.

Memory pool statistics request

Memory pool statistics request header field는 다음과 같습니다.

Memory pool statistics request header
OPGroup IDCommand ID
003

이 command는 data로 빈 CBOR map을 보냅니다.

Memory pool statistics response

Memory pool statistics response header field는 다음과 같습니다.

Memory pool statistics response header
OPGroup IDCommand ID
103

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)<pool_name> {
        (str)"blksiz"   : (int)
        (str)"nblks"    : (int)
        (str)"nfree"    : (int)
        (str)"min'      : (int)
    }
    ...
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

Memory pool statistics response field
<pool_name>Pool name을 나타내는 string이며 pool statistics dictionary의 key로 사용됩니다.
blksizPool 안 memory block의 size입니다.
nblksPool 안 block 개수입니다.
nfreeFree block 개수입니다.
minRuntime 동안 pool이 도달한 가장 낮은 free block 개수입니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Date-time command

이 command를 사용하면 device의 현재 date-time을 나타내는 string을 가져오거나 새 시간을 설정할 수 있습니다. Get과 set 모두 다음 format을 사용합니다.

yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ

Date-time get

Device에서 date-time을 가져옵니다.

Date-time get request

Date-time get request header field는 다음과 같습니다.

Date-time get request header
OPGroup IDCommand ID
004

이 command는 data로 빈 CBOR map을 보냅니다.

Date-time get response

Date-time get response header field는 다음과 같습니다.

Date-time get response header
OPGroup IDCommand ID
104

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)"datetime" : (str)
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

Date-time get response field
datetimeyyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ format의 string입니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Date-time set

Device에 date-time을 설정합니다.

Date-time set request

Date-time set request header field는 다음과 같습니다.

Date-time set request header
OPGroup IDCommand ID
204

원문에서 response라고 표기한 request의 CBOR data는 다음과 같습니다.

{
    (str)"datetime" : (str)
}

Request field의 의미는 다음과 같습니다.

Date-time set request field
datetimeyyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ format의 string입니다.

Date-time set response

Date-time set response header field는 다음과 같습니다.

Date-time set response header
OPGroup IDCommand ID
304

성공하면 command는 data로 빈 CBOR map을 보냅니다.

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Error field의 의미는 다음과 같습니다.

Date-time set error field
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

System reset

System을 reset합니다. SMP client가 command 수락 여부를 받을 수 있도록 device는 reset 전에 response를 보내야 합니다.

기본적으로 모든 조건에서 command를 수락합니다. CONFIG_MCUMGR_GRP_OS_RESET_HOOK을 활성화하고 application이 callback을 등록하면 command가 들어올 때 callback이 호출됩니다. Module reboot 전에 필요한 정리 작업을 수행하거나 error response로 reset request를 완전히 거부할 수 있습니다. 자세한 내용은 MCUmgr Callbacks를 참고합니다.

System reset request

System reset request header field는 다음과 같습니다.

System reset request header
OPGroup IDCommand ID
205

보통은 data로 빈 CBOR map을 보냅니다. 이전 reset 시도에서 rc가 MGMT_ERR_EBUSY였다면 다음 map으로 reset을 강제할 수 있습니다.

{
    (opt)"force"       : (int)
}

Request field의 의미는 다음과 같습니다.

System reset request field
force값이 0보다 크면 reset을 강제합니다. 0이면 선택 사항입니다.

System reset response

System reset response header field는 다음과 같습니다.

System reset response header
OPGroup IDCommand ID
305

성공하면 command는 data로 빈 CBOR map을 보냅니다.

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Error field의 의미는 다음과 같습니다.

System reset error field
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

MCUmgr parameter

MCUmgr library의 parameter를 가져오는 데 사용합니다.

MCUmgr parameter request

MCUmgr parameter request header field는 다음과 같습니다.

MCUmgr parameter request header
OPGroup IDCommand ID
006

이 command는 data로 빈 CBOR map을 보냅니다.

MCUmgr parameter response

MCUmgr parameter response header field는 다음과 같습니다.

MCUmgr parameter response header
OPGroup IDCommand ID
106

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)"buf_size"     : (uint)
    (str)"buf_count"    : (uint)
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

MCUmgr parameter response field
buf_sizeSMP buffer 하나의 size입니다. SMP header와 CBOR payload를 포함합니다.
buf_count지원되는 SMP buffer 개수입니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

OS/Application info

Linux uname command와 비슷하게 실행 중인 image 정보를 가져옵니다. Kernel name·version, build date/time, processor type과 application-defined detail을 반환할 수 있습니다. CONFIG_MCUMGR_GRP_OS_INFO로 활성화합니다.

OS/Application info request

OS/Application info request header field는 다음과 같습니다.

OS/Application info request header
OPGroup IDCommand ID
007

Request의 CBOR data는 다음과 같습니다.

{
    (str,opt)"format"      : (str)
}

Request field의 의미는 다음과 같습니다.

OS/Application info request field
format반환 response의 format specifier입니다. Field는 command에 들어온 character 순서가 아니라 본래 index의 오름차순으로 붙습니다.
s: Kernel name, n: Node name, r: Kernel release, v: Kernel version, b: Build date/time(CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME 필요), m: Machine, p: Processor, i: Hardware platform, o: Operating system, a: 위 field 전체의 축약형입니다. 생략하면 s를 사용합니다.

OS/Application info response

OS/Application info response header field는 다음과 같습니다.

OS/Application info response header
OPGroup IDCommand ID
107

성공한 response의 CBOR data는 다음과 같습니다.

{
    (str)"output"       : (str)
}

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Response field의 의미는 다음과 같습니다.

OS/Application info response field
output요청한 parameter를 포함한 text response입니다.
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Bootloader information

On-board bootloader와 그 parameter 정보를 가져옵니다.

Bootloader information request

Bootloader information request header는 다음과 같습니다.

Bootloader information request header
OPGroup IDCommand ID
008

Request의 CBOR data는 다음과 같습니다.

{
    (str,opt)"query"  : (str)
}

Request field의 의미는 다음과 같습니다.

Bootloader information request field
queryParameter query를 나타내는 string입니다. Query 처리는 bootloader backend에 맡기므로 형태 제한이 없습니다. Query가 없으면 response는 bootloader를 식별하는 string을 반환합니다.

Bootloader information response

Bootloader information response header는 다음과 같습니다.

Bootloader information response header
OPGroup IDCommand ID
108

Request에 query가 없을 때 response의 CBOR data는 다음과 같습니다.

{
    (str)"bootloader"      : (str)
}
Bootloader name response field
bootloaderBootloader name을 나타내는 string입니다.

query가 있을 때 response는 다음과 같습니다.

{
    (str,opt)<response>   : ()
    ...
}

Query response field의 의미는 다음과 같습니다.

Bootloader query response field
<response>query에 대한 response입니다. 선택 사항이며 query가 답을 만들지 않으면 생략할 수 있고 SMP version 2 error OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER가 예상됩니다. Bootloader backend와 query에 따라 여러 parameter 또는 map을 반환할 수 있습니다.
...Parameter 특성 정보입니다.

Parameter에는 값이 지정된 parameter 전용 정보 keyword가 추가로 동반될 수 있습니다.

Error가 발생하면 CBOR data는 다음 형식입니다.

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1 및 group 기반이 아닌 SMP version 2
{
    (str)"rc"       : (int)
}

Error field의 의미는 다음과 같습니다.

Bootloader information error field
err → groupGroup 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다.
err → rcGroup 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다.
rcmcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다.

Bootloader information: MCUboot

Application bootloader가 MCUboot이면 빈 request에 다음과 같이 response합니다.

{
    (str)"bootloader"      : (str)"MCUboot"
}

현재 MCUboot는 operation mode query를 지원합니다.

{
    (str)"query"           : (str)"mode"
}

mode query의 response는 다음과 같습니다.

{
    (str)"mode"                     : (int)
    (str,opt)"no-downgrade"         : (bool)
}

mode 값은 다음 중 하나입니다.

MCUboot operation mode
-1알 수 없는 MCUboot mode
0Single application mode
1Scratch partition을 사용하는 swap mode
2Overwrite(upgrade-only) mode
3Scratch 없는 swap mode
4Revert 없는 DirectXIP mode
5Revert가 있는 DirectXIP mode
6RAM loader mode

no-downgrade는 MCUboot에서 downgrade prevention이 활성화됐음을 나타내며 true일 때 항상 전송되는 flag입니다. Upload image version이 현재 실행 중인 application보다 낮으면 MCUboot가 update에 사용하지 않습니다. 이 구성에서는 MCUmgr도 더 낮은 version의 image를 거부할 수 있습니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.