.. _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.

Shell command line execute request
==================================

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.                    |
    +-----------------------+---------------------------------------------------+

Shell command line execute response
===================================

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`