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

Zephyr 3.7.0 · Device Management

SMP Protocol Specification

MCUmgr request와 response가 어떤 header와 payload로 구성되고 error를 어떻게 표현하는지 설명합니다.

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

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

Part 1

요약·해설

Big-endian frame header의 bit layout, sequence matching, 표준·사용자 group 경계, SMP version 1·2의 성공 및 error response 규칙을 다룹니다.

Header

8 bytes

Payload

CBOR by default

Versions

Legacy · v2 errors

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 253220F785D432A80D5E9F5B7F4A671D8870E37BE0324B181F63CE56CA8D1855
.. _mcumgr_smp_protocol_specification:

SMP Protocol Specification
##########################

This is description of Simple Management Protocol, SMP, that is used by
MCUmgr to pass requests to devices and receive responses from them.

SMP is an application layer protocol. The underlying transport layer is not
in scope of this documentation.

.. note::
    SMP in this context refers to SMP for MCUmgr (Simple Management Protocol),
    it is unrelated to SMP in Bluetooth (Security Manager Protocol), but there
    is an MCUmgr SMP transport for Bluetooth.

Frame: The envelope
*******************

Each frame consists of a header and data. The ``Data Length`` field in the
header may be used for reassembly purposes if underlying transport layer supports
fragmentation.
Frames are encoded in "Big Endian" (Network endianness) when fields are more than
one byte long, and takes the following form:

.. _mcumgr_smp_protocol_frame:

.. table::
    :align: center

    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |3              |2              |1              |0              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |7|6|5|4|3|2|1|0|7|6|5|4|3|2|1|0|7|6|5|4|3|2|1|0|7|6|5|4|3|2|1|0|
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | Res |Ver| OP  |      Flags    |          Data Length          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |            Group ID           | Sequence Num  |   Command ID  |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                             Data                              |
    |                             ...                               |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

.. note::
    The original specification states that SMP should support receiving
    both the "Little-endian" and "Big-endian" frames but in reality the
    MCUmgr library is hardcoded to always treat "Network" side as
    "Big-endian".


Data is optional and is not present when ``Data Length`` is zero.
The encoding of data depends on the target of group/ID.

A description of the various fields and their meaning:

.. table::
    :align: center

    +-------------------+---------------------------------------------------+
    | Field             | Description                                       |
    +===================+===================================================+
    | ``Res``           | This is reserved, not-used field and must be      |
    |                   | always set to 0.                                  |
    +-------------------+---------------------------------------------------+
    | ``Ver`` (Version) | This indicates the version of the protocol being  |
    |                   | used, this should be set to 0b01 to use the newer |
    |                   | SMP transport where error codes are more detailed |
    |                   | and returned in the map, otherwise left as 0b00   |
    |                   | to use the legacy SMP protocol. Versions 0b10 and |
    |                   | 0b11 are reserved for future use and should not   |
    |                   | be used.                                          |
    +-------------------+---------------------------------------------------+
    | ``OP``            | :c:enum:`mcumgr_op_t`, determines whether         |
    |                   | information is written to a device or requested   |
    |                   | from it and whether a packet contains request to  |
    |                   | an SMP server or response from it.                |
    +-------------------+---------------------------------------------------+
    | ``Flags``         | Reserved for flags; there are no flags defined    |
    |                   | yet, the field should be set to 0                 |
    +-------------------+---------------------------------------------------+
    | ``Data Length``   | Length of the ``Data`` field                      |
    +-------------------+---------------------------------------------------+
    | ``Group ID``      | :c:enum:`mcumgr_group_t`, see                     |
    |                   | :ref:`mcumgr_smp_protocol_group_ids` for further  |
    |                   | details.                                          |
    +-------------------+---------------------------------------------------+
    | ``Sequence Num``  | This is a frame sequence number.                  |
    |                   | The number is increased by one with each request  |
    |                   | frame.                                            |
    |                   | The Sequence Num of a response should match       |
    |                   | the one in the request.                           |
    +-------------------+---------------------------------------------------+
    | ``Command ID``    | This is a command, within ``Group``.              |
    +-------------------+---------------------------------------------------+
    | ``Data``          | This is data payload of the ``Data Length``       |
    |                   | size. It is optional as ``Data Length`` may be    |
    |                   | set to zero, which means that no data follows     |
    |                   | the header.                                       |
    +-------------------+---------------------------------------------------+

