Shell
=====

The shell runs above the console and provides two functionalities:

-  Processes console input. See the :doc:`Enabling the Console and Shell
   tutorial <../../../tutorials/blinky/blinky_console>` for example of the
   shell.
-  Implements the :doc:`newtmgr <../../../newtmgr/index>` line
   protocol over serial transport.

The shell uses the OS default event queue for shell events and runs in
the context of the main task. An application can, optionally, specify a
dedicated event queue for the shell to use.

.. contents::
  :local:
  :depth: 2

The ``sys/shell`` package implements the shell. To use the shell you
must:

-  Include the ``sys/shell`` package.
-  Set the ``SHELL_TASK`` syscfg setting value to 1 to enable the shell.

**Note:** The functions for the shell API are only compiled and linked
with the application when the ``SHELL_TASK`` setting is enabled. When
you develop a package that supports shell commands, we recommend that
your pakcage define:

1. A syscfg setting that enables shell command processing for your
   package, with a restriction that when this setting is enabled, the
   ``SHELL_TASK`` setting must also be enabled.
2. A conditional dependency on the ``sys/shell`` package when the
   setting defined in 1 above is enabled.

Here are example definitions from the ``syscfg.yml`` and ``pkg.yml``
files for the ``sys/log/full`` package. It defines the ``LOG_CLI``
setting to enable the log command in the shell:

.. code-block:: console

    # sys/log/full syscfg.yml
     LOG_CLI:
            description: 'Expose "log" command in shell.'
            value: 0
            restrictions:
                - SHELL_TASK

    # sys/log/full pkg.yml
    pkg.deps.LOG_CLI:
        - "@apache-mynewt-core/sys/shell"

Description
-----------

Processing Console Input Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The shell's first job is to direct incoming commands to other
subsystems. It parses the incoming character string into tokens and uses
the first token to determine the subsystem command handler to call to
process the command. When the shell calls the command handler, it passes
the other tokens as arguments to the handler.

Registering Command Handlers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A package that implements a shell command must register a command
handler to process the command.

**New in release 1.1**: The shell supports the concept of modules and
allows a package to group shell commands under a name space. To run a
command in the shell, you enter the module name and the command name.
You can set a default module, using the ``select`` command, so that you
only need to enter the command name to run a command from the default
module. You can switch the module you designate as the default module.

There are two methods to register command handlers in Mynewt 1.1:

-  Method 1 (New in release 1.1): Define and register a set of commands
   for a module. This method allows grouping shell commands into
   namespaces. A package calls the ``shell_register()`` function to
   define a module and register the command handlers for the module.

   **Note:** The ``SHELL_MAX_MODULES`` syscfg setting specifies the
   maximum number of modules that can be registered. You can increase
   this value if your application and the packages it includes register
   more than the default value.

-  Method 2: Register a command handler without defining a module. A
   package calls the ``shell_cmd_register()`` function defined in Mynewt
   1.0 to register a command handler. When a shell command is registered
   using this method, the command is automatically added to the
   ``compat`` module. The ``compat`` module supports backward
   compatibility for all the shell commands that are registered using
   the ``shell_cmd_register()`` function.

   **Notes:**

   -  The ``SHELL_COMPAT`` syscfg setting must be set to 1 to enable
      backward compatibility support and the ``shell_cmd_register()``
      function. Since Mynewt packages use method 2 to register shell
      commands and Mynewt plans to continue this support in future
      releases, you must keep the default setting value of 1.

   -  The ``SHELL_MAX_COMPAT_COMMANDS`` syscfg setting specifies the
      maximum number of command handlers that can be registered using
      this method. You can increase this value if your application and
      the packages it includes register more than the default value.

Enabling Help Information for Shell Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The shell supports command help. A package that supports command help
initializes the ``struct shell_cmd`` data structure with help text for
the command before it registers the command with the shell. The
``SHELL_CMD_HELP`` syscfg setting enables or disbles help support for
all shell commands. The feature is enabled by default.

**Note:** A package that implements help for a shell command should only
initialize the help data structures within the
``#if MYNEWT_VAL(SHELL_CMD_HELP)`` preprocessor directive.

Enabling the OS and Prompt Shell Modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The shell implements the ``os`` and ``prompt`` modules. These modules
support the shell commands to view OS resources.

The ``os`` module implements commands to list task and mempool usage
information and to view and change the time of day. The
``SHELL_OS_MODULE`` syscfg setting enables or disables the module. The
module is enabled by default.

The ``prompt`` module implements the ``ticks`` command that controls
whether to print the current os ticks in the prompt. The
``SHELL_PROMPT_MODULE`` syscfg setting enables or disables this module.
The module is disabled by default.

