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

Zephyr 3.7.0 · SMP Groups

SMP Group 3 · Settings Management

Device setting을 원격으로 읽고 바꾸며, 삭제·적용하거나 persistent storage와 동기화합니다.

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

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

Part 1

요약·해설

Group ID 3의 네 command ID가 여섯 operation을 구분하는 방법, binary value의 type 계약, maximum size 협상과 settings access hook을 설명합니다.

Group ID

3

Operations

Read · write · delete · commit · load · save

Policy

Settings access callback

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 2DBBBFF403DB36682BE3F0025A9C8543B814DDD3C0310C90021D41578A234485
.. _mcumgr_smp_group_3:

Settings (Config) Management Group
##################################

Settings management group (known as Configuration Manager in the original MCUmgr repository)
defines the following commands:

.. table::
    :align: center

    +----------------+------------------------------+
    | ``Command ID`` | Command description          |
    +================+==============================+
    | ``0``          | Read/write setting           |
    +----------------+------------------------------+
    | ``1``          | Delete setting               |
    +----------------+------------------------------+
    | ``2``          | Commit settings              |
    +----------------+------------------------------+
    | ``3``          | Load/Save settings           |
    +----------------+------------------------------+

Note that the Zephyr version adds additional commands and features which are not supported by
the original upstream version, however, the original client functionality should work for
read/write functionality.

Read/write setting command
**************************

Read/write setting command allows updating a setting entry on a device or
getting the current value of a setting from a device.

Read setting request
====================

Read setting request header fields:

.. table::
    :align: center

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

CBOR data of request:

.. code-block:: none

    {
        (str)"name"         : (str)
        (str,opt)"max_size" : (uint)
    }

where:

.. table::
    :align: center

    +------------+-----------------------------------------+
    | "name"     | string of the setting to retrieve       |
    +------------+-----------------------------------------+
    | "max_size" | optional maximum size of data to return |
    +------------+-----------------------------------------+

Read setting response
=====================

Read setting response header fields:

.. table::
    :align: center

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

CBOR data of successful response:

.. code-block:: none

    {
        (str)"val"          : (bstr)
        (str,opt)"max_size" : (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

      .. code-block:: none

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

where:

.. table::
    :align: center

    +------------------+-------------------------------------------------------------------------+
    | "val"            | binary string of the returned data, note that the underlying data type  |
    |                  | cannot be specified through this and must be known by the client.       |
    +------------------+-------------------------------------------------------------------------+
    | "max_size"       | will be set if the maximum supported data size is smaller than the      |
    |                  | maximum requested data size, and contains the maximum data size which   |
    |                  | the device supports, equivalent to                                      |
    |                  | kconfig:option:`CONFIG_MCUMGR_GRP_SETTINGS_NAME_LEN`.                   |
    +------------------+-------------------------------------------------------------------------+
    | "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.         |
    +------------------+-------------------------------------------------------------------------+

Write setting request
=====================

Write setting request header fields:

.. table::
    :align: center

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

CBOR data of request:

.. code-block:: none

    {
        (str)"name"    : (str)
        (str)"val"     : (bstr)
    }

where:

.. table::
    :align: center

    +--------+-------------------------------------+
    | "name" | string of the setting to update/set |
    +--------+-------------------------------------+
    | "val"  | value to set the setting to         |
    +--------+-------------------------------------+

Write setting response
======================

Write setting response header fields:

.. table::
    :align: center

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

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

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

Delete setting command
**********************

Delete setting command allows deleting a setting on a device.

Delete setting request
======================

Delete setting request header fields:

.. table::
    :align: center

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

CBOR data of request:

.. code-block:: none

    {
        (str)"name"   : (str)
    }

where:

.. table::
    :align: center

    +--------+---------------------------------+
    | "name" | string of the setting to delete |
    +--------+---------------------------------+

Delete setting response
=======================

Delete setting response header fields:

.. table::
    :align: center

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

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

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

Commit settings command
***********************

Commit settings command allows committing all settings that have been set but not yet applied on a
device.

Commit settings request
=======================

Commit settings request header fields:

.. table::
    :align: center

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

The command sends an empty CBOR map as data.

Commit settings response
========================

Commit settings response header fields:

.. table::
    :align: center

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

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

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

Load/Save settings command
**************************

Load/Save settings command allows loading/saving all serialized items from/to persistent storage
on a device.

Load settings request
=====================

Load settings request header fields:

.. table::
    :align: center

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

The command sends an empty CBOR map as data.

Load settings response
======================

Load settings response header fields:

.. table::
    :align: center

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

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

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

Save settings request
=====================

Save settings request header fields:

.. table::
    :align: center

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

The command sends an empty CBOR map as data.

Save settings response
======================

Save settings response header fields:

.. table::
    :align: center

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

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

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

Settings access callback
************************

There is a settings access MCUmgr callback available (see :ref:`mcumgr_callbacks` for details on
callbacks) which allows for applications/modules to know when settings management commands are
used and, optionally, block access (for example through the use of a security mechanism). This
callback can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_SETTINGS_ACCESS_HOOK`, registered
with the event :c:enumerator:`MGMT_EVT_OP_SETTINGS_MGMT_ACCESS`, whereby the supplied callback data
is :c:struct:`settings_mgmt_access`.

Part 3

한국어 전문 번역

Settings management group은 원래 MCUmgr repository에서 Configuration Manager라고 불리며 다음 command를 정의합니다.

Settings management command
Command IDCommand description
0Setting read/write
1Setting delete
2Settings commit
3Settings load/save

Zephyr version에는 원래 upstream version이 지원하지 않는 command와 feature가 추가되어 있습니다. 다만 original client의 read/write 기능은 그대로 동작해야 합니다.

Setting read/write command

이 command를 사용하면 device의 setting entry를 update하거나 현재 setting 값을 가져올 수 있습니다.

Setting read request

Setting read request header field는 다음과 같습니다.

Read setting request header
OPGroup IDCommand ID
030

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

{
    (str)"name"         : (str)
    (str,opt)"max_size" : (uint)
}

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

Read setting request field
name가져올 setting을 나타내는 string입니다.
max_size반환할 data의 선택적인 maximum size입니다.

Setting read response

Setting read response header field는 다음과 같습니다.

Read setting response header
OPGroup IDCommand ID
130

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

{
    (str)"val"          : (bstr)
    (str,opt)"max_size" : (uint)
}

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Read setting response field
val반환된 data의 binary string입니다. 이 field만으로 underlying data type을 지정할 수 없으므로 client가 type을 알고 있어야 합니다.
max_sizeDevice가 지원하는 maximum data size가 요청한 maximum보다 작을 때 설정됩니다. Device가 지원하는 maximum size를 담으며 CONFIG_MCUMGR_GRP_SETTINGS_NAME_LEN에 해당합니다.
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가 발생할 때만 나타납니다.

Setting write request

Setting write request header field는 다음과 같습니다.

Write setting request header
OPGroup IDCommand ID
230

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

{
    (str)"name"    : (str)
    (str)"val"     : (bstr)
}

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

Write setting request field
nameUpdate하거나 설정할 setting을 나타내는 string입니다.
valSetting에 지정할 값입니다.

Setting write response

Setting write response header field는 다음과 같습니다.

Write setting response header
OPGroup IDCommand ID
330

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

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Write setting 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가 발생할 때만 나타납니다.

Setting delete command

Setting delete command는 device에서 setting 하나를 삭제합니다.

Setting delete request

Setting delete request header field는 다음과 같습니다.

Delete setting request header
OPGroup IDCommand ID
231

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

{
    (str)"name"   : (str)
}

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

Delete setting request field
name삭제할 setting을 나타내는 string입니다.

Setting delete response

Setting delete response header field는 다음과 같습니다.

Delete setting response header
OPGroup IDCommand ID
331

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

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Delete setting 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가 발생할 때만 나타납니다.

Settings commit command

Settings commit command는 device에 설정됐지만 아직 적용되지 않은 모든 setting을 commit해 적용합니다.

Settings commit request

Settings commit request header field는 다음과 같습니다.

Commit settings request header
OPGroup IDCommand ID
232

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

Settings commit response

Settings commit response header field는 다음과 같습니다.

Commit settings response header
OPGroup IDCommand ID
332

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

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Commit settings 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가 발생할 때만 나타납니다.

Settings load/save command

Settings load/save command는 device의 persistent storage에서 또는 그 storage로 serialization된 모든 item을 load/save합니다.

Settings load request

Settings load request header field는 다음과 같습니다.

Load settings request header
OPGroup IDCommand ID
033

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

Settings load response

Settings load response header field는 다음과 같습니다.

Load settings response header
OPGroup IDCommand ID
133

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

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Load settings 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가 발생할 때만 나타납니다.

Settings save request

Settings save request header field는 다음과 같습니다.

Save settings request header
OPGroup IDCommand ID
233

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

Settings save response

Settings save response header field는 다음과 같습니다.

Save settings response header
OPGroup IDCommand ID
333

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

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

SMP version 2
{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}
SMP version 1
{
    (str)"rc"       : (int)
}

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

Save settings 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가 발생할 때만 나타납니다.

Settings access callback

Settings access용 MCUmgr callback이 제공됩니다. MCUmgr callback의 자세한 내용은 MCUmgr Callbacks를 참고합니다. 이 callback으로 application이나 module은 settings management command가 사용되는 시점을 알 수 있고, security mechanism 등을 통해 선택적으로 access를 차단할 수 있습니다.

CONFIG_MCUMGR_GRP_SETTINGS_ACCESS_HOOK으로 callback을 활성화하고 MGMT_EVT_OP_SETTINGS_MGMT_ACCESS event로 등록합니다. Callback에 전달되는 data는 settings_mgmt_access structure입니다.

Source

출처

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