content/docs/12.7.0/_sources/applications/nsh/customizing.rst.txt - nuttx-website - Git at Google

 ========================*
 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.
	========================*
	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.