Updates to README files

8 files changed, 599 insertions, 572 deletions

diff --git a/apps/README.txt b/apps/README.txt
index 55accfcf6..4451ef03f 100644
--- a/apps/README.txt
+++ b/apps/README.txt
@@ -33,7 +33,7 @@ NuttX directory.  Like:
  `- apps
 
 If all of the above conditions are TRUE, then NuttX will be able to
-find the application directory.  If your application directory has a 
+find the application directory.  If your application directory has a
 different name or is location at a different position, then you will
 have to inform the NuttX build system of that location.  There are several
 ways to do that:
@@ -61,7 +61,7 @@ collected during the make context build phase.
 
 To execute an application function:
 
-  exec_builtin() is defined in the nuttx/include/apps/builtin.h 
+  exec_builtin() is defined in the nuttx/include/apps/builtin.h
 
 NuttShell (NSH) Built-In Commands
 ---------------------------------
@@ -98,7 +98,7 @@ Application Configuration File
 The old-style NuttX configuration uses a special configuration file is
 used to configure which applications are to be included in the build.
 The source for this file is  configs/<board>/<configuration>/appconfig.
-The existence of the appconfig file in the board configuration directory\
+The existence of the appconfig file in the board configuration directory
 is sufficient to enable building of applications.
 
 The appconfig file is copied into the apps/ directory as .config when
@@ -250,12 +250,13 @@ A: Here are four:
       a) Copy 'MyBoard' directory to configs/MyBoard.
       b) Add a symbolic link to MyApplication at apps/external
       c) Configure NuttX (usually by:
-      
+
          tools/configure.sh MyBoard/MyConfiguration
 
          or simply by copying defconfig->nutt/.config,
-         setenv.sh->nuttx/setenv.sh, Make.defs->nuttx/Make.defs,
-         appconfig->apps/.config
+         setenv.sh->nuttx/setenv.sh, and Make.defs->nuttx/Make.defs
+         (and appconfig->apps/.config for the old-style, deprecated
+         configuration files).
 
       Using the 'external' link makes it especially easy to add a
       'built-in' application an existing configuration.
diff --git a/apps/examples/README.txt b/apps/examples/README.txt
index 2e1454b3f..7e3b0d0f0 100644
--- a/apps/examples/README.txt
+++ b/apps/examples/README.txt
@@ -1,16 +1,14 @@
 examples
 ^^^^^^^^
 
-  appconfig and CONFIG_APPS
-  
+  Selecting examples:
+
     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, 
+    configs/<board-name>/defconfig file via the CONFIG_EXAMPLES_xyz
+    setting where xyz is the name of the example. For example,
 
-      CONFIGURE_APPS += examples/ostest
+      CONFIG_EXAMPLES_OSTEST=y
 
     Selects the examples/ostest example.
 
@@ -30,6 +28,25 @@ examples
       the specific example.  See the following for examples that
       support this option).
 
+      NOTE: The use of CONFIG_EXAMPLES_XYZ_BUILTIN is being phased
+      out.  For many example, the definition of CONFIG_NSH_BUILTIN_APPS
+      is sufficient built the example as an NSH built-in application.
+
+  Older configurations.
+
+    Older, deprecated configuration files might use a variable called
+    CONFIGURED_APPS to selected examples.  Those CONFIGURED_APPS settings
+    where kept in files called appconfig.  For example, in those older
+    configuration files, the OS test example would have been selected with
+    an entry like the following in the appconfig file:
+
+      CONFIGURED_APPS += examples/ostest
+
+    appconfig files are not longer used in the current NuttX configuration
+    system.  And syntax like the above is being phased out (but is still
+    supported by the make system butonly until the last configuration is
+    converted to the newer style configuration files).
+
 examples/adc
 ^^^^^^^^^^^^
 
@@ -44,7 +61,7 @@ examples/adc
       Default: Built as a standalone problem
 
   Specific configuration options for this example include:
- 
+
     CONFIG_EXAMPLES_ADC_DEVPATH - The default path to the ADC device. Default: /dev/adc0
     CONFIG_EXAMPLES_ADC_NSAMPLES - If CONFIG_NSH_BUILTIN_APPS
       is defined, then the number of samples is provided on the command line
@@ -69,7 +86,7 @@ examples/buttons
   CONFIG_EXAMPLES_IRQBUTTONS_MAX      - Highest interrupting button number (MAX=7)
 
   Name strings for buttons:
-  
+
     CONFIG_EXAMPLES_BUTTONS_NAME0, CONFIG_EXAMPLES_BUTTONS_NAME1,
     CONFIG_EXAMPLES_BUTTONS_NAME2, CONFIG_EXAMPLES_BUTTONS_NAME3,
     CONFIG_EXAMPLES_BUTTONS_NAME4, CONFIG_EXAMPLES_BUTTONS_NAME5,
@@ -99,9 +116,9 @@ examples/can
       mode for testing. The STM32 CAN driver does support loopback mode.
     CONFIG_NSH_BUILTIN_APPS - Build the CAN test as an NSH built-in function.
       Default: Built as a standalone problem
- 
+
   Specific configuration options for this example include:
- 
+
     CONFIG_EXAMPLES_CAN_DEVPATH - The path to the CAN device. Default: /dev/can0
     CONFIG_EXAMPLES_CAN_NMSGS - If CONFIG_NSH_BUILTIN_APPS
       is defined, then the number of loops is provided on the command line
@@ -223,7 +240,7 @@ examples/composite
     emulation) or "/dev/ttyACM0" (for the CDC/ACM serial device).
   CONFIG_EXAMPLES_COMPOSITE_BUFSIZE - The size of the serial I/O buffer in
     bytes.  Default 256 bytes.
- 
+
   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:
@@ -266,7 +283,7 @@ 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:
 
@@ -274,7 +291,7 @@ 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.
@@ -282,6 +299,7 @@ examples/dhcpd
                                      (as well as various other UDP-related
                                      configuration settings)
     CONFIG_NET_BROADCAST=y         - UDP broadcast support is needed.
+    CONFIG_NETUTILS_UIPLIB=y       - The UIP library is needed
 
     CONFIG_EXAMPLES_DHCPD_NOMAC     - (May be defined to use software assigned MAC)
     CONFIG_EXAMPLES_DHCPD_IPADDR    - Target IP address
@@ -292,12 +310,6 @@ examples/dhcpd
   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/discover
 ^^^^^^^^^^^^^^^^^
 
@@ -354,7 +366,7 @@ examples/elf
 
        LDELFFLAGS = -r -e main
 
-     If you use GCC to link, you make also need to include '-nostdlib' or 
+     If you use GCC to link, you make also need to include '-nostdlib' or
      '-nostartfiles' and '-nodefaultlibs'.
 
   3. This example also requires genromfs.  genromfs can be build as part of the
@@ -421,9 +433,9 @@ examples/ftpc
   optional port number.
 
   NOTE:  By default, FTPC uses readline to get data from stdin.  So your
-  appconfig file must have the following build path:
+  defconfig file must have the following build path:
 
-    CONFIGURED_APPS += system/readline
+    CONFIG_SYSTEM_READLINE=y
 
   NOTE: If you use the ftpc task over a telnet NSH connection, then you
   should set the following configuration item:
@@ -437,7 +449,7 @@ examples/ftpc
 
   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
@@ -449,6 +461,7 @@ examples/ftpd
   configurations specific to the FTPD example (the FTPD daemon itself may
   require other configuration options as well).
 
+   CONFIG_EXAMPLES_FTPD - Enable the FTPD example.
    CONFIG_EXAMPLES_FTPD_PRIO - Priority of the FTP daemon.
      Default: SCHED_PRIORITY_DEFAULT
    CONFIG_EXAMPLES_FTPD_STACKSIZE - Stack size allocated for the
@@ -495,11 +508,11 @@ examples/ftpd
     CONFIG_FTPD_WORKERSTACKSIZE - The stacksize to allocate for each
       FTP daemon worker thread.  Default:  2048 bytes.
 
-  The appconfig file (apps/.config) should include:
+  The following netutils libraries should be enabled in your defconfig
+  file:
 
-    CONFIGURED_APPS += examples/ftpd
-    CONFIGURED_APPS += netutils/uiplib
-    CONFIGURED_APPS += netutils/ftpd
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_TELNED=y
 
 examples/hello
 ^^^^^^^^^^^^^^
@@ -524,7 +537,7 @@ examples/helloxx
     CONFIG_HAVE_CXX -- Enable C++ Support
 
   Optional NuttX configuration settings:
-  
+
     CONFIG_HAVE_CXXINITIALIZE -- Enable support for static constructors
       (may not be available on all platforms).
 
@@ -589,12 +602,8 @@ examples/igmp
       Network mask
   * CONFIG_EXAMPLES_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
+  * CONFIG_EXAMPLES_UIPLIB
+      The UIP library is needed
 
 examples/json
 ^^^^^^^^^^^^^
@@ -635,7 +644,7 @@ examples/lcdrw
       LCD X resolution.  Default: 240
   * CONFIG_EXAMPLES_LDCRW_YRES
       LCD Y resolution.  Default: 320
-  
+
   NOTE: This test exercises internal lcd 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
@@ -721,14 +730,23 @@ examples/nettest
   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
+    CONFIG_EXAMPLES_NETTEST=y - Enables the nettest example
+    CONFIG_EXAMPLES_UIPLIB=y  - The UIP livrary in needed.
 
   See also examples/tcpecho
 
+examples/nrf24l01_term
+^^^^^^^^^^^^^^^^^^^^^^
+
+  These is a simple test of NRF24L01-based wireless connectivity.  Enabled\
+  with:
+
+    CONFIG_EXAMPLES_NRF24L01TERM
+
+  Options:
+
+    CONFIG_NSH_BUILTIN_APPS - Built as an NSH built-in applications.
+
 examples/nsh
 ^^^^^^^^^^^^
 
@@ -737,37 +755,37 @@ examples/nsh
   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:
+  Applications using this example will need to provide an defconfig
+  file in the configuration directory with instruction to build
+  applicationslike:
 
-  CONFIGURED_APPS += nshlib
+    CONFIG_NSH_LIBRARY=y
 
   NOTE:  If the NSH serial console is used, then following is also
   required to build the readline() library:
 
-  CONFIGURED_APPS += system/readline
+    CONFIG_SYSTEM_READLINE=y
 
   And if networking is included:
 
-  CONFIGURED_APPS += uiplib
-  CONFIGURED_APPS += dhcpc
-  CONFIGURED_APPS += resolv
-  CONFIGURED_APPS += tftp
-  CONFIGURED_APPS += webclient
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_DHCPC=y
+    CONFIG_NETUTILS_RESOLV=y
+    CONFIG_NETUTILS_TFTPC=y
+    CONFIG_NETUTILS_WEBCLIENT=y
 
-  If the Telnet console is enabled, then the appconfig file (apps/.config)
-  should also include:
+  If the Telnet console is enabled, then the defconfig file should
+  also include:
 
-  CONFIGURED_APPS += netutils/telnetd
+    CONFIG_NETUTILS_TELNETD=y
 
   Also if the Telnet console is enabled, make sure that you have the
   following set in the NuttX configuration file or else the performance
   will be very bad (because there will be only one character per TCP
   transfer):
-  
-  CONFIG_STDIO_BUFFER_SIZE - Some value >= 64
-  CONFIG_STDIO_LINEBUFFER=y
+
+    CONFIG_STDIO_BUFFER_SIZE - Some value >= 64
+    CONFIG_STDIO_LINEBUFFER=y
 
 examples/nx
 ^^^^^^^^^^^
@@ -777,7 +795,7 @@ examples/nx
   can be selected:
 
     CONFIG_EXAMPLES_NX_BUILTIN -- Build the NX example as a "built-in"
-      that can be executed from the NSH command line    
+      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
@@ -930,7 +948,7 @@ examplex/nxhello
   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    
+      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
@@ -963,7 +981,7 @@ examples/nximage
   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    
+      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
@@ -1066,11 +1084,11 @@ examples/nxtext
   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    
+      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
@@ -1243,10 +1261,10 @@ examples/poll
   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:
+  provide the following definition in the defconfig file to enable the
+  UIP library:
 
-  CONFIGURED_APPS += uiplib
+    CONFIG_NETUTILS_UIPLIB=y
 
 examples/posix_spawn
 ^^^^^^^^^^^^^^^^^^^^
@@ -1294,7 +1312,7 @@ examples/posix_spawn
 
        LDELFFLAGS = -r -e main
 
-     If you use GCC to link, you make also need to include '-nostdlib' or 
+     If you use GCC to link, you make also need to include '-nostdlib' or
      '-nostartfiles' and '-nodefaultlibs'.
 
   3. This example also requires genromfs.  genromfs can be build as part of the
@@ -1338,9 +1356,9 @@ examples/pwm
     CONFIG_NSH_BUILTIN_APPS - Build the PWM test as an NSH built-in function.
       Default: Not built!  The example can only be used as an NSH built-in
       application
- 
+
   Specific configuration options for this example include:
- 
+
     CONFIG_EXAMPLES_PWM_DEVPATH - The path to the default PWM device. Default: /dev/pwm0
     CONFIG_EXAMPLES_PWM_FREQUENCY - The initial PWM frequency.  Default: 100 Hz
     CONFIG_EXAMPLES_PWM_DUTYPCT - The initial PWM duty as a percentage.  Default: 50%
@@ -1369,7 +1387,7 @@ examples/qencoder
   directory.
 
   Specific configuration options for this example include:
- 
+
     CONFIG_EXAMPLES_QENCODER_DEVPATH - The path to the QE device. Default:
       /dev/qe0
     CONFIG_EXAMPLES_QENCODER_NSAMPLES - If CONFIG_NSH_BUILTIN_APPS
@@ -1396,7 +1414,7 @@ examples/relays
 examples/rgmp
 ^^^^^^^^^^^^^
 
-  RGMP stands for RTOS and GPOS on Multi-Processor.  RGMP is a project for 
+  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
@@ -1446,18 +1464,17 @@ examples/sendmail
   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 
+  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:
+  Applications using this example will need to enble the following
+  netutils libraries in their defconfig file:
 
-  CONFIGURED_APPS += uiplib
-  CONFIGURED_APPS += smtp
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_SMTP=y
 
 examples/serloop
 ^^^^^^^^^^^^^^^^
@@ -1507,7 +1524,7 @@ examples/smart_test
 ^^^^^^^^^^^^^^^^^^^
 
   Performs a file-based test on a SMART (or any) filesystem. Validates
-  seek, append and seek-with-write operations.  
+  seek, append and seek-with-write operations.
 
     * CONFIG_EXAMPLES_SMART_TEST=y
 
@@ -1542,6 +1559,9 @@ examples/telnetd
   the NuttX environment, the NuttShell (at apps/nshlib) supercedes this
   tiny shell and also supports telnetd.
 
+    CONFIG_EXAMPLES_TELNETD - Enable the Telnetd example
+    CONFIG_NETUTILS_UIPLIB, CONFIG_NETUTILS_TELNED - Enable netutils
+      libraries needed by the Telnetd example.
     CONFIG_EXAMPLES_TELNETD_DAEMONPRIO - Priority of the Telnet daemon.
       Default: SCHED_PRIORITY_DEFAULT
     CONFIG_EXAMPLES_TELNETD_DAEMONSTACKSIZE - Stack size allocated for the
@@ -1556,17 +1576,11 @@ examples/telnetd
     CONFIG_EXAMPLES_TELNETD_DRIPADDR - The default router address. Default
       10.0.0.1
     CONFIG_EXAMPLES_TELNETD_NETMASK - The network mask.  Default: 255.255.255.0
- 
-  The appconfig file (apps/.config) should include:
-
-    CONFIGURED_APPS += examples/telnetd
-    CONFIGURED_APPS += netutils/uiplib
-    CONFIGURED_APPS += netutils/telnetd
 
   Also, make sure that you have the following set in the NuttX configuration
   file or else the performance will be very bad (because there will be only
   one character per TCP transfer):
-  
+
     CONFIG_STDIO_BUFFER_SIZE - Some value >= 64
     CONFIG_STDIO_LINEBUFFER=y
 
@@ -1581,12 +1595,11 @@ examples/thttpd
     CONFIG_EXAMPLES_THTTPD_DRIPADDR - Default router IP addess
     CONFIG_EXAMPLES_THTTPD_NETMASK  - Network mask
 
-  Applications using this example will need to provide an appconfig
-  file in the configuration directory with instruction to build applications
-  like:
+  Applications using this example will need to enable the following
+  netutils libraries in the defconfig file:
 
-    CONFIGURED_APPS += uiplib
-    CONFIGURED_APPS += thttpd
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_THTTPD=y
 
 examples/tiff
 ^^^^^^^^^^^^^
@@ -1611,18 +1624,18 @@ examples/tiff
 
   The following must also be defined in your apps/ configuration file:
 
-    CONFIGURED_APPS += examples/tiff
-    CONFIGURED_APPS += graphics/tiff
+    CONFIG_EXAMPLES_TIFF=y
+    CONFIG_GRAPHICS_TIFF=y
 
 examples/touchscreen
 ^^^^^^^^^^^^^^^^^^^^
 
   This configuration implements a simple touchscreen test at
   apps/examples/touchscreen.  This test will create an empty X11 window
-  and will print the touchscreen output as it is received from the 
+  and will print the touchscreen output as it is received from the
   simulated touchscreen driver.
 
-    CONFIG_EXAMPLES_TOUCHSCREEN_BUILTIN - Build the touchscreen test as 
+    CONFIG_EXAMPLES_TOUCHSCREEN_BUILTIN - Build the touchscreen test as
       an NSH built-in function.  Default: Built as a standalone problem
     CONFIG_EXAMPLES_TOUCHSCREEN_MINOR - The minor device number.  Minor=N
       corresponds to touchscreen device /dev/inputN.  Note this value must
@@ -1638,13 +1651,13 @@ examples/touchscreen
 
   The following additional configurations must be set in the NuttX
   configuration file:
-  
+
     CONFIG_INPUT=y
     (Plus any touchscreen-specific settings).
 
   The following must also be defined in your apps configuration file:
 
-    CONFIGURED_APPS += examples/touchscreen
+    CONFIG_EXAMPLES_TOUCHSREEN=y
 
   The board-specific logic must provide the following interfaces that will
   be called by the example in order to initialize and uninitialize the
@@ -1659,11 +1672,10 @@ 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:
+  Applications using this example will need to enabled the following
+  netutils libraries in the defconfig file:
 
-  CONFIGURED_APPS += uiplib
+    CONFIG_NETUTILS_UIPLIB=y
 
 examples/uip
 ^^^^^^^^^^^^
@@ -1699,14 +1711,13 @@ examples/uip
     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:
+  Applications using this example will need to enable the following
+  netutils libraries in their defconfig file:
 
-    CONFIGURED_APPS += uiplib
-    CONFIGURED_APPS += dhcpc
-    CONFIGURED_APPS += resolv
-    CONFIGURED_APPS += webserver
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_DHCPC=y
+    CONFIG_NETUTILS_RESOLV=y
+    CONFIG_NETUTILS_WEBSERVER=y
 
   NOTE:  This example does depend on the perl script at
   nuttx/tools/mkfsdata.pl.  You must have perl installed on your
@@ -1890,37 +1901,37 @@ examples/usbterm
 
   Configuration options:
 
-  CONFIG_EXAMPLES_USBTERM_BUILTIN - Build the usbterm example as an NSH
-    built-in command.  NOTE:  This is not fully functional as of this
-    writing.. It should work, but there is no mechanism in place yet
-    to exit the USB terminal program and return to NSH.
-  CONFIG_EXAMPLES_USBTERM_DEVINIT - If defined, then the example will
-    call a user provided function as part of its initialization:
-       int usbterm_devinit(void);
-    And another user provided function at termination:
-       void usbterm_devuninit(void);
-  CONFIG_EXAMPLES_USBTERM_BUFLEN - The size of the input and output
-    buffers used for receiving data. Default 256 bytes.
+    CONFIG_EXAMPLES_USBTERM_BUILTIN - Build the usbterm example as an NSH
+      built-in command.  NOTE:  This is not fully functional as of this
+      writing.. It should work, but there is no mechanism in place yet
+      to exit the USB terminal program and return to NSH.
+    CONFIG_EXAMPLES_USBTERM_DEVINIT - If defined, then the example will
+      call a user provided function as part of its initialization:
+         int usbterm_devinit(void);
+      And another user provided function at termination:
+         void usbterm_devuninit(void);
+    CONFIG_EXAMPLES_USBTERM_BUFLEN - The size of the input and output
+      buffers used for receiving data. Default 256 bytes.
 
   If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG and CONFIG_DEBUG_USB, or
   CONFIG_USBDEV_TRACE), then the example code will also manage the USB trace
   output.  The amount of trace output can be controlled using:
 
-  CONFIG_EXAMPLES_USBTERM_TRACEINIT
-    Show initialization events
-  CONFIG_EXAMPLES_USBTERM_TRACECLASS
-    Show class driver events
-  CONFIG_EXAMPLES_USBTERM_TRACETRANSFERS
-    Show data transfer events
-  CONFIG_EXAMPLES_USBTERM_TRACECONTROLLER
-    Show controller events
-  CONFIG_EXAMPLES_USBTERM_TRACEINTERRUPTS
-    Show interrupt-related events.
+    CONFIG_EXAMPLES_USBTERM_TRACEINIT
+      Show initialization events
+    CONFIG_EXAMPLES_USBTERM_TRACECLASS
+      Show class driver events
+    CONFIG_EXAMPLES_USBTERM_TRACETRANSFERS
+      Show data transfer events
+    CONFIG_EXAMPLES_USBTERM_TRACECONTROLLER
+      Show controller events
+    CONFIG_EXAMPLES_USBTERM_TRACEINTERRUPTS
+      Show interrupt-related events.
 
   NOTE:  By default, USBterm uses readline to get data from stdin.  So your
-  appconfig file must have the following build path:
+  defconfig file must have the following build path:
 
-    CONFIGURED_APPS += system/readline
+    CONFIG_SYSTEM_READLINE=y
 
   NOTE: If you use the USBterm task over a telnet NSH connection, then you
   should set the following configuration item:
@@ -1953,9 +1964,9 @@ examples/watchdog
     CONFIG_NSH_BUILTIN_APPS - Build the watchdog time test as an NSH
       built-in function. Default: Not built!  The example can only be used
       as an NSH built-in application
- 
+
   Specific configuration options for this example include:
- 
+
     CONFIG_EXAMPLES_WATCHDOG_DEVPATH - The path to the Watchdog device.
       Default: /dev/watchdog0
     CONFIG_EXAMPLES_WATCHDOG_PINGTIME - Time in milliseconds that the example
@@ -2000,13 +2011,12 @@ examples/wget
     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:
+  Applications using this example will need to enable the following netutils
+  libraries in the defconfig file:
 
-    CONFIGURED_APPS += uiplib
-    CONFIGURED_APPS += resolv
-    CONFIGURED_APPS += webclient
+    CONFIG_NETUTILS_UIPLIB=y
+    CONFIG_NETUTILS_RESOLV=y
+    CONFIG_NETUTILS_WEBCLIENT=y
 
 examples/wget
 ^^^^^^^^^^^^^
diff --git a/apps/examples/touchscreen/Makefile b/apps/examples/touchscreen/Makefile
index 1a65c7282..6a3127f42 100644
--- a/apps/examples/touchscreen/Makefile
+++ b/apps/examples/touchscreen/Makefile
@@ -83,7 +83,7 @@ $(COBJS): %$(OBJEXT): %.c
 	$(call ARCHIVE, $(BIN), $(OBJS))
 	@touch .built
 
-ifeq ($(CONFIG_EXAMPLES_TOUCHSCREEN_BUILTIN),y)
+ifeq ($(CONFIG_NSH_BUILTIN_APPS),y)
 $(BUILTIN_REGISTRY)$(DELIM)$(APPNAME)_main.bdat: $(DEPCONFIG) Makefile
 	$(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main)
 
diff --git a/apps/interpreters/README.txt b/apps/interpreters/README.txt
index 9fe39a69c..667268809 100644
--- a/apps/interpreters/README.txt
+++ b/apps/interpreters/README.txt
@@ -33,7 +33,7 @@ pcode
       sub-directory.
 
     Example:
-  
+
       ./INSTALL.sh -16 $PWD/../../../apps/interpreters
 
     After installation, the NuttX apps/interpresters directory will contain
@@ -52,11 +52,18 @@ pcode
               `-- model-specific source files
 
   pashello
