sergiotarxz/nuttx-apps
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updates to README files

Browse Source
This commit is contained in:
Gregory Nutt 2013-06-01 17:25:16 -06:00
parent 8ecaf62d3b
commit b673cbebb9
8 changed files with 599 additions and 572 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.txt
View File

@ -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.

284
examples/README.txt
View File

@ -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
^^^^^^^^^^^^^

2
examples/touchscreen/Makefile
View File

@ -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)

13
interpreters/README.txt
View File

@ -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

15
interpreters/ficl/README.txt
View File

@ -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

20
netutils/README.txt
View File

@ -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.

27
nshlib/README.txt
View File

@ -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

797
system/i2c/README.txt
View File

@ -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)