1.. _mcumgr_smp_group_2:
2
3Statistics management
4#####################
5
6Statistics management allows to obtain data gathered by Statistics subsystem
7of Zephyr, enabled with :kconfig:option:`CONFIG_STATS`.
8
9Statistics management group defines commands:
10
11.. table::
12    :align: center
13
14    +-------------------+-----------------------------------------------+
15    | ``Command ID``    | Command description                           |
16    +===================+===============================================+
17    | ``0``             | Group data                                    |
18    +-------------------+-----------------------------------------------+
19    | ``1``             | List groups                                   |
20    +-------------------+-----------------------------------------------+
21
22Statistics: group data
23**********************
24
25The command is used to obtain data for group specified by a name.
26The name is one of group names as registered, with
27:c:macro:`STATS_INIT_AND_REG` macro or :c:func:`stats_init_and_reg` function
28call, within module that gathers the statistics.
29
30Statistics: group data request
31==============================
32
33Statistics group data request header:
34
35.. table::
36    :align: center
37
38    +--------+--------------+----------------+
39    | ``OP`` | ``Group ID`` | ``Command ID`` |
40    +========+==============+================+
41    | ``0``  | ``2``        |  ``0``         |
42    +--------+--------------+----------------+
43
44CBOR data of request:
45
46.. code-block:: none
47
48    {
49        (str)"name" :  (str)
50    }
51
52where:
53
54.. table::
55    :align: center
56
57    +-----------------------+---------------------------------------------------+
58    | "name"                | group name.                                       |
59    +-----------------------+---------------------------------------------------+
60
61Statistics: group data response
62===============================
63
64Statistics group data response header:
65
66.. table::
67    :align: center
68
69    +--------+--------------+----------------+
70    | ``OP`` | ``Group ID`` | ``Command ID`` |
71    +========+==============+================+
72    | ``1``  | ``2``        |  ``0``         |
73    +--------+--------------+----------------+
74
75CBOR data of successful response:
76
77.. code-block:: none
78
79    {
80        (str)"name"     : (str)
81        (str)"fields"   : {
82            (str)<entry_name> : (uint)
83            ...
84        }
85    }
86
87In case of error the CBOR data takes the form:
88
89
90.. tabs::
91
92   .. group-tab:: SMP version 2
93
94      .. code-block:: none
95
96          {
97              (str)"err" : {
98                  (str)"group"    : (uint)
99                  (str)"rc"       : (uint)
100              }
101          }
102
103   .. group-tab:: SMP version 1 (and non-group SMP version 2)
104
105      .. code-block:: none
106
107          {
108              (str)"rc"       : (int)
109          }
110
111where:
112
113.. table::
114    :align: center
115
116    +------------------+-------------------------------------------------------------------------+
117    | "name"           | this is name of group the response contains data for.                   |
118    +------------------+-------------------------------------------------------------------------+
119    | "fields"         | this is map of entries within groups that consists of pairs where the   |
120    |                  | entry name is mapped to value it represents in statistics.              |
121    +------------------+-------------------------------------------------------------------------+
122    | <entry_name>     | single entry to value mapping; value is hardcoded to unsigned integer   |
123    |                  | type, in a CBOR meaning.                                                |
124    +------------------+-------------------------------------------------------------------------+
125    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
126    |                  | appears if an error is returned when using SMP version 2.               |
127    +------------------+-------------------------------------------------------------------------+
128    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
129    |                  | non-zero (error condition) when using SMP version 2.                    |
130    +------------------+-------------------------------------------------------------------------+
131    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
132    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
133    +------------------+-------------------------------------------------------------------------+
134
135Statistics: list of groups
136**************************
137
138The command is used to obtain list of groups of statistics that are gathered
139on a device. This is a list of names as given to groups with
140:c:macro:`STATS_INIT_AND_REG` macro or :c:func:`stats_init_and_reg` function
141calls, within module that gathers the statistics; this means that this command
142may be considered optional as it is known during compilation what groups will
143be included into build and listing them is not needed prior to issuing a query.
144
145Statistics: list of groups request
146==================================
147
148Statistics group list request header:
149
150.. table::
151    :align: center
152
153    +--------+--------------+----------------+
154    | ``OP`` | ``Group ID`` | ``Command ID`` |
155    +========+==============+================+
156    | ``0``  | ``2``        |  ``1``         |
157    +--------+--------------+----------------+
158
159The command sends an empty CBOR map as data.
160
161Statistics: list of groups response
162===================================
163
164Statistics group list request header:
165
166.. table::
167    :align: center
168
169    +--------+--------------+----------------+
170    | ``OP`` | ``Group ID`` | ``Command ID`` |
171    +========+==============+================+
172    | ``1``  | ``2``        |  ``1``         |
173    +--------+--------------+----------------+
174
175CBOR data of successful response:
176
177.. code-block:: none
178
179    {
180        (str)"stat_list" :  [
181            (str)<stat_group_name>, ...
182        ]
183    }
184
185In case of error the CBOR data takes the form:
186
187
188.. tabs::
189
190   .. group-tab:: SMP version 2
191
192      .. code-block:: none
193
194          {
195              (str)"err" : {
196                  (str)"group"    : (uint)
197                  (str)"rc"       : (uint)
198              }
199          }
200
201   .. group-tab:: SMP version 1 (and non-group SMP version 2)
202
203      .. code-block:: none
204
205          {
206              (str)"rc"       : (int)
207          }
208
209where:
210
211.. table::
212    :align: center
213
214    +------------------+-------------------------------------------------------------------------+
215    | "stat_list"      | array of strings representing group names; this array may be empty if   |
216    |                  | there are no groups.                                                    |
217    +------------------+-------------------------------------------------------------------------+
218    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
219    |                  | appears if an error is returned when using SMP version 2.               |
220    +------------------+-------------------------------------------------------------------------+
221    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
222    |                  | non-zero (error condition) when using SMP version 2.                    |
223    +------------------+-------------------------------------------------------------------------+
224    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
225    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
226    +------------------+-------------------------------------------------------------------------+
227