-  
+
     There is a simple Pascal example at apps/examples/pashello.  This is the
     standard "Hello, World!" example written in Pascal and interpreted from
     Pascal P-Code at runtime.  To use this example, place the following in
-    your appconfig file"
+    your defonfig file:
+
+      CONFIG_EXAMPLES_PASHELLO=y
+      CONFIG_INTERPRETERS_PCODE=y
+
+    Old Style (deprecated).  In the older configuration files, you would have
+    used an appconfig file containing the following definitions in order to
+    accomplish the same thing:
 
       # Path to example in apps/examples containing the passhello_main entry point
 
diff --git a/apps/interpreters/ficl/README.txt b/apps/interpreters/ficl/README.txt
index bac9f3148..57e370338 100644
--- a/apps/interpreters/ficl/README.txt
+++ b/apps/interpreters/ficl/README.txt
@@ -29,12 +29,17 @@ information as "recommendations" -- not necessarily proven instructions.
    For example, './configure.sh ficl-4.1.0' will leave the Makefile
    fragment 'Make.srcs' in the ficl build directory.
 
-5. Create your NuttX configuration.  The appconfig file should include
-   (1) the path to your application code, and (2) the path to the Ficl
-   build directory.  That latter would appear as the following line in
-   your appconfig file:
+5. Create your NuttX configuration.  Using the 'make menuconfig', you
+   should select:
 
