nuttx/Documentation/applications/nsh/customizing.rst

========================*
Customizing the NuttShell
========================*

**Overview.** The NuttShell (NSH) is a simple shell application that may
be used with NuttX. It supports a variety of commands and is (very)
loosely based on the Bash shell and the common utilities used with Bash
shell programming. The paragraphs in this appendix will focus on
customizing NSH: Adding new commands, changing the initialization
sequence, etc.

The NSH Library and NSH Initialization
======================================

**Overview.** NSH is implemented as a library that can be found at
``apps/nshlib``. As a library, it can be custom built into any
application that follows the NSH initialization sequence described
below. As an example, the code at ``apps/examples/nsh/nsh_main.c``
illustrates how to start NSH and the logic there was intended to be
incorporated into your own custom code. Although code was generated
simply as an example, in the end most people just use this example code
as their application ``main()`` function. That initialization performed
by that example is discussed in the following paragraphs.

NSH Initialization sequence
---------------------------

The NSH start-up sequence is very simple. As an example, the code at
``apps/system/nsh/nsh_main.c`` illustrates how to start NSH. It simple
does the following:

  #. This function calls ``nsh_initialize()`` which initializes the NSH
     library. ``nsh_initialize()`` is described in more detail below.

  #. If the Telnetconsole is enabled, it calls ``nsh_telnetstart()`` which
     resides in the NSH library. ``nsh_telnetstart()`` will start the
     Telnet daemon that will listen for Telnet connections and start
     remote NSH sessions.

  #. If a local console is enabled (probably on a serial port), then
     ``nsh_consolemain()`` is called. ``nsh_consolemain()`` also resides
     in the NSH library. ``nsh_consolemain()`` does not return so that
     finished the entire NSH initialization sequence.

``nsh_initialize()``
--------------------

The NSH initialization function, ``nsh_initialize()``, be found in
``apps/nshlib/nsh_init.c``. It does only four things:

  #. ``nsh_romfsetc()``: If so configured, it executes NSH system init and
     start-up script that can be found at ``/etc/init.d/rc.sysinit`` and
     ``/etc/init.d/rcS`` in the target file system. The ``nsh_romfsetc()``
     function can be found in ``apps/nshlib/nsh_romfsetc.c``.
     This function will (1) register a ROMFS file system, then (2) mount
     the ROMFS file system. ``/etc`` is the default location where a
     read-only, ROMFS file system is mounted by ``nsh_romfsetc()``.

     The ROMFS image is, itself, just built into the firmware. By default,
     this ``rc.sysinit`` system init script contains the following logic::

        # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX

        mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
        mkfatfs /dev/ramXXXMKRDMINORXXX
        mount -t vfat /dev/ramXXXMKRDMINORXXX XXXRDMOUNTPOINTXXX

     Where the ``XXXX*XXXX`` strings get replaced in the template when the
     ROMFS image is created:

     -  ``XXXMKRDMINORXXX`` will become the RAM device minor number.
        Default: 0

     -  ``XXMKRDSECTORSIZEXXX`` will become the RAM device sector size

     -  ``XXMKRDBLOCKSXXX`` will become the number of sectors in the
        device.

     -  ``XXXRDMOUNTPOINTXXX`` will become the configured mount point.
        Default: ``/etc``

     By default, the substituted values would yield an ``rc.sysinit`` file like::

        # Create a RAMDISK and mount it at /tmp

        mkrd -m 1 -s 512 1024
        mkfatfs /dev/ram1
        mount -t vfat /dev/ram1 /tmp

     This script will, then:

     -  Create a RAMDISK of size 512*1024 bytes at ``/dev/ram1``,

     -  Format a FAT file system on the RAM disk at ``/dev/ram1``, and
        then

     -  Mount the FAT file system at a configured mountpoint, ``/tmp``.

     This ``rc.sysinit.template`` template file can be found at
     ``apps/nshlib/rc.sysinit.template``. The resulting ROMFS file system can be
     found in ``apps/nshlib/nsh_romfsimg.h``.

  #. ``board_app_initialize()``: Next any architecture-specific NSH
     initialization will be performed (if any). For the STM3240G-EVAL,
     this architecture specific initialization can be found at
     ``boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c``. This it does
     things like: (1) Initialize SPI devices, (2) Initialize SDIO, and (3)
     mount any SD cards that may be inserted.

  #. ``nsh_netinit()``: The ``nsh_netinit()`` function can be found in
     ``apps/nshlib/nsh_netinit.c``.

  #. The start-up script ``rcS`` is executed after the system-init script
     to startup some application and other system service.

     This ``rcS`` template file can be found at
     ``apps/nshlib/rcS.template``. The resulting ROMFS file system can be
     found in ``apps/nshlib/nsh_romfsimg.h``.

