1.. _mcumgr_smp_group_9:
2
3Shell management
4################
5
6Shell management allows passing commands to the shell subsystem over the SMP
7protocol.
8
9Shell management group defines following commands:
10
11.. table::
12    :align: center
13
14    +-------------------+-----------------------------------------------+
15    | ``Command ID``    | Command description                           |
16    +===================+===============================================+
17    | ``0``             | Shell command line execute                    |
18    +-------------------+-----------------------------------------------+
19
20Shell command line execute
21**************************
22
23The command allows to execute command line in a similar way to typing it into
24a shell, but both a request and a response are transported over SMP.
25
26Shell command line execute request
27==================================
28
29Execute command request header:
30
31.. table::
32    :align: center
33
34    +--------+--------------+----------------+
35    | ``OP`` | ``Group ID`` | ``Command ID`` |
36    +========+==============+================+
37    | ``2``  | ``9``        |  ``0``         |
38    +--------+--------------+----------------+
39
40CBOR data of request:
41
42.. code-block:: none
43
44    {
45        (str)"argv"     : [
46            (str)<cmd>
47            (str,opt)<arg>
48            ...
49        ]
50    }
51
52where:
53
54.. table::
55    :align: center
56
57    +-----------------------+---------------------------------------------------+
58    | "argv"                | array consisting of strings representing command  |
59    |                       | and its arguments.                                |
60    +-----------------------+---------------------------------------------------+
61    | <cmd>                 | command to be executed.                           |
62    +-----------------------+---------------------------------------------------+
63    | <arg>                 | optional arguments to command.                    |
64    +-----------------------+---------------------------------------------------+
65
66Shell command line execute response
67===================================
68
69Command line execute response header fields:
70
71.. table::
72    :align: center
73
74    +--------+--------------+----------------+
75    | ``OP`` | ``Group ID`` | ``Command ID`` |
76    +========+==============+================+
77    | ``3``  | ``9``        |  ``0``         |
78    +--------+--------------+----------------+
79
80CBOR data of successful response:
81
82.. code-block:: none
83
84    {
85        (str)"o"            : (str)
86        (str)"ret"          : (int)
87    }
88
89In case of error the CBOR data takes the form:
90
91.. tabs::
92
93   .. group-tab:: SMP version 2
94
95      .. code-block:: none
96
97          {
98              (str)"err" : {
99                  (str)"group"    : (uint)
100                  (str)"rc"       : (uint)
101              }
102          }
103
104   .. group-tab:: SMP version 1 (and non-group SMP version 2)
105
106      .. code-block:: none
107
108          {
109              (str)"rc"       : (int)
110          }
111
112where:
113
114.. table::
115    :align: center
116
117    +------------------+-------------------------------------------------------------------------+
118    | "o"              | command output.                                                         |
119    +------------------+-------------------------------------------------------------------------+
120    | "ret"            | return code from shell command execution.                               |
121    +------------------+-------------------------------------------------------------------------+
122    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
123    |                  | appears if an error is returned when using SMP version 2.               |
124    +------------------+-------------------------------------------------------------------------+
125    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
126    |                  | non-zero (error condition) when using SMP version 2.                    |
127    +------------------+-------------------------------------------------------------------------+
128    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
129    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
130    +------------------+-------------------------------------------------------------------------+
131
132.. note::
133    In older versions of Zephyr, "rc" was used for both the mcumgr status code
134    and shell command execution return code, this legacy behaviour can be
135    restored by enabling :kconfig:option:`CONFIG_MCUMGR_GRP_SHELL_LEGACY_RC_RETURN_CODE`
136