-   CONFIGURED_APPS += interpreters/ficl
+     CONFIG_INTERPRETERS_FICL=y
+
+   Deprecated: In the older style configuration, you would have used
+   an appconfig file to include (1) the path to your application code,
+   and (2) the path to the Ficl build directory.  That latter would
+   have appeared as the following line in your appconfig file:
+
+     CONFIGURED_APPS += interpreters/ficl
 
  6. Configure and build NuttX.  On successful completion, the Ficl objects
     will be available in apps/libapps.a and that NuttX binary will be
diff --git a/apps/netutils/README.txt b/apps/netutils/README.txt
index eaf508d48..52becf800 100644
--- a/apps/netutils/README.txt
+++ b/apps/netutils/README.txt
@@ -69,11 +69,13 @@ highly influenced by uIP) include:
               See http://acme.com/software/thttpd/ for general THTTPD
               information.  See apps/include/netutils/thttpd.h
               for interface information. Applications using this thttpd
-              will need to provide an appconfig file in the configuration
-              directory with instruction to build applications like:
+              will need to provide the following definitions in the
+              defconfig file to select the appropriate netutils
+              libraries:
+
+                CONFIG_NETUTILS_UIPLIB=y
+                CONFIG_NETUTILS_THTTPD=y
 
-               CONFIGURED_APPS += uiplib
-               CONFIGURED_APPS += thttpd
   xmlrpc    - The Embeddable Lightweight XML-RPC Server discussed at
               http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364
 
