path: root/apps/examples/README.txt

examples
^^^^^^^^

  appconfig and CONFIG_APPS
  
    The examples directory contains several sample applications that
    can be linked with NuttX.  The specific example is selected in the
    configs/<board-name>/appconfig file via the CONFIGURED_APPS setting.
    This setting provides the path to the directory containing the
    application Makefile (this path is a relative to the apps/ top-
    level directory).  For example, 

      CONFIGURE_APPS += examples/ostest

    Selects the examples/ostest example.

  Built-In functions

    Some of the examples may be built as "built-in" functions that
    can be executed at run time (rather than as NuttX "main" programs).
    These "built-in" examples can be also be executed from the NuttShell
    (NSH) command line.  In order to configure these built-in  NSH
    functions, you have to set up the following:

    - CONFIG_NSH_BUILTIN_APPS - Enable support for external registered,
      "named" applications that can be executed from the NSH
      command line (see apps/README.txt for more information).
    - CONFIG_EXAMPLES_XYZ_BUILTIN -- Build the XYZ example as a "built-in"
      that can be executed from the NSH command line (where XYZ is
      the specific example.  See the following for examples that
      support this option).

examples/buttons
^^^^^^^^^^^^^^^^

  This is a simple configuration that may be used to test the board-
  specific button interfaces.  Configuration options:

  CONFIG_ARCH_BUTTONS                - Must be defined for button support
  CONFIG_EXAMPLE_BUTTONS_MIN         - Lowest button number (MIN=0)
  CONFIG_EXAMPLE_BUTTONS_MAX         - Highest button number (MAX=7)

  CONFIG_ARCH_IRQBUTTONS             - Must be defined for interrupting button support
  CONFIG_EXAMPLE_IRQBUTTONS_MIN      - Lowest interrupting button number (MIN=0)
  CONFIG_EXAMPLE_IRQBUTTONS_MAX      - Highest interrupting button number (MAX=7)

  Name strings for buttons:
  
    CONFIG_EXAMPLE_BUTTONS_NAME0, CONFIG_EXAMPLE_BUTTONS_NAME1,
    CONFIG_EXAMPLE_BUTTONS_NAME2, CONFIG_EXAMPLE_BUTTONS_NAME3,
    CONFIG_EXAMPLE_BUTTONS_NAME4, CONFIG_EXAMPLE_BUTTONS_NAME5,
    CONFIG_EXAMPLE_BUTTONS_NAME6, CONFIG_EXAMPLE_BUTTONS_NAME7,

  Additional architecture-/board- specific configuration settings may also
  be required.

  NOTE: This test exercises internal button driver interfaces.  As such, it
  relies on internal OS interfaces that are not normally available to a
  user-space program.  As a result, this example cannot be used if a
  NuttX is built as a protected, supervisor kernel (CONFIG_NUTTX_KERNEL).

examples/dhcpd
^^^^^^^^^^^^^^

  This examples builds a tiny DCHP server for the target system.
  
  NOTE: For test purposes, this example can be built as a
  host-based DHCPD server.  This can be built as follows:

    cd examples/dhcpd
    make -f Makefile.host TOPDIR=<nuttx-directory>

  NuttX configuration settings:
  
    CONFIG_NET=y                   - Of course
    CONFIG_NSOCKET_DESCRIPTORS     - And, of course, you must allocate some
                                     socket descriptors.
    CONFIG_NET_UDP=y               - UDP support is required for DHCP
                                     (as well as various other UDP-related
                                     configuration settings)
    CONFIG_NET_BROADCAST=y         - UDP broadcast support is needed.

    CONFIG_EXAMPLE_DHCPD_NOMAC     - (May be defined to use software assigned MAC)
    CONFIG_EXAMPLE_DHCPD_IPADDR    - Target IP address
    CONFIG_EXAMPLE_DHCPD_DRIPADDR  - Default router IP addess
    CONFIG_EXAMPLE_DHCPD_NETMASK   - Network mask

  See also CONFIG_NETUTILS_DHCPD_* settings described elsewhere
  and used in netutils/dhcpd/dhcpd.c. These settings are required
  to described the behavior of the daemon.

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib

