Part 1
요약·해설
Group ID 3의 네 command ID가 여섯 operation을 구분하는 방법, binary value의 type 계약, maximum size 협상과 settings access hook을 설명합니다.
3
Read · write · delete · commit · load · save
Settings access callback
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
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를 정의합니다.
| Command ID | Command description |
|---|---|
| 0 | Setting read/write |
| 1 | Setting delete |
| 2 | Settings commit |
| 3 | Settings 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는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 0 | 3 | 0 |
Request의 CBOR data는 다음과 같습니다.
{
(str)"name" : (str)
(str,opt)"max_size" : (uint)
}
Request field의 의미는 다음과 같습니다.
name | 가져올 setting을 나타내는 string입니다. |
max_size | 반환할 data의 선택적인 maximum size입니다. |
Setting read response
Setting read response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 1 | 3 | 0 |
성공한 response의 CBOR data는 다음과 같습니다.
{
(str)"val" : (bstr)
(str,opt)"max_size" : (uint)
}
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Response field의 의미는 다음과 같습니다.
val | 반환된 data의 binary string입니다. 이 field만으로 underlying data type을 지정할 수 없으므로 client가 type을 알고 있어야 합니다. |
max_size | Device가 지원하는 maximum data size가 요청한 maximum보다 작을 때 설정됩니다. Device가 지원하는 maximum size를 담으며 CONFIG_MCUMGR_GRP_SETTINGS_NAME_LEN에 해당합니다. |
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다. |
Setting write request
Setting write request header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 2 | 3 | 0 |
Request의 CBOR data는 다음과 같습니다.
{
(str)"name" : (str)
(str)"val" : (bstr)
}
Request field의 의미는 다음과 같습니다.
name | Update하거나 설정할 setting을 나타내는 string입니다. |
val | Setting에 지정할 값입니다. |
Setting write response
Setting write response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 3 | 3 | 0 |
성공하면 command는 data로 빈 CBOR map을 보냅니다.
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Error field의 의미는 다음과 같습니다.
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_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는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 2 | 3 | 1 |
Request의 CBOR data는 다음과 같습니다.
{
(str)"name" : (str)
}
Request field의 의미는 다음과 같습니다.
name | 삭제할 setting을 나타내는 string입니다. |
Setting delete response
Setting delete response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 3 | 3 | 1 |
성공하면 command는 data로 빈 CBOR map을 보냅니다.
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Error field의 의미는 다음과 같습니다.
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_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는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 2 | 3 | 2 |
이 command는 data로 빈 CBOR map을 보냅니다.
Settings commit response
Settings commit response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 3 | 3 | 2 |
성공하면 command는 data로 빈 CBOR map을 보냅니다.
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Error field의 의미는 다음과 같습니다.
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_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는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 0 | 3 | 3 |
이 command는 data로 빈 CBOR map을 보냅니다.
Settings load response
Settings load response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 1 | 3 | 3 |
성공하면 command는 data로 빈 CBOR map을 보냅니다.
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Error field의 의미는 다음과 같습니다.
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_err_t입니다. SMP version 1에서 값이 0이 아닌 error condition일 때, 또는 SMP version 2에서 SMP error가 발생할 때만 나타납니다. |
Settings save request
Settings save request header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 2 | 3 | 3 |
이 command는 data로 빈 CBOR map을 보냅니다.
Settings save response
Settings save response header field는 다음과 같습니다.
| OP | Group ID | Command ID |
|---|---|---|
| 3 | 3 | 3 |
성공하면 command는 data로 빈 CBOR map을 보냅니다.
Error가 발생하면 CBOR data는 다음 형식입니다.
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}{
(str)"rc" : (int)
}Error field의 의미는 다음과 같습니다.
err → group | Group 기반 error code의 mcumgr_group_t group입니다. SMP version 2를 사용하며 error가 반환될 때만 나타납니다. |
err → rc | Group 기반 error code의 index입니다. SMP version 2에서 값이 0이 아닌 error condition일 때만 나타납니다. |
rc | mcumgr_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
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.