.. note::
    Contents of ``Data`` depends on a value of an ``OP``, a ``Group ID``,
    and a ``Command ID``.

.. _mcumgr_smp_protocol_group_ids:

Management ``Group ID``'s
=========================

The SMP protocol supports predefined common groups and allows user defined
groups. The following table presents a list of common groups:


.. table::
    :align: center

    +---------------+-----------------------------------------------+
    | Decimal ID    | Group description                             |
    +===============+===============================================+
    | ``0``         | :ref:`mcumgr_smp_group_0`                     |
    +---------------+-----------------------------------------------+
    | ``1``         | :ref:`mcumgr_smp_group_1`                     |
    +---------------+-----------------------------------------------+
    | ``2``         | :ref:`mcumgr_smp_group_2`                     |
    +---------------+-----------------------------------------------+
    | ``3``         | :ref:`mcumgr_smp_group_3`                     |
    +---------------+-----------------------------------------------+
    | ``4``         | Application/system log management             |
    |               | (currently not used by Zephyr)                |
    +---------------+-----------------------------------------------+
    | ``5``         | Run-time tests                                |
    |               | (unused by Zephyr)                            |
    +---------------+-----------------------------------------------+
    | ``6``         | Split image management                        |
    |               | (unused by Zephyr)                            |
    +---------------+-----------------------------------------------+
    | ``7``         | Test crashing application                     |
    |               | (unused by Zephyr)                            |
    +---------------+-----------------------------------------------+
    | ``8``         | :ref:`mcumgr_smp_group_8`                     |
    +---------------+-----------------------------------------------+
    | ``9``         | :ref:`mcumgr_smp_group_9`                     |
    +---------------+-----------------------------------------------+
    | ``63``        | :ref:`mcumgr_smp_group_63`                    |
    +---------------+-----------------------------------------------+
    | ``64``        | This is the base group for defining           |
    |               | an application specific management groups.    |
    +---------------+-----------------------------------------------+

The payload for above groups, except for user groups (``64`` and above) is
always CBOR encoded. The group ``64``, and above can define their own scheme
for data communication.

Minimal response
****************

Regardless of a command issued, as long as there is SMP client on the
other side of a request, a response should be issued containing the header
followed by CBOR map container.
Lack of response is only allowed when there is no SMP service or device is
non-responsive.

Minimal response SMP data
=========================

Minimal response is:

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