examples/ftpc
^^^^^^^^^^^^^

  This is a simple FTP client shell used to exercise the capabilities
  of the FTPC library (apps/netutils/ftpc).  This example is configured
  to that it will only work as a "built-in" program that can be run from
  NSH when CONFIG_NSH_BUILTIN_APPS is defined.

  From NSH, the startup command sequence is as follows.  This is only
  an example, your configration could have different mass storage devices,
  mount paths, and FTP directories:

    nsh> mount -t vfat /dev/mmcsd0 /tmp # Mount the SD card at /tmp
    nsh> cd /tmp                        # cd into the /tmp directory
    nsh> ftpc xx.xx.xx.xx[:pp]          # Start the FTP client
    nfc> login <name> <password>        # Log into the FTP server
    nfc> help                           # See a list of FTP commands

  where xx.xx.xx.xx is the IP address of the FTP server and pp is an
  optional port number.

  NOTE: The ftpc task uses the system console for input/output.  It will
  not work from NSH over a telnet NSH connection (Well, it will work you 
  just won't be able to access the command line).

  You may also want to define the following in your configuration file.
  Otherwise, you will have not feeback about what is going on:
 
    CONFIG_DEBUG=y
    CONFIG_DEBUG_VERBOSE=y
    CONFIG_DEBUG_FTPC=y

examples/hello
^^^^^^^^^^^^^^

  This is the mandatory, "Hello, World!!" example.  It is little more
  than examples/null with a single printf statement.  Again useful only
  for bringing up new NuttX architectures.

  NuttX configuration settings:

    CONFIG_EXAMPLE_HELLOXX_NOSTATICCONST - Set if system does not support
      static constructors.
    CONFIG_EXAMPLE_HELLOXX_NOSTACKCONST - Set if the systgem does not
      support constructionof objects on the stack.

examples/helloxx
^^^^^^^^^^^^^^^^

  This is C++ version of the "Hello, World!!" example.  It is intended
  only to verify that the C++ compiler is function, that basic C++
  library suupport is available, and that class are instantiated
  correctly.

examples/hidkbd
^^^^^^^^^^^^^^^^

  This is a simple test to debug/verify the USB host HID keyboard class
  driver.

    CONFIG_EXAMPLES_HIDKBD_DEFPRIO - Priority of "waiter" thread.
    CONFIG_EXAMPLES_HIDKBD_STACKSIZE - Stacksize of "waiter" thread.

examples/igmp
^^^^^^^^^^^^^

  This is a trivial test of the NuttX IGMP capability.  It present it
  does not do much of value -- Much more is needed in order to verify
  the IGMP features!

  * CONFIG_EXAMPLE_IGMP_NOMAC
      Set if the hardware has no MAC address; one will be assigned
  * CONFIG_EXAMPLE_IGMP_IPADDR
      Target board IP address
  * CONFIG_EXAMPLE_IGMP_DRIPADDR
      Default router address
  * CONFIG_EXAMPLE_IGMP_NETMASK
      Network mask
  * CONFIG_EXAMPLE_IGMP_GRPADDR
      Multicast group address

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib

examples/mm
^^^^^^^^^^^

  This is a simplified version of the "built-in" memory manager test of
  mm/mm_test.c.  It is simplified because it does not have access to the
  internals of the memory manager as does mm/mm_test.c, but it has the
  advantage that it runs in the actual NuttX tasking environment (the
  mm/mm_test.c only runs in a PC simulation environment).

examples/mount
^^^^^^^^^^^^^^

  This contains a simple test of filesystem mountpoints.

  * CONFIG_EXAMPLES_MOUNT_DEVNAME
      The name of the user-provided block device to mount.
      If CONFIG_EXAMPLES_MOUNT_DEVNAME is not provided, then
      a RAM disk will be configured.

  * CONFIG_EXAMPLES_MOUNT_NSECTORS
      The number of "sectors" in the RAM disk used when
      CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined.

  * CONFIG_EXAMPLES_MOUNT_SECTORSIZE
      The size of each sectors in the RAM disk used when
      CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined.

  * CONFIG_EXAMPLES_MOUNT_RAMDEVNO
      The RAM device minor number used to mount the RAM disk used
      when CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined.  The
      default is zero (meaning that "/dev/ram0" will be used).

examples/netttest
^^^^^^^^^^^^^^^^^

  This is a simple network test for verifying client- and server-
  functionality in a TCP/IP connection.

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib

examples/nsh
^^^^^^^^^^^^

  This directory provides an example of how to configure and use
  the NuttShell (NSH) application.  NSH is a simple shell
  application.  NSH is described in its own README located at
  apps/nshlib/README.txt

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += nshlib

  And if networking is included:

  CONFIGURED_APPS += uiplib
  CONFIGURED_APPS += dhcpc
  CONFIGURED_APPS += resolv
  CONFIGURED_APPS += tftp
  CONFIGURED_APPS += webclient

examples/nx
^^^^^^^^^^^

  This directory contains a simple test of a subset of the NX APIs
  defined in include/nuttx/nx/nx.h.  The following configuration options
  can be selected:

    CONFIG_EXAMPLES_NX_BUILTIN -- Build the NX example as a "built-in"
      that can be executed from the NSH command line    
    CONFIG_EXAMPLES_NX_VPLANE -- The plane to select from the frame-
      buffer driver for use in the test.  Default: 0
    CONFIG_EXAMPLES_NX_DEVNO - The LCD device to select from the LCD
      driver for use in the test: Default: 0
    CONFIG_EXAMPLES_NX_BGCOLOR -- The color of the background.  Default depends on
      CONFIG_EXAMPLES_NX_BPP.
    CONFIG_EXAMPLES_NX_COLOR1 -- The color of window 1. Default depends on
      CONFIG_EXAMPLES_NX_BPP.
    CONFIG_EXAMPLES_NX_COLOR2 -- The color of window 2. Default depends on
      CONFIG_EXAMPLES_NX_BPP.
    CONFIG_EXAMPLES_NX_TBCOLOR -- The color of the toolbar. Default depends on
      CONFIG_EXAMPLES_NX_BPP.
    CONFIG_EXAMPLES_NX_FONTID - Selects the font (see font ID numbers in
      include/nuttx/nx/nxfonts.h)
    CONFIG_EXAMPLES_NX_FONTCOLOR -- The color of the fonts. Default depends on
      CONFIG_EXAMPLES_NX_BPP.
    CONFIG_EXAMPLES_NX_BPP -- Pixels per pixel to use.  Valid options
      include 2, 4, 8, 16, 24, and 32.  Default is 32.
    CONFIG_EXAMPLES_NX_RAWWINDOWS -- Use raw windows;  Default is to
      use pretty, framed NXTK windows with toolbars.
    CONFIG_EXAMPLES_NX_EXTERNINIT - The driver for the graphics device on
      this platform requires some unusual initialization.  This is the
      for, for example, SPI LCD/OLED devices.  If this configuration is
      selected, then the platform code must provide an LCD initialization
      function with a prototype like:

      #ifdef CONFIG_NX_LCDDRIVER
      FAR struct lcd_dev_s *up_nxdrvinit(unsigned int devno);
      #else
      FAR struct fb_vtable_s *up_nxdrvinit(unsigned int devno);
      #endif

  This test can be performed with either the single-user version of
  NX or with the multiple user version of NX selected with CONFIG_NX_MULTIUSER.
  If CONFIG_NX_MULTIUSER is defined, then the following configuration
  options also apply:

    CONFIG_EXAMPLES_NX_STACKSIZE -- The stacksize to use when creating
      the NX server.  Default 2048
    CONFIG_EXAMPLES_NX_CLIENTPRIO -- The client priority.  Default: 100
    CONFIG_EXAMPLES_NX_SERVERPRIO -- The server priority.  Default: 120
    CONFIG_EXAMPLES_NX_LISTENERPRIO -- The priority of the event listener
      thread. Default 80.
    CONFIG_EXAMPLES_NX_NOTIFYSIGNO -- The signal number to use with
      nx_eventnotify().  Default: 4

  If CONFIG_NX_MULTIUSER is defined, then the example also expects the
  following settings and will generate an error if they are not as expected:

    CONFIG_DISABLE_MQUEUE=n
    CONFIG_DISABLE_SIGNALS=n
    CONFIG_DISABLE_PTHREAD=n
    CONFIG_NX_BLOCKING=y

examples/nxffs
^^^^^^^^^^^^^^

  This is a test of the NuttX NXFFS FLASH file system.  This is an NXFFS
  stress test and beats on the file system very hard.  It should only
  be used in a simulation environment!  Putting this NXFFS test on real
  hardware will most likely destroy your FLASH.  You have been warned.

examples/nxflat
^^^^^^^^^^^^^^^

  This example builds a small NXFLAT test case.  This includes several
  test programs under examples/nxflat tests.  These tests are build using
  the NXFLAT format and installed in a ROMFS file system.  At run time,
  each program in the ROMFS file system is executed.  Requires CONFIG_NXFLAT.

examplex/nxhello
^^^^^^^^^^^^^^^^

  A very simple graphics example that just says "Hello, World!" in the
  center of the display.

  The following configuration options can be selected:

    CONFIG_EXAMPLES_NXHELLO_BUILTIN -- Build the NXHELLO example as a "built-in"
      that can be executed from the NSH command line    
    CONFIG_EXAMPLES_NXHELLO_VPLANE -- The plane to select from the frame-
      buffer driver for use in the test.  Default: 0
    CONFIG_EXAMPLES_NXHELLO_DEVNO - The LCD device to select from the LCD
      driver for use in the test: Default: 0
    CONFIG_EXAMPLES_NXHELLO_BGCOLOR -- The color of the background.  Default
      depends on CONFIG_EXAMPLES_NXHELLO_BPP.
    CONFIG_EXAMPLES_NXHELLO_FONTID - Selects the font (see font ID numbers in
      include/nuttx/nx/nxfonts.h)
    CONFIG_EXAMPLES_NXHELLO_FONTCOLOR -- The color of the fonts used in the
      background window. Default depends on CONFIG_EXAMPLES_NXHELLO_BPP.
    CONFIG_EXAMPLES_NXHELLO_BPP -- Pixels per pixel to use.  Valid options
      include 2, 4, 8, 16, 24, and 32.  Default is 32.
    CONFIG_EXAMPLES_NXHELLO_EXTERNINIT - The driver for the graphics device on
      this platform requires some unusual initialization.  This is the
      for, for example, SPI LCD/OLED devices.  If this configuration is
      selected, then the platform code must provide an LCD initialization
      function with a prototype like:

      #ifdef CONFIG_NX_LCDDRIVER
      FAR struct lcd_dev_s *up_nxdrvinit(unsigned int devno);
      #else
      FAR struct fb_vtable_s *up_nxdrvinit(unsigned int devno);
      #endif

examples/nximage
^^^^^^^^^^^^^^^^

  This is a simple example that just puts the NuttX logo image in the center
  of the display.  This only works for RGB23 (888), RGB16 (656), RGB8 (332),
  and 8-bit greyscale for now.

    CONFIG_EXAMPLES_NXIMAGE_BUILTIN -- Build the NXIMAGE example as a "built-in"
      that can be executed from the NSH command line    
    CONFIG_EXAMPLES_NXIMAGE_VPLANE -- The plane to select from the frame-
      buffer driver for use in the test.  Default: 0
    CONFIG_EXAMPLES_NXIMAGE_DEVNO - The LCD device to select from the LCD
      driver for use in the test: Default: 0
    CONFIG_EXAMPLES_NXIMAGE_BPP -- Pixels per pixel to use.  Valid options
      include 8, 16, and 24.  Default is 16.
    CONFIG_EXAMPLES_NXIMAGE_XSCALEp5, CONFIG_EXAMPLES_NXIMAGE_XSCALE1p5,
    CONFIG_EXAMPLES_NXIMAGE_XSCALE2p0 -- The logo image width is 160 columns.
      One of these may be defined to rescale the image horizontally by .5, 1.5,
      or 2.0.
    CONFIG_EXAMPLES_NXIMAGE_YSCALEp5, CONFIG_EXAMPLES_NXIMAGE_YSCALE1p5,
    CONFIG_EXAMPLES_NXIMAGE_YSCALE2p0 -- The logo image height is 160 rows.
      One of these may be defined to rescale the image vertically by .5, 1.5,
      or 2.0.
    CONFIG_EXAMPLES_NXIMAGE_GREYSCALE -- Grey scale image.  Default: RGB.
    CONFIG_EXAMPLES_NXIMAGE_EXTERNINIT - The driver for the graphics device on
      this platform requires some unusual initialization.  This is the
      for, for example, SPI LCD/OLED devices.  If this configuration is
      selected, then the platform code must provide an LCD initialization
      function with a prototype like:

      #ifdef CONFIG_NX_LCDDRIVER
      FAR struct lcd_dev_s *up_nxdrvinit(unsigned int devno);
      #else
      FAR struct fb_vtable_s *up_nxdrvinit(unsigned int devno);
      #endif

    How was that run-length encoded image produced?

    a. I used GIMP output the image as a .c file.
    b. I added som C logic to palette-ize the RGB image in the GIMP .c file
    c. Then I add some simple run-length encoding to palette-ized image.

    NOTE: As of this writing, most of the pixel depth, scaling options, and
    combinations thereof  have not been tested.

examplex/nxlines
^^^^^^^^^^^^^^^^

  A very simple graphics example that just exercised the NX line drawing
  logic.

  The following configuration options can be selected:

    CONFIG_EXAMPLES_NXLINES_BUILTIN -- Build the NXLINES example as a "built-in"
      that can be executed from the NSH command line    
    CONFIG_EXAMPLES_NXLINES_VPLANE -- The plane to select from the frame-
      buffer driver for use in the test.  Default: 0
    CONFIG_EXAMPLES_NXLINES_DEVNO - The LCD device to select from the LCD
      driver for use in the test: Default: 0
    CONFIG_EXAMPLES_NXLINES_BGCOLOR -- The color of the background.  Default
      depends on CONFIG_EXAMPLES_NXLINES_BPP.
    CONFIG_EXAMPLES_NXLINES_LINEWIDTH - Selects the width of the lines in
      pixels (default: 16)
    CONFIG_EXAMPLES_NXLINES_LINECOLOR -- The color of the central lines drawn
      in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
      (there really is no meaningful default).
    CONFIG_EXAMPLES_NXLINES_BORDERWIDTH -- The width of the circular border
      drawn in the background window. (default: 4).
    CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the circular border
      drawn in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
      (there really is no meaningful default).
    CONFIG_EXAMPLES_NXLINES_CIRCLECOLOR -- The color of the circular region
      filled in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
      (there really is no meaningful default).
    CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the lines drawn in the
      background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP (there
      really is no meaningful default).

    CONFIG_EXAMPLES_NXLINES_BPP -- Pixels per pixel to use.  Valid options
      include 2, 4, 8, 16, 24, and 32.  Default is 16.
    CONFIG_EXAMPLES_NXLINES_EXTERNINIT - The driver for the graphics device on
      this platform requires some unusual initialization.  This is the
      for, for example, SPI LCD/OLED devices.  If this configuration is
      selected, then the platform code must provide an LCD initialization
      function with a prototype like:

      #ifdef CONFIG_NX_LCDDRIVER
      FAR struct lcd_dev_s *up_nxdrvinit(unsigned int devno);
      #else
      FAR struct fb_vtable_s *up_nxdrvinit(unsigned int devno);
      #endif

examples/nxtext
^^^^^^^^^^^^^^^

  This directory contains another simple test of a subset of the NX APIs
  defined in include/nuttx/nx/nx.h.  This text focuses on text displays on
  the dispaly background combined with pop-up displays over the text.
  The text display will continue to update while the pop-up is visible.

  NOTE:  This example will *only* work with FB drivers and with LCD
  drivers that support reading the contents of the internal LCD memory
  *unless* you define CONFIG_EXAMPLES_NXTEXT_NOGETRUN.  If you notice
  garbage on the display or a failure at the point where the display
  should scroll, it is probably because you have an LCD driver that is
  write-only.
  
  The following configuration options can be selected:

    CONFIG_EXAMPLES_NXTEXT_BUILTIN -- Build the NXTEXT example as a "built-in"
      that can be executed from the NSH command line    
    CONFIG_EXAMPLES_NXTEXT_VPLANE -- The plane to select from the frame-
      buffer driver for use in the test.  Default: 0
    CONFIG_EXAMPLES_NXTEXT_DEVNO - The LCD device to select from the LCD
      driver for use in the test: Default: 0
    CONFIG_EXAMPLES_NXTEXT_BGCOLOR -- The color of the background.  Default
      depends on CONFIG_EXAMPLES_NXTEXT_BPP.
    CONFIG_EXAMPLES_NXTEXT_BGFONTID - Selects the font to use in the
      background text (see font ID numbers in include/nuttx/nx/nxfonts.h)
    CONFIG_EXAMPLES_NXTEXT_BGFONTCOLOR -- The color of the fonts used in the
      background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP.
    CONFIG_EXAMPLES_NXTEXT_PUCOLOR -- The color of the pop-up window.  Default
      depends on CONFIG_EXAMPLES_NXTEXT_BPP.
    CONFIG_EXAMPLES_NXTEXT_PUFONTID - Selects the font to use in the pop-up
      windows (see font ID numbers in include/nuttx/nx/nxfonts.h)
    CONFIG_EXAMPLES_NXTEXT_PUFONTCOLOR -- The color of the fonts used in the
      background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP.
    CONFIG_EXAMPLES_NXTEXT_BPP -- Pixels per pixel to use.  Valid options
      include 2, 4, 8, 16, 24, and 32.  Default is 32.
    CONFIG_EXAMPLES_NXTEXT_NOGETRUN -- If your display is read-only OR if
      reading is not reliable, then select this configuration to avoid
      reading from the display.
    CONFIG_EXAMPLES_NXTEXT_EXTERNINIT - The driver for the graphics device on
      this platform requires some unusual initialization.  This is the
      for, for example, SPI LCD/OLED devices.  If this configuration is
      selected, then the platform code must provide an LCD initialization
      function with a prototype like:

      #ifdef CONFIG_NX_LCDDRIVER
      FAR struct lcd_dev_s *up_nxdrvinit(unsigned int devno);
      #else
      FAR struct fb_vtable_s *up_nxdrvinit(unsigned int devno);
      #endif

    CONFIG_EXAMPLES_NXTEXT_BMCACHE - The maximum number of characters that
      can be put in the background window.  Default is 128.
    CONFIG_EXAMPLES_NXTEXT_GLCACHE - The maximum nuber of pre-rendered
      fonts that can be retained for the background window.

  This test can be performed with either the single-user version of
  NX or with the multiple user version of NX selected with CONFIG_NX_MULTIUSER.
  If CONFIG_NX_MULTIUSER is defined, then the following configuration
  options also apply:

    CONFIG_EXAMPLES_NXTEXT_STACKSIZE -- The stacksize to use when creating
      the NX server.  Default 2048
    CONFIG_EXAMPLES_NXTEXT_CLIENTPRIO -- The client priority.  Default: 100
    CONFIG_EXAMPLES_NXTEXT_SERVERPRIO -- The server priority.  Default: 120
    CONFIG_EXAMPLES_NXTEXT_LISTENERPRIO -- The priority of the event listener
      thread. Default 80.
    CONFIG_EXAMPLES_NXTEXT_NOTIFYSIGNO -- The signal number to use with
      nx_eventnotify().  Default: 4

  If CONFIG_NX_MULTIUSER is defined, then the example also expects the
  following settings and will generate an error if they are not as expected:

    CONFIG_DISABLE_MQUEUE=n
    CONFIG_DISABLE_SIGNALS=n
    CONFIG_DISABLE_PTHREAD=n
    CONFIG_NX_BLOCKING=y

examples/null
^^^^^^^^^^^^^

  This is the do nothing application.  It is only used for bringing
  up new NuttX architectures in the most minimal of environments.

examples/ostest
^^^^^^^^^^^^^^^

  This is the NuttX 'qualification' suite.  It attempts to exercise
  a broad set of OS functionality.  Its coverage is not very extensive
  as of this writing, but it is used to qualify each NuttX release.

  The behavior of the ostest can be modified with the following
  settings in the configs/<board-name>/defconfig file:

  * CONFIG_EXAMPLES_OSTEST_LOOPS
      Used to control the number of executions of the test.  If
      undefined, the test executes one time.  If defined to be
      zero, the test runs forever.
  * CONFIG_EXAMPLES_OSTEST_STACKSIZE
      Used to create the ostest task.  Default is 8192.
  * CONFIG_EXAMPLES_OSTEST_NBARRIER_THREADS
      Specifies the number of threads to create in the barrier
      test.  The default is 8 but a smaller number may be needed on
      systems without sufficient memory to start so many threads.

examples/pashello
^^^^^^^^^^^^^^^^^

  This is "Hello, World" implemented via the Pascal P-Code interpreter. In
  order to use this example, you must first download and install the
  NuttX pascal module.  After unpacking the pascal module, you can find
  installation instructions in pascal/nuttx/README.txt.

  The correct install location for the NuttX examples and build files is
  apps/interpreters.

examples/pipe
^^^^^^^^^^^^^

  A test of the mkfifo() and pipe() APIs.

 * CONFIG_EXAMPLES_PIPE_STACKSIZE
     Sets the size of the stack to use when creating the child tasks.
     The default size is 1024.

examples/poll
^^^^^^^^^^^^^

  A test of the poll() and select() APIs using FIFOs and, if available,
  stdin, and a TCP/IP socket.  In order to build this test, you must the
  following selected in your NuttX configuration file:

  CONFIG_NFILE_DESCRIPTORS          - Defined to be greater than 0
  CONFIG_DISABLE_POLL               - NOT defined

  In order to use the TCP/IP select test, you have also the following
  additional things selected in your NuttX configuration file:

  CONFIG_NET                        - Defined for general network support
  CONFIG_NET_TCP                    - Defined for TCP/IP support
  CONFIG_NSOCKET_DESCRIPTORS        - Defined to be greater than 0
  CONFIG_NET_NTCP_READAHEAD_BUFFERS - Defined to be greater than zero

  CONFIG_EXAMPLE_POLL_NOMAC         - (May be defined to use software assigned MAC)
  CONFIG_EXAMPLE_POLL_IPADDR        - Target IP address
  CONFIG_EXAMPLE_POLL_DRIPADDR      - Default router IP addess
  CONFIG_EXAMPLE_POLL_NETMASK       - Network mask

  In order to for select to work with incoming connections, you
  must also select:

  CONFIG_NET_TCPBACKLOG             - Incoming connections pend in a backlog until accept() is called.

  In additional to the target device-side example, there is also
  a host-side application in this directory.  It can be compiled under
  Linux or Cygwin as follows:

    cd examples/usbserial
    make -f Makefile.host TOPDIR=<nuttx-directory> TARGETIP=<target-ip>

  Where <target-ip> is the IP address of your target board.

  This will generate a small program called 'host'.  Usage:

  1. Build the examples/poll target program with TCP/IP poll support
     and start the target.

  3. Then start the host application:

       ./host

  The host and target will exchange are variety of small messages. Each
  message sent from the host should cause the select to return in target.
  The target example should read the small message and send it back to
  the host.  The host should then receive the echo'ed message.

  If networking is enabled, applications using this example will need to
  provide an appconfig file in the configuration driver with instruction
  to build applications like:

  CONFIGURED_APPS += uiplib

examples/rgmp
^^^^^^^^^^^^^

  RGMP stands for RTOS and GPOS on Multi-Processor.  RGMP is a project for 
  running GPOS and RTOS simultaneously on multi-processor platforms. You can
  port your favorite RTOS to RGMP together with an unmodified Linux to form a
  hybrid operating system. This makes your application able to use both RTOS
  and GPOS features.

  See http://rgmp.sourceforge.net/wiki/index.php/Main_Page for further

  At present, the RGMP example folder contains only an empty main.c file.

examples/romfs
^^^^^^^^^^^^^^

  This example exercises the romfs filesystem.  Configuration options
  include:

  * CONFIG_EXAMPLES_ROMFS_RAMDEVNO
      The minor device number to use for the ROM disk.  The default is
      1 (meaning /dev/ram1)

  * CONFIG_EXAMPLES_ROMFS_SECTORSIZE
      The ROM disk sector size to use.  Default is 64.

  * CONFIG_EXAMPLES_ROMFS_MOUNTPOINT
      The location to mount the ROM disk.  Deafault: "/usr/local/share"

examples/sendmail
^^^^^^^^^^^^^^^^^

  This examples exercises the uIP SMTP logic by sending a test message
  to a selected recipient.  This test can also be built to execute on
  the Cygwin/Linux host environment:

    cd examples/sendmail
    make -f Makefile.host TOPDIR=<nuttx-directory>

 Settings unique to this example include:

    CONFIG_EXAMPLE_SENDMAIL_NOMAC     - May be defined to use software assigned MAC (optional)
    CONFIG_EXAMPLE_SENDMAIL_IPADDR    - Target IP address (required)
    CONFIG_EXAMPLE_SENDMAIL_DRIPADDR  - Default router IP addess (required)
    CONFIG_EXAMPLE_SENDMAILT_NETMASK  - Network mask (required)
    CONFIG_EXAMPLE_SENDMAIL_RECIPIENT - The recipient of the email (required)
    CONFIG_EXAMPLE_SENDMAIL_SENDER    - Optional. Default: "nuttx-testing@example.com"
    CONFIG_EXAMPLE_SENDMAIL_SUBJECT   - Optional. Default: "Testing SMTP from NuttX"
    CONFIG_EXAMPLE_SENDMAIL_BODY   -    Optional. Default: "Test message sent by NuttX"

  NOTE: This test has not been verified on the NuttX target environment.
  As of this writing, unit-tested in the Cygwin/Linux host environment.

  NOTE 2: This sendmail example only works for the simplest of 
  environments.  Virus protection software on your host may have
  to be disabled to allow you to send messages.  Only very open,
  unprotected recipients can be used.  Most will protect themselves
  from this test email because it looks like SPAM.

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib
  CONFIGURED_APPS += smtp

examples/serloop
^^^^^^^^^^^^^^^^

  This is a mindlessly simple loopback test on the console.  Useful
  for testing new serial drivers.  Configuration options include:

  * CONFIG_EXAMPLES_SERLOOP_BUFIO
      Use C buffered I/O (getchar/putchar) vs. raw console I/O
      (read/read).

examples/thttpd
^^^^^^^^^^^^^^^

  An example that builds netutils/thttpd with some simple NXFLAT
  CGI programs.  see configs/README.txt for most THTTPD settings.
  In addition to those, this example accepts:

    CONFIG_EXAMPLE_THTTPD_NOMAC    - (May be defined to use software assigned MAC)
    CONFIG_EXAMPLE_THTTPD_DRIPADDR - Default router IP addess
    CONFIG_EXAMPLE_THTTPD_NETMASK  - Network mask

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib
  CONFIGURED_APPS += thttpd

examples/tiff
^^^^^^^^^^^^^

  This is a simple unit test for the TIFF creation library at apps/graphic/tiff.
  It is configured to work in the Linux user-mode simulation and has not been
  tested in any other environment.  Since the example also depends on some
  other logic to mount a file system, currently it will only work as an NSH
  built-on, i.e., if the following is defined:

    CONFIG_NSH_BUILTIN_APPS=y
    CONFIG_EXAMPLES_TIFF_BUILTIN=y

  At a miniumum, to run in an embedded environment, you will probably have to
  change the configured paths to the TIFF files defined in the example.

    CONFIG_EXAMPLES_TIFF_OUTFILE - Name of the resulting TIFF file.  Default is
       "/tmp/result.tif"
    CONFIG_EXAMPLES_TIFF_TMPFILE1/2 - Names of two temporaries files that
      will be used in the file creation.  Defaults are "/tmp/tmpfile1.dat" and
      "/tmp/tmpfile2.dat"

  The following must also be defined in your appconfig file:

    CONFIGURED_APPS += examples/tiff
    CONFIGURED_APPS += graphics/tiff

examples/udp
^^^^^^^^^^^^

  This is a simple network test for verifying client- and server-
  functionality over UDP.

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib

examples/uip
^^^^^^^^^^^^

  This is a port of uIP tiny webserver example application.  Settings
  specific to this example include:

    CONFIG_EXAMPLE_UIP_NOMAC     - (May be defined to use software assigned MAC)
    CONFIG_EXAMPLE_UIP_IPADDR    - Target IP address
    CONFIG_EXAMPLE_UIP_DRIPADDR  - Default router IP addess
    CONFIG_EXAMPLE_UIP_NETMASK   - Network mask
    CONFIG_EXAMPLE_UIP_DHCPC     - Select to get IP address via DHCP

  If you use DHCPC, then some special configuration network options are
  required.  These include:

    CONFIG_NET=y                 - Of course
    CONFIG_NSOCKET_DESCRIPTORS   - And, of course, you must allocate some
                                   socket descriptors.
    CONFIG_NET_UDP=y             - UDP support is required for DHCP
                                   (as well as various other UDP-related
                                   configuration settings).
    CONFIG_NET_BROADCAST=y       - UDP broadcast support is needed.
    CONFIG_NET_BUFSIZE=650       - Per RFC2131 (p. 9), the DHCP client must be
    (or larger)                    prepared to receive DHCP messages of up to
                                   576 bytes (excluding Ethernet, IP, or UDP
                                   headers and FCS).

  Other configuration items apply also to the selected webserver net utility.
  Additional relevant settings for the uIP webserver net utility are:

    CONFIG_NETUTILS_HTTPDSTACKSIZE
    CONFIG_NETUTILS_HTTPDFILESTATS
    CONFIG_NETUTILS_HTTPDNETSTATS

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib
  CONFIGURED_APPS += dhcpc
  CONFIGURED_APPS += resolv
  CONFIGURED_APPS += webserver

examples/usbserial
^^^^^^^^^^^^^^^^^^

  TARGET CONFIGURATION:

    This is another implementation of "Hello, World" but this one uses
    a USB serial driver.  Configuration options can be used to simply
    the test. These options include:

    CONFIG_EXAMPLES_USBSERIAL_INONLY
       Only verify IN (device-to-host) data transfers.  Default: both
    CONFIG_EXAMPLES_USBSERIAL_OUTONLY
       Only verify OUT (host-to-device) data transfers.  Default: both
    CONFIG_EXAMPLES_USBSERIAL_ONLYSMALL
       Send only small, single packet messages.  Default: Send large and small.
    CONFIG_EXAMPLES_USBSERIAL_ONLYBIG
       Send only large, multi-packet messages.  Default: Send large and small.

    If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG and CONFIG_DEBUG_USB), then
    the example code will also manage the USB trace output.  The amount of trace output
    can be controlled using:

    CONFIG_EXAMPLES_USBSERIAL_TRACEINIT
      Show initialization events
    CONFIG_EXAMPLES_USBSERIAL_TRACECLASS
      Show class driver events
    CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS
      Show data transfer events
    CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER
      Show controller events
    CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS
      Show interrupt-related events.

    Error results are always shown in the trace output

  HOST-SIDE TEST PROGRAM

    In additional to the target device-side example, there is also a
    host-side application in this directory.  This host side application
    must be executed on a Linux host in order to perform the USBSERIAL
    test.  The host application can be compiled under Linux (or Cygwin?)
    as follows:

      cd examples/usbserial
      make -f Makefile.host TOPDIR=<nuttx-directory>

  RUNNING THE TEST

    This will generate a small program called 'host'.  Usage:

    1. Build the examples/usbserial target program and start the target.

    2. Wait a bit, then do enter:

       dmesg

       At the end of the dmesg output, you should see the serial
       device was successfully idenfied and assigned to a tty device,
       probably /dev/ttyUSB0.

    3. Then start the host application:

         ./host [<tty-dev>]

       Where:

         <tty-dev> is the USB TTY device to use.  The default is /dev/ttyUSB0.

    The host and target will exchange are variety of very small and very large
    serial messages.