@@ -85,16 +87,16 @@ Telnetd in NuttX is to support the NuttShell (NSH) Telnet front end.  See
 apps/include/netutils/telnetd.h for information about how to incorporate
 Telnetd into your custom applications.
 
-To enable and link the Telnetd daemon, you need to include the following in 
-in your appconfig (apps/.config) file:
+To enable and link the Telnetd daemon, you need to include the following in
+in your defconfig file:
 
-  CONFIGURED_APPS += uiplib
-  CONFIGURED_APPS += netutils/telnetd
+  CONFIG_NETUTILS_UIPLIB=y
+  CONFIG_NETUTILS_TELNETD=y
 
 Also if the Telnet console is enabled, make sure that you have the following
 set in the NuttX configuration file or else the performance will be very bad
 (because there will be only one character per TCP transfer):
-  
+
   CONFIG_STDIO_BUFFER_SIZE   Some value >= 64
   CONFIG_STDIO_LINEBUFFER=y  Since Telnetd is line oriented, line buffering
                              is optimal.
diff --git a/apps/nshlib/README.txt b/apps/nshlib/README.txt
index a03f4a8ee..bd2dd75f7 100644
--- a/apps/nshlib/README.txt
+++ b/apps/nshlib/README.txt
@@ -273,7 +273,7 @@ o date [-s "MMM DD HH:MM:SS YYYY"]
 
   Only one format is used both on display and when setting the date/time:
   MMM DD HH:MM:SS YYYY.  For example,
-  
+
     data -s "Sep 1 11:30:00 2011"
 
   24-hour time format is assumed.
@@ -326,7 +326,7 @@ o df
     Size   Blocks     Used Available Mounted on
       64        6        6         0 /etc
      512      985        2       983 /tmp
-  nsh> 
+  nsh>
 
 o echo [<string|$name> [<string|$name>...]]
 
@@ -757,7 +757,7 @@ o rmdir <dir-path>
   Recall that NuttX uses a pseudo filesystem for its root file system. The
   rmdir command can only be used to remove directories from volumes set up
   with the mount command; it cannot be used to remove directories from the
-  pseudo filesystem. 
+  pseudo filesystem.
 
   Example:
   ^^^^^^^^
@@ -808,7 +808,7 @@ o unset <name>
     nsh>
 
  o urldecode [-f] <string or filepath>
- 
+
  o urlencode [-f] <string or filepath>
 
 o usleep <usec>
@@ -844,7 +844,7 @@ NSH Configuration Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The availability of the above commands depends upon features that
-may or may not be enabled in the NuttX configuration file.  The 
+may or may not be enabled in the NuttX configuration file.  The
 following table indicates the dependency of each command on NuttX
 configuration settings.  General configuration settings are discussed
 in the NuttX Porting Guide.  Configuration settings specific to NSH
@@ -948,7 +948,7 @@ NSH-Specific Configuration Settings
       Support external registered, "builtin" applications that can be
       executed from the NSH command line (see apps/README.txt for
       more information).
-  
+
   * CONFIG_NSH_FILEIOSIZE
       Size of a static I/O buffer used for file access (ignored if
       there is no filesystem). Default is 1024.
@@ -1099,7 +1099,7 @@ NSH-Specific Configuration Settings
 
   * CONFIG_NET=y
       Of course, networking must be enabled
- 
+
   * CONFIG_NSOCKET_DESCRIPTORS
       And, of course, you must allocate some socket descriptors.
 
@@ -1137,7 +1137,7 @@ NSH-Specific Configuration Settings
 
   * CONFIG_NET=y
       Of course, networking must be enabled
- 
+
   * CONFIG_NSOCKET_DESCRIPTORS
       And, of course, you must allocate some socket descriptors.
 
@@ -1147,7 +1147,7 @@ NSH-Specific Configuration Settings
 
   * CONFIG_NET_BROADCAST=y
       UDP broadcast support is needed.
- 
+
   * CONFIG_NET_BUFSIZE=650 (or larger)
       Per RFC2131 (p. 9), the DHCP client must be prepared to receive DHCP
       messages of up to 576 bytes (excluding Ethernet, IP, or UDP headers and FCS).
@@ -1166,7 +1166,7 @@ NSH-Specific Configuration Settings
       start with '/'.
 
   * CONFIG_NSH_ROMFSDEVNO
