1.. _mcumgr_smp_group_3:
2
3Settings (Config) Management Group
4##################################
5
6Settings management group (known as Configuration Manager in the original MCUmgr repository)
7defines the following commands:
8
9.. table::
10    :align: center
11
12    +----------------+------------------------------+
13    | ``Command ID`` | Command description          |
14    +================+==============================+
15    | ``0``          | Read/write setting           |
16    +----------------+------------------------------+
17    | ``1``          | Delete setting               |
18    +----------------+------------------------------+
19    | ``2``          | Commit settings              |
20    +----------------+------------------------------+
21    | ``3``          | Load/Save settings           |
22    +----------------+------------------------------+
23
24Note that the Zephyr version adds additional commands and features which are not supported by
25the original upstream version, however, the original client functionality should work for
26read/write functionality.
27
28Read/write setting command
29**************************
30
31Read/write setting command allows updating a setting entry on a device or
32getting the current value of a setting from a device.
33
34Read setting request
35====================
36
37Read setting request header fields:
38
39.. table::
40    :align: center
41
42    +--------+--------------+----------------+
43    | ``OP`` | ``Group ID`` | ``Command ID`` |
44    +========+==============+================+
45    | ``0``  | ``3``        | ``0``          |
46    +--------+--------------+----------------+
47
48CBOR data of request:
49
50.. code-block:: none
51
52    {
53        (str)"name"         : (str)
54        (str,opt)"max_size" : (uint)
55    }
56
57where:
58
59.. table::
60    :align: center
61
62    +------------+-----------------------------------------+
63    | "name"     | string of the setting to retrieve       |
64    +------------+-----------------------------------------+
65    | "max_size" | optional maximum size of data to return |
66    +------------+-----------------------------------------+
67
68Read setting response
69=====================
70
71Read setting response header fields:
72
73.. table::
74    :align: center
75
76    +--------+--------------+----------------+
77    | ``OP`` | ``Group ID`` | ``Command ID`` |
78    +========+==============+================+
79    | ``1``  | ``3``        | ``0``          |
80    +--------+--------------+----------------+
81
82CBOR data of successful response:
83
84.. code-block:: none
85
86    {
87        (str)"val"          : (bstr)
88        (str,opt)"max_size" : (uint)
89    }
90
91In case of error the CBOR data takes the form:
92
93.. tabs::
94
95   .. group-tab:: SMP version 2
96
97      .. code-block:: none
98
99          {
100              (str)"err" : {
101                  (str)"group"    : (uint)
102                  (str)"rc"       : (uint)
103              }
104          }
105
106   .. group-tab:: SMP version 1
107
108      .. code-block:: none
109
110          {
111              (str)"rc"       : (int)
112          }
113
114where:
115
116.. table::
117    :align: center
118
119    +------------------+-------------------------------------------------------------------------+
120    | "val"            | binary string of the returned data, note that the underlying data type  |
121    |                  | cannot be specified through this and must be known by the client.       |
122    +------------------+-------------------------------------------------------------------------+
123    | "max_size"       | will be set if the maximum supported data size is smaller than the      |
124    |                  | maximum requested data size, and contains the maximum data size which   |
125    |                  | the device supports, equivalent to                                      |
126    |                  | kconfig:option:`CONFIG_MCUMGR_GRP_SETTINGS_NAME_LEN`.                   |
127    +------------------+-------------------------------------------------------------------------+
128    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
129    |                  | appears if an error is returned when using SMP version 2.               |
130    +------------------+-------------------------------------------------------------------------+
131    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
132    |                  | non-zero (error condition) when using SMP version 2.                    |
133    +------------------+-------------------------------------------------------------------------+
134    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
135    |                  | using SMP version 1.                                                    |
136    +------------------+-------------------------------------------------------------------------+
137
138Write setting request
139=====================
140
141Write setting request header fields:
142
143.. table::
144    :align: center
145
146    +--------+--------------+----------------+
147    | ``OP`` | ``Group ID`` | ``Command ID`` |
148    +========+==============+================+
149    | ``2``  | ``3``        | ``0``          |
150    +--------+--------------+----------------+
151
152CBOR data of request:
153
154.. code-block:: none
155
156    {
157        (str)"name"    : (str)
158        (str)"val"     : (bstr)
159    }
160
161where:
162
163.. table::
164    :align: center
165
166    +--------+-------------------------------------+
167    | "name" | string of the setting to update/set |
168    +--------+-------------------------------------+
169    | "val"  | value to set the setting to         |
170    +--------+-------------------------------------+
171
172Write setting response
173======================
174
175Write setting response header fields:
176
177.. table::
178    :align: center
179
180    +--------+--------------+----------------+
181    | ``OP`` | ``Group ID`` | ``Command ID`` |
182    +========+==============+================+
183    | ``3``  | ``3``        | ``0``          |
184    +--------+--------------+----------------+
185
186The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
187the form:
188
189.. tabs::
190
191   .. group-tab:: SMP version 2
192
193      .. code-block:: none
194
195          {
196              (str)"err" : {
197                  (str)"group"    : (uint)
198                  (str)"rc"       : (uint)
199              }
200          }
201
202   .. group-tab:: SMP version 1
203
204      .. code-block:: none
205
206          {
207              (str)"rc"       : (int)
208          }
209
210where:
211
212.. table::
213    :align: center
214
215    +------------------+-------------------------------------------------------------------------+
216    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
217    |                  | appears if an error is returned when using SMP version 2.               |
218    +------------------+-------------------------------------------------------------------------+
219    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
220    |                  | non-zero (error condition) when using SMP version 2.                    |
221    +------------------+-------------------------------------------------------------------------+
222    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
223    |                  | using SMP version 1.                                                    |
224    +------------------+-------------------------------------------------------------------------+
225
226Delete setting command
227**********************
228
229Delete setting command allows deleting a setting on a device.
230
231Delete setting request
232======================
233
234Delete setting request header fields:
235
236.. table::
237    :align: center
238
239    +--------+--------------+----------------+
240    | ``OP`` | ``Group ID`` | ``Command ID`` |
241    +========+==============+================+
242    | ``2``  | ``3``        | ``1``          |
243    +--------+--------------+----------------+
244
245CBOR data of request:
246
247.. code-block:: none
248
249    {
250        (str)"name"   : (str)
251    }
252
253where:
254
255.. table::
256    :align: center
257
258    +--------+---------------------------------+
259    | "name" | string of the setting to delete |
260    +--------+---------------------------------+
261
262Delete setting response
263=======================
264
265Delete setting response header fields:
266
267.. table::
268    :align: center
269
270    +--------+--------------+----------------+
271    | ``OP`` | ``Group ID`` | ``Command ID`` |
272    +========+==============+================+
273    | ``3``  | ``3``        | ``1``          |
274    +--------+--------------+----------------+
275
276The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
277the form:
278
279.. tabs::
280
281   .. group-tab:: SMP version 2
282
283      .. code-block:: none
284
285          {
286              (str)"err" : {
287                  (str)"group"    : (uint)
288                  (str)"rc"       : (uint)
289              }
290          }
291
292   .. group-tab:: SMP version 1
293
294      .. code-block:: none
295
296          {
297              (str)"rc"       : (int)
298          }
299
300where:
301
302.. table::
303    :align: center
304
305    +------------------+-------------------------------------------------------------------------+
306    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
307    |                  | appears if an error is returned when using SMP version 2.               |
308    +------------------+-------------------------------------------------------------------------+
309    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
310    |                  | non-zero (error condition) when using SMP version 2.                    |
311    +------------------+-------------------------------------------------------------------------+
312    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
313    |                  | using SMP version 1.                                                    |
314    +------------------+-------------------------------------------------------------------------+
315
316Commit settings command
317***********************
318
319Commit settings command allows committing all settings that have been set but not yet applied on a
320device.
321
322Commit settings request
323=======================
324
325Commit settings request header fields:
326
327.. table::
328    :align: center
329
330    +--------+--------------+----------------+
331    | ``OP`` | ``Group ID`` | ``Command ID`` |
332    +========+==============+================+
333    | ``2``  | ``3``        | ``2``          |
334    +--------+--------------+----------------+
335
336The command sends sends empty CBOR map as data.
337
338Commit settings response
339========================
340
341Commit settings response header fields:
342
343.. table::
344    :align: center
345
346    +--------+--------------+----------------+
347    | ``OP`` | ``Group ID`` | ``Command ID`` |
348    +========+==============+================+
349    | ``3``  | ``3``        | ``2``          |
350    +--------+--------------+----------------+
351
352The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
353the form:
354
355.. tabs::
356
357   .. group-tab:: SMP version 2
358
359      .. code-block:: none
360
361          {
362              (str)"err" : {
363                  (str)"group"    : (uint)
364                  (str)"rc"       : (uint)
365              }
366          }
367
368   .. group-tab:: SMP version 1
369
370      .. code-block:: none
371
372          {
373              (str)"rc"       : (int)
374          }
375
376where:
377
378.. table::
379    :align: center
380
381    +------------------+-------------------------------------------------------------------------+
382    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
383    |                  | appears if an error is returned when using SMP version 2.               |
384    +------------------+-------------------------------------------------------------------------+
385    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
386    |                  | non-zero (error condition) when using SMP version 2.                    |
387    +------------------+-------------------------------------------------------------------------+
388    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
389    |                  | using SMP version 1.                                                    |
390    +------------------+-------------------------------------------------------------------------+
391
392Load/Save settings command
393**************************
394
395Load/Save settings command allows loading/saving all serialized items from/to persistent storage
396on a device.
397
398Load settings request
399=====================
400
401Load settings request header fields:
402
403.. table::
404    :align: center
405
406    +--------+--------------+----------------+
407    | ``OP`` | ``Group ID`` | ``Command ID`` |
408    +========+==============+================+
409    | ``0``  | ``3``        | ``3``          |
410    +--------+--------------+----------------+
411
412The command sends sends empty CBOR map as data.
413
414Load settings response
415======================
416
417Load settings response header fields:
418
419.. table::
420    :align: center
421
422    +--------+--------------+----------------+
423    | ``OP`` | ``Group ID`` | ``Command ID`` |
424    +========+==============+================+
425    | ``1``  | ``3``        | ``3``          |
426    +--------+--------------+----------------+
427
428The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
429the form:
430
431.. tabs::
432
433   .. group-tab:: SMP version 2
434
435      .. code-block:: none
436
437          {
438              (str)"err" : {
439                  (str)"group"    : (uint)
440                  (str)"rc"       : (uint)
441              }
442          }
443
444   .. group-tab:: SMP version 1
445
446      .. code-block:: none
447
448          {
449              (str)"rc"       : (int)
450          }
451
452where:
453
454.. table::
455    :align: center
456
457    +------------------+-------------------------------------------------------------------------+
458    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
459    |                  | appears if an error is returned when using SMP version 2.               |
460    +------------------+-------------------------------------------------------------------------+
461    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
462    |                  | non-zero (error condition) when using SMP version 2.                    |
463    +------------------+-------------------------------------------------------------------------+
464    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
465    |                  | using SMP version 1.                                                    |
466    +------------------+-------------------------------------------------------------------------+
467
468Save settings request
469=====================
470
471Save settings request header fields:
472
473.. table::
474    :align: center
475
476    +--------+--------------+----------------+
477    | ``OP`` | ``Group ID`` | ``Command ID`` |
478    +========+==============+================+
479    | ``2``  | ``3``        | ``3``          |
480    +--------+--------------+----------------+
481
482The command sends sends empty CBOR map as data.
483
484Save settings response
485======================
486
487Save settings response header fields:
488
489.. table::
490    :align: center
491
492    +--------+--------------+----------------+
493    | ``OP`` | ``Group ID`` | ``Command ID`` |
494    +========+==============+================+
495    | ``3``  | ``3``        | ``3``          |
496    +--------+--------------+----------------+
497
498The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
499the form:
500
501.. tabs::
502
503   .. group-tab:: SMP version 2
504
505      .. code-block:: none
506
507          {
508              (str)"err" : {
509                  (str)"group"    : (uint)
510                  (str)"rc"       : (uint)
511              }
512          }
513
514   .. group-tab:: SMP version 1
515
516      .. code-block:: none
517
518          {
519              (str)"rc"       : (int)
520          }
521
522where:
523
524.. table::
525    :align: center
526
527    +------------------+------------------------------------------------------------------------+
528    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only     |
529    |                  | appears if an error is returned when using SMP version 2.              |
530    +------------------+------------------------------------------------------------------------+
531    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if      |
532    |                  | non-zero (error condition) when using SMP version 2.                   |
533    +------------------+------------------------------------------------------------------------+
534    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when |
535    |                  | using SMP version 1.                                                   |
536    +------------------+------------------------------------------------------------------------+
537
538Settings access callback
539************************
540
541There is a settings access MCUmgr callback available (see :ref:`mcumgr_callbacks` for details on
542callbacks) which allows for applications/modules to know when settings management commands are
543used and, optionally, block access (for example through the use of a security mechanism). This
544callback can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_SETTINGS_ACCESS_HOOK`, registered
545with the event :c:enum:`MGMT_EVT_OP_SETTINGS_MGMT_ACCESS`, whereby the supplied callback data is
546:c:struct:`settings_mgmt_access`.
547