NSH Commands
============

**Overview.** NSH supports a variety of commands as part of the NSH
program. All of the NSH commands are listed in the NSH documentation
`above <#cmdoverview>`__. Not all of these commands may be available at
any time, however. Many commands depend upon certain NuttX configuration
options. You can enter the help command at the NSH prompt to see the
commands actual available:

For example, if network support is disabled, then all network-related
commands will be missing from the list of commands presented by
'``nsh> help``'. You can see the specific command dependencies in the
table `above <#cmddependencies>`__.

Adding New NSH Commands
-----------------------

New commands can be added to the NSH very easily. You simply need to add
two things:

  #. The implementation of your command, and

  #. A new entry in the NSH command table

**Implementation of Your Command.** For example, if you want to add a
new a new command called ``mycmd`` to NSH, you would first implement the
``mycmd`` code in a function with this prototype:

.. code-block:: c

  int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv);

The ``argc`` and ``argv`` are used to pass command line arguments to the
NSH command. Command line parameters are passed in a very standard way:
``argv[0]`` will be the name of the command, and ``argv[1]`` through
``argv[argc-1]`` are the additional arguments provided on the NSH
command line.

The first parameter, ``vtbl``, is special. This is a pointer to
session-specific state information. You don't need to know the contents
of the state information, but you do need to pass this ``vtbl`` argument
when you interact with the NSH logic. The only use you will need to make
of the ``vtbl`` argument will be for outputting data to the console. You
don't use ``printf()`` within NSH commands. Instead you would use:

.. code-block:: c

  void nsh_output(FAR struct nsh_vtbl_s *vtbl, const char *fmt, ...);

So if you only wanted to output "Hello, World!" on the console, then
your whole command implementation might be:

.. code-block:: c

  int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv)
  {
    nsh_output(vtbl, "Hello, World!");
    return 0;
  }

The prototype for the new command should be placed in
``apps/examples/nshlib/nsh.h``.

**Adding You Command to the NSH Command Table**. All of the commands
support by NSH appear in a single table called:

.. code-block:: c

  const struct cmdmap_s g_cmdmap[]

That table can be found in the file
``apps/examples/nshlib/nsh_parse.c``. The structure ``cmdmap_s`` is also
defined in ``apps/nshlib/nsh_parse.c``:

.. code-block:: c

  struct cmdmap_s
  {
    const char *cmd;        /* Name of the command */
    cmd_t       handler;    /* Function that handles the command */
    uint8_t     minargs;    /* Minimum number of arguments (including command) */
    uint8_t     maxargs;    /* Maximum number of arguments (including command) */
    const char *usage;      /* Usage instructions for 'help' command */
  };

This structure provides everything that you need to describe your
command: Its name (``cmd``), the function that handles the command
(``cmd_mycmd()``), the minimum and maximum number of arguments needed by
the command, and a string describing the command line arguments. That
last string is what is printed when enter "``nsh> help``".

So, for you sample command, you would add the following the to the
``g_cmdmap[]`` table:

.. code-block:: c

  { "mycmd", cmd_mycmd, 1, 1, NULL },

This entry is particularly simply because ``mycmd`` is so simple. Look
at the other commands in ``g_cmdmap[]`` for more complex examples.