Note that in the case of a successful command, an empty map will be returned (``rc``/``err`` is
only returned if there is an error condition, therefore if only an empty map is returned or a
response lacks these, the request can be considered as being successful. For SMP version 2,
errors relating to SMP itself that are not group specific will still be returned as ``rc``
errors, SMP version 2 clients must therefore be able to handle both types of errors.

Specifications of management groups supported by Zephyr
*******************************************************

.. toctree::
    :maxdepth: 1

    smp_groups/smp_group_0.rst
    smp_groups/smp_group_1.rst
    smp_groups/smp_group_2.rst
    smp_groups/smp_group_3.rst
    smp_groups/smp_group_8.rst
    smp_groups/smp_group_9.rst

Part 3

한국어 전문 번역

이 문서는 MCUmgr가 device로 request를 보내고 response를 받는 데 사용하는 Simple Management Protocol, 즉 SMP를 설명합니다.

SMP는 application layer protocol입니다. 그 아래에서 packet을 운반하는 transport layer는 이 문서의 범위에 포함되지 않습니다.

Frame: 봉투 구조

각 frame은 header와 data로 구성됩니다. 아래 transport가 fragmentation을 지원하면 header의 Data Length field를 reassembly에 사용할 수 있습니다. 한 byte보다 큰 field는 모두 Big Endian, 즉 network byte order로 encode하며 frame 형식은 다음과 같습니다.

SMP frame bit layout
3210
76543210765432107654321076543210
ResVerOPFlagsData Length
Group IDSequence NumCommand ID
Data
...

Data는 선택 사항입니다. Data Length가 0이면 존재하지 않으며, data encoding은 target group과 command ID에 따라 달라집니다.

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

SMP frame field
FieldDescription
ResReserved field입니다. 사용하지 않으며 항상 0으로 설정해야 합니다.
Ver (Version)사용 중인 protocol version을 나타냅니다. 더 상세한 group별 error code를 map으로 반환하는 새 SMP protocol은 0b01로 설정합니다. Legacy SMP protocol은 0b00입니다. 0b10과 0b11은 향후 사용을 위해 예약돼 있으므로 사용하면 안 됩니다.
OPmcumgr_op_t 값입니다. Device에 정보를 쓰는지 요청하는지, packet이 SMP server로 가는 request인지 server가 보낸 response인지 결정합니다.
FlagsFlag용 reserved field입니다. 아직 정의된 flag가 없으므로 0으로 설정해야 합니다.
Data LengthData field의 byte length입니다.
Group IDmcumgr_group_t 값입니다. 아래 Management Group ID 절에서 자세히 설명합니다.
Sequence NumFrame sequence number입니다. Request frame마다 1씩 증가하며, response의 값은 대응하는 request와 같아야 합니다.
Command ID선택한 Group 안에서 수행할 command입니다.
DataData Length 크기의 payload입니다. Length가 0이면 header 뒤에 data가 오지 않습니다.

Management Group ID

SMP protocol은 미리 정의된 common group을 지원하고, application이 자체 group도 정의할 수 있게 합니다. Common group 목록은 다음과 같습니다.

Management group ID
Decimal IDGroup description
0Default/OS Management Group
1Application/software image management group
2Statistics management
3Settings (Config) Management Group
4Application/system log management. 현재 Zephyr에서는 사용하지 않습니다.
5Run-time tests. Zephyr에서는 사용하지 않습니다.
6Split image management. Zephyr에서는 사용하지 않습니다.
7Application crash test. Zephyr에서는 사용하지 않습니다.
8File management
9Shell management
63Zephyr Management Group
64Application-specific management group을 정의할 때 사용하는 base group입니다.

User group인 64 이상을 제외한 위 group의 payload는 항상 CBOR로 encode합니다. Group 64 이상은 자체 data communication scheme을 정의할 수 있습니다.

최소 response

어떤 command를 보냈든 request 반대편에 SMP client가 존재하면 header 뒤에 CBOR map container를 붙인 response를 보내야 합니다. Response를 생략할 수 있는 경우는 SMP service가 없거나 device가 응답하지 못할 때뿐입니다.

최소 response의 SMP data

최소 response 형식은 protocol version에 따라 다음과 같습니다.

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

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

Minimal response 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일 때만 나타납니다.

Command가 성공하면 empty map이 반환됩니다. rc와 err는 error일 때만 포함되므로, 빈 map이거나 이 field들이 없는 response는 성공으로 판단할 수 있습니다. SMP version 2에서도 특정 group과 무관한 SMP 자체 error는 top-level rc로 반환되므로, version 2 client는 err map과 rc 두 형식을 모두 처리해야 합니다.

Zephyr가 지원하는 management group specification

Zephyr 3.7.0은 별도 문서에서 OS Management group 0, Image Management group 1, Statistics group 2, Settings group 3, File Management group 8, Shell group 9를 정의합니다.

Source

출처

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