doc/services/device_mgmt/smp_groups/smp_group_9.rst
.. _mcumgr_smp_group_9:
Shell management ################
Shell management allows passing commands to the shell subsystem over the SMP protocol.
Shell management group defines following commands:
.. table:: :align: center
+-------------------+-----------------------------------------------+
| ``Command ID`` | Command description |
+===================+===============================================+
| ``0`` | Shell command line execute |
+-------------------+-----------------------------------------------+
Shell command line execute
The command allows to execute command line in a similar way to typing it into a shell, but both a request and a response are transported over SMP.
Execute command request header:
.. table:: :align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``2`` | ``9`` | ``0`` |
+--------+--------------+----------------+
CBOR data of request:
.. code-block:: none
{
(str)"argv" : [
(str)<cmd>
(str,opt)<arg>
...
]
}
where:
.. table:: :align: center
+-----------------------+---------------------------------------------------+
| "argv" | array consisting of strings representing command |
| | and its arguments. |
+-----------------------+---------------------------------------------------+
| <cmd> | command to be executed. |
+-----------------------+---------------------------------------------------+
| <arg> | optional arguments to command. |
+-----------------------+---------------------------------------------------+
Command line execute response header fields:
.. table:: :align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``3`` | ``9`` | ``0`` |
+--------+--------------+----------------+
CBOR data of successful response:
.. code-block:: none
{
(str)"o" : (str)
(str)"ret" : (int)
}
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 (and non-group SMP version 2)
.. code-block:: none
{
(str)"rc" : (int)
}
where:
.. table:: :align: center
+------------------+-------------------------------------------------------------------------+
| "o" | command output. |
+------------------+-------------------------------------------------------------------------+
| "ret" | return code from shell command execution. |
+------------------+-------------------------------------------------------------------------+
| "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. |
+------------------+-------------------------------------------------------------------------+
.. 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
restored by enabling :kconfig:option:CONFIG_MCUMGR_GRP_SHELL_LEGACY_RC_RETURN_CODE