Enabling Command Name Completion
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The shell supports command name completion. The ``SHELL_COMPLETION``
syscfg setting enables or disables the feature. The feature is enabled
by default.

Processing Newtmgr Line Protocol Over Serial Transport
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The shell's second job is to handle packet framing, encoding, and
decoding of newtmgr protocol messages that are sent over the console.
The Newtmgr serial transport package
(``mgmt/newtmgr/transport/newtmgr_shell``) calls the
``shell_nlip_input_register()`` function to register a handler that the
shell calls when it receives newtmgr request messages.

The ``SHELL_NEWTMGR`` syscfg setting specifies whether newtmgr is
enabled over shell. The setting is enabled by default.

Data Structures
---------------

The ``struct shell_cmd`` data structure represents a shell command and
is used to register a command.

.. code-block:: console

    struct shell_cmd {
        const char *sc_cmd;
        shell_cmd_func_t sc_cmd_func;
        const struct shell_cmd_help *help;
    };

+------------+----------------+
| Element    | Description    |
+============+================+
| ``sc_cmd`` | Character      |
|            | string of the  |
|            | command name.  |
+------------+----------------+
| ``sc_cmd_f | Pointer to the |
| unc_t``    | command        |
|            | handler that   |
|            | processes the  |
|            | command.       |
+------------+----------------+
| ``help``   | Pointer to the |
|            | shell\_cmd\_he |
|            | lp             |
|            | structure. If  |
|            | the pointer is |
|            | NULL, help     |
|            | information is |
|            | not provided.  |
+------------+----------------+

The ``sc_cmd_func_t`` is the command handler function type.

.. code:: c

    typedef int (*shell_cmd_func_t)(int argc, char *argv[]);

The ``argc`` parameter specifies the number of command line arguments
and the ``argv`` parameter is an array of character pointers to the
command arguments. The ``SHELL_CMD_ARGC_MAX`` syscfg setting specifies
the maximum number of command line arguments that any shell command can
have. This value must be increased if a shell command requires more than
``SHELL_CMD_ARGC_MAX`` number of command line arguments.

The ``struct shell_module`` data structure represents a shell module. It
is used to register a shell module and the shell commands for the
module.

.. code:: c

    struct shell_module {
        const char *name;
        const struct shell_cmd *commands;
    };

+---------------+----------------+
| Eleme   nt    | Description    |
+===============+================+
| ``name``      | Character      |
|               | string of the  |
|               | module name.   |
+---------------+----------------+
| ``commands``  | Array of       |
|               | ``shell_cmd``  |
|               | structures     |
|               | that specify   |
|               | the commands   |
|               | for the        |
|               | module. The    |
|               | ``sc_cmd``,    |
|               | ``sc_cmd_func``|
|               | , and ``help`` |
|               | fields in the  |
|               | last entry     |
|               | must be set to |
|               | NULL to        |
|               | indicate the   |
|               | last entry in  |
|               | the array.     |
+---------------+----------------+

**Note**: A command handler registered via the ``shell_cmd_register()``
function is automatically added to the ``compat`` module.

The ``struct shell_param`` and ``struct shell_cmd_help`` data
structures hold help texts for a shell command.

.. code:: c

    struct shell_param {
        const char *param_name;
        const char *help;
    };

+------------------+--------------------------------------------------------+
| Element          | Description                                            |
+==================+========================================================+
| ``param_name``   | Character string of the command parameter name.        |
+------------------+--------------------------------------------------------+
| ``help``         | Character string of the help text for the parameter.   |
+------------------+--------------------------------------------------------+

.. code:: c

    struct shell_cmd_help {
        const char *summary;
        const char *usage;
        const struct shell_param *params;
    };

+------------+----------------+
| Element    | Description    |
+============+================+
| ``summary``| Character      |
|            | string of a    |
|            | short          |
|            | description of |
|            | the command.   |
+------------+----------------+
| ``usage``  | Character      |
|            | string of a    |
|            | usage          |
|            | description    |
|            | for the        |
|            | command.       |
+------------+----------------+
| ``params`` | Array of       |
|            | ``shell_param` |
|            | `              |
|            | structures     |
|            | that describe  |
|            | each parameter |
|            | for the        |
|            | command. The   |
|            | last           |
|            | ``struct shell |
|            | _param``       |
|            | in the array   |
|            | must have the  |
|            | ``param_name`` |
|            | and ``help``   |
|            | fields set to  |
|            | NULL to        |
|            | indicate the   |
|            | last entry in  |
|            | the array.     |
+------------+----------------+

API
---

.. doxygenfile:: sys/shell/include/shell/shell.h
