1.. _mcumgr_smp_group_10:
2
3Enumeration Management Group
4#############################
5
6Enumeration management group defines the following commands:
7
8.. table::
9    :align: center
10
11    +----------------+-----------------------------+
12    | ``Command ID`` | Command description         |
13    +================+=============================+
14    | ``0``          | Count of supported groups   |
15    +----------------+-----------------------------+
16    | ``1``          | List supported groups       |
17    +----------------+-----------------------------+
18    | ``2``          | Fetch single group ID       |
19    +----------------+-----------------------------+
20    | ``3``          | Details on supported groups |
21    +----------------+-----------------------------+
22
23Count of supported groups command
24*********************************
25
26Count of supported groups returns the total number of MCUmgr command groups that a device supports.
27
28Count of supported groups request
29=================================
30
31Read setting request header fields:
32
33.. table::
34    :align: center
35
36    +--------+--------------+----------------+
37    | ``OP`` | ``Group ID`` | ``Command ID`` |
38    +========+==============+================+
39    | ``0``  | ``10``       | ``0``          |
40    +--------+--------------+----------------+
41
42The command sends an empty CBOR map as data.
43
44Count of supported groups response
45==================================
46
47Count of supported groups response header fields:
48
49.. table::
50    :align: center
51
52    +--------+--------------+----------------+
53    | ``OP`` | ``Group ID`` | ``Command ID`` |
54    +========+==============+================+
55    | ``1``  | ``10``       | ``0``          |
56    +--------+--------------+----------------+
57
58CBOR data of successful response:
59
60.. code-block:: none
61
62    {
63        (str)"count"        : (uint)
64    }
65
66In case of error the CBOR data takes the form:
67
68.. tabs::
69
70   .. group-tab:: SMP version 2
71
72      .. code-block:: none
73
74          {
75              (str)"err" : {
76                  (str)"group"    : (uint)
77                  (str)"rc"       : (uint)
78              }
79          }
80
81   .. group-tab:: SMP version 1
82
83      .. code-block:: none
84
85          {
86              (str)"rc"       : (int)
87          }
88
89where:
90
91.. table::
92    :align: center
93
94    +------------------+-------------------------------------------------------------------------+
95    | "count"          | contains the total number of supported MCUmgr groups on the device.     |
96    +------------------+-------------------------------------------------------------------------+
97    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
98    |                  | appears if an error is returned when using SMP version 2.               |
99    +------------------+-------------------------------------------------------------------------+
100    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
101    |                  | non-zero (error condition) when using SMP version 2.                    |
102    +------------------+-------------------------------------------------------------------------+
103    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
104    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
105    +------------------+-------------------------------------------------------------------------+
106
107List supported groups command
108*****************************
109
110List supported groups command allows listing the group IDs of supported MCUmgr groups on the
111device.
112
113List supported groups request
114=============================
115
116List supported groups request header fields:
117
118.. table::
119    :align: center
120
121    +--------+--------------+----------------+
122    | ``OP`` | ``Group ID`` | ``Command ID`` |
123    +========+==============+================+
124    | ``0``  | ``10``       | ``1``          |
125    +--------+--------------+----------------+
126
127The command sends an empty CBOR map as data.
128
129List supported groups response
130==============================
131
132List supported groups response header fields:
133
134.. table::
135    :align: center
136
137    +--------+--------------+----------------+
138    | ``OP`` | ``Group ID`` | ``Command ID`` |
139    +========+==============+================+
140    | ``1``  | ``10``       | ``1``          |
141    +--------+--------------+----------------+
142
143CBOR data of successful response:
144
145.. code-block:: none
146
147    {
148        (str)"groups" : [
149            (uint)
150            ...
151        ]
152    }
153
154In case of error the CBOR data takes the form:
155
156.. tabs::
157
158   .. group-tab:: SMP version 2
159
160      .. code-block:: none
161
162          {
163              (str)"err" : {
164                  (str)"group"    : (uint)
165                  (str)"rc"       : (uint)
166              }
167          }
168
169   .. group-tab:: SMP version 1
170
171      .. code-block:: none
172
173          {
174              (str)"rc"       : (int)
175          }
176
177where:
178
179.. table::
180    :align: center
181
182    +------------------+-------------------------------------------------------------------------+
183    | "groups"         | contains a list of the supported MCUmgr group IDs on the device.        |
184    +------------------+-------------------------------------------------------------------------+
185    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
186    |                  | appears if an error is returned when using SMP version 2.               |
187    +------------------+-------------------------------------------------------------------------+
188    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
189    |                  | non-zero (error condition) when using SMP version 2.                    |
190    +------------------+-------------------------------------------------------------------------+
191    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
192    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
193    +------------------+-------------------------------------------------------------------------+
194
195Fetch single group ID command
196*****************************
197
198Fetch single group ID command allows listing the group IDs of supported MCUmgr groups on the
199device, one by one.
200
201Fetch single group ID request
202=============================
203
204Fetch single group ID request header fields:
205
206.. table::
207    :align: center
208
209    +--------+--------------+----------------+
210    | ``OP`` | ``Group ID`` | ``Command ID`` |
211    +========+==============+================+
212    | ``0``  | ``10``       | ``2``          |
213    +--------+--------------+----------------+
214
215CBOR data of request:
216
217.. code-block:: none
218
219    {
220        (str,opt)"index" : (uint)
221    }
222
223where:
224
225.. table::
226    :align: center
227
228    +----------+-----------------------------------------------------------------+
229    | "index"  | contains the (0-based) index of the group to return information |
230    |          | on, can be omitted to return the first group's details.         |
231    +----------+-----------------------------------------------------------------+
232
233Fetch single group ID response
234==============================
235
236Fetch single group ID response header fields:
237
238.. table::
239    :align: center
240
241    +--------+--------------+----------------+
242    | ``OP`` | ``Group ID`` | ``Command ID`` |
243    +========+==============+================+
244    | ``1``  | ``10``       | ``2``          |
245    +--------+--------------+----------------+
246
247CBOR data of successful response:
248
249.. code-block:: none
250
251    {
252        (str)"group"    : (uint)
253        (str,opt)"end"  : (bool)
254    }
255
256In case of error the CBOR data takes the form:
257
258.. tabs::
259
260   .. group-tab:: SMP version 2
261
262      .. code-block:: none
263
264          {
265              (str)"err" : {
266                  (str)"group"    : (uint)
267                  (str)"rc"       : (uint)
268              }
269          }
270
271   .. group-tab:: SMP version 1
272
273      .. code-block:: none
274
275          {
276              (str)"rc"       : (int)
277          }
278
279where:
280
281.. table::
282    :align: center
283
284    +------------------+-------------------------------------------------------------------------+
285    | "group"          | contains the list of the supported MCUmgr group IDs on the device.      |
286    +------------------+-------------------------------------------------------------------------+
287    | "end"            | will be set to true if the listed group is the final supported group on |
288    |                  | the device, otherwise will be omitted.                                  |
289    +------------------+-------------------------------------------------------------------------+
290    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
291    |                  | appears if an error is returned when using SMP version 2.               |
292    +------------------+-------------------------------------------------------------------------+
293    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
294    |                  | non-zero (error condition) when using SMP version 2.                    |
295    +------------------+-------------------------------------------------------------------------+
296    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
297    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
298    +------------------+-------------------------------------------------------------------------+
299
300Details on supported groups command
301***********************************
302
303Details on supported groups command allows fetching details on each supported MCUmgr group, such
304as the name and number of handlers. A device can specify an allow list of groups to return details
305on or details on all groups can be returned.
306
307This command is optional, it can be enabled using :kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS`.
308The optional name and number of handlers can be enabled/disabled with
309:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_NAME` and
310:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_HANDLERS`.
311
312Details on supported groups request
313===================================
314
315Details on supported groups request header fields:
316
317.. table::
318    :align: center
319
320    +--------+--------------+----------------+
321    | ``OP`` | ``Group ID`` | ``Command ID`` |
322    +========+==============+================+
323    | ``0``  | ``10``       | ``3``          |
324    +--------+--------------+----------------+
325
326.. tabs::
327
328   .. group-tab:: Details on all groups
329
330      The command sends an empty CBOR map as data.
331
332   .. group-tab:: Details on specified groups
333
334      CBOR data of request:
335
336      .. code-block:: none
337
338          {
339              (str)"groups" : [
340                  (uint)
341                  ...
342              ]
343          }
344
345      where:
346
347      .. table::
348          :align: center
349
350          +----------+--------------------------------------------------------------+
351          | "groups" | contains a list of the MCUmgr group IDs to fetch details on. |
352          +----------+--------------------------------------------------------------+
353
354Details on supported groups response
355====================================
356
357Details on supported groups response header fields:
358
359.. table::
360    :align: center
361
362    +--------+--------------+----------------+
363    | ``OP`` | ``Group ID`` | ``Command ID`` |
364    +========+==============+================+
365    | ``1``  | ``10``       | ``3``          |
366    +--------+--------------+----------------+
367
368CBOR data of successful response:
369
370.. code-block:: none
371
372    {
373        (str)"groups" : [
374            {
375                (str)"group"          : (uint)
376                (str,opt)"name"       : (str)
377                (str,opt)"handlers"   : (uint)
378            }
379            ...
380        ]
381    }
382
383In case of error the CBOR data takes the form:
384
385.. tabs::
386
387   .. group-tab:: SMP version 2
388
389      .. code-block:: none
390
391          {
392              (str)"err" : {
393                  (str)"group"    : (uint)
394                  (str)"rc"       : (uint)
395              }
396          }
397
398   .. group-tab:: SMP version 1
399
400      .. code-block:: none
401
402          {
403              (str)"rc"       : (int)
404          }
405
406where:
407
408.. table::
409    :align: center
410
411    +------------------+-------------------------------------------------------------------------+
412    | "group"          | the group ID of the MCUmgr command group.                               |
413    +------------------+-------------------------------------------------------------------------+
414    | "name"           | the name of the MCUmgr command group.                                   |
415    +------------------+-------------------------------------------------------------------------+
416    | "handlers"       | the number of handlers that the MCUmgr command group supports.          |
417    +------------------+-------------------------------------------------------------------------+
418    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
419    |                  | appears if an error is returned when using SMP version 2.               |
420    +------------------+-------------------------------------------------------------------------+
421    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
422    |                  | non-zero (error condition) when using SMP version 2.                    |
423    +------------------+-------------------------------------------------------------------------+
424    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
425    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
426    +------------------+-------------------------------------------------------------------------+
427
428Details on supported groups callback
429************************************
430
431There is a details on supported groups MCUmgr callback available (see :ref:`mcumgr_callbacks` for
432details on callbacks) which allows for applications/modules to add additional fields to this
433response. This callback can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_HOOK`,
434registered with the event :c:enumerator:`MGMT_EVT_OP_ENUM_MGMT_DETAILS`, whereby the supplied
435callback data is :c:struct:`enum_mgmt_detail_output`. Note that
436:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_STATES` will need incrementing by the number of
437additional extra fields that are added.
438