doc: mcumgr: Add documentation for SMP group 10 (enum)
Adds documentation for enumeration management group Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
This commit is contained in:
Jamie McCrae
Carles Cufí
parent
e577b140c3
commit
4f5c6da4e5
2 changed files with 438 additions and 0 deletions
|
|
@ -28,4 +28,5 @@ SMP Groups
|
|||
smp_groups/smp_group_3.rst
|
||||
smp_groups/smp_group_8.rst
|
||||
smp_groups/smp_group_9.rst
|
||||
smp_groups/smp_group_10.rst
|
||||
smp_groups/smp_group_63.rst
|
||||
|
|
|
|||
437
doc/services/device_mgmt/smp_groups/smp_group_10.rst
Normal file
437
doc/services/device_mgmt/smp_groups/smp_group_10.rst
Normal file
|
|
@ -0,0 +1,437 @@
|
|||
.. _mcumgr_smp_group_10:
|
||||
|
||||
Enumeration Management Group
|
||||
#############################
|
||||
|
||||
Enumeration management group defines the following commands:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+----------------+-----------------------------+
|
||||
| ``Command ID`` | Command description |
|
||||
+================+=============================+
|
||||
| ``0`` | Count of supported groups |
|
||||
+----------------+-----------------------------+
|
||||
| ``1`` | List supported groups |
|
||||
+----------------+-----------------------------+
|
||||
| ``2`` | Fetch single group ID |
|
||||
+----------------+-----------------------------+
|
||||
| ``3`` | Details on supported groups |
|
||||
+----------------+-----------------------------+
|
||||
|
||||
Count of supported groups command
|
||||
*********************************
|
||||
|
||||
Count of supported groups returns the total number of MCUmgr command groups that a device supports.
|
||||
|
||||
Count of supported groups request
|
||||
=================================
|
||||
|
||||
Read setting request header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``0`` | ``10`` | ``0`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
The command sends an empty CBOR map as data.
|
||||
|
||||
Count of supported groups response
|
||||
==================================
|
||||
|
||||
Count of supported groups response header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``1`` | ``10`` | ``0`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
CBOR data of successful response:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"count" : (uint)
|
||||
}
|
||||
|
||||
In case of error the CBOR data takes the form:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: SMP version 2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"err" : {
|
||||
(str)"group" : (uint)
|
||||
(str)"rc" : (uint)
|
||||
}
|
||||
}
|
||||
|
||||
.. group-tab:: SMP version 1
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"rc" : (int)
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "count" | contains the total number of supported MCUmgr groups on the device. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "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. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
|
||||
List supported groups command
|
||||
*****************************
|
||||
|
||||
List supported groups command allows listing the group IDs of supported MCUmgr groups on the
|
||||
device.
|
||||
|
||||
List supported groups request
|
||||
=============================
|
||||
|
||||
List supported groups request header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``0`` | ``10`` | ``1`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
The command sends an empty CBOR map as data.
|
||||
|
||||
List supported groups response
|
||||
==============================
|
||||
|
||||
List supported groups response header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``1`` | ``10`` | ``1`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
CBOR data of successful response:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"groups" : [
|
||||
(uint)
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
In case of error the CBOR data takes the form:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: SMP version 2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"err" : {
|
||||
(str)"group" : (uint)
|
||||
(str)"rc" : (uint)
|
||||
}
|
||||
}
|
||||
|
||||
.. group-tab:: SMP version 1
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"rc" : (int)
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "groups" | contains a list of the supported MCUmgr group IDs on the device. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "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. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
|
||||
Fetch single group ID command
|
||||
*****************************
|
||||
|
||||
Fetch single group ID command allows listing the group IDs of supported MCUmgr groups on the
|
||||
device, one by one.
|
||||
|
||||
Fetch single group ID request
|
||||
=============================
|
||||
|
||||
Fetch single group ID request header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``0`` | ``10`` | ``2`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
CBOR data of request:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str,opt)"index" : (uint)
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+----------+-----------------------------------------------------------------+
|
||||
| "index" | contains the (0-based) index of the group to return information |
|
||||
| | on, can be omitted to return the first group's details. |
|
||||
+----------+-----------------------------------------------------------------+
|
||||
|
||||
Fetch single group ID response
|
||||
==============================
|
||||
|
||||
Fetch single group ID response header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``1`` | ``10`` | ``2`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
CBOR data of successful response:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"group" : (uint)
|
||||
(str,opt)"end" : (bool)
|
||||
}
|
||||
|
||||
In case of error the CBOR data takes the form:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: SMP version 2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"err" : {
|
||||
(str)"group" : (uint)
|
||||
(str)"rc" : (uint)
|
||||
}
|
||||
}
|
||||
|
||||
.. group-tab:: SMP version 1
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"rc" : (int)
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "group" | contains the list of the supported MCUmgr group IDs on the device. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "end" | will be set to true if the listed group is the final supported group on |
|
||||
| | the device, otherwise will be omitted. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "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. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
|
||||
Details on supported groups command
|
||||
***********************************
|
||||
|
||||
Details on supported groups command allows fetching details on each supported MCUmgr group, such
|
||||
as the name and number of handlers. A device can specify an allow list of groups to return details
|
||||
on or details on all groups can be returned.
|
||||
|
||||
This command is optional, it can be enabled using :kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS`.
|
||||
The optional name and number of handlers can be enabled/disabled with
|
||||
:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_NAME` and
|
||||
:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_HANDLERS`.
|
||||
|
||||
Details on supported groups request
|
||||
===================================
|
||||
|
||||
Details on supported groups request header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``0`` | ``10`` | ``3`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Details on all groups
|
||||
|
||||
The command sends an empty CBOR map as data.
|
||||
|
||||
.. group-tab:: Details on specified groups
|
||||
|
||||
CBOR data of request:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"groups" : [
|
||||
(uint)
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+----------+--------------------------------------------------------------+
|
||||
| "groups" | contains a list of the MCUmgr group IDs to fetch details on. |
|
||||
+----------+--------------------------------------------------------------+
|
||||
|
||||
Details on supported groups response
|
||||
====================================
|
||||
|
||||
Details on supported groups response header fields:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+--------+--------------+----------------+
|
||||
| ``OP`` | ``Group ID`` | ``Command ID`` |
|
||||
+========+==============+================+
|
||||
| ``1`` | ``10`` | ``3`` |
|
||||
+--------+--------------+----------------+
|
||||
|
||||
CBOR data of successful response:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"groups" : [
|
||||
{
|
||||
(str)"group" : (uint)
|
||||
(str,opt)"name" : (str)
|
||||
(str,opt)"handlers" : (uint)
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
In case of error the CBOR data takes the form:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: SMP version 2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"err" : {
|
||||
(str)"group" : (uint)
|
||||
(str)"rc" : (uint)
|
||||
}
|
||||
}
|
||||
|
||||
.. group-tab:: SMP version 1
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
{
|
||||
(str)"rc" : (int)
|
||||
}
|
||||
|
||||
where:
|
||||
|
||||
.. table::
|
||||
:align: center
|
||||
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "group" | the group ID of the MCUmgr command group. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "name" | the name of the MCUmgr command group. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "handlers" | the number of handlers that the MCUmgr command group supports. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
| "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. |
|
||||
+------------------+-------------------------------------------------------------------------+
|
||||
|
||||
Details on supported groups callback
|
||||
************************************
|
||||
|
||||
There is a details on supported groups MCUmgr callback available (see :ref:`mcumgr_callbacks` for
|
||||
details on callbacks) which allows for applications/modules to add additional fields to this
|
||||
response. This callback can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_HOOK`,
|
||||
registered with the event :c:enumerator:`MGMT_EVT_OP_ENUM_MGMT_DETAILS`, whereby the supplied
|
||||
callback data is :c:struct:`enum_mgmt_detail_output`. Note that
|
||||
:kconfig:option:`CONFIG_MCUMGR_GRP_ENUM_DETAILS_STATES` will need incrementing by the number of
|
||||
additional extra fields that are added.
|
||||
Loading…
Add table
Add a link
Reference in a new issue