michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: device_mgmt: smp: Update rc documentation

Browse source 
Updates documentation on when the rc response is returned.

Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
This commit is contained in:
Jamie McCrae 2022-10-24 11:12:24 +01:00 • committed by Carles Cufí
commit 235ab90230
5 changed files with 109 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

73
doc/services/device_mgmt/smp_groups/smp_group_0.rst
View file

@ -89,7 +89,7 @@ CBOR data of successful response:
(str)"r" : (str)
}
In case of error the CBOR data takes form:
In case of error the CBOR data takes the form:
.. code-block:: none
@ -106,6 +106,7 @@ where:
| "r" | Replying echo string |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
Task statistics command
@ -127,7 +128,7 @@ Task statistics request header fields:
| ``0`` | ``0`` | ``2`` |
+--------+--------------+----------------+
The command sends empty CBOR map as data.
The command sends an empty CBOR map as data.
Task statistics response
@ -144,7 +145,7 @@ Task statistics response header fields:
| ``1`` | ``0`` | ``2`` |
+--------+--------------+----------------+
CBOR data of response:
CBOR data of successful response:
.. code-block:: none
@ -163,9 +164,15 @@ CBOR data of response:
}
...
}
(str)"rc" : (int)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
@ -194,6 +201,7 @@ where:
| "next_checkin" | set to 0 by Zephyr |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
.. note::
@ -220,7 +228,7 @@ Memory pool statistics request header fields:
| ``0`` | ``0`` | ``3`` |
+--------+--------------+----------------+
The command sends empty CBOR map as data.
The command sends an empty CBOR map as data.
Memory pool statistics response
===============================
@ -236,7 +244,7 @@ Memory pool statistics response header fields:
| ``1`` | ``0`` | ``3`` |
+--------+--------------+----------------+
CBOR data of response:
CBOR data of successful response:
.. code-block:: none
@ -248,7 +256,14 @@ CBOR data of response:
(str)"min' : (int)
}
...
(str)"rc" : (int)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
@ -270,6 +285,7 @@ where:
| | during run-time |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
Date-time command
@ -300,7 +316,7 @@ Date-time request header fields:
| ``0`` | ``0`` | ``4`` |
+--------+--------------+----------------+
The command sends empty CBOR map as data.
The command sends an empty CBOR map as data.
Data-time get response
----------------------
@ -316,13 +332,20 @@ Date-time get response header fields:
| ``1`` | ``0`` | ``4`` |
+--------+--------------+----------------+
CBOR data of response:
CBOR data of successful response:
.. code-block:: none
{
(str)"datetime" : (str)
(opt,str)"rc" : (int)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
@ -335,7 +358,7 @@ where:
| | yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes`; |
| | may not appear if 0 |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
@ -390,7 +413,8 @@ Date-time set response header fields:
| ``1`` | ``0`` | ``4`` |
+--------+--------------+----------------+
CBOR data of response:
The command sends an empty CBOR map as data if successful. In case of error the
CBOR data takes the form:
.. code-block:: none
@ -405,6 +429,7 @@ where:
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
System reset
@ -433,7 +458,7 @@ System reset request header fields:
| ``2`` | ``0`` | ``5`` |
+--------+--------------+----------------+
Normally the command sends empty CBOR map as data, but if previous
Normally the command sends an empty CBOR map as data, but if previous
reset attempt has been responded with "rc" code equal ``10`` (busy),
then following map may be send to force the reset:
@ -467,12 +492,13 @@ System reset response header fields
| ``3`` | ``0`` | ``5`` |
+--------+--------------+----------------+
CBOR data of response:
The command sends an empty CBOR map as data if successful. In case of error the
CBOR data takes the form:
.. code-block:: none
{
(opt,str)"rc" : (int)
(str)"rc" : (int)
}
where:
@ -482,7 +508,7 @@ where:
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes`; |
| | may not appear if 0 |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
MCUMGR Parameters
@ -504,7 +530,7 @@ MCUMGR parameters request header fields:
| ``0`` | ``0`` | ``6`` |
+--------+--------------+----------------+
The command sends empty CBOR map as data.
The command sends an empty CBOR map as data.
MCUMGR Parameters Response
==========================
@ -520,14 +546,21 @@ MCUMGR parameters response header fields
| ``2`` | ``0`` | ``6`` |
+--------+--------------+----------------+
CBOR data of response:
CBOR data of successful response:
.. code-block:: none
{
(str)"buf_size" : (uint)
(str)"buf_count" : (uint)
(opt,str)"rc" : (int)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
@ -542,7 +575,7 @@ where:
| "buf_count" | Number of SMP buffers supported |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes`; |
| | may not appear if 0 |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
.. _mcumgr_os_application_info:

18
doc/services/device_mgmt/smp_groups/smp_group_1.rst
View file

@ -125,7 +125,7 @@ CBOR data of successful response:
(str,opt)"splitStatus" : (int)
}
In case of error the CBOR data takes form:
In case of error the CBOR data takes the form:
.. code-block:: none
@ -178,6 +178,7 @@ where:
| | with application part; this is unused by Zephyr |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
| "rsn" | optional string that clarifies reason for an |
| | error; specifically useful for error code ``1``, |
@ -317,13 +318,19 @@ Set state of image request header fields:
| ``3`` | ``1`` | ``1`` |
+--------+--------------+----------------+
CBOR data of response:
CBOR data of successful response:
.. code-block:: none
{
(str,opt)"off" : (uint)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
(str,opt)"rsn" : (str)
}
@ -337,6 +344,7 @@ where:
| "off" | offset of last successfully written byte of update|
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
| "rsn" | Optional string that clarifies reason for an |
| | error; specifically useful for error code ``1``, |
@ -403,7 +411,8 @@ Image erase response header fields:
| ``3`` | ``1`` | ``5`` |
+--------+--------------+----------------+
CBOR data of response:
The command sends an empty CBOR map as data if successful. In case of error the
CBOR data takes the form:
.. code-block:: none
@ -419,6 +428,7 @@ where:
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
| "rsn" | Optional string that clarifies reason for an |
| | error; specifically useful for error code ``1``, |

25
doc/services/device_mgmt/smp_groups/smp_group_2.rst
View file

@ -41,7 +41,7 @@ Statistics group data request header:
| ``0`` | ``2`` | ``0`` |
+--------+--------------+----------------+
CBOR Payload of request:
CBOR data of request:
.. code-block:: none
@ -72,7 +72,7 @@ Statistics group data response header:
| ``1`` | ``2`` | ``0`` |
+--------+--------------+----------------+
CBOR Payload of response:
CBOR data of successful response:
.. code-block:: none
@ -82,6 +82,13 @@ CBOR Payload of response:
(str)<entry_name> : (uint)
...
}
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
@ -102,6 +109,7 @@ where:
| | to unsigned integer type, in a CBOR meaning |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
Statistics: list of groups
@ -129,7 +137,7 @@ Statistics group list request header:
| ``0`` | ``2`` | ``1`` |
+--------+--------------+----------------+
The command sends empty CBOR map as data.
The command sends an empty CBOR map as data.
Statistics: list of groups response
===================================
@ -145,8 +153,7 @@ Statistics group list request header:
| ``1`` | ``2`` | ``1`` |
+--------+--------------+----------------+
CBOR Payload of response:
CBOR data of successful response:
.. code-block:: none
@ -154,6 +161,13 @@ CBOR Payload of response:
(str)"stat_list" : [
(str)<stat_group_name>, ...
]
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
@ -167,4 +181,5 @@ where:
| | array may be empty if there are no groups |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+

31
doc/services/device_mgmt/smp_groups/smp_group_8.rst
View file

@ -102,11 +102,10 @@ CBOR data of successful response:
{
(str)"off" : (uint)
(str)"data" : (byte str)
(str)"rc" : (int)
(str,opt)"len" : (uint)
}
In case of error the CBOR data takes form:
In case of error the CBOR data takes the form:
.. code-block:: none
@ -130,6 +129,7 @@ where:
| | when "off" is 0 |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
In case when "rc" is not 0, success, the other fields will not appear.
@ -218,13 +218,20 @@ File upload response header:
| ``3`` | ``8`` | ``0`` |
+--------+--------------+----------------+
CBOR data of request:
CBOR data of successful response:
.. code-block:: none
{
(str,opt)"off" : (uint)
(str)"rc" : (int)
(str)"off" : (uint)
}
In case of error the CBOR data takes the form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
@ -233,10 +240,10 @@ where:
:align: center
+-----------------------+---------------------------------------------------+
| "off" | offset of last successfully written data; |
| | appears only when "rc" is 0 |
| "off" | offset of last successfully written data. |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
File status
@ -314,8 +321,8 @@ where:
+-----------------------+---------------------------------------------------+
| "len" | length of file (in bytes) |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` (only |
| | present if an error occurred) |
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
In case when "rc" is not 0, success, the other fields will not appear.
@ -417,7 +424,7 @@ CBOR data of successful response:
(str)"output" : (uint or bstr)
}
In case of error the CBOR data takes form:
In case of error the CBOR data takes the form:
.. code-block:: none
@ -431,8 +438,8 @@ where:
:align: center
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` (only |
| | present if an error occurred) |
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
| "type" | type of hash/checksum that was performed |
| | :ref:`mcumgr_group_8_hash_checksum_types` |

8
doc/services/device_mgmt/smp_groups/smp_group_9.rst
View file

@ -86,7 +86,7 @@ CBOR data of successful response:
(str)"ret" : (int)
}
In case of error the CBOR data takes form:
In case of error the CBOR data takes the form:
.. code-block:: none
@ -100,16 +100,14 @@ where:
:align: center
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` (only |
| | present if an error occurred) |
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
| | only appears if non-zero (error condition). |
+-----------------------+---------------------------------------------------+
| "o" | command output |
+-----------------------+---------------------------------------------------+
| "ret" | return code from shell command execution |
+-----------------------+---------------------------------------------------+
In case when "rc" is not 0, success, the other fields will not appear.
.. note::
In older versions of Zephyr, "rc" was used for both the mcumgr status code
and shell command execution return code, this legacy behaviour can be