examples/usbstorage
^^^^^^^^^^^^^^^^^^^

  This example registers a block device driver, then exports the block
  the device using the USB storage class driver.  In order to use this
  example, your board-specific logic must provide the function:

    void usbstrg_archinitialize(void);

  This function will be called by the example/usbstorage in order to
  do the actual registration of the block device drivers.  For examples
  of the implementation of usbstrg_archinitialize() see
  configs/mcu123-lpc124x/src/up_usbstrg.c or
  configs/stm3210e-eval/src/usbstrg.c

  Configuration options:

  CONFIG_EXAMPLES_USBSTRG_BUILTIN
    This example can be built as two NSH "built-in" commands if this option
    is selection: 'msconn' will connect the USB mass storage device; 'msdis'
    will disconnect the USB storage device.
  CONFIG_EXAMPLES_USBSTRG_NLUNS
    Defines the number of logical units (LUNs) exported by the USB storage
    driver.  Each LUN corresponds to one exported block driver (or partition
    of a block driver).  May be 1, 2, or 3.  Default is 1.
  CONFIG_EXAMPLES_USBSTRG_DEVMINOR1
    The minor device number of the block driver for the first LUN. For
    example, N in /dev/mmcsdN.  Used for registering the block driver. Default
    is zero.
  CONFIG_EXAMPLES_USBSTRG_DEVPATH1
    The full path to the registered block driver.  Default is "/dev/mmcsd0"
  CONFIG_EXAMPLES_USBSTRG_DEVMINOR2 and CONFIG_EXAMPLES_USBSTRG_DEVPATH2
    Similar parameters that would have to be provided if CONFIG_EXAMPLES_USBSTRG_NLUNS
    is 2 or 3.  No defaults.
  CONFIG_EXAMPLES_USBSTRG_DEVMINOR3 and CONFIG_EXAMPLES_USBSTRG_DEVPATH3
    Similar parameters that would have to be provided if CONFIG_EXAMPLES_USBSTRG_NLUNS
    is 3.  No defaults.
  CONFIG_EXAMPLES_USBSTRG_DEBUGMM
    Enables some debug tests to check for memory usage and memory leaks.

  If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG and CONFIG_DEBUG_USB), then
  the example code will also manage the USB trace output.  The amount of trace output
  can be controlled using:

  CONFIG_EXAMPLES_USBSTRG_TRACEINIT
    Show initialization events
  CONFIG_EXAMPLES_USBSTRG_TRACECLASS
    Show class driver events
  CONFIG_EXAMPLES_USBSTRG_TRACETRANSFERS
    Show data transfer events
  CONFIG_EXAMPLES_USBSTRG_TRACECONTROLLER
    Show controller events
  CONFIG_EXAMPLES_USBSTRG_TRACEINTERRUPTS
    Show interrupt-related events.

  Error results are always shown in the trace output

  NOTE 1: When built as an NSH add-on command (CONFIG_EXAMPLES_USBSTRG_BUILTIN=y),
  Caution should be used to assure that the SD drive (or other storage device) is
  not in use when the USB storage device is configured.  Specifically, the SD
  driver should be unmounted like:

  nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH
  ...
  nsh> umount /mnd/sdcard                    # Unmount before connecting USB!!!
  nsh> msconn                                # Connect the USB storage device
  ...
  nsh> msdis                                 # Disconnect USB storate device
  nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount

  Failure to do this could result in corruption of the SD card format.

  NOTE 2: This test exercises internal USB device driver interfaces.  As such,
  it relies on internal OS interfaces that are not normally available to a
  user-space program.  As a result, this example cannot be used if a
  NuttX is built as a protected, supervisor kernel (CONFIG_NUTTX_KERNEL).

examples/wget
^^^^^^^^^^^^^

  A simple web client example.  It will obtain a file from a server using the HTTP
  protocol.  Settings unique to this example include:

    CONFIG_EXAMPLE_WGET_URL       - The URL of the file to get
    CONFIG_EXAMPLE_WGET_NOMAC     - (May be defined to use software assigned MAC)
    CONFIG_EXAMPLE_WGET_IPADDR    - Target IP address
    CONFIG_EXAMPLE_WGET_DRIPADDR  - Default router IP addess
    CONFIG_EXAMPLE_WGET_NETMASK   - Network mask

  This example uses netutils/webclient.  Additional configuration settings apply
  to that code as follows (but built-in defaults are probably OK):

    CONFIG_WEBCLIENT_GETMIMETYPE, CONFIG_WEBCLIENT_MAXHTTPLINE,
    CONFIG_WEBCLIENT_MAXMIMESIZE, CONFIG_WEBCLIENT_MAXHOSTNAME,
    CONFIG_WEBCLIENT_MAXFILENAME

  Of course, the example also requires other settings including CONFIG_NET and
  CONFIG_NET_TCP.  The example also uses the uIP resolver which requires CONFIG_UDP.

  WARNNG: As of this writing, wget is untested on the target platform.  At present
  it has been tested only in the host-based configuration described in the following
  note.  The primary difference is that the target version will rely on the also
  untested uIP name resolver.

  NOTE: For test purposes, this example can be built as a host-based wget function.
  This can be built as follows:

    cd examples/wget
    make -f Makefile.host

  Applications using this example will need to provide an appconfig
  file in the configuration driver with instruction to build applications
  like:

  CONFIGURED_APPS += uiplib
  CONFIGURED_APPS += resolv
  CONFIGURED_APPS += webclient