-      This is the minor number of the ROMFS block device.  The default is 
+      This is the minor number of the ROMFS block device.  The default is
       '0' corresponding to /dev/ram0.
 
   * CONFIG_NSH_ROMFSSECTSIZE
@@ -1180,7 +1180,7 @@ NSH-Specific Configuration Settings
   describe that FAT FS.
 
   * CONFIG_NSH_FATDEVNO
-      This is the minor number of the FAT FS block device.  The default is 
+      This is the minor number of the FAT FS block device.  The default is
       '1' corresponding to /dev/ram1.
 
   * CONFIG_NSH_FATSECTSIZE
@@ -1212,7 +1212,6 @@ Common Problems
   Problem:
     The function 'readline' is undefined.
   Usual Cause:
-    The following is missing from your appconfig file:
-
-    CONFIGURED_APPS += system/readline
+    The following is missing from your defconfig file:
 
+      CONFIG_SYSTEM_READLINE=y
diff --git a/apps/system/i2c/README.txt b/apps/system/i2c/README.txt
index 7b432533b..1d6f22025 100644
--- a/apps/system/i2c/README.txt
+++ b/apps/system/i2c/README.txt
@@ -1,397 +1,400 @@
-README File for the I2C Tool

-============================

-

-The I2C tool provides a way to debug I2C related problems.  This README file

-will provide usage information for the I2C tools.

-

-CONTENTS

-========

-

-  o System Requirements

-    - I2C Driver

-    - Configuration Options

-  o Help

-  o Common Line Form

-  o Common Command Options

-    - "Sticky" Options

-    - Environment variables

-    - Common Option Summary

-  o Command summary

-    - bus

-    - dev

-    - get

-    - set

-    - verf

-  o I2C Build Configuration

-    - NuttX Configuration Requirements

-    - I2C Tool Configuration Options

-

-System Requirements

-===================

-

-I2C Driver

-----------

-In order to use the I2C driver, you system -- in particular, your I2C driver --

-must meet certain requirements:

-

-1. It support calling up_i2cinitialize() numerous times, resetting the I2C

-   hardware on each (initial) time.  up_i2cuninitialize() will be called after

-   each call to up_i2cinitialize() to free any resources and disable the I2C.

-2. up_i2cinitialize must accept any interface number without crashing.  It

-   must simply return NULL if the device is not supported.

-3. The I2C driver must support the transfer method (CONFIG_I2C_TRANSFER=y).

-

-The I2C tool is designed to be implemented as a NuttShell (NSH) add-on.  Read

-the apps/nshlib/README.txt file for information about add-ons.

-

-Configuration Options

----------------------

-CONFIG_I2CTOOL_BUILTIN - Build the tools as an NSH built-in command

-CONFIG_I2CTOOL_MINBUS - Smallest bus index supported by the hardware (default 0).

-CONFIG_I2CTOOL_MAXBUS - Largest bus index supported by the hardware (default 3)

-CONFIG_I2CTOOL_MINADDR - Minium device address (default: 0x03)

-CONFIG_I2CTOOL_MAXADDR - Largest device address (default: 0x77)

-CONFIG_I2CTOOL_MAXREGADDR - Largest register address (default: 0xff)

-CONFIG_I2CTOOL_DEFFREQ - Default frequency (default: 4000000)

-

-HELP

-====

-

-First of all, the I2C tools supports a pretty extensive help output.  That

-help output can be view by entering either:

-

-  nsh> i2c help

-

-or

-

-  nsh> i2c ?

-

-Here is an example of the help output.  I shows the general form of the

-command line, the various I2C commands supported with their unique command

-line options, and a more detailed summary of the command I2C command

-options.

-

-  nsh> i2c help

-  Usage: i2c <cmd> [arguments]

-  Where <cmd> is one of:

-

-    Show help     : ?

-    List buses    : bus

-    List devices  : dev [OPTIONS] <first> <last>

-    Read register : get [OPTIONS] [<repititions>]

-    Show help     : help

-    Write register: set [OPTIONS] <value> [<repititions>]

-    Verify access : verf [OPTIONS] <value> [<repititions>]

-

-  Where common "sticky" OPTIONS include:

-    [-a addr] is the I2C device address (hex).  Default: 03 Current: 03

-    [-b bus] is the I2C bus number (decimal).  Default: 1 Current: 1

-    [-r regaddr] is the I2C device register address (hex).  Default: 00 Current: 00

-    [-w width] is the data width (8 or 16 decimal).  Default: 8 Current: 8

-    [-s|n], send/don't send start between command and data.  Default: -n Current: -n

-    [-i|j], Auto increment|don't increment regaddr on repititions.  Default: NO Current: NO

-    [-f freq] I2C frequency.  Default: 100000 Current: 100000

-

-  NOTES:

-  o An environment variable like $PATH may be used for any argument.

-  o Arguments are "sticky".  For example, once the I2C address is

-    specified, that address will be re-used until it is changed.

-

-  WARNING:

-  o The I2C dev command may have bad side effects on your I2C devices.

-    Use only at your own risk.

-

-COMMAND LINE FORM

-=================

-

-The I2C is started from NSH by invoking the 'i2c' command from the NSH

-command line. The general form of the 'i2c' command is:

-

-  i2c <cmd> [arguments]

-

-Where <cmd> is a "sub-command" and identifies one I2C operations supported

-by the tool.  [arguments] represents the list of arguments needed to perform

-the I2C operation.  Those arguments vary from command to command as

-described below.  However, there is also a core set of common OPTIONS

-supported by all commands.  So perhaps a better representation of the

-general I2C command would be:

-

-  i2c <cmd> [OPTIONS] [arguments]

-

-Where [OPTIONS] represents the common options and and arguments represent

-the operation-specific arguments.

-

-COMMON COMMAND OPTIONS

-======================

-

-"Sticky" Options

-----------------

-In order to interact with I2C devices, there are a number of I2C parameters

-that must be set correctly.  One way to do this would be to provide to set

-the value of each separate command for each I2C parameter.  The I2C tool

-takes a different approach, instead:  The I2C configuration can be specified

-as a (potentially long) sequence of command line arguments.

-

-These arguments, however, are "sticky."  They are sticky in the sense that

-once you set the I2C parameter, that value will remain until it is reset

-with a new value (or until you reset the board).

-

-Environment Variables

----------------------

-NOTE also that if environment variables are not disabled (by

-CONFIG_DISABLE_ENVIRON=y), then these options may also be environment

-variables.  Environment variables must be preceded with the special

-character $.  For example, PWD is the variable that holds the current

-working directory and so $PWD could be used as a command line argument.  The

-use of environment variables on the I2C tools command is really only useful

-if you wish to write NSH scripts to execute a longer, more complex series of

-I2C commands.

-

-Common Option Summary

----------------------

-

-[-a addr] is the I2C device address (hex).  Default: 03 Current: 03

-

-  The [-a addr] sets the I2C device address.  The valid range is 0x03

-  through 0x77 (this valid range is controlled by the configuration settings

-  CONFIG_I2CTOOL_MINADDR and CONFIG_I2CTOOL_MAXADDR).  If you are working

-  with the same device, the address needs to be set only once.

-  

-  All I2C address are 7-bit, hexadecimal values.

-

-  NOTE 1: Notice in the "help" output above it shows both default value of

-  the I2C address (03 hex) and the current address value (also 03 hex).

-

-  NOTE 2: Sometimes I2C addresses are represented as 8-bit values (with

-  bit zero indicating a read or write operation).  The I2C tool uses a

-  7-bit representation of the address with bit 7 unused and no read/write

-  indication in bit 0.  Essentially, the 7-bit address is like the 8-bit

-  address shifted right by 1.

-

-  NOTE 3: Most I2C bus controllers will also support 10-bit addressing.

-  That capability has not been integrated into the I2C tool as of this

-  writing.

-

-[-b bus] is the I2C bus number (decimal).  Default: 1 Current: 1

-

-  Most devices support multiple I2C devices and also have unique bus

-  numbering.  This option identifies which bus you are working with now.

-  The valid range of bus numbers is controlled by the configuration settings

