1.. _mcumgr_smp_protocol_specification:
2
3SMP Protocol Specification
4##########################
5
6This is description of Simple Management Protocol, SMP, that is used by
7MCUmgr to pass requests to devices and receive responses from them.
8
9SMP is an application layer protocol. The underlying transport layer is not
10in scope of this documentation.
11
12.. note::
13    SMP in this context refers to SMP for MCUmgr (Simple Management Protocol),
14    it is unrelated to SMP in Bluetooth (Security Manager Protocol), but there
15    is an MCUmgr SMP transport for Bluetooth.
16
17Frame: The envelope
18*******************
19
20Each frame consists of a header and data. The ``Data Length`` field in the
21header may be used for reassembly purposes if underlying transport layer supports
22fragmentation.
23Frames are encoded in "Big Endian" (Network endianness) when fields are more than
24one byte long, and takes the following form:
25
26.. _mcumgr_smp_protocol_frame:
27
28.. table::
29    :align: center
30
31    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
32    |3              |2              |1              |0              |
33    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
34    |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|
35    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
36    | Res |Ver| OP  |      Flags    |          Data Length          |
37    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
38    |            Group ID           | Sequence Num  |   Command ID  |
39    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
40    |                             Data                              |
41    |                             ...                               |
42    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
43
44.. note::
45    The original specification states that SMP should support receiving
46    both the "Little-endian" and "Big-endian" frames but in reality the
47    MCUmgr library is hardcoded to always treat "Network" side as
48    "Big-endian".
49
50
51Data is optional and is not present when ``Data Length`` is zero.
52The encoding of data depends on the target of group/ID.
53
54A description of the various fields and their meaning:
55
56.. table::
57    :align: center
58
59    +-------------------+---------------------------------------------------+
60    | Field             | Description                                       |
61    +===================+===================================================+
62    | ``Res``           | This is reserved, not-used field and must be      |
63    |                   | always set to 0.                                  |
64    +-------------------+---------------------------------------------------+
65    | ``Ver`` (Version) | This indicates the version of the protocol being  |
66    |                   | used, this should be set to 0b01 to use the newer |
67    |                   | SMP transport where error codes are more detailed |
68    |                   | and returned in the map, otherwise left as 0b00   |
69    |                   | to use the legacy SMP protocol. Versions 0b10 and |
70    |                   | 0b11 are reserved for future use and should not   |
71    |                   | be used.                                          |
72    +-------------------+---------------------------------------------------+
73    | ``OP``            | :c:enum:`mcumgr_op_t`, determines whether         |
74    |                   | information is written to a device or requested   |
75    |                   | from it and whether a packet contains request to  |
76    |                   | an SMP server or response from it.                |
77    +-------------------+---------------------------------------------------+
78    | ``Flags``         | Reserved for flags; there are no flags defined    |
79    |                   | yet, the field should be set to 0                 |
80    +-------------------+---------------------------------------------------+
81    | ``Data Length``   | Length of the ``Data`` field                      |
82    +-------------------+---------------------------------------------------+
83    | ``Group ID``      | :c:enum:`mcumgr_group_t`, see                     |
84    |                   | :ref:`mcumgr_smp_protocol_group_ids` for further  |
85    |                   | details.                                          |
86    +-------------------+---------------------------------------------------+
87    | ``Sequence Num``  | This is a frame sequence number.                  |
88    |                   | The number is increased by one with each request  |
89    |                   | frame.                                            |
90    |                   | The Sequence Num of a response should match       |
91    |                   | the one in the request.                           |
92    +-------------------+---------------------------------------------------+
93    | ``Command ID``    | This is a command, within ``Group``.              |
94    +-------------------+---------------------------------------------------+
95    | ``Data``          | This is data payload of the ``Data Length``       |
96    |                   | size. It is optional as ``Data Length`` may be    |
97    |                   | set to zero, which means that no data follows     |
98    |                   | the header.                                       |
99    +-------------------+---------------------------------------------------+
100
101.. note::
102    Contents of ``Data`` depends on a value of an ``OP``, a ``Group ID``,
103    and a ``Command ID``.
104
105.. _mcumgr_smp_protocol_group_ids:
106
107Management ``Group ID``'s
108=========================
109
110The SMP protocol supports predefined common groups and allows user defined
111groups. The following table presents a list of common groups:
112
113
114.. table::
115    :align: center
116
117    +---------------+-----------------------------------------------+
118    | Decimal ID    | Group description                             |
119    +===============+===============================================+
120    | ``0``         | :ref:`mcumgr_smp_group_0`                     |
121    +---------------+-----------------------------------------------+
122    | ``1``         | :ref:`mcumgr_smp_group_1`                     |
123    +---------------+-----------------------------------------------+
124    | ``2``         | :ref:`mcumgr_smp_group_2`                     |
125    +---------------+-----------------------------------------------+
126    | ``3``         | :ref:`mcumgr_smp_group_3`                     |
127    +---------------+-----------------------------------------------+
128    | ``4``         | Application/system log management             |
129    |               | (currently not used by Zephyr)                |
130    +---------------+-----------------------------------------------+
131    | ``5``         | Run-time tests                                |
132    |               | (unused by Zephyr)                            |
133    +---------------+-----------------------------------------------+
134    | ``6``         | Split image management                        |
135    |               | (unused by Zephyr)                            |
136    +---------------+-----------------------------------------------+
137    | ``7``         | Test crashing application                     |
138    |               | (unused by Zephyr)                            |
139    +---------------+-----------------------------------------------+
140    | ``8``         | :ref:`mcumgr_smp_group_8`                     |
141    +---------------+-----------------------------------------------+
142    | ``9``         | :ref:`mcumgr_smp_group_9`                     |
143    +---------------+-----------------------------------------------+
144    | ``63``        | Zephyr specific basic commands group          |
145    +---------------+-----------------------------------------------+
146    | ``64``        | This is the base group for defining           |
147    |               | an application specific management groups.    |
148    +---------------+-----------------------------------------------+
149
150The payload for above groups, except for user groups (``64`` and above) is
151always CBOR encoded. The group ``64``, and above can define their own scheme
152for data communication.
153
154Minimal response
155****************
156
157Regardless of a command issued, as long as there is SMP client on the
158other side of a request, a response should be issued containing the header
159followed by CBOR map container.
160Lack of response is only allowed when there is no SMP service or device is
161non-responsive.
162
163Minimal response SMP data
164=========================
165
166Minimal response is:
167
168.. tabs::
169
170   .. group-tab:: SMP version 2
171
172      .. code-block:: none
173
174          {
175              (str)"err" : {
176                  (str)"group"    : (uint)
177                  (str)"rc"       : (uint)
178              }
179          }
180
181   .. group-tab:: SMP version 1 (and non-group SMP version 2)
182
183      .. code-block:: none
184
185          {
186              (str)"rc"       : (int)
187          }
188
189where:
190
191.. table::
192    :align: center
193
194    +------------------+-------------------------------------------------------------------------+
195    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
196    |                  | appears if an error is returned when using SMP version 2.               |
197    +------------------+-------------------------------------------------------------------------+
198    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
199    |                  | non-zero (error condition) when using SMP version 2.                    |
200    +------------------+-------------------------------------------------------------------------+
201    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
202    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
203    +------------------+-------------------------------------------------------------------------+
204
205Note that in the case of a successful command, an empty map will be returned (``rc``/``err`` is
206only returned if there is an error condition, therefore if only an empty map is returned or a
207response lacks these, the request can be considered as being successful. For SMP version 2,
208errors relating to SMP itself that are not group specific will still be returned as ``rc``
209errors, SMP version 2 clients must therefore be able to handle both types of errors.
210
211Specifications of management groups supported by Zephyr
212*******************************************************
213
214.. toctree::
215    :maxdepth: 1
216
217    smp_groups/smp_group_0.rst
218    smp_groups/smp_group_1.rst
219    smp_groups/smp_group_2.rst
220    smp_groups/smp_group_3.rst
221    smp_groups/smp_group_8.rst
222    smp_groups/smp_group_9.rst
223