-  CONFIG_I2CTOOL_MINBUS and CONFIG_I2CTOOL_MAXBUS.

-  

-  The bus numbers are small, decimal numbers.

-

-[-r regaddr] is the I2C device register address (hex).  Default: 00 Current: 00

-

-  The I2C set and get commands will access registers on the I2C device.  This

-  option selects the device register address (sometimes called the sub-address).

-  This is an 8-bit hexadecimal value.  The maximum value is determined by

-  the configuration setting CONFIG_I2CTOOL_MAXREGADDR.

-

-[-w width] is the data width (8 or 16 decimal).  Default: 8 Current: 8

-

-  Device register data may be 8-bit or 16-bit.  This options selects one of

-  those two data widths.

-

-[-s|n], send/don't send start between command and data.  Default: -n Current: -n

-

-  This determines whether or not there should be a new I2C START between

-  sending of the register address and sending/receiving of the register data.

-

-[-i|j], Auto increment|don't increment regaddr on repititions.  Default: NO Current: NO

-

-  On commands that take a optional number of repetitions, the option can be

-  used to temporarily increment the regaddr value by one on each repitition.

-

-[-f freq] I2C frequency.  Default: 400000 Current: 400000

-

-  The [-f freq] sets the frequency of the I2C device.

-

-COMMAND SUMMARY

-===============

-

-We have already seen the I2C help (or ?) commands above.  This section will

-discuss the remaining commands.

-

-List buses: bus [OPTIONS]

---------------------------

-

-This command will simply list all of the configured I2C buses and indicate

-which are supported by the driver and which are not:

-  

-   BUS   EXISTS?

-  Bus 1: YES

-  Bus 2: NO

-

-The valid range of bus numbers is controlled by the configuration settings

-CONFIG_I2CTOOL_MINBUS and CONFIG_I2CTOOL_MAXBUS.

-

-List devices: dev [OPTIONS] <first> <last>

-------------------------------------------

-

-The 'dev' command will attempt to identify all of the I2C devices on the

-selected bus.  The <first> and <last> arguments are 7-bit, hexadecimal

-I2C addresses.  This command will examine a range of addresses beginning

-with <first> and continuing through <last>.  It will request the value

-of register zero from each device.

-

-If the device at an address responds, then this command will display the

-address of the device.  If the device does not respond, this command will

-display "--".  The resulting display is like:

-

-nsh> i2c dev 03 77

-     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f

-00:          -- -- -- -- -- -- -- -- -- -- -- -- --

-10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

-20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

-30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

-40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- --

-50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

-70: -- -- -- -- -- -- -- --

-

-WARNINGS:

-  o The I2C dev command may have bad side effects on certain I2C devices.

-    For example, if could cause data loss in an EEPROM device.

-  o The I2C dev command also depends upon the underlying behavior of the

-    I2C driver.  How does the driver respond to addressing failures?

-

-Read register: get [OPTIONS]

-----------------------------

-

-  This command will read the value of the I2C register using the selected

-  I2C parameters in the common options.  No other arguments are required.

-  

-  This command with write the 8-bit address value then read an 8- or 16-bit

-  data value from the device.  Optionally, it may re-start the transfer

-  before obtaining the data.

-

-  An optional <repititions> argument can be supplied to repeat the

-  read operation an arbitrary number of times (up to 2 billion).  If

-  auto-increment is select (-i), then the register address will be

-  temporarily incremented on each repitions.  The increment is temporary

-  in the since that it will not alter the "sticky" value of the

-  register address.

-

-  On success, the output will look like the following (the data value

-  read will be shown as a 4-character hexadecimal number if the 16-bit

-  data width option is selected).

-

-  READ Bus: 1 Addr: 49 Subaddr: 04 Value: 96

-

-  All values (except the bus numbers) are hexadecimal.

-

-Write register: set [OPTIONS] <value>

--------------------------------------

-

-  This command will write a value to an I2C register using the selected

-  I2C parameters in the common options.  The value to write must be provided

-  as the final, hexadecimal value.  This value may be an 8-bit value (in the

-  range 00-ff) or a 16-bit value (in the range 0000-ffff), depending upon

-  the selected data width.

-  

-  This command will write the 8-bit address value then write the 8- or 16-bit

-  data value to the device.  Optionally, it may re-start the transfer

-  before writing the data.

-

-  An optional <repititions> argument can be supplied to repeat the

-  write operation an arbitrary number of times (up to 2 billion).  If

-  auto-increment is select (-i), then the register address will be

-  temporarily incremented on each repitions.  The increment is temporary

-  in the since that it will not alter the "sticky" value of the

-  register address.

-

-  On success, the output will look like the following (the data value

-  written will be shown as a 4-character hexadecimal number if the 16-bit

-  data width option is selected).

-

-  WROTE Bus: 1 Addr: 49 Subaddr: 04 Value: 96

-

-  All values (except the bus numbers) are hexadecimal.

-

-Verify access : verf [OPTIONS] <value> [<repititions>]

-------------------------------------------------------

-

-  This command combines writing and reading from an I2C device register.

-  It will write a value to an will write a value to an I2C register using

-  the selected I2C parameters in the common options just as described for

-  tie 'set' command.  Then this command will read the value back just

-  as described with the 'get' command.  Finally, this command will compare

-  the value read and against the value written and emit an error message

-  if they do not match.

-

-  If no value is provided, then this command will use the register address

-  itself as the data, providing for a address-in-address test.

-

-  An optional <repititions> argument can be supplied to repeat the

-  verify operation an arbitrary number of times (up to 2 billion).  If

-  auto-increment is select (-i), then the register address will be

-  temporarily incremented on each repitions.  The increment is temporary

-  in the since that it will not alter the "sticky" value of the

-  register address.

-

-  On success, the output will look like the following (the data value

-  written will be shown as a 4-character hexadecimal number if the 16-bit

-  data width option is selected).

-

-  VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE

-

-  All values (except the bus numbers) are hexadecimal.

-

-I2C BUILD CONFIGURATION

-=======================

-

-NuttX Configuration Requirements

---------------------------------

-The I2C tools requires the following in your NuttX configuration:

-

-1. Device-specific I2C support must be enabled.  The I2C tool will call the

-   platform-specific function up_i2cinitialize() to get instances of the

-   I2C interface and the platform-specific function up_i2cuninitialize()

-   to discard instances of the I2C interface.

-

-   NOTE 1: The I2C interface is defined in include/nuttx/i2c.h.

-

-   NOTE 2: This I2C tool uses direct I2C device interfaces.  As such, it

-   relies on internal OS interfaces that are not normally available to a

-   user-space program.  As a result, the I2C tool cannot be used if a

-   NuttX is built as a protected, supervisor kernel (CONFIG_NUTTX_KERNEL).

-

-2. I2C driver configuration

-

-   The CONFIG_I2C_TRANSFER option must also be set in your NuttX

-   configuration.  This configuration is the defconfig file in your

-   configuration directory that is copied to the NuttX top-level

-   directory as .config when NuttX is configured.

-

-     CONFIG_I2C_TRANSFER=y

-

-   NOTE:  CONFIG_I2C_TRANSFER adds extra methods to the I2C interface.

-   Not all I2C interfaces support these extra methods.  If your platform's

-   I2C driver does not support these extra methods, then you cannot use

-   the I2C tool unless you extend the support in your platform I2C

-   driver.

-

-3. Application configuration.

-

-   The path to the I2C tool directory must also be set in your NuttX

-   application configuration.  This application configuration is the

-   appconfig file in your configuration directory that is copied to the

-   NuttX application directory as .config when NuttX is configured.

-

-     CONFIGURE_APPS += system/i2c

-

-I2C Tool Configuration Options

-------------------------------

-

-The default behavior of the I2C tool can be modified by the setting the

-options in the NuttX configuration.  This configuration is the defconfig

-file in your configuration directory that is copied to the NuttX top-level

-directory as .config when NuttX is configured.

-

-  CONFIG_I2CTOOL_BUILTIN: Build the tools as an NSH built-in command

-  CONFIG_I2CTOOL_MINBUS: Smallest bus index supported by the hardware (default 0).

-  CONFIG_I2CTOOL_MAXBUS: Largest bus index supported by the hardware (default 3)

-  CONFIG_I2CTOOL_MINADDR: Minium device address (default: 0x03)

-  CONFIG_I2CTOOL_MAXADDR: Largest device address (default: 0x77)

-  CONFIG_I2CTOOL_MAXREGADDR: Largest register address (default: 0xff)

-  CONFIG_I2CTOOL_DEFFREQ: Default frequency (default: 4000000)

+README File for the I2C Tool
+============================
+
+The I2C tool provides a way to debug I2C related problems.  This README file
+will provide usage information for the I2C tools.
+
+CONTENTS
+========
+
+  o System Requirements
+    - I2C Driver
+    - Configuration Options
+  o Help
+  o Common Line Form
+  o Common Command Options
+    - "Sticky" Options
+    - Environment variables
+    - Common Option Summary
+  o Command summary
+    - bus
+    - dev
+    - get
+    - set
+    - verf
+  o I2C Build Configuration
+    - NuttX Configuration Requirements
+    - I2C Tool Configuration Options
+
+System Requirements
+===================
+
+I2C Driver
+----------
+In order to use the I2C driver, you system -- in particular, your I2C driver --
+must meet certain requirements:
+
+1. It support calling up_i2cinitialize() numerous times, resetting the I2C
+   hardware on each (initial) time.  up_i2cuninitialize() will be called after
+   each call to up_i2cinitialize() to free any resources and disable the I2C.
+2. up_i2cinitialize must accept any interface number without crashing.  It
+   must simply return NULL if the device is not supported.
+3. The I2C driver must support the transfer method (CONFIG_I2C_TRANSFER=y).
+
+The I2C tool is designed to be implemented as a NuttShell (NSH) add-on.  Read
+the apps/nshlib/README.txt file for information about add-ons.
+
+Configuration Options
+---------------------
+CONFIG_I2CTOOL_BUILTIN - Build the tools as an NSH built-in command
+CONFIG_I2CTOOL_MINBUS - Smallest bus index supported by the hardware (default 0).
+CONFIG_I2CTOOL_MAXBUS - Largest bus index supported by the hardware (default 3)
+CONFIG_I2CTOOL_MINADDR - Minium device address (default: 0x03)
+CONFIG_I2CTOOL_MAXADDR - Largest device address (default: 0x77)
+CONFIG_I2CTOOL_MAXREGADDR - Largest register address (default: 0xff)
+CONFIG_I2CTOOL_DEFFREQ - Default frequency (default: 4000000)
+
+HELP
+====
+
+First of all, the I2C tools supports a pretty extensive help output.  That
+help output can be view by entering either:
+
+  nsh> i2c help
+
+or
+
+  nsh> i2c ?
+
+Here is an example of the help output.  I shows the general form of the
+command line, the various I2C commands supported with their unique command
+line options, and a more detailed summary of the command I2C command
+options.
+
+  nsh> i2c help
+  Usage: i2c <cmd> [arguments]
+  Where <cmd> is one of:
+
+    Show help     : ?
+    List buses    : bus
+    List devices  : dev [OPTIONS] <first> <last>
+    Read register : get [OPTIONS] [<repititions>]
+    Show help     : help
+    Write register: set [OPTIONS] <value> [<repititions>]
+    Verify access : verf [OPTIONS] <value> [<repititions>]
+
+  Where common "sticky" OPTIONS include:
+    [-a addr] is the I2C device address (hex).  Default: 03 Current: 03
+    [-b bus] is the I2C bus number (decimal).  Default: 1 Current: 1
+    [-r regaddr] is the I2C device register address (hex).  Default: 00 Current: 00
+    [-w width] is the data width (8 or 16 decimal).  Default: 8 Current: 8
+    [-s|n], send/don't send start between command and data.  Default: -n Current: -n
+    [-i|j], Auto increment|don't increment regaddr on repititions.  Default: NO Current: NO
+    [-f freq] I2C frequency.  Default: 100000 Current: 100000
+
+  NOTES:
+  o An environment variable like $PATH may be used for any argument.
+  o Arguments are "sticky".  For example, once the I2C address is
+    specified, that address will be re-used until it is changed.
+
+  WARNING:
+  o The I2C dev command may have bad side effects on your I2C devices.
+    Use only at your own risk.
+
+COMMAND LINE FORM
+=================
+
+The I2C is started from NSH by invoking the 'i2c' command from the NSH
+command line. The general form of the 'i2c' command is:
+
+  i2c <cmd> [arguments]
+
+Where <cmd> is a "sub-command" and identifies one I2C operations supported
+by the tool.  [arguments] represents the list of arguments needed to perform
+the I2C operation.  Those arguments vary from command to command as
+described below.  However, there is also a core set of common OPTIONS
+supported by all commands.  So perhaps a better representation of the
+general I2C command would be:
+
+  i2c <cmd> [OPTIONS] [arguments]
+
+Where [OPTIONS] represents the common options and and arguments represent
+the operation-specific arguments.
+
+COMMON COMMAND OPTIONS
+======================
+
+"Sticky" Options
+----------------
+In order to interact with I2C devices, there are a number of I2C parameters
+that must be set correctly.  One way to do this would be to provide to set
+the value of each separate command for each I2C parameter.  The I2C tool
+takes a different approach, instead:  The I2C configuration can be specified
+as a (potentially long) sequence of command line arguments.
+
+These arguments, however, are "sticky."  They are sticky in the sense that
+once you set the I2C parameter, that value will remain until it is reset
+with a new value (or until you reset the board).
+
+Environment Variables
+---------------------
+NOTE also that if environment variables are not disabled (by
+CONFIG_DISABLE_ENVIRON=y), then these options may also be environment
+variables.  Environment variables must be preceded with the special
+character $.  For example, PWD is the variable that holds the current
+working directory and so $PWD could be used as a command line argument.  The
+use of environment variables on the I2C tools command is really only useful
+if you wish to write NSH scripts to execute a longer, more complex series of
+I2C commands.
+
+Common Option Summary
+---------------------
+
+[-a addr] is the I2C device address (hex).  Default: 03 Current: 03
+
+  The [-a addr] sets the I2C device address.  The valid range is 0x03
+  through 0x77 (this valid range is controlled by the configuration settings
+  CONFIG_I2CTOOL_MINADDR and CONFIG_I2CTOOL_MAXADDR).  If you are working
+  with the same device, the address needs to be set only once.
+
+  All I2C address are 7-bit, hexadecimal values.
+
+  NOTE 1: Notice in the "help" output above it shows both default value of
+  the I2C address (03 hex) and the current address value (also 03 hex).
+
+  NOTE 2: Sometimes I2C addresses are represented as 8-bit values (with
+  bit zero indicating a read or write operation).  The I2C tool uses a
+  7-bit representation of the address with bit 7 unused and no read/write
+  indication in bit 0.  Essentially, the 7-bit address is like the 8-bit
+  address shifted right by 1.
+
+  NOTE 3: Most I2C bus controllers will also support 10-bit addressing.
+  That capability has not been integrated into the I2C tool as of this
+  writing.
+
+[-b bus] is the I2C bus number (decimal).  Default: 1 Current: 1
+
+  Most devices support multiple I2C devices and also have unique bus
+  numbering.  This option identifies which bus you are working with now.
+  The valid range of bus numbers is controlled by the configuration settings
+  CONFIG_I2CTOOL_MINBUS and CONFIG_I2CTOOL_MAXBUS.
+
+  The bus numbers are small, decimal numbers.
+
+[-r regaddr] is the I2C device register address (hex).  Default: 00 Current: 00
+
+  The I2C set and get commands will access registers on the I2C device.  This
+  option selects the device register address (sometimes called the sub-address).
+  This is an 8-bit hexadecimal value.  The maximum value is determined by
+  the configuration setting CONFIG_I2CTOOL_MAXREGADDR.
+
+[-w width] is the data width (8 or 16 decimal).  Default: 8 Current: 8
+
+  Device register data may be 8-bit or 16-bit.  This options selects one of
+  those two data widths.
+
+[-s|n], send/don't send start between command and data.  Default: -n Current: -n
+
+  This determines whether or not there should be a new I2C START between
+  sending of the register address and sending/receiving of the register data.
+
+[-i|j], Auto increment|don't increment regaddr on repititions.  Default: NO Current: NO
+
+  On commands that take a optional number of repetitions, the option can be
+  used to temporarily increment the regaddr value by one on each repitition.
+
+[-f freq] I2C frequency.  Default: 400000 Current: 400000
+
+  The [-f freq] sets the frequency of the I2C device.
+
+COMMAND SUMMARY
+===============
+
+We have already seen the I2C help (or ?) commands above.  This section will
+discuss the remaining commands.
+
+List buses: bus [OPTIONS]
+--------------------------
+
+This command will simply list all of the configured I2C buses and indicate
+which are supported by the driver and which are not:
+
+   BUS   EXISTS?
+  Bus 1: YES
+  Bus 2: NO
+
+The valid range of bus numbers is controlled by the configuration settings
+CONFIG_I2CTOOL_MINBUS and CONFIG_I2CTOOL_MAXBUS.
+
+List devices: dev [OPTIONS] <first> <last>
+------------------------------------------
+
+The 'dev' command will attempt to identify all of the I2C devices on the
+selected bus.  The <first> and <last> arguments are 7-bit, hexadecimal
+I2C addresses.  This command will examine a range of addresses beginning
+with <first> and continuing through <last>.  It will request the value
+of register zero from each device.
+
+If the device at an address responds, then this command will display the
+address of the device.  If the device does not respond, this command will
+display "--".  The resulting display is like:
+
+nsh> i2c dev 03 77
+     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+00:          -- -- -- -- -- -- -- -- -- -- -- -- --
+10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- --
+50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+70: -- -- -- -- -- -- -- --
+
+WARNINGS:
+  o The I2C dev command may have bad side effects on certain I2C devices.
+    For example, if could cause data loss in an EEPROM device.
+  o The I2C dev command also depends upon the underlying behavior of the
+    I2C driver.  How does the driver respond to addressing failures?
+
+Read register: get [OPTIONS]
+----------------------------
+
+  This command will read the value of the I2C register using the selected
+  I2C parameters in the common options.  No other arguments are required.
+
+  This command with write the 8-bit address value then read an 8- or 16-bit
+  data value from the device.  Optionally, it may re-start the transfer
+  before obtaining the data.
+
+  An optional <repititions> argument can be supplied to repeat the
+  read operation an arbitrary number of times (up to 2 billion).  If
+  auto-increment is select (-i), then the register address will be
+  temporarily incremented on each repitions.  The increment is temporary
+  in the since that it will not alter the "sticky" value of the
+  register address.
+
+  On success, the output will look like the following (the data value
+  read will be shown as a 4-character hexadecimal number if the 16-bit
+  data width option is selected).
+
+  READ Bus: 1 Addr: 49 Subaddr: 04 Value: 96
+
+  All values (except the bus numbers) are hexadecimal.
+
+Write register: set [OPTIONS] <value>
+-------------------------------------
+
+  This command will write a value to an I2C register using the selected
+  I2C parameters in the common options.  The value to write must be provided
+  as the final, hexadecimal value.  This value may be an 8-bit value (in the
+  range 00-ff) or a 16-bit value (in the range 0000-ffff), depending upon
+  the selected data width.
+
+  This command will write the 8-bit address value then write the 8- or 16-bit
+  data value to the device.  Optionally, it may re-start the transfer
+  before writing the data.
+
+  An optional <repititions> argument can be supplied to repeat the
+  write operation an arbitrary number of times (up to 2 billion).  If
+  auto-increment is select (-i), then the register address will be
+  temporarily incremented on each repitions.  The increment is temporary
+  in the since that it will not alter the "sticky" value of the
+  register address.
+
+  On success, the output will look like the following (the data value
+  written will be shown as a 4-character hexadecimal number if the 16-bit
+  data width option is selected).
+
+  WROTE Bus: 1 Addr: 49 Subaddr: 04 Value: 96
+
+  All values (except the bus numbers) are hexadecimal.
+
+Verify access : verf [OPTIONS] <value> [<repititions>]
+------------------------------------------------------
+
+  This command combines writing and reading from an I2C device register.
+  It will write a value to an will write a value to an I2C register using
+  the selected I2C parameters in the common options just as described for
+  tie 'set' command.  Then this command will read the value back just
+  as described with the 'get' command.  Finally, this command will compare
+  the value read and against the value written and emit an error message
+  if they do not match.
+
+  If no value is provided, then this command will use the register address
+  itself as the data, providing for a address-in-address test.
+
+  An optional <repititions> argument can be supplied to repeat the
+  verify operation an arbitrary number of times (up to 2 billion).  If
+  auto-increment is select (-i), then the register address will be
+  temporarily incremented on each repitions.  The increment is temporary
+  in the since that it will not alter the "sticky" value of the
+  register address.
+
+  On success, the output will look like the following (the data value
+  written will be shown as a 4-character hexadecimal number if the 16-bit
+  data width option is selected).
+
+  VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE
+
+  All values (except the bus numbers) are hexadecimal.
+
+I2C BUILD CONFIGURATION
+=======================
+
+NuttX Configuration Requirements
+--------------------------------
+The I2C tools requires the following in your NuttX configuration:
+
+1. Application configuration.
+
+   Using 'make menuconfig', select the i2c tool.  The following
+   definition should appear in your .config file:
+
+     CONFIG_SYSTEM_I2C=y
+
+   Deprecated.  In the older style configuration, there would have been
+   an appconfig file containing the path to the I2C tool directory like:
+
+     CONFIGURE_APPS += system/i2c
+
+2. Device-specific I2C support must be enabled.  The I2C tool will call the
+   platform-specific function up_i2cinitialize() to get instances of the
+   I2C interface and the platform-specific function up_i2cuninitialize()
+   to discard instances of the I2C interface.
+
+   NOTE 1: The I2C interface is defined in include/nuttx/i2c.h.
+
+   NOTE 2: This I2C tool uses direct I2C device interfaces.  As such, it
+   relies on internal OS interfaces that are not normally available to a
+   user-space program.  As a result, the I2C tool cannot be used if a
+   NuttX is built as a protected, supervisor kernel (CONFIG_NUTTX_KERNEL).
+
+3. I2C driver configuration
+
+   The CONFIG_I2C_TRANSFER option must also be set in your NuttX
+   configuration.  This configuration is the defconfig file in your
+   configuration directory that is copied to the NuttX top-level
+   directory as .config when NuttX is configured.
+
+     CONFIG_I2C_TRANSFER=y
+
+   NOTE:  CONFIG_I2C_TRANSFER adds extra methods to the I2C interface.
+   Not all I2C interfaces support these extra methods.  If your platform's
+   I2C driver does not support these extra methods, then you cannot use
+   the I2C tool unless you extend the support in your platform I2C
+   driver.
+
+I2C Tool Configuration Options
+------------------------------
+
+The default behavior of the I2C tool can be modified by the setting the
+options in the NuttX configuration.  This configuration is the defconfig
+file in your configuration directory that is copied to the NuttX top-level
+directory as .config when NuttX is configured.
+
+  CONFIG_I2CTOOL_BUILTIN: Build the tools as an NSH built-in command
+  CONFIG_I2CTOOL_MINBUS: Smallest bus index supported by the hardware (default 0).
+  CONFIG_I2CTOOL_MAXBUS: Largest bus index supported by the hardware (default 3)
+  CONFIG_I2CTOOL_MINADDR: Minium device address (default: 0x03)
+  CONFIG_I2CTOOL_MAXADDR: Largest device address (default: 0x77)
+  CONFIG_I2CTOOL_MAXREGADDR: Largest register address (default: 0xff)
+  CONFIG_I2CTOOL_DEFFREQ: Default frequency (default: 4000000)