diff --git a/README.md b/README.md index 3af3771a0..a9c33ce04 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,239 @@ -Application Folder -================== +# Application Folder -Contents --------- +## Contents - General - Directory Location - Built-In Applications - NuttShell (NSH) Built-In Commands - Synchronous Built-In Commands - Application Configuration File - Example Built-In Application - Building NuttX with Board-Specific Pieces Outside the Source Tree +- General +- Directory Location +- Built-In Applications +- NuttShell (NSH) Built-In Commands +- Synchronous Built-In Commands +- Application Configuration File +- Example Built-In Application +- Building NuttX with Board-Specific Pieces Outside the Source Tree -General -------- -This folder provides various applications found in sub-directories. These -applications are not inherently a part of NuttX but are provided to help -you develop your own applications. The apps/ directory is a "break away" -part of the configuration that you may choose to use or not. +## General + +This folder provides various applications found in sub-directories. These +applications are not inherently a part of NuttX but are provided to help you +develop your own applications. The `apps/` directory is a _break away_ part of +the configuration that you may choose to use or not. + +## Directory Location -Directory Location ------------------- The default application directory used by the NuttX build should be named -apps/ (or apps-x.y.z/ where x.y.z is the NuttX version number). This apps/ -directory should appear in the directory tree at the same level as the -NuttX directory. Like: +`apps/` (or `apps-x.y.z/` where `x.y.z` is the NuttX version number). This +`apps/` directory should appear in the directory tree at the same level as the +NuttX directory. Like: +``` . |- nuttx | `- 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 -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: +If all of the above conditions are TRUE, then NuttX will be able to 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: -1) You can define CONFIG_APPS_DIR to be the full path to your application +1) You can define `CONFIG_APPS_DIR` to be the full path to your application directory in the NuttX configuration file. 2) You can provide the path to the application directory on the command line - like: make APPDIR= or make CONFIG_APPS_DIR= -3) When you configure NuttX using tools/configure.sh, you can provide that - path to the application directory on the configuration command line - like: ./configure.sh -a : + like: `make APPDIR=` or `make CONFIG_APPS_DIR=` +3) When you configure NuttX using `tools/configure.sh`, you can provide that + path to the application directory on the configuration command line like: + `./configure.sh -a :` -Built-In Applications ---------------------- -NuttX also supports applications that can be started using a name string. -In this case, application entry points with their requirements are gathered +## Built-In Applications + +NuttX also supports applications that can be started using a name string. In +this case, application entry points with their requirements are gathered together in two files: - - builtin/builtin_proto.h Entry points, prototype function - - builtin/builtin_list.h Application specific information and requirements +- `builtin/builtin_proto.h` – Entry points, prototype function +- `builtin/builtin_list.h` – Application specific information and requirements -The build occurs in several phases as different build targets are executed: -(1) context, (2) depend, and (3) default (all). Application information is -collected during the make context build phase. +The build occurs in several phases as different build targets are executed: (1) +context, (2) depend, and (3) default (all). Application information is collected +during the make context build phase. To execute an application function: - exec_builtin() is defined in the nuttx/include/apps/builtin/builtin.h +`exec_builtin()` is defined in the `nuttx/include/apps/builtin/builtin.h`. + +## NuttShell (NSH) Built-In Commands -NuttShell (NSH) Built-In Commands ---------------------------------- One use of builtin applications is to provide a way of invoking your custom -application through the NuttShell (NSH) command line. NSH will support -a seamless method invoking the applications, when the following option is -enabled in the NuttX configuration file: +application through the NuttShell (NSH) command line. NSH will support a +seamless method invoking the applications, when the following option is enabled +in the NuttX configuration file: - CONFIG_NSH_BUILTIN_APPS=y +```conf +CONFIG_NSH_BUILTIN_APPS=y +``` -Applications registered in the apps/builtin/builtin_list.h file will then -be accessible from the NSH command line. If you type 'help' at the NSH -prompt, you will see a list of the registered commands. +Applications registered in the `apps/builtin/builtin_list.h` file will then be +accessible from the NSH command line. If you type `help` at the NSH prompt, you +will see a list of the registered commands. + +## Synchronous Built-In Commands -Synchronous Built-In Commands ------------------------------ By default, built-in commands started from the NSH command line will run -asynchronously with NSH. If you want to force NSH to execute commands -then wait for the command to execute, you can enable that feature by -adding the following to the NuttX configuration file: +asynchronously with NSH. If you want to force NSH to execute commands then wait +for the command to execute, you can enable that feature by adding the following +to the NuttX configuration file: - CONFIG_SCHED_WAITPID=y +```conf +CONFIG_SCHED_WAITPID=y +``` -The configuration option enables support for the waitpid() RTOS interface. -When that interface is enabled, NSH will use it to wait, sleeping until -the built-in command executes to completion. +The configuration option enables support for the `waitpid()` RTOS interface. +When that interface is enabled, NSH will use it to wait, sleeping until the +built-in command executes to completion. -Of course, even with CONFIG_SCHED_WAITPID=y defined, specific commands -can still be forced to run asynchronously by adding the ampersand (&) -after the NSH command. +Of course, even with `CONFIG_SCHED_WAITPID=y` defined, specific commands can +still be forced to run asynchronously by adding the ampersand (`&`) after the +NSH command. -Application Configuration File ------------------------------- -The NuttX configuration uses kconfig-frontends tools and the NuttX -configuration file (.config) file. For example, the NuttX .config -may have: +## Application Configuration File - CONFIG_EXAMPLES_HELLO=y +The NuttX configuration uses `kconfig-frontends` tools and the NuttX +configuration file (`.config`) file. For example, the NuttX `.config` may have: -This will select the apps/examples/hello in the following way: +```conf +CONFIG_EXAMPLES_HELLO=y +``` -- The top-level make will include examples/Make.defs -- examples/Make.defs will set CONFIGURED_APPS += $(APPDIR)/examples/hello +This will select the `apps/examples/hello` in the following way: + +- The top-level make will include `examples/Make.defs` +- `examples/Make.defs` will set `CONFIGURED_APPS += $(APPDIR)/examples/hello` like this: +```makefile ifneq ($(CONFIG_EXAMPLES_HELLO),) CONFIGURED_APPS += $(APPDIR)/examples/hello endif +``` -Example Built-In Application ----------------------------- -An example application skeleton can be found under the examples/hello -sub-directory. This example shows how a builtin application can be added -to the project. One must: +## Example Built-In Application + +An example application skeleton can be found under the `examples/hello` +sub-directory. This example shows how a builtin application can be added to the +project. One must: 1. Create sub-directory as: progname 2. In this directory there should be: - - A Make.defs file that would be included by the apps/Makefile - - A Kconfig file that would be used by the configuration tool (see the - file kconfig-language.txt in the NuttX tools repository). This - Kconfig file should be included by the apps/Kconfig file - - A Makefile, and + - A `Make.defs` file that would be included by the `apps/Makefile` + - A `Kconfig` file that would be used by the configuration tool (see the + file `kconfig-language.txt` in the NuttX tools repository). This `Kconfig` + file should be included by the `apps/Kconfig` file + - A `Makefile`, and - The application source code. 3. The application source code should provide the entry point: + + ```c main() + ``` - 4. Set the requirements in the file: Makefile, specially the lines: + 4. Set the requirements in the file: `Makefile`, specially the lines: + ```makefile PROGNAME = progname PRIORITY = SCHED_PRIORITY_DEFAULT STACKSIZE = 768 ASRCS = asm source file list as a.asm b.asm ... CSRCS = C source file list as foo1.c foo2.c .. + ``` - 4b. The Make.defs file should include a line like: + 5. The `Make.defs` file should include a line like: + ```makefile ifneq ($(CONFIG_PROGNAME),) CONFIGURED_APPS += progname endif + ``` -Building NuttX with Board-Specific Pieces Outside the Source Tree ------------------------------------------------------------------ +## Building NuttX with Board-Specific Pieces Outside the Source Tree -Q: Has anyone come up with a tidy way to build NuttX with board- - specific pieces outside the source tree? +Q: Has anyone come up with a tidy way to build NuttX with board- specific pieces + outside the source tree? + A: Here are three: - 1) There is a make target called 'make export'. It will build - NuttX, then bundle all of the header files, libraries, startup - objects, and other build components into a .zip file. You - can move that .zip file into any build environment you - want. You can even build NuttX under a DOS CMD window. + 1) There is a make target called `make export`. It will build NuttX, then + bundle all of the header files, libraries, startup objects, and other + build components into a `.zip` file. You can move that `.zip` file into + any build environment you want. You can even build NuttX under a DOS `CMD` + window. - This make target is documented in the top level nuttx/README.txt. + This make target is documented in the top level `nuttx/README.txt`. - 2) You can replace the entire apps/ directory. If there is - nothing in the apps/ directory that you need, you can define - CONFIG_APPS_DIR in your .config file so that it points to a - different, custom application directory. + 2) You can replace the entire `apps/` directory. If there is nothing in the + `apps/` directory that you need, you can define `CONFIG_APPS_DIR` in your + `.config` file so that it points to a different, custom application + directory. - You can copy any pieces that you like from the old apps/directory - to your custom apps directory as necessary. + You can copy any pieces that you like from the old apps/directory to your + custom apps directory as necessary. - This is documented in NuttX/boards/README.txt and - nuttx/Documentation/NuttxPortingGuide.html (Online at + This is documented in `NuttX/boards/README.txt` and + `nuttx/Documentation/NuttxPortingGuide.html` (Online at https://bitbucket.org/nuttx/nuttx/src/master/Documentation/NuttxPortingGuide.html#apndxconfigs - under Build options). And in the apps/README.txt file. + under _Build options_). And in the `apps/README.txt` file. - 3) If you like the random collection of stuff in the apps/ directory - but just want to expand the existing components with your own, - external sub-directory then there is an easy way to that too: - You just create a symbolic link in the apps/ directory that - redirects to your application sub-directory. + 3) If you like the random collection of stuff in the `apps/` directory but + just want to expand the existing components with your own, external + sub-directory then there is an easy way to that too: You just create a + symbolic link in the `apps/` directory that redirects to your application + sub-directory. - In order to be incorporated into the build, the directory that - you link under the apps/ directory should contain (1) a Makefile - that supports the clean and distclean targets (see other Makefiles - for examples), and (2) a tiny Make.defs file that simply adds the - custom build directories to the variable CONFIGURED_APPS like: + In order to be incorporated into the build, the directory that you link + under the `apps/` directory should contain (1) a `Makefile` that supports + the `clean` and `distclean` targets (see other `Makefile`s for examples), + and (2) a tiny `Make.defs` file that simply adds the custom build + directories to the variable `CONFIGURED_APPS` like: - CONFIGURED_APPS += my_directory1 my_directory2 + ```makefile + CONFIGURED_APPS += my_directory1 my_directory2 + ``` - The apps/Makefile will always automatically check for the - existence of subdirectories containing a Makefile and a Make.defs - file. The Makefile will be used only to support cleaning operations. - The Make.defs file provides the set of directories to be built; these - directories must also contain a Makefile. That Makefile must be able - to build the sources and add the objects to the apps/libapps.a archive. - (see other Makefiles for examples). It should support the all, - install, context, and depend targets. + The `apps/Makefile` will always automatically check for the existence of + subdirectories containing a `Makefile` and a `Make.defs` file. The + `Makefile` will be used only to support cleaning operations. The Make.defs + file provides the set of directories to be built; these directories must + also contain a `Makefile`. That `Makefile` must be able to build the + sources and add the objects to the `apps/libapps.a` archive. (see other + `Makefile`s for examples). It should support the all, install, context, + and depend targets. - apps/Makefile does not depend on any hardcoded lists of directories. - Instead, it does a wildcard search to find all appropriate - directories. This means that to install a new application, you - simply have to copy the directory (or link it) into the apps/ - directory. If the new directory includes a Makefile and Make.defs - file, then it will automatically be included in the build. + `apps/Makefile` does not depend on any hardcoded lists of directories. + Instead, it does a wildcard search to find all appropriate directories. + This means that to install a new application, you simply have to copy the + directory (or link it) into the `apps/` directory. If the new directory + includes a `Makefile` and `Make.defs` file, then it will automatically be + included in the build. - If the directory that you add also includes a Kconfig file, then it - will automatically be included in the NuttX configuration system as - well. apps/Makefile uses a tool at apps/tools/mkkconfig.sh that - dynamically builds the apps/Kconfig file at pre-configuration time. + If the directory that you add also includes a `Kconfig` file, then it will + automatically be included in the NuttX configuration system as well. + `apps/Makefile` uses a tool at `apps/tools/mkkconfig.sh` that dynamically + builds the `apps/Kconfig` file at pre-configuration time. - You could, for example, create a script called install.sh that - installs a custom application, configuration, and board specific - directory: + You could, for example, create a script called `install.sh` that installs + a custom application, configuration, and board specific directory: - a) Copy 'MyBoard' directory to boards/MyBoard. - b) Add a symbolic link to MyApplication at apps/external - c) Configure NuttX (usually by: + a) Copy `MyBoard` directory to `boards/MyBoard`. + b) Add a symbolic link to `MyApplication` at `apps/external`. + c) Configure NuttX, usually by: - tools/configure.sh MyBoard:MyConfiguration + ```bash + tools/configure.sh MyBoard:MyConfiguration + ``` - Use of the name ''apps/external'' is suggested because that name - is included in the .gitignore file and will save you some nuisance - when working with GIT. + Use of the name `apps/external` is suggested because that name is included + in the `.gitignore` file and will save you some nuisance when working with + GIT. diff --git a/examples/README.md b/examples/README.md index fa6ba3e95..f1fb179bc 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,2113 +1,2061 @@ -examples -^^^^^^^^ +# Examples - Selecting examples: +### Selecting Examples - The examples directory contains several sample applications that - can be linked with NuttX. The specific example is selected in the - boards////configs//defconfig - file via the CONFIG_EXAMPLES_xyz setting where xyz is the name of the - example. For example, +The examples directory contains several sample applications that can be linked +with NuttX. The specific example is selected in the +`boards////configs//defconfig` file +via the `CONFIG_EXAMPLES_xyz` setting where `xyz` is the name of the example. +For example: - CONFIG_EXAMPLES_HELLO=y +```conf +CONFIG_EXAMPLES_HELLO=y +``` - Selects the examples/hello "Hello, World!" example. +Selects the `examples/hello` _Hello, World!_ example. - Built-In functions +### Built-In Functions - Some of the examples may be built as "built-in" functions that - can be executed at run time (rather than as NuttX "main" programs). - These "built-in" examples can be also be executed from the NuttShell - (NSH) command line. In order to configure these built-in NSH - functions, you have to set up the following: +Some of the examples may be built as _built-in_ functions that can be executed +at run time (rather than as NuttX _main_ programs). These _built-in_ examples +can be also be executed from the NuttShell (NSH) command line. In order to +configure these built-in NSH functions, you have to set up the following: - - CONFIG_NSH_BUILTIN_APPS - Enable support for external registered, - "named" applications that can be executed from the NSH - command line (see apps/README.txt for more information). +- `CONFIG_NSH_BUILTIN_APPS` – Enable support for external registered, _named_ + applications that can be executed from the NSH command line (see + `apps/README.md` for more information). -examples/adc -^^^^^^^^^^^^ +## `adc` Read from ADC - A mindlessly simple test of an ADC devices. It simply reads from the - ADC device and dumps the data to the console forever. +A mindlessly simple test of an ADC devices. It simply reads from the ADC device +and dumps the data to the console forever. - This test depends on these specific ADC/NSH configurations settings (your - specific ADC settings might require additional settings). +This test depends on these specific ADC/NSH configurations settings (your +specific ADC settings might require additional settings). - CONFIG_ADC - Enabled ADC support - CONFIG_NSH_BUILTIN_APPS - Build the ADC test as an NSH built-in function. - Default: Built as a standalone program +- `CONFIG_ADC` – Enabled ADC support. +- `CONFIG_NSH_BUILTIN_APPS` – Build the ADC test as an NSH built-in function. + Default: Built as a standalone program. - Specific configuration options for this example include: +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 - This number of samples is - collected and the program terminates. Default: Samples are collected - indefinitely. - CONFIG_EXAMPLES_ADC_GROUPSIZE - The number of samples to read at once. - Default: 4 - -examples/ajoystick -^^^^^^^^^^^^^^^^^^ - - This is a simple test of the analog joystick driver. See details about - this driver in nuttx/include/nuttx/input/ajoystick.h. +- `CONFIG_EXAMPLES_ADC_DEVPATH` – The default path to the ADC device. Default: + `/dev/adc0`. +- `CONFIG_EXAMPLES_ADC_NSAMPLES` – This number of samples is collected and the + program terminates. Default: Samples are collected indefinitely. +- `CONFIG_EXAMPLES_ADC_GROUPSIZE` – The number of samples to read at once. + Default: `4`. - Configuration Pre-requisites: +## `ajoystick` Analog Joystick - CONFIG_AJOYSTICK - The analog joystick driver +This is a simple test of the analog joystick driver. See details about this +driver in `nuttx/include/nuttx/input/ajoystick.h`. - Example Configuration: - CONFIG_EXAMPLES_AJOYSTICK - Enabled the analog joystick example - CONFIG_EXAMPLES_AJOYSTICK_DEVNAME - Joystick device name. Default - "/dev/adjoy0" - CONFIG_EXAMPLES_AJOYSTICK_SIGNO - Signal used to signal the test - application. Default 13. +Configuration Pre-requisites: -examples/alarm -^^^^^^^^^^^^^^ - A simple example that tests the alarm IOCTLs of the RTC driver. - - Dependencies: - - CONFIG_RTC_DRIVER - RTC driver must be initialized to allow user space - access to the RTC. - CONFIG_RTC_ALARM - Support for RTC alarms must be enabled. - - Configuration: +- `CONFIG_AJOYSTICK` – The analog joystick driver. - CONFIG_EXAMPLES_ALARM - Enable the RTC driver alarm test - CONFIG_EXAMPLES_ALARM_PROGNAME - this isthe name of the - program that will be used when the NSH ELF program is - installed. - CONFIG_EXAMPLES_ALARM_PRIORITY - Alarm daemon priority - CONFIG_EXAMPLES_ALARM_STACKSIZE - Alarm daemon stack size - CONFIG_EXAMPLES_ALARM_DEVPATH - RTC device path (/dev/rtc0) - ONFIG_EXAMPLES_ALARM_SIGNO - Alarm signal +Example Configuration: +- `CONFIG_EXAMPLES_AJOYSTICK` – Enabled the analog joystick example. +- `CONFIG_EXAMPLES_AJOYSTICK_DEVNAME` – Joystick device name. Default + `/dev/adjoy0`. +- `CONFIG_EXAMPLES_AJOYSTICK_SIGNO` – Signal used to signal the test + application. Default `13`. -examples/apa102 -^^^^^^^^^^^^^^^ +## `alarm` RTC Alarm - Rainbow example for APA102 LED Strip. +A simple example that tests the alarm IOCTLs of the RTC driver. -examples/bastest -^^^^^^^^^^^^^^^^ - This directory contains a small program that will mount a ROMFS file system - containing the BASIC test files extracted from the BAS 2.4 release. See - examples/bastest/README.txt for licensing and usage information. +Dependencies: - CONFIG_EXAMPLES_BASTEST_DEVMINOR - The minor device number of the ROMFS block - driver. For example, the N in /dev/ramN. Used for registering the RAM - block driver that will hold the ROMFS file system containing the BASIC - files to be tested. Default: 0 +- `CONFIG_RTC_DRIVER` – RTC driver must be initialized to allow user space + access to the RTC. +- `CONFIG_RTC_ALARM` – Support for RTC alarms must be enabled. - CONFIG_EXAMPLES_BASTEST_DEVPATH - The path to the ROMFS block driver device. This - must match EXAMPLES_BASTEST_DEVMINOR. Used for registering the RAM block driver - that will hold the ROMFS file system containing the BASIC files to be - tested. Default: "/dev/ram0" +Configuration: -examples/bridge -^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_ALARM` – Enable the RTC driver alarm test. +- `CONFIG_EXAMPLES_ALARM_PROGNAME` – This is the name of the program that will + be used when the NSH ELF program is installed. +- `CONFIG_EXAMPLES_ALARM_PRIORITY` – Alarm daemon priority. +- `CONFIG_EXAMPLES_ALARM_STACKSIZE` – Alarm daemon stack size. +- `CONFIG_EXAMPLES_ALARM_DEVPATH` – RTC device path (`/dev/rtc0`). +- `CONFIG_EXAMPLES_ALARM_SIGNO` – Alarm signal. - A simple test of a system with multiple networks. It simply echoes all UDP - packets received on network 1 and network 2 to network 2 and network 1, - respectively. Interface 1 and interface may or may not lie on the same - network. - - CONFIG_EXAMPLES_BRIDGE - Enables the simple UDP bridge test - - There identical configurations for each of the two networks, NETn where n - refers to the network being configured n={1,2}. Let 'm' refer to the - other network. +## `apa102` Rainbow on `APA102` LED Strip - CONFIG_EXAMPLES_BRIDGE_NETn_IFNAME - The register name of the network n - device. Must match the previously registered driver name and must - not be the same as other network device name, - CONFIG_EXAMPLES_BRIDGE_NETm_IFNAME - CONFIG_EXAMPLES_BRIDGE_NETn_RECVPORT - Network n listen port number - CONFIG_EXAMPLES_BRIDGE_NETn_SNDPORT - Network 2 send port number - CONFIG_EXAMPLES_BRIDGE_NETn_IOBUFIZE - Size of the network n UDP - send/receive I/O buffer - CONFIG_EXAMPLES_BRIDGE_NETn_STACKSIZE - Network n daemon stacksize - CONFIG_EXAMPLES_BRIDGE_NETn_PRIORITY - Network n daemon task priority +Rainbow example for `APA102` LED Strip. - If used as a NSH add-on, then it is assumed that initialization of both - networks was performed externally prior to the time that this test was - started. Otherwise, the following options are available: +## `bastest` Bas BASIC Interpreter - CONFIG_EXAMPLES_BRIDGE_NETn_NOMAC - Select of the network n hardware - does not have a built-in MAC address. If selected, the MAC address - provided by CONFIG_EXAMPLES_BRIDGE_NETn_MACADDR will be used to assign - the MAC address to the network n device. - CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC - Use DHCP Client to get the network n - IP address. - CONFIG_EXAMPLES_BRIDGE_NETn_IPADDR -- If CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC - is not selected, then this is the fixed IP address for network n. - CONFIG_EXAMPLES_BRIDGE_NETn_DRIPADDR - Netweork n default router IP - address (Gateway) - CONFIG_EXAMPLES_BRIDGE_NETn_NETMASK - Network n mask. +This directory contains a small program that will mount a ROMFS file system +containing the BASIC test files extracted from the Bas `2.4` release. See +`examples/bastest/README.md` for licensing and usage information. -examples/buttons -^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_BASTEST_DEVMINOR` – The minor device number of the ROMFS + block driver. For example, the `N` in `/dev/ramN`. Used for registering the + RAM block driver that will hold the ROMFS file system containing the BASIC + files to be tested. Default: `0`. - To be provided +- `CONFIG_EXAMPLES_BASTEST_DEVPATH` – The path to the ROMFS block driver device. + This must match `EXAMPLES_BASTEST_DEVMINOR`. Used for registering the RAM + block driver that will hold the ROMFS file system containing the BASIC files + to be tested. Default: `/dev/ram0`. -examples/can -^^^^^^^^^^^^ +## `bridge` Network Bridge - If the CAN device is configured in loopback mode, then this example can - be used to test the CAN device in loop back mode. It simple sinces a - sequence of CAN messages and verifies that those messages are returned - exactly as sent. +A simple test of a system with multiple networks. It simply echoes all UDP +packets received on network `1` and network `2` to network `2` and network `1`, +respectively. Interface `1` and interface may or may not lie on the same +network. - This test depends on these specific CAN/NSH configurations settings (your - specific CAN settings might require additional settings). +- `CONFIG_EXAMPLES_BRIDGE` – Enables the simple UDP bridge test. - CONFIG_CAN - Enables CAN support. - CONFIG_CAN_LOOPBACK - A CAN driver may or may not support a loopback - 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 program +There identical configurations for each of the two networks, `NETn` where `n` +refers to the network being configured `n={1,2}`. Let `m` refer to the other +network. - Specific configuration options for this example include: +- `CONFIG_EXAMPLES_BRIDGE_NETn_IFNAME` – The register name of the network `n` + device. Must match the previously registered driver name and must not be the + same as other network device name, `CONFIG_EXAMPLES_BRIDGE_NETm_IFNAME`. +- `CONFIG_EXAMPLES_BRIDGE_NETn_RECVPORT` – Network `n` listen port number. +- `CONFIG_EXAMPLES_BRIDGE_NETn_SNDPORT` – Network `2` send port number. +- `CONFIG_EXAMPLES_BRIDGE_NETn_IOBUFIZE` – Size of the network `n` UDP + send/receive I/O buffer. +- `CONFIG_EXAMPLES_BRIDGE_NETn_STACKSIZE` – Network `n` daemon stacksize. +- `CONFIG_EXAMPLES_BRIDGE_NETn_PRIORITY` – Network `n` daemon task priority. - CONFIG_EXAMPLES_CAN_DEVPATH - The path to the CAN device. Default: /dev/can0 - CONFIG_EXAMPLES_CAN_NMSGS - This number of CAN message is collected - and the program terminates. Default: messages are sent and received - indefinitely. +If used as a NSH add-on, then it is assumed that initialization of both networks +was performed externally prior to the time that this test was started. +Otherwise, the following options are available: - The default behavior assumes loopback mode. Messages are sent, then read - and verified. The behavior can be altered for other kinds of testing where - the test only sends or received (but does not verify) can messages. +- `CONFIG_EXAMPLES_BRIDGE_NETn_NOMAC` – Select of the network `n` hardware does + not have a built-in MAC address. If selected, the MAC address. provided by + `CONFIG_EXAMPLES_BRIDGE_NETn_MACADDR` will be used to assign the MAC address + to the network n device. +- `CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC` – Use DHCP Client to get the network n IP + address. +- `CONFIG_EXAMPLES_BRIDGE_NETn_IPADDR` – If `CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC` + is not selected, then this is the fixed IP address for network `n`. +- `CONFIG_EXAMPLES_BRIDGE_NETn_DRIPADDR` – Network `n` default router IP address + (Gateway). +- `CONFIG_EXAMPLES_BRIDGE_NETn_NETMASK` – Network `n` mask. - CONFIG_EXAMPLES_CAN_READONLY - Only receive messages - CONFIG_EXAMPLES_CAN_WRITEONLY - Only send messages +## `buttons` Read GPIO Buttons -examples/canard -^^^^^^^^^^^^^^^ +To be provided. - Example application for canutils/libcarnard. +## `can` CAN Device Test -examples/cctype -^^^^^^^^^^^^^^^ +If the CAN device is configured in loopback mode, then this example can be used +to test the CAN device in loop back mode. It simple sinces a sequence of CAN +messages and verifies that those messages are returned exactly as sent. - Verifies all possible inputs for all functions defined in the header file - cctype. +This test depends on these specific CAN/NSH configurations settings (your +specific CAN settings might require additional settings). -examples/chat -^^^^^^^^^^^^^ +- `CONFIG_CAN` – Enables CAN support. +- `CONFIG_CAN_LOOPBACK` – A CAN driver may or may not support a loopback 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 program. - Demonstrates AT chat functionality over a TTY device. This is useful with AT - modems, for example, to establish a pppd connection (see the related pppd - example). Moreover, some AT modems - such as ones made by u-blox - have an - internal TCP/IP stack, often with an implementation of TLS/SSL. In such cases - the chat utility can be used to configure the internal TCP/IP stack, establish - socket connections, set up security (e.g., download base64-encoded - certificates to the modem), and perform data exchange through sockets over the - TTY device. +Specific configuration options for this example include: - Useful configuration parameters: - CONFIG_EXAMPLES_CHAT_PRESET[0..3] - preset chat scripts - CONFIG_EXAMPLES_CHAT_TTY_DEVNODE - TTY device node name - CONFIG_EXAMPLES_CHAT_TIMEOUT_SECONDS - default receive timeout +- `CONFIG_EXAMPLES_CAN_DEVPATH` – The path to the CAN device. Default: + `/dev/can0`. +- `CONFIG_EXAMPLES_CAN_NMSGS` – This number of CAN message is collected and the + program terminates. Default: messages are sent and received indefinitely. -examples/configdata -^^^^^^^^^^^^^^^^^^^ +The default behavior assumes loopback mode. Messages are sent, then read and +verified. The behavior can be altered for other kinds of testing where the test +only sends or received (but does not verify) can messages. - This is a Unit Test for the MTD configuration data driver +- `CONFIG_EXAMPLES_CAN_READONLY` – Only receive messages. +- `CONFIG_EXAMPLES_CAN_WRITEONLY` – Only send messages. -examples/cpuhog -^^^^^^^^^^^^^^^ +## `canard` - Attempts to keep the system busy by passing data through a pipe in loop - back mode. This may be useful if you are trying run down other problems - that you think might only occur when the system is very busy. +Example application for `canutils/libcarnard`. -examples/dac -^^^^^^^^^^^^ +## `cctype` - This is a tool for writing values to DAC device. +Verifies all possible inputs for all functions defined in the header file +`cctype`. -examples/dhcpd -^^^^^^^^^^^^^^ +## `chat` AT over TTY - This examples builds a tiny DHCP server for the target system. +Demonstrates AT chat functionality over a TTY device. This is useful with AT +modems, for example, to establish a `pppd` connection (see the related `pppd` +example). Moreover, some AT modems – such as ones made by u-blox – have an +internal TCP/IP stack, often with an implementation of TLS/SSL. In such cases +the chat utility can be used to configure the internal TCP/IP stack, establish +socket connections, set up security (e.g., download base64-encoded certificates +to the modem), and perform data exchange through sockets over the TTY device. - NOTE: For test purposes, this example can be built as a - host-based DHCPD server. This can be built as follows: +Useful configuration parameters: - cd examples/dhcpd - make -f Makefile.host TOPDIR= +- `CONFIG_EXAMPLES_CHAT_PRESET[0..3]` – preset chat scripts. +- `CONFIG_EXAMPLES_CHAT_TTY_DEVNODE` – TTY device node name. +- `CONFIG_EXAMPLES_CHAT_TIMEOUT_SECONDS` – default receive timeout. - NuttX configuration settings: +## `configdata` - CONFIG_NET=y - Of course - CONFIG_NET_UDP=y - UDP support is required for DHCP - (as well as various other UDP-related - configuration settings) - CONFIG_NET_BROADCAST=y - UDP broadcast support is needed. - CONFIG_NETUTILS_NETLIB=y - The networking library is needed +This is a Unit Test for the MTD configuration data driver. - CONFIG_EXAMPLES_DHCPD_NOMAC - (May be defined to use software assigned MAC) +## `cpuhog` Keep CPU Busy - See also CONFIG_NETUTILS_DHCPD_* settings described elsewhere - and used in netutils/dhcpd/dhcpd.c. These settings are required - to described the behavior of the daemon. +Attempts to keep the system busy by passing data through a pipe in loop back +mode. This may be useful if you are trying run down other problems that you +think might only occur when the system is very busy. -examples/discover -^^^^^^^^^^^^^^^^^ +## `dac` Write to DAC - This example exercises netutils/discover utility. This example initializes - and starts the UDP discover daemon. This daemon is useful for discovering - devices in local networks, especially with DHCP configured devices. It - listens for UDP broadcasts which also can include a device class so that - groups of devices can be discovered. It is also possible to address all - classes with a kind of broadcast discover. +This is a tool for writing values to DAC device. - This example will automatically be built as an NSH built-in if - CONFIG_NSH_BUILTIN_APPS is selected. Otherwise, it will be a standalone - program with entry point "discover_main". +## `dhcpd` DHCP Server - NuttX configuration settings: +This examples builds a tiny DHCP server for the target system. - CONFIG_EXAMPLES_DISCOVER_DHCPC - DHCP Client - CONFIG_EXAMPLES_DISCOVER_NOMAC - Use canned MAC address - CONFIG_EXAMPLES_DISCOVER_IPADDR - Target IP address - CONFIG_EXAMPLES_DISCOVER_DRIPADDR - Router IP address - CONFIG_EXAMPLES_DISCOVER_NETMASK - Network Mask +**Note**: For test purposes, this example can be built as a host-based DHCPD +server. This can be built as follows: -examples/djoystick -^^^^^^^^^^^^^^^^^^ +```bash +cd examples/dhcpd +make -f Makefile.host TOPDIR= +``` - This is a simple test of the discrete joystick driver. See details about - this driver in nuttx/include/nuttx/input/djoystick.h. +NuttX configuration settings: - Configuration Pre-requisites: +- `CONFIG_NET=y` – of course. +- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various + other UDP-related configuration settings). +- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed. +- `CONFIG_NETUTILS_NETLIB=y` – The networking library is needed. +- `CONFIG_EXAMPLES_DHCPD_NOMAC` – (May be defined to use software assigned MAC) - CONFIG_DJOYSTICK - The discrete joystick driver +See also `CONFIG_NETUTILS_DHCPD_*` settings described elsewhere and used in +`netutils/dhcpd/dhcpd.c`. These settings are required to described the behavior +of the daemon. - Example Configuration: - CONFIG_EXAMPLES_DJOYSTICK - Enabled the discrete joystick example - CONFIG_EXAMPLES_DJOYSTICK_DEVNAME - Joystick device name. Default - "/dev/djoy0" - CONFIG_EXAMPLES_DJOYSTICK_SIGNO - Signal used to signal the test - application. Default 13. +## `discover` UDP Discover Daemon +This example exercises `netutils/discover` utility. This example initializes and +starts the UDP discover daemon. This daemon is useful for discovering devices in +local networks, especially with DHCP configured devices. It listens for UDP +broadcasts which also can include a device class so that groups of devices can +be discovered. It is also possible to address all classes with a kind of +broadcast discover. -examples/dsptest -^^^^^^^^^^^^^^^^^^ +This example will automatically be built as an NSH built-in if +`CONFIG_NSH_BUILTIN_APPS` is selected. Otherwise, it will be a standalone +program with entry point `discover_main`. - This is a Unit Test for the Nuttx DSP library. It use Unity testing framework. +NuttX configuration settings: - Dependencies: +- `CONFIG_EXAMPLES_DISCOVER_DHCPC` – DHCP Client. +- `CONFIG_EXAMPLES_DISCOVER_NOMAC` – Use canned MAC address. +- `CONFIG_EXAMPLES_DISCOVER_IPADDR` – Target IP address. +- `CONFIG_EXAMPLES_DISCOVER_DRIPADDR` – Router IP address. +- `CONFIG_EXAMPLES_DISCOVER_NETMASK` – Network Mask. - CONFIG_LIBDSP=y - CONFIG_LIBDSP_DEBUG=y - CONFIG_TESTING_UNITY=y +## `djoystick` Discrete Joystick - Optional configuration: +This is a simple test of the discrete joystick driver. See details about this +driver in `nuttx/include/nuttx/input/djoystick.h`. - CONFIG_TESTING_UNITY_OUTPUT_COLOR - enable colored output +Configuration Pre-requisites: -examples/elf -^^^^^^^^^^^^ +- `CONFIG_DJOYSTICK` – The discrete joystick driver. - This example builds a small ELF loader test case. This includes several - test programs under examples/elf tests. These tests are build using - the relocatable ELF format and installed in a ROMFS file system. At run time, - each program in the ROMFS file system is executed. Requires CONFIG_ELF. - Other configuration options: +Example Configuration: - CONFIG_EXAMPLES_ELF_DEVMINOR - The minor device number of the ROMFS block - driver. For example, the N in /dev/ramN. Used for registering the RAM - block driver that will hold the ROMFS file system containing the ELF - executables to be tested. Default: 0 +- `CONFIG_EXAMPLES_DJOYSTICK` – Enabled the discrete joystick example. +- `CONFIG_EXAMPLES_DJOYSTICK_DEVNAME` – Joystick device name. Default + `/dev/djoy0`. +- `CONFIG_EXAMPLES_DJOYSTICK_SIGNO` – Signal used to signal the test + application. Default `13`. - CONFIG_EXAMPLES_ELF_DEVPATH - The path to the ROMFS block driver device. This - must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver - that will hold the ROMFS file system containing the ELF executables to be - tested. Default: "/dev/ram0" - NOTES: +## `dsptest` DSP - 1. CFLAGS should be provided in CELFFLAGS. RAM and FLASH memory regions - may require long allcs. For ARM, this might be: +This is a Unit Test for the Nuttx DSP library. It use Unity testing framework. - CELFFLAGS = $(CFLAGS) -mlong-calls +Dependencies: - Similarly for C++ flags which must be provided in CXXELFFLAGS. +```conf +CONFIG_LIBDSP=y +CONFIG_LIBDSP_DEBUG=y +CONFIG_TESTING_UNITY=y +``` - 2. Your top-level nuttx/Make.defs file must also include an appropriate definition, - LDELFFLAGS, to generate a relocatable ELF object. With GNU LD, this should - include '-r' and '-e main' (or _main on some platforms). +Optional configuration: - LDELFFLAGS = -r -e main +- `CONFIG_TESTING_UNITY_OUTPUT_COLOR` – enable colored output. - If you use GCC to link, you make also need to include '-nostdlib' or - '-nostartfiles' and '-nodefaultlibs'. +## `elf` ELF loader - 3. This example also requires genromfs. genromfs can be build as part of the - nuttx toolchain. Or can built from the genromfs sources that can be found - in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the - PATH variable must include the path to the genromfs executable. +This example builds a small ELF loader test case. This includes several test +programs under `examples/elf` tests. These tests are build using the relocatable +ELF format and installed in a ROMFS file system. At run time, each program in +the ROMFS file system is executed. Requires `CONFIG_ELF`. Other configuration +options: - 4. ELF size: The ELF files in this example are, be default, quite large - because they include a lot of "build garbage". You can greatly reduce the - size of the ELF binaries are using the 'objcopy --strip-unneeded' command to - remove un-necessary information from the ELF files. +- `CONFIG_EXAMPLES_ELF_DEVMINOR` – The minor device number of the ROMFS block + driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM + block driver that will hold the ROMFS file system containing the ELF + executables to be tested. Default: `0`. - 5. Simulator. You cannot use this example with the NuttX simulator on - Cygwin. That is because the Cygwin GCC does not generate ELF file but - rather some Windows-native binary format. +- `CONFIG_EXAMPLES_ELF_DEVPATH` – The path to the ROMFS block driver device. + This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block + driver that will hold the ROMFS file system containing the ELF executables to + be tested. Default: `/dev/ram0`. - If you really want to do this, you can create a NuttX x86 buildroot toolchain - and use that be build the ELF executables for the ROMFS file system. +**Notes**: - 6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at nuttx/binfmt/libelf/gnu-elf.ld. - That example might have to be tuned for your particular linker output to - position additional sections correctly. The GNU LD LDELFFLAGS then might - be: +1. `CFLAGS` should be provided in `CELFFLAGS`. RAM and FLASH memory regions may + require long allcs. For ARM, this might be: - LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld + ```makefile + CELFFLAGS = $(CFLAGS) -mlong-calls + ``` -examples/fb -^^^^^^^^^^^ + Similarly for C++ flags which must be provided in `CXXELFFLAGS`. - A simple test of the framebuffer character driver. +2. Your top-level `nuttx/Make.defs` file must also include an appropriate + definition, `LDELFFLAGS`, to generate a relocatable ELF object. With GNU LD, + this should include `-r` and `-e main` (or `_main` on some platforms). -examples/flash_test -^^^^^^^^^^^^^^^^^^^ + ```makefile + LDELFFLAGS = -r -e main + ``` - This example performs a SMART flash block device test. This test performs - a sector allocate, read, write, free and garbage collection test on a SMART - MTD block device. + If you use GCC to link, you make also need to include `-nostdlib` or + `-nostartfiles` and `-nodefaultlibs`. - * CONFIG_EXAMPLES_FLASH_TEST=y - Enables the FLASH Test +3. This example also requires `genromfs`. `genromfs` can be build as part of the + nuttx toolchain. Or can built from the `genromfs` sources that can be found + in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the + `PATH` variable must include the path to the genromfs executable. - Dependencies: +4. ELF size: The ELF files in this example are, be default, quite large because + they include a lot of _build garbage_. You can greatly reduce the size of the + ELF binaries are using the `objcopy --strip-unneeded` command to remove + un-necessary information from the ELF files. - * CONFIG_MTD_SMART=y - SMART block driver support - * CONFIG_BUILD_PROTECTED=n and CONFIG_BUILD_KERNEL=n - This test uses - internal OS interfaces and so is not available in the NUTTX kernel - builds +5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. + That is because the Cygwin GCC does not generate ELF file but rather some + Windows-native binary format. -examples/flowc -^^^^^^^^^^^^^^ + If you really want to do this, you can create a NuttX x86 buildroot toolchain + and use that be build the ELF executables for the ROMFS file system. - A simple test of serial hardware flow control. +6. Linker scripts. You might also want to use a linker scripts to combine + sections better. An example linker script is at + `nuttx/binfmt/libelf/gnu-elf.ld`. That example might have to be tuned for + your particular linker output to position additional sections correctly. The + GNU LD `LDELFFLAGS` then might be: -examples/ft80x -^^^^^^^^^^^^^^ + ```makefile + LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld + ``` - This examples has ports of several FTDI demos for the FTDI/BridgeTek FT80x - GUI chip. As an example configuration, see - nuttx/boards/arm/stm32/viewtool-stm32f107/configs/ft80x/defconfig. +## `fb` Framebuffer -examples/ftpc -^^^^^^^^^^^^^ +A simple test of the framebuffer character driver. - This is a simple FTP client shell used to exercise the capabilities - of the FTPC library (apps/netutils/ftpc). +## `flash_test` SMART Flash - From NSH, the startup command sequence is as follows. This is only - an example, your configuration could have different mass storage devices, - mount paths, and FTP directories: +This example performs a SMART flash block device test. This test performs a +sector allocate, read, write, free and garbage collection test on a SMART MTD +block device. - nsh> mount -t vfat /dev/mmcsd0 /tmp # Mount the SD card at /tmp - nsh> cd /tmp # cd into the /tmp directory - nsh> ftpc xx.xx.xx.xx[:pp] # Start the FTP client - nfc> login # Log into the FTP server - nfc> help # See a list of FTP commands +- `CONFIG_EXAMPLES_FLASH_TEST=y` – Enables the FLASH Test. - where xx.xx.xx.xx is the IP address of the FTP server and pp is an - optional port number. +Dependencies: - NOTE: By default, FTPC uses readline to get data from stdin. So your - defconfig file must have the following build path: +- `CONFIG_MTD_SMART=y` – SMART block driver support. +- `CONFIG_BUILD_PROTECTED=n` and `CONFIG_BUILD_KERNEL=n` – This test uses + internal OS interfaces and so is not available in the NUTTX kernel builds. - CONFIG_SYSTEM_READLINE=y +## `flowc` Serial Hardware Flow Control - NOTE: If you use the ftpc task over a telnet NSH connection, then you - should set the following configuration item: +A simple test of serial hardware flow control. - CONFIG_EXAMPLES_FTPC_FGETS=y +## `ft80x` FT80x GUI Chip - By default, the FTPC client will use readline() to get characters from - the console. Readline includes and command-line editor and echos - characters received in stdin back through stdout. Neither of these - behaviors are desire-able if Telnet is used. +This examples has ports of several FTDI demos for the FTDI/BridgeTek FT80x GUI +chip. As an example configuration, see +`nuttx/boards/arm/stm32/viewtool-stm32f107/configs/ft80x/defconfig`. - You may also want to define the following in your configuration file. - Otherwise, you will have not feedback about what is going on: +## `ftpc` FTP Client - CONFIG_DEBUG_FEATURES=y - CONFIG_DEBUG_INFO=y - CONFIG_DEBUG_FTPC=y +This is a simple FTP client shell used to exercise the capabilities of the FTPC +library (`apps/netutils/ftpc`). -examples/ftpd -^^^^^^^^^^^^^^ +From NSH, the startup command sequence is as follows. This is only an example, +your configuration could have different mass storage devices, mount paths, and +FTP directories: - This example exercises the FTPD daemon at apps/netuils/ftpd. Below are - configurations specific to the FTPD example (the FTPD daemon itself may - require other configuration options as well). +``` +nsh> mount -t vfat /dev/mmcsd0 /tmp # Mount the SD card at /tmp +nsh> cd /tmp # cd into the /tmp directory +nsh> ftpc xx.xx.xx.xx[:pp] # Start the FTP client +nfc> login # Log into the FTP server +nfc> help # See a list of FTP commands +``` - 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 - FTP daemon. Default: 2048 - CONFIG_EXAMPLES_FTPD_NONETINIT - Define to suppress configuration of the - network by apps/examples/ftpd. You would need to suppress network - configuration if the network is configuration prior to running the - example. +where `xx.xx.xx.xx` is the IP address of the FTP server and `pp` is an optional +port number. - NSH always initializes the network so if CONFIG_NSH_NETINIT is - defined, so is CONFIG_EXAMPLES_FTPD_NONETINIT (se it does not explicitly - need to be defined in that case): +**Note**: By default, FTPC uses `readline` to get data from `stdin`. So your +defconfig file must have the following build path: - CONFIG_NSH_BUILTIN_APPS - Build the FTPD daemon example test as an - NSH built-in function. By default the FTPD daemon will be built - as a standalone application. +```conf +CONFIG_SYSTEM_READLINE=y +``` - If CONFIG_EXAMPLES_FTPD_NONETINIT is not defined, then the following may - be specified to customized the network configuration: +**Note**: If you use the ftpc task over a telnet NSH connection, then you should +set the following configuration item: - CONFIG_EXAMPLES_FTPD_NOMAC - If the hardware has no MAC address of its - own, define this =y to provide a bogus address for testing. - CONFIG_EXAMPLES_FTPD_IPADDR - The target IP address. Default 10.0.0.2 - CONFIG_EXAMPLES_FTPD_DRIPADDR - The default router address. Default - 10.0.0.1 - CONFIG_EXAMPLES_FTPD_NETMASK - The network mask. Default: 255.255.255.0 +```conf +CONFIG_EXAMPLES_FTPC_FGETS=y +``` - Other required configuration settings: Of course TCP networking support - is required. But here are a couple that are less obvious: +By default, the FTPC client will use `readline()` to get characters from the +console. Readline includes and command-line editor and echos characters received +in stdin back through `stdout`. Neither of these behaviors are desire-able if +Telnet is used. - CONFIG_DISABLE_PTHREAD - pthread support is required +You may also want to define the following in your configuration file. Otherwise, +you will have not feedback about what is going on: - Other FTPD configuration options they may be of interest: +```conf +CONFIG_DEBUG_FEATURES=y +CONFIG_DEBUG_INFO=y +CONFIG_DEBUG_FTPC=y +``` - CONFIG_FTPD_VENDORID - The vendor name to use in FTP communications. - Default: "NuttX" - CONFIG_FTPD_SERVERID - The server name to use in FTP communications. - Default: "NuttX FTP Server" - CONFIG_FTPD_CMDBUFFERSIZE - The maximum size of one command. Default: - 512 bytes. - CONFIG_FTPD_DATABUFFERSIZE - The size of the I/O buffer for data - transfers. Default: 2048 bytes. - CONFIG_FTPD_WORKERSTACKSIZE - The stacksize to allocate for each - FTP daemon worker thread. Default: 2048 bytes. +## `ftpd` FTP daemon - The following netutils libraries should be enabled in your defconfig - file: +This example exercises the FTPD daemon at `apps/netuils/ftpd`. Below are +configurations specific to the FTPD example (the FTPD daemon itself may require +other configuration options as well). - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_TELNED=y +- `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 FTP daemon. + Default: `2048`. +- `CONFIG_EXAMPLES_FTPD_NONETINIT` – Define to suppress configuration of the + network by `apps/examples/ftpd`. You would need to suppress network + configuration if the network is configuration prior to running the example. -examples/gpio -^^^^^^^^^^^^ +NSH always initializes the network so if `CONFIG_NSH_NETINIT` is defined, so is +`CONFIG_EXAMPLES_FTPD_NONETINIT` (se it does not explicitly need to be defined +in that case): - A simple test/example of the NuttX GPIO driver. +- `CONFIG_NSH_BUILTIN_APPS` – Build the FTPD daemon example test as an NSH + built-in function. By default the FTPD daemon will be built as a standalone + application. -examples/hello -^^^^^^^^^^^^^^ +If `CONFIG_EXAMPLES_FTPD_NONETINIT` is not defined, then the following may be +specified to customized the network configuration: - This is the mandatory, "Hello, World!!" example. It is little more - than examples/null with a single printf statement. Really useful only - for bringing up new NuttX architectures. +- `CONFIG_EXAMPLES_FTPD_NOMAC` – If the hardware has no MAC address of its own, + define this `=y` to provide a bogus address for testing. +- `CONFIG_EXAMPLES_FTPD_IPADDR` – The target IP address. Default `10.0.0.2`. +- `CONFIG_EXAMPLES_FTPD_DRIPADDR` – The default router address. Default: + `10.0.0.1`. +- `CONFIG_EXAMPLES_FTPD_NETMASK` – The network mask. Default: `255.255.255.0`. - * CONFIG_NSH_BUILTIN_APPS - Build the "Hello, World" example as an NSH built-in application. +Other required configuration settings: Of course TCP networking support is +required. But here are a couple that are less obvious: -examples/helloxx -^^^^^^^^^^^^^^^^ +- `CONFIG_DISABLE_PTHREAD` – `pthread` support is required. - This is C++ version of the "Hello, World!!" example. It is intended - only to verify that the C++ compiler is functional, that basic C++ - library suupport is available, and that class are instantiated - correctly. - - NuttX configuration prerequisites: - - 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). - - NuttX configuration settings specific to this examp;le: - - CONFIG_NSH_BUILTIN_APPS -- Build the helloxx example as a - "built-in" that can be executed from the NSH command line. - - Also needed: - - CONFIG_HAVE_CXX=y - - And you may have to tinker with the following to get libxx to compile - properly: - - CCONFIG_ARCH_SIZET_LONG=y or =n - - The argument of the 'new' operators should take a type of size_t. But size_t - has an unknown underlying. In the nuttx sys/types.h header file, size_t - is typed as uint32_t (which is determined by architecture-specific logic). - But the C++ compiler may believe that size_t is of a different type resulting - in compilation errors in the operator. Using the underlying integer type - Instead of size_t seems to resolve the compilation issues. - -examples/hidkbd -^^^^^^^^^^^^^^^^ - - This is a simple test to debug/verify the USB host HID keyboard class - driver. - - CONFIG_EXAMPLES_HIDKBD_DEFPRIO - Priority of "waiter" thread. Default: - 50 - CONFIG_EXAMPLES_HIDKBD_STACKSIZE - Stacksize of "waiter" thread. Default - 1024 - CONFIG_EXAMPLES_HIDKBD_DEVNAME - Name of keyboard device to be used. - Default: "/dev/kbda" - CONFIG_EXAMPLES_HIDKBD_ENCODED - Decode special key press events in the - user buffer. In this case, the example coded will use the interfaces - defined in include/nuttx/input/kbd_codec.h to decode the returned - keyboard data. These special keys include such things as up/down - arrows, home and end keys, etc. If this not defined, only 7-bit print- - able and control ASCII characters will be provided to the user. - Requires CONFIG_HIDKBD_ENCODED && CONFIG_LIB_KBDCODEC - -examples/igmp -^^^^^^^^^^^^^ - - This is a trivial test of the NuttX IGMP capability. It present it - does not do much of value -- Much more is needed in order to verify - the IGMP features! - - * CONFIG_EXAMPLES_IGMP_NOMAC - Set if the hardware has no MAC address; one will be assigned - * CONFIG_EXAMPLES_IGMP_IPADDR - Target board IP address - * CONFIG_EXAMPLES_IGMP_DRIPADDR - Default router address - * CONFIG_EXAMPLES_IGMP_NETMASK - Network mask - * CONFIG_EXAMPLES_IGMP_GRPADDR - Multicast group address - * CONFIG_EXAMPLES_NETLIB - The networking library is needed +Other FTPD configuration options they may be of interest: -examples/i2cchar -^^^^^^^^^^^^^^^^ +- `CONFIG_FTPD_VENDORID` – The vendor name to use in FTP communications. + Default: `NuttX`. +- `CONFIG_FTPD_SERVERID` – The server name to use in FTP communications. + Default: `NuttX FTP Server`. +- `CONFIG_FTPD_CMDBUFFERSIZE` – The maximum size of one command. Default: `512` + bytes. +- `CONFIG_FTPD_DATABUFFERSIZE` – The size of the I/O buffer for data transfers. + Default: `2048` bytes. +- `CONFIG_FTPD_WORKERSTACKSIZE` – The stacksize to allocate for each FTP daemon + worker thread. Default: `2048` bytes. - A mindlessly simple test of an I2C driver. It reads an write garbage data to the - I2C transmitter and/or received as fast possible. +The following netutils libraries should be enabled in your `defconfig` file: - This test depends on these specific I2S/AUDIO/NSH configurations settings (your - specific I2S settings might require additional settings). +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETUTILS_TELNED=y +``` - CONFIG_I2S - Enabled I2S support - CONFIG_AUDIO - Enabled audio support - CONFIG_DRIVERS_AUDIO - Enable audio device support - CONFIG_AUDIO_I2SCHAR = Enabled support for the I2S character device - CONFIG_NSH_BUILTIN_APPS - Build the I2S test as an NSH built-in function. - Default: Built as a standalone program - - Specific configuration options for this example include: - - CONFIG_EXAMPLES_I2SCHAR - Enables the I2C test - CONFIG_EXAMPLES_I2SCHAR_DEVPATH - The default path to the ADC device. - Default: /dev/i2schar0 - CONFIG_EXAMPLES_I2SCHAR_TX - This should be set if the I2S device supports - a transmitter. - CONFIG_EXAMPLES_I2SCHAR_TXBUFFERS - This is the default number of audio - buffers to send before the TX transfers terminate. When both TX and - RX transfers terminate, the task exits (and, if an NSH builtin, the - i2schar command returns). This number can be changed from the NSH - command line. - CONFIG_EXAMPLES_I2SCHAR_TXSTACKSIZE - This is the stack size to use when - starting the transmitter thread. Default 1536. - CONFIG_EXAMPLES_I2SCHAR_RX - This should be set if the I2S device supports - a transmitter. - CONFIG_EXAMPLES_I2SCHAR_RXBUFFERS - This is the default number of audio - buffers to receive before the RX transfers terminate. When both TX and - RX transfers terminate, the task exits (and, if an NSH builtin, the - i2schar command returns). This number can be changed from the NSH - command line. - CONFIG_EXAMPLES_I2SCHAR_RXSTACKSIZE - This is the stack size to use when - starting the receiver thread. Default 1536. - CONFIG_EXAMPLES_I2SCHAR_BUFSIZE - The size of the data payload in one - audio buffer. Applies to both TX and RX audio buffers. - CONFIG_EXAMPLES_I2SCHAR_DEVINIT - Define if architecture-specific I2S - device initialize is available. If defined, the platform specific - code must provide a function i2schar_devinit() that will be called - each time that this test executes. Not available in the kernel build - mode. - -examples/ina219 -^^^^^^^^^^^^^^^ - - This is a simple infinite loop that polls the INA219 sensor and displays - the measurements. - -examples/ipforward -^^^^^^^^^^^^^^^^^^ - - A simple test of IP forwarding using TUN devices. This can be used on any - platform, but was intended for use on the simulation platform because it - performs a test of IP forwarding without the use of hardware. - -examples/json -^^^^^^^^^^^^^ - - This example exercises the cJSON implementation at apps/netutils/json. - This example contains logic taken from the cJSON project: - - http://sourceforge.net/projects/cjson/ - - The example corresponds to SVN revision r42 (with lots of changes for - NuttX coding standards). As of r42, the SVN repository was last updated - on 2011-10-10 so I presume that the code is stable and there is no risk - of maintaining duplicate logic in the NuttX repository. - -examples/leds -^^^^^^^^^^^^ - - This is a simple test of the board LED driver at nuttx/drivers/leds/userled_*.c. - -examples/lis2csh_reader -^^^^^^^^^^^^^^^^^^^^^^^ - - A simple reader example for the LIS3DSH acceleration sensor as found on - STM32F4Discovery rev. C - -examples/hts221_reader -^^^^^^^^^^^^^^^^^^^^^^^ - - A simple reader example for the HTS221 humidity sensor. - -examples/lsm303_reader -^^^^^^^^^^^^^^^^^^^^^^^ +## `gpio` GPIO Read and Write - A simple reader example for the LSM303 acc-mag sensor. +A simple `test/example` of the NuttX GPIO driver. -examples/lsm6dsl_reader -^^^^^^^^^^^^^^^^^^^^^^^ +## `hello` Hello World - A simple reader example for the LSM6DSL acc-gyro sensor. +This is the mandatory, _Hello, World!!_ example. It is little more than +`examples/null` with a single `printf` statement. Really useful only for +bringing up new NuttX architectures. -examples/media -^^^^^^^^^^^^^^ +- `CONFIG_NSH_BUILTIN_APPS` – Build the _Hello, World_ example as an NSH + built-in application. - The media test simply writes values onto the media hidden behind a - character driver and verifies that the media can be successfully written - and read. This low level test is useful in the early phases of the - bringup of a new block or mtd driver because it avoids the complexity of - a file system. +## `helloxx` Hello World in C++ - This test uses a character driver and cannot directly access block or mtd - drivers. This test is suitable for use EEPROM character drivers (see - nuttx/drivers/eeprom), or with block drivers wrapped as character drivers - (see nuttx/drivers/bch) +This is C++ version of the _Hello, World!!_ example. It is intended only to +verify that the C++ compiler is functional, that basic C++ library support is +available, and that class are instantiated correctly. - int ret = bchdev_register(, - , false); +NuttX configuration prerequisites: - MTD drivers need an additional wrapper layer, the FTL wrapper must first - be used to convert the MTD driver to a block device: +- `CONFIG_HAVE_CXX` – Enable C++ Support. - int ret = ftl_initialize(, mtd); - ret = bchdev_register(/dev/mtdblock, , - false); +Optional NuttX configuration settings: -examples/module -^^^^^^^^^^^^^^ +- `CONFIG_HAVE_CXXINITIALIZE` – Enable support for static constructors (may not + be available on all platforms). - This example builds a small loadable module test case. This includes a - character driver under examples/module/drivers. This driver is built using - the relocatable ELF format and installed in a ROMFS file system. At run time, - the driver module is loaded and exercised. Requires CONFIG_MODULE. - Other configuration options: +NuttX configuration settings specific to this example: - CONFIG_EXAMPLES_ELF_DEVMINOR - The minor device number of the ROMFS block - driver. For example, the N in /dev/ramN. Used for registering the RAM - block driver that will hold the ROMFS file system containing the ELF - executables to be tested. Default: 0 +- `CONFIG_NSH_BUILTIN_APPS` – Build the helloxx example as a _built-in_ that can + be executed from the NSH command line. - CONFIG_EXAMPLES_ELF_DEVPATH - The path to the ROMFS block driver device. This - must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver - that will hold the ROMFS file system containing the ELF executables to be - tested. Default: "/dev/ram0" +Also needed: - NOTES: +- `CONFIG_HAVE_CXX=y` - 1. CFLAGS should be provided in CMODULEFLAGS. RAM and FLASH memory regions - may require long allcs. For ARM, this might be: +And you may have to tinker with the following to get libxx to compile properly: - CMODULEFLAGS = $(CFLAGS) -mlong-calls +- `CCONFIG_ARCH_SIZET_LONG=y` or `=n`. - Similarly for C++ flags which must be provided in CXXMODULEFLAGS. +The argument of the `new` operators should take a type of `size_t`. But `size_t` +has an unknown underlying. In the nuttx `sys/types.h` header file, `size_t` is +typed as `uint32_t` (which is determined by architecture-specific logic). But +the C++ compiler may believe that `size_t` is of a different type resulting in +compilation errors in the operator. Using the underlying integer type Instead of +`size_t` seems to resolve the compilation issues. - 2. Your top-level nuttx/Make.defs file must also include an appropriate definition, - LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, this should - include '-r' and '-e '. +## `hidkbd` USB Host HID keyboard - LDMODULEFLAGS = -r -e module_initialize +This is a simple test to `debug/verify` the USB host HID keyboard class driver. - If you use GCC to link, you make also need to include '-nostdlib' or - '-nostartfiles' and '-nodefaultlibs'. +- `CONFIG_EXAMPLES_HIDKBD_DEFPRIO` – Priority of _waiter_ thread. Default: `50`. +- `CONFIG_EXAMPLES_HIDKBD_STACKSIZE` – Stacksize of _waiter_ thread. Default + `1024`. +- `CONFIG_EXAMPLES_HIDKBD_DEVNAME` – Name of keyboard device to be used. + Default: `/dev/kbda`. +- `CONFIG_EXAMPLES_HIDKBD_ENCODED` – Decode special key press events in the + user buffer. In this case, the example coded will use the interfaces defined + in `include/nuttx/input/kbd_codec.h` to decode the returned keyboard data. + These special keys include such things as up/down arrows, home and end keys, + etc. If this not defined, only 7-bit printable and control ASCII characters + will be provided to the user. Requires `CONFIG_HIDKBD_ENCODED` and + `CONFIG_LIB_KBDCODEC`. - 3. This example also requires genromfs. genromfs can be build as part of the - nuttx toolchain. Or can built from the genromfs sources that can be found - in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the - PATH variable must include the path to the genromfs executable. +## `igmp` Trivial IGMP - 4. ELF size: The ELF files in this example are, be default, quite large - because they include a lot of "build garbage". You can greatly reduce the - size of the ELF binaries are using the 'objcopy --strip-unneeded' command to - remove un-necessary information from the ELF files. +This is a trivial test of the NuttX IGMP capability. It present it does not do +much of value – Much more is needed in order to verify the IGMP features! - 5. Simulator. You cannot use this example with the NuttX simulator on - Cygwin. That is because the Cygwin GCC does not generate ELF file but - rather some Windows-native binary format. +- `CONFIG_EXAMPLES_IGMP_NOMAC` – Set if the hardware has no MAC address; one + will be assigned. +- `CONFIG_EXAMPLES_IGMP_IPADDR` – Target board IP address. +- `CONFIG_EXAMPLES_IGMP_DRIPADDR` – Default router address. +- `CONFIG_EXAMPLES_IGMP_NETMASK` – Network mask. +- `CONFIG_EXAMPLES_IGMP_GRPADDR` – Multicast group address. +- `CONFIG_EXAMPLES_NETLIB` – The networking library is needed. - If you really want to do this, you can create a NuttX x86 buildroot toolchain - and use that be build the ELF executables for the ROMFS file system. +## `i2cchar` Transfer Through I2C - 6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at nuttx/libc/modlib/gnu-elf.ld. - That example might have to be tuned for your particular linker output to - position additional sections correctly. The GNU LD LDMODULEFLAGS then might - be: +A mindlessly simple test of an I2C driver. It reads an write garbage data to the +I2C transmitter and/or received as fast possible. - LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld +This test depends on these specific I2S/AUDIO/NSH configurations settings (your +specific I2S settings might require additional settings). -examples/modbus -^^^^^^^^^^^^^^^ +- `CONFIG_I2S` – Enabled I2S support. +- `CONFIG_AUDIO` – Enabled audio support. +- `CONFIG_DRIVERS_AUDIO` – Enable audio device support. +- `CONFIG_AUDIO_I2SCHAR` – Enabled support for the I2S character device. +- `CONFIG_NSH_BUILTIN_APPS` – Build the I2S test as an NSH built-in function. + Default: Built as a standalone program. - This is a port of the FreeModbus Linux demo. It derives from the - demos/LINUX directory of the FreeModBus version 1.5.0 (June 6, 2010) - that can be downloaded in its entirety from http://developer.berlios.de/project/showfiles.php?group_id=6120. +Specific configuration options for this example include: - CONFIG_EXAMPLES_MODBUS_PORT, Default 0 (for /dev/ttyS0) - CONFIG_EXAMPLES_MODBUS_BAUD, Default B38400 - CONFIG_EXAMPLES_MODBUS_PARITY, Default MB_PAR_EVEN +- `CONFIG_EXAMPLES_I2SCHAR` – Enables the I2C test. - CONFIG_EXAMPLES_MODBUS_REG_INPUT_START, Default 1000 - CONFIG_EXAMPLES_MODBUS_REG_INPUT_NREGS, Default 4 - CONFIG_EXAMPLES_MODBUS_REG_HOLDING_START, Default 2000 - CONFIG_EXAMPLES_MODBUS_REG_HOLDING_NREGS, Default 130 +- `CONFIG_EXAMPLES_I2SCHAR_DEVPATH` – The default path to the ADC device. + Default: `/dev/i2schar0`. - The FreeModBus library resides at apps/modbus. See apps/modbus/README.txt - for additional configuration information. +- `CONFIG_EXAMPLES_I2SCHAR_TX` – This should be set if the I2S device supports a + transmitter. -examples/mount -^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_I2SCHAR_TXBUFFERS` – This is the default number of audio + buffers to send before the TX transfers terminate. When both TX and RX + transfers terminate, the task exits (and, if an NSH builtin, the `i2schar` + command returns). This number can be changed from the NSH command line. - This contains a simple test of filesystem mountpoints. +- `CONFIG_EXAMPLES_I2SCHAR_TXSTACKSIZE` – This is the stack size to use when + starting the transmitter thread. Default `1536`. - * CONFIG_EXAMPLES_MOUNT_DEVNAME - The name of the user-provided block device to mount. - If CONFIG_EXAMPLES_MOUNT_DEVNAME is not provided, then - a RAM disk will be configured. +- `CONFIG_EXAMPLES_I2SCHAR_RX` – This should be set if the I2S device supports a + transmitter. - * CONFIG_EXAMPLES_MOUNT_NSECTORS - The number of "sectors" in the RAM disk used when - CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined. +- `CONFIG_EXAMPLES_I2SCHAR_RXBUFFERS` – This is the default number of audio + buffers to receive before the RX transfers terminate. When both TX and RX + transfers terminate, the task exits (and, if an NSH builtin, the `i2schar` + command returns). This number can be changed from the NSH command line. - * CONFIG_EXAMPLES_MOUNT_SECTORSIZE - The size of each sectors in the RAM disk used when - CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined. +- `CONFIG_EXAMPLES_I2SCHAR_RXSTACKSIZE` – This is the stack size to use when + starting the receiver thread. Default `1536`. - * CONFIG_EXAMPLES_MOUNT_RAMDEVNO - The RAM device minor number used to mount the RAM disk used - when CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined. The - default is zero (meaning that "/dev/ram0" will be used). +- `CONFIG_EXAMPLES_I2SCHAR_BUFSIZE` – The size of the data payload in one audio + buffer. Applies to both TX and RX audio buffers. -examples/mtdpart -^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_I2SCHAR_DEVINIT` – Define if architecture-specific I2S device + initialize is available. If defined, the platform specific code must provide a + function `i2schar_devinit()` that will be called each time that this test + executes. Not available in the kernel build mode. - This examples provides a simple test of MTD partition logic. +## `ina219` Current/Power Monitor `INA219` - * CONFIG_EXAMPLES_MTDPART - Enables the MTD partition test example - * CONFIG_EXAMPLES_MTDPART_ARCHINIT - The default is to use the RAM MTD - device at drivers/mtd/rammtd.c. But an architecture-specific MTD driver - can be used instead by defining CONFIG_EXAMPLES_MTDPART_ARCHINIT. In - this case, the initialization logic will call mtdpart_archinitialize() - to obtain the MTD driver instance. - * CONFIG_EXAMPLES_MTDPART_NPARTITIONS - This setting provides the number - of partitions to test. The test will divide the reported size of the - MTD device into equal-sized sub-regions for each test partition. Default: - 3 +This is a simple infinite loop that polls the `INA219` sensor and displays the +measurements. - When CONFIG_EXAMPLES_MTDPART_ARCHINIT is not defined, this test will use - the RAM MTD device at drivers/mtd/rammtd.c to simulate FLASH. The size of - the allocated RAM drive will be: CONFIG_EXMPLES_RAMMTD_ERASESIZE * - CONFIG_EXAMPLES_MTDPART_NEBLOCKS +## `ipforward` IP Forwarding Using TUN - * CONFIG_EXAMPLES_MTDPART_ERASESIZE - This value gives the size of one - erase block in the MTD RAM device. This must exactly match the default - configuration in drivers/mtd/rammtd.c! - * CONFIG_EXAMPLES_MTDPART_NEBLOCKS - This value gives the number of erase - blocks in MTD RAM device. +A simple test of IP forwarding using TUN devices. This can be used on any +platform, but was intended for use on the simulation platform because it +performs a test of IP forwarding without the use of hardware. -examples/mtdrwb -^^^^^^^^^^^^^^^^ - - This examples provides a simple test of MTD Read-Ahead/Write buffering - logic. - - * CONFIG_EXAMPLES_MTDRWB - Enables the MTD R/W buffering test example - * CONFIG_EXAMPLES_MTDRWB_ARCHINIT - The default is to use the RAM MTD - device at drivers/mtd/rammtd.c. But an architecture-specific MTD driver - can be used instead by defining CONFIG_EXAMPLES_MTDRWB_ARCHINIT. In - this case, the initialization logic will call mtdrwb_archinitialize() - to obtain the MTD driver instance. - - When CONFIG_EXAMPLES_MTDRWB_ARCHINIT is not defined, this test will use - the RAM MTD device at drivers/mtd/rammtd.c to simulate FLASH. The size of - the allocated RAM drive will be: CONFIG_EXMPLES_RAMMTD_ERASESIZE * - CONFIG_EXAMPLES_MTDRWB_NEBLOCKS - - * CONFIG_EXAMPLES_MTDRWB_ERASESIZE - This value gives the size of one - erase block in the MTD RAM device. This must exactly match the default - configuration in drivers/mtd/rammtd.c! - * CONFIG_EXAMPLES_MTDRWB_NEBLOCKS - This value gives the number of erase - blocks in MTD RAM device. - -examples/netpkt -^^^^^^^^^^^^^^^ - - A test of AF_PACKET, "raw" sockets. Contributed by Lazlo Sitzer. - -examples/netloop -^^^^^^^^^^^^^^^^ - - This is a simple test of the netwok loopback device. examples/nettest can - also be configured to provide (better) test of local loopback transfers. - This version derives from examples/poll and is focused on testing poll() - with loopback devices. - - CONFIG_EXAMPLES_NETLOOP=y - Enables the nettest example - - Dependencies: - - CONFIG_NET_LOOPBACK - Requires local loopback support - CONFIG_NET_TCP - Requires TCP support with the following: - CONFIG_NET_TCPBACKLOG - CONFIG_NET_TCP_WRITE_BUFFERS - CONFIG_NET_IPv4 - Currently supports only IPv4 - -examples/nettest -^^^^^^^^^^^^^^^^ - - This is a simple network test for verifying client- and server- - functionality in a TCP/IP connection. - - CONFIG_EXAMPLES_NETTEST=y - Enables the nettest example - CONFIG_EXAMPLES_NETLIB=y - The networking library in needed. - - Configurations: - - - Server on target hardware; client on host - - Client on target hardware; Server on host - - Server and Client on different targets. - - Loopback configuration with both client and server on the same target. - - 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/nx -^^^^^^^^^^^ - - This directory contains a simple test of a subset of the NX APIs - defined in include/nuttx/nx/nx.h. The following configuration options - can be selected: - - CONFIG_NSH_BUILTIN_APPS -- Build the NX example as a "built-in" - that can be executed from the NSH command line - CONFIG_EXAMPLES_NX_BGCOLOR -- The color of the background. Default depends on - CONFIG_EXAMPLES_NX_BPP. - CONFIG_EXAMPLES_NX_COLOR1 -- The color of window 1. Default depends on - CONFIG_EXAMPLES_NX_BPP. - CONFIG_EXAMPLES_NX_COLOR2 -- The color of window 2. Default depends on - CONFIG_EXAMPLES_NX_BPP. - CONFIG_EXAMPLES_NX_TBCOLOR -- The color of the toolbar. Default depends on - CONFIG_EXAMPLES_NX_BPP. - CONFIG_EXAMPLES_NX_FONTID - Selects the font (see font ID numbers in - include/nuttx/nx/nxfonts.h) - CONFIG_EXAMPLES_NX_FONTCOLOR -- The color of the fonts. Default depends on - CONFIG_EXAMPLES_NX_BPP. - CONFIG_EXAMPLES_NX_BPP -- Pixels per pixel to use. Valid options - include 2, 4, 8, 16, 24, and 32. Default is 32. - CONFIG_EXAMPLES_NX_RAWWINDOWS -- Use raw windows; Default is to - use pretty, framed NXTK windows with toolbars. - CONFIG_EXAMPLES_NX_STACKSIZE -- The stacksize to use when creating - the NX server. Default 2048 - CONFIG_EXAMPLES_NX_CLIENTPRIO -- The client priority. Default: 100 - CONFIG_EXAMPLES_NX_SERVERPRIO -- The server priority. Default: 120 - CONFIG_EXAMPLES_NX_LISTENERPRIO -- The priority of the event listener - thread. Default 80. - CONFIG_EXAMPLES_NX_NOTIFYSIGNO -- The signal number to use with - nx_eventnotify(). Default: 4 - - The example also has the following settings and will generate an error - if they are not as expected: - - CONFIG_DISABLE_MQUEUE=n - CONFIG_DISABLE_PTHREAD=n - CONFIG_NX_BLOCKING=y - CONFIG_LIB_BOARDCTL=y - -examples/nxterm -^^^^^^^^^^^^^^^^^^ - - This directory contains yet another version of the NuttShell (NSH). This - version uses the NX console device defined in include/nuttx/nx/nxterm.h - for output. the result is that the NSH input still come from the standard - console input (probably a serial console). But the text output will go to - an NX winbdow. Prerequisite configuration settings for this test include: - - CONFIG_NX=y -- NX graphics must be enabled - CONFIG_NXTERM=y -- The NX console driver must be built - CONFIG_DISABLE_MQUEUE=n -- Message queue support must be available. - CONFIG_DISABLE_PTHREAD=n -- pthreads are needed - CONFIG_NX_BLOCKING=y -- pthread APIs must be blocking - CONFIG_NSH_CONSOLE=y -- NSH must be configured to use a console. - - The following configuration options can be selected to customize the - test: - - CONFIG_EXAMPLES_NXTERM_BGCOLOR -- The color of the background. Default - Default is a darker royal blue. - CONFIG_EXAMPLES_NXTERM_WCOLOR -- The color of the window. Default is a light - slate blue. - CONFIG_EXAMPLES_NXTERM_FONTID -- Selects the font (see font ID numbers in - include/nuttx/nx/nxfonts.h) - CONFIG_EXAMPLES_NXTERM_FONTCOLOR -- The color of the fonts. Default is - black. - CONFIG_EXAMPLES_NXTERM_BPP -- Pixels per pixel to use. Valid options - include 2, 4, 8, 16, 24, and 32. Default is 32. - CONFIG_EXAMPLES_NXTERM_TOOLBAR_HEIGHT -- The height of the toolbar. - Default: 16 - CONFIG_EXAMPLES_NXTERM_TBCOLOR -- The color of the toolbar. Default is - a medium grey. - CONFIG_EXAMPLES_NXTERM_MINOR -- The NX console device minor number. - Default is 0 corresponding to /dev/nxterm0 - CONFIG_EXAMPLES_NXTERM_DEVNAME -- The quoted, full path to the - NX console device corresponding to CONFIG_EXAMPLES_NXTERM_MINOR. - Default: "/dev/nxterm0" - CONFIG_EXAMPLES_NXTERM_PRIO - Priority of the NxTerm task. - Default: SCHED_PRIORITY_DEFAULT - CONFIG_EXAMPLES_NXTERM_STACKSIZE - Stack size allocated for the - NxTerm task. Default: 2048 - CONFIG_EXAMPLES_NXTERM_STACKSIZE -- The stacksize to use when creating - the NX server. Default 2048 - CONFIG_EXAMPLES_NXTERM_CLIENTPRIO -- The client priority. Default: 100 - CONFIG_EXAMPLES_NXTERM_SERVERPRIO -- The server priority. Default: 120 - CONFIG_EXAMPLES_NXTERM_LISTENERPRIO -- The priority of the event listener - thread. Default 80. - CONFIG_EXAMPLES_NXTERM_NOTIFYSIGNO -- The signal number to use with - nx_eventnotify(). Default: 4 - -examples/nxflat -^^^^^^^^^^^^^^^ - - This example builds a small NXFLAT test case. This includes several - test programs under examples/nxflat tests. These tests are build using - the NXFLAT format and installed in a ROMFS file system. At run time, - each program in the ROMFS file system is executed. Requires CONFIG_NXFLAT. - -examplex/nxhello -^^^^^^^^^^^^^^^^ - - A very simple graphics example that just says "Hello, World!" in the - center of the display. - - The following configuration options can be selected: - - CONFIG_NSH_BUILTIN_APPS -- Build the NXHELLO example as a "built-in" - that can be executed from the NSH command line - CONFIG_EXAMPLES_NXHELLO_VPLANE -- The plane to select from the frame- - buffer driver for use in the test. Default: 0 - CONFIG_EXAMPLES_NXHELLO_DEVNO - The LCD device to select from the LCD - driver for use in the test: Default: 0 - CONFIG_EXAMPLES_NXHELLO_BGCOLOR -- The color of the background. Default - depends on CONFIG_EXAMPLES_NXHELLO_BPP. - CONFIG_EXAMPLES_NXHELLO_FONTID - Selects the font (see font ID numbers in - include/nuttx/nx/nxfonts.h) - CONFIG_EXAMPLES_NXHELLO_FONTCOLOR -- The color of the fonts used in the - background window. Default depends on CONFIG_EXAMPLES_NXHELLO_BPP. - CONFIG_EXAMPLES_NXHELLO_BPP -- Pixels per pixel to use. Valid options - include 2, 4, 8, 16, 24, and 32. Default is 32. - -examples/nximage -^^^^^^^^^^^^^^^^ - - This is a simple example that just puts the NuttX logo image in the center - of the display. This only works for RGB23 (888), RGB16 (656), RGB8 (332), - and 8-bit greyscale for now. - - CONFIG_NSH_BUILTIN_APPS -- Build the NXIMAGE example as a "built-in" - that can be executed from the NSH command line - CONFIG_EXAMPLES_NXIMAGE_VPLANE -- The plane to select from the frame- - buffer driver for use in the test. Default: 0 - CONFIG_EXAMPLES_NXIMAGE_DEVNO - The LCD device to select from the LCD - driver for use in the test: Default: 0 - CONFIG_EXAMPLES_NXIMAGE_BPP -- Pixels per pixel to use. Valid options - include 8, 16, and 24. Default is 16. - CONFIG_EXAMPLES_NXIMAGE_XSCALEp5, CONFIG_EXAMPLES_NXIMAGE_XSCALE1p5, - CONFIG_EXAMPLES_NXIMAGE_XSCALE2p0 -- The logo image width is 160 columns. - One of these may be defined to rescale the image horizontally by .5, 1.5, - or 2.0. - CONFIG_EXAMPLES_NXIMAGE_YSCALEp5, CONFIG_EXAMPLES_NXIMAGE_YSCALE1p5, - CONFIG_EXAMPLES_NXIMAGE_YSCALE2p0 -- The logo image height is 160 rows. - One of these may be defined to rescale the image vertically by .5, 1.5, - or 2.0. - CONFIG_EXAMPLES_NXIMAGE_GREYSCALE -- Grey scale image. Default: RGB. - - How was that run-length encoded image produced? - - a. I used GIMP output the image as a .c file. - b. I added some C logic to palette-ize the RGB image in the GIMP .c file - c. Then I add some simple run-length encoding to palette-ized image. - - But now there is a tool that can be found in the NxWidgets package at - NxWidgets/tools/bitmap_converter.py that can be used to convert any - graphics format to the NuttX RLE format. - - NOTE: As of this writing, most of the pixel depth, scaling options, and - combinations thereof have not been tested. - -examplex/nxlines -^^^^^^^^^^^^^^^^ - - A very simple graphics example that just exercised the NX line drawing - logic. - - The following configuration options can be selected: - - CONFIG_EXAMPLES_NXLINES_VPLANE -- The plane to select from the frame- - buffer driver for use in the test. Default: 0 - CONFIG_EXAMPLES_NXLINES_DEVNO - The LCD device to select from the LCD - driver for use in the test: Default: 0 - CONFIG_EXAMPLES_NXLINES_BGCOLOR -- The color of the background. Default - depends on CONFIG_EXAMPLES_NXLINES_BPP. - CONFIG_EXAMPLES_NXLINES_LINEWIDTH - Selects the width of the lines in - pixels (default: 16) - CONFIG_EXAMPLES_NXLINES_LINECOLOR -- The color of the central lines drawn - in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP - (there really is no meaningful default). - CONFIG_EXAMPLES_NXLINES_BORDERWIDTH -- The width of the circular border - drawn in the background window. (default: 16). - CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the circular border - drawn in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP - (there really is no meaningful default). - CONFIG_EXAMPLES_NXLINES_CIRCLECOLOR -- The color of the circular region - filled in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP - (there really is no meaningful default). - CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the lines drawn in the - background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP (there - really is no meaningful default). - - CONFIG_EXAMPLES_NXLINES_BPP -- Pixels per pixel to use. Valid options - include 2, 4, 8, 16, 24, and 32. Default is 16. - CONFIG_NSH_BUILTIN_APPS - Build the NX lines examples as an NSH built-in - function. - -examples/nxtext -^^^^^^^^^^^^^^^ - - This directory contains another simple test of a subset of the NX APIs - defined in include/nuttx/nx/nx.h. This text focuses on text displays on - the display background combined with pop-up displays over the text. - The text display will continue to update while the pop-up is visible. - - NOTE: This example will *only* work with FB drivers and with LCD - drivers that support reading the contents of the internal LCD memory - *unless* you define CONFIG_EXAMPLES_NXTEXT_NOGETRUN. If you notice - garbage on the display or a failure at the point where the display - should scroll, it is probably because you have an LCD driver that is - write-only. - - The following configuration options can be selected: - - CONFIG_NSH_BUILTIN_APPS -- Build the NXTEXT example as a "built-in" - that can be executed from the NSH command line - CONFIG_EXAMPLES_NXTEXT_BGCOLOR -- The color of the background. Default - depends on CONFIG_EXAMPLES_NXTEXT_BPP. - CONFIG_EXAMPLES_NXTEXT_BGFONTID - Selects the font to use in the - background text (see font ID numbers in include/nuttx/nx/nxfonts.h) - CONFIG_EXAMPLES_NXTEXT_BGFONTCOLOR -- The color of the fonts used in the - background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP. - CONFIG_EXAMPLES_NXTEXT_PUCOLOR -- The color of the pop-up window. Default - depends on CONFIG_EXAMPLES_NXTEXT_BPP. - CONFIG_EXAMPLES_NXTEXT_PUFONTID - Selects the font to use in the pop-up - windows (see font ID numbers in include/nuttx/nx/nxfonts.h) - CONFIG_EXAMPLES_NXTEXT_PUFONTCOLOR -- The color of the fonts used in the - background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP. - CONFIG_EXAMPLES_NXTEXT_BPP -- Pixels per pixel to use. Valid options - include 2, 4, 8, 16, 24, and 32. Default is 32. - CONFIG_EXAMPLES_NXTEXT_NOGETRUN -- If your display is read-only OR if - reading is not reliable, then select this configuration to avoid - reading from the display. - CONFIG_EXAMPLES_NXTEXT_BMCACHE - The maximum number of characters that - can be put in the background window. Default is 128. - CONFIG_EXAMPLES_NXTEXT_GLCACHE - The maximum number of pre-rendered - fonts that can be retained for the background window. - CONFIG_EXAMPLES_NXTEXT_STACKSIZE -- The stacksize to use when creating - the NX server. Default 2048 - CONFIG_EXAMPLES_NXTEXT_CLIENTPRIO -- The client priority. Default: 100 - CONFIG_EXAMPLES_NXTEXT_SERVERPRIO -- The server priority. Default: 120 - CONFIG_EXAMPLES_NXTEXT_LISTENERPRIO -- The priority of the event listener - thread. Default 80. - CONFIG_EXAMPLES_NXTEXT_NOTIFYSIGNO -- The signal number to use with - nx_eventnotify(). Default: 4 - - The example also expects the following settings and will generate an - error if they are not as expected: - - CONFIG_DISABLE_MQUEUE=n - CONFIG_DISABLE_PTHREAD=n - CONFIG_NX_BLOCKING=y - -examples/null -^^^^^^^^^^^^^ - - This is the do nothing application. It is only used for bringing - up new NuttX architectures in the most minimal of environments. - -examples/obd2 -^^^^^^^^^^^^^ - - A simple test of apps/canutils/libobd2. - -examples/oneshot -^^^^^^^^^^^^^^^^ - - Simple test of a oneshot driver. - -examples/pca9635 -^^^^^^^^^^^^^^^^ - - A simple test of the PCA9635PW LED driver. - -examples/pdcurses -^^^^^^^^^^^^^^^^^ - - This directory contains the demo/test programs that accompany the public - domain cursors package (pdcurses) that can be found at apps/graphics/pdcurs34. - -examples/pipe -^^^^^^^^^^^^^ - - A test of the mkfifo() and pipe() APIs. Requires CONFIG_PIPES - - * CONFIG_EXAMPLES_PIPE_STACKSIZE - Sets the size of the stack to use when creating the child tasks. - The default size is 1024. +## `json` cJSON -examples/poll -^^^^^^^^^^^^^ +This example exercises the cJSON implementation at `apps/netutils/json`. This +example contains logic taken from the cJSON project: - A test of the poll() and select() APIs using FIFOs and, if available, - stdin, and a TCP/IP socket. In order to use the TCP/IP select - test, you must have the following things selected in your NuttX - configuration file: +http://sourceforge.net/projects/cjson/ - CONFIG_NET - Defined for general network support - CONFIG_NET_TCP - Defined for TCP/IP support - CONFIG_NET_NTCP_READAHEAD_BUFFERS - Defined to be greater than zero +The example corresponds to SVN revision `r42` (with lots of changes for NuttX +coding standards). As of `r42`, the SVN repository was last updated on +`2011-10-10` so I presume that the code is stable and there is no risk of +maintaining duplicate logic in the NuttX repository. - CONFIG_EXAMPLES_POLL_NOMAC - (May be defined to use software assigned MAC) - CONFIG_EXAMPLES_POLL_IPADDR - Target IP address - CONFIG_EXAMPLES_POLL_DRIPADDR - Default router IP address - CONFIG_EXAMPLES_POLL_NETMASK - Network mask +## `leds` Toggle LEDs - In order to for select to work with incoming connections, you - must also select: +This is a simple test of the board LED driver at +`nuttx/drivers/leds/userled_*.c`. - CONFIG_NET_TCPBACKLOG - Incoming connections pend in a backlog until accept() is called. +## `lis2csh_reader` `LIS3DSH` Accelerometer - In additional to the target device-side example, there is also - a host-side application in this directory. It can be compiled under - Linux or Cygwin as follows: +A simple reader example for the `LIS3DSH` acceleration sensor as found on +STM32F4Discovery rev. C. - cd examples/usbserial - make -f Makefile.host TOPDIR= TARGETIP= +## `hts221_reader` `HTS221` Humidity Sensor - Where is the IP address of your target board. +A simple reader example for the `HTS221` humidity sensor. - This will generate a small program called 'host'. Usage: +## `lsm303_reader` `LSM303` Accelerometer/Magnetometer - 1. Build the examples/poll target program with TCP/IP poll support - and start the target. +A simple reader example for the `LSM303` acc-mag sensor. - 3. Then start the host application: +## `lsm6dsl_reader` `LSM6DSL` Accelerometer/Gyroscope - ./host +A simple reader example for the `LSM6DSL` acc-gyro sensor. - The host and target will exchange are variety of small messages. Each - message sent from the host should cause the select to return in target. - The target example should read the small message and send it back to - the host. The host should then receive the echo'ed message. +## `media` - If networking is enabled, applications using this example will need to - provide the following definition in the defconfig file to enable the - networking library: +The media test simply writes values onto the media hidden behind a character +driver and verifies that the media can be successfully written and read. This +low level test is useful in the early phases of the bringup of a new block or +mtd driver because it avoids the complexity of a file system. - CONFIG_NETUTILS_NETLIB=y +This test uses a character driver and cannot directly access block or mtd +drivers. This test is suitable for use EEPROM character drivers (see +`nuttx/drivers/eeprom`), or with block drivers wrapped as character drivers (see +`nuttx/drivers/bch`) -examples/posix_spawn -^^^^^^^^^^^^^^^^^^^^ +```c +int ret = bchdev_register(, + , false); +``` - This is a simple test of the posix_spawn() API. The example derives from - examples/elf. As a result, these tests are built using the relocatable - ELF format installed in a ROMFS file system. At run time, the test program - in the ROMFS file system is spawned using posix_spawn(). +MTD drivers need an additional wrapper layer, the FTL wrapper must first be used +to convert the MTD driver to a block device: - Requires: +```c +int ret = ftl_initialize(, mtd); +ret = bchdev_register(/dev/mtdblock, , + false); +``` - CONFIG_BINFMT_DISABLE=n - Don't disable the binary loader - CONFIG_ELF=y - Enable ELF binary loader - CONFIG_LIBC_EXECFUNCS=y - Enable support for posix_spawn - CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_spawn_exports" - - The name of the symbol table - created by the test. - CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_spawn_nexports" - - Name of variable holding the - number of symbols - CONFIG_POSIX_SPAWN_STACKSIZE=768 - This default setting. +## `module` Loadable Module - Test-specific configuration options: +This example builds a small loadable module test case. This includes a character +driver under `examples/module/drivers`. This driver is built using the +relocatable ELF format and installed in a ROMFS file system. At run time, the +driver module is loaded and exercised. Requires `CONFIG_MODULE`. Other +configuration options: - CONFIG_EXAMPLES_POSIXSPAWN_DEVMINOR - The minor device number of the ROMFS - block. driver. For example, the N in /dev/ramN. Used for registering the - RAM block driver that will hold the ROMFS file system containing the ELF - executables to be tested. Default: 0 +- `CONFIG_EXAMPLES_ELF_DEVMINOR` – The minor device number of the ROMFS block + driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM + block driver that will hold the ROMFS file system containing the ELF + executables to be tested. Default: `0`. - CONFIG_EXAMPLES_POSIXSPAWN_DEVPATH - The path to the ROMFS block driver - device. This must match EXAMPLES_POSIXSPAWN_DEVMINOR. Used for - registering the RAM block driver that will hold the ROMFS file system - containing the ELF executables to be tested. Default: "/dev/ram0" +- `CONFIG_EXAMPLES_ELF_DEVPATH` – The path to the ROMFS block driver device. + This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block + driver that will hold the ROMFS file system containing the ELF executables to + be tested. Default: `/dev/ram0`. - NOTES: +**Notes**: - 1. CFLAGS should be provided in CELFFLAGS. RAM and FLASH memory regions - may require long allcs. For ARM, this might be: +1. `CFLAGS` should be provided in `CMODULEFLAGS`. RAM and FLASH memory regions + may require long allcs. For ARM, this might be: - CELFFLAGS = $(CFLAGS) -mlong-calls + ```makefile + CMODULEFLAGS = $(CFLAGS) -mlong-calls + ``` - Similarly for C++ flags which must be provided in CXXELFFLAGS. + Similarly for C++ flags which must be provided in `CXXMODULEFLAGS`. - 2. Your top-level nuttx/Make.defs file must also include an appropriate - definition, LDELFFLAGS, to generate a relocatable ELF object. With GNU - LD, this should include '-r' and '-e main' (or _main on some platforms). +2. Your top-level `nuttx/Make.defs` file must also include an appropriate + definition, LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, + this should include `-r` and `-e `. - LDELFFLAGS = -r -e main + ```makefile + LDMODULEFLAGS = -r -e module_initialize + ``` - If you use GCC to link, you make also need to include '-nostdlib' or - '-nostartfiles' and '-nodefaultlibs'. + 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 - nuttx toolchain. Or can built from the genromfs sources that can be found - in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the - PATH variable must include the path to the genromfs executable. +3. This example also requires `genromfs`. `genromfs` can be build as part of the + nuttx toolchain. Or can built from the `genromfs` sources that can be found + in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the + PATH variable must include the path to the `genromfs` executable. - 4. ELF size: The ELF files in this example are, be default, quite large - because they include a lot of "build garbage". You can greatly reduce the - size of the ELF binaries are using the 'objcopy --strip-unneeded' command to - remove un-necessary information from the ELF files. +4. ELF size: The ELF files in this example are, be default, quite large because + they include a lot of _build garbage_. You can greatly reduce the size of the + ELF binaries are using the `objcopy --strip-unneeded` command to remove + un-necessary information from the ELF files. - 5. Simulator. You cannot use this example with the NuttX simulator on - Cygwin. That is because the Cygwin GCC does not generate ELF file but - rather some Windows-native binary format. +5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. + That is because the Cygwin GCC does not generate ELF file but rather some + Windows-native binary format. - If you really want to do this, you can create a NuttX x86 buildroot toolchain - and use that be build the ELF executables for the ROMFS file system. + If you really want to do this, you can create a NuttX x86 `buildroot` + toolchain and use that be build the ELF executables for the ROMFS file + system. - 6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at nuttx/binfmt/libelf/gnu-elf.ld. - That example might have to be tuned for your particular linker output to - position additional sections correctly. The GNU LD LDELFFLAGS then might - be: +6. Linker scripts. You might also want to use a linker scripts to combine + sections better. An example linker script is at + `nuttx/libc/modlib/gnu-elf.ld`. That example might have to be tuned for your + particular linker output to position additional sections correctly. The GNU + LD `LDMODULEFLAGS` then might be: - LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld + ```makefile + LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld + ``` -examples/powerled -^^^^^^^^^^^^^^^^^ +## `modbus` FreeModbus - This is a powerled driver example application. This application support three - operation modes which can be selected from NSH command line: +This is a port of the FreeModbus Linux demo. It derives from the demos/LINUX +directory of the FreeModBus version `1.5.0` (June 6, 2010) that can be +downloaded in its entirety from +http://developer.berlios.de/project/showfiles.php?group_id=6120. - 1. Demo mode +- `CONFIG_EXAMPLES_MODBUS_PORT`, Default `0` (for `/dev/ttyS0`). +- `CONFIG_EXAMPLES_MODBUS_BAUD`, Default B`38400`. +- `CONFIG_EXAMPLES_MODBUS_PARITY`, Default `MB_PAR_EVEN`. +- `CONFIG_EXAMPLES_MODBUS_REG_INPUT_START`, Default `1000`. +- `CONFIG_EXAMPLES_MODBUS_REG_INPUT_NREGS`, Default `4`. +- `CONFIG_EXAMPLES_MODBUS_REG_HOLDING_START`, Default `2000`. +- `CONFIG_EXAMPLES_MODBUS_REG_HOLDING_NREGS`, Default `130`. - 2. Continuous mode +The FreeModBus library resides at `apps/modbus`. See `apps/modbus/README.txt` +for additional configuration information. - 3. Flash mode +## `mount` Mount Filesystem -examples/pty_test -^^^^^^^^^^^^^^^^^ +This contains a simple test of filesystem mountpoints. - A test of NuttX pseudo-terminals. Provided by Alan Carvalho de Assis. +- `CONFIG_EXAMPLES_MOUNT_DEVNAME` – The name of the user-provided block device + to mount. If `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not provided, then a RAM disk + will be configured. -examples/pwfb -^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_MOUNT_NSECTORS` – The number of _sectors_ in the RAM disk + used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined. - A graphics example using pre-window frame buffers. The example shows - three windows containing text moving around, crossing each other from - "above" and from "below". The example application is NOT updating the - windows any anyway! The application is only changing the window - position. The windows are being updated from the per-winidow - framebuffers automatically. +- `CONFIG_EXAMPLES_MOUNT_SECTORSIZE` – The size of each sectors in the RAM disk + used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined. - This example is reminiscent of Pong: Each window travels in straight - line until it hits an edge, then it bounces off. The window is also - raised when it hits the edge (gets "focus"). This tests all - combinations of overap. +- `CONFIG_EXAMPLES_MOUNT_RAMDEVNO` – The RAM device minor number used to mount + the RAM disk used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined. The + default is zero (meaning that `/dev/ram0` will be used). - NOTE: A significant amount of RAM, usually external SDRAM, is required - to run this demo. At 16bpp and a 480x272 display, each window requires - about 70Kb of RAM for its framebuffer. +## `mtdpart` MTD Partition Test -examples/pwm -^^^^^^^^^^^^ +This examples provides a simple test of MTD partition logic. - A test of a PWM device driver. It simply enables a pulsed output for - a specified frequency and duty for a specified period of time. This - example can ONLY be built as an NSH built-in function. +- `CONFIG_EXAMPLES_MTDPART` – Enables the MTD partition test example. - This test depends on these specific PWM/NSH configurations settings (your - specific PWM settings might require additional settings). +- `CONFIG_EXAMPLES_MTDPART_ARCHINIT` – The default is to use the RAM MTD device + at `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used + instead by defining `CONFIG_EXAMPLES_MTDPART_ARCHINIT`. In this case, the + initialization logic will call `mtdpart_archinitialize()` to obtain the MTD + driver instance. - CONFIG_PWM - Enables PWM support. - CONFIG_PWM_PULSECOUNT - Enables PWM pulse count support (if the hardware - supports it). - CONFIG_NSH_BUILTIN_APPS - Build the PWM test as an NSH built-in function. +- `CONFIG_EXAMPLES_MTDPART_NPARTITIONS` – This setting provides the number of + partitions to test. The test will divide the reported size of the MTD device + into equal-sized sub-regions for each test partition. Default: `3`. - Specific configuration options for this example include: +When `CONFIG_EXAMPLES_MTDPART_ARCHINIT` is not defined, this test will use the +RAM MTD device at `drivers/mtd/rammtd.c` to simulate FLASH. The size of the +allocated RAM drive will be: `CONFIG_EXMPLES_RAMMTD_ERASESIZE * +CONFIG_EXAMPLES_MTDPART_NEBLOCKS`. - 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% - CONFIG_EXAMPLES_PWM_DURATION - The initial PWM pulse train duration in seconds. - Used only if the current pulse count is zero (pulse count is only supported - if CONFIG_PWM_PULSECOUNT is defined). Default: 5 seconds - CONFIG_EXAMPLES_PWM_PULSECOUNT - The initial PWM pulse count. This option is - only available if CONFIG_PWM_PULSECOUNT is non-zero. Default: 0 (i.e., use - the duration, not the count). +* `CONFIG_EXAMPLES_MTDPART_ERASESIZE` – This value gives the size of one erase + block in the MTD RAM device. This must exactly match the default configuration + in `drivers/mtd/rammtd.c`! -examples/qencoder -^^^^^^^^^^^^^^^^^ +* `CONFIG_EXAMPLES_MTDPART_NEBLOCKS` – This value gives the number of erase + blocks in MTD RAM device. - This example is a simple test of a Quadrature Encoder driver. It simply reads - positional data from the encoder and prints it., +## `mtdrwb` MTD Read-ahead and Write Buffering - This test depends on these specific QE/NSH configurations settings (your - specific PWM settings might require additional settings). +This examples provides a simple test of MTD Read-Ahead/Write buffering logic. - CONFIG_SENSORS_QENCODER - Enables quadrature encoder support (upper-half driver). - CONFIG_NSH_BUILTIN_APPS - Build the QE test as an NSH built-in function. - Default: Built as a standalone progrem. +- `CONFIG_EXAMPLES_MTDRWB` – Enables the MTD R/W buffering test example. - Additional configuration options will mostly likely be required for the board- - specific lower-half driver. See the README.txt file in your board configuration - directory. +- `CONFIG_EXAMPLES_MTDRWB_ARCHINIT` – The default is to use the RAM MTD device + at `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used + instead by defining `CONFIG_EXAMPLES_MTDRWB_ARCHINIT`. In this case, the + initialization logic will call `mtdrwb_archinitialize()` to obtain the MTD + driver instance. - Specific configuration options for this example include: +When `CONFIG_EXAMPLES_MTDRWB_ARCHINIT` is not defined, this test will use the +RAM MTD device at `drivers/mtd/rammtd.c` to simulate FLASH. The size of the +allocated RAM drive will be: `CONFIG_EXMPLES_RAMMTD_ERASESIZE * +CONFIG_EXAMPLES_MTDRWB_NEBLOCKS` - CONFIG_EXAMPLES_QENCODER_DEVPATH - The path to the QE device. Default: - /dev/qe0 - CONFIG_EXAMPLES_QENCODER_NSAMPLES - This number of samples is - collected and the program terminates. Default: Samples are collected - indefinitely. - CONFIG_EXAMPLES_QENCODER_DELAY - This value provides the delay (in - milliseconds) between each sample. Default: 100 milliseconds +- `CONFIG_EXAMPLES_MTDRWB_ERASESIZE` – This value gives the size of one erase + block in the MTD RAM device. This must exactly match the default configuration + in `drivers/mtd/rammtd.c`! -examples/random -^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_MTDRWB_NEBLOCKS` – This value gives the number of erase + blocks in MTD RAM device. - This is a very simply test of /dev/random. It simple collects random - numbers and displays them on the console. +## `netpkt` `AF_PACKET` _Raw_ Sockets - Prerequistes: +A test of `AF_PACKET`, _raw_ sockets. Contributed by Lazlo Sitzer. - CONFIG_DEV_RANDOM - Support for /dev/random must be enabled in order - to select this example. +## `netloop` Network loopback device - Configuration: +This is a simple test of the netwok loopback device. `examples/nettest` can also +be configured to provide (better) test of local loopback transfers. This version +derives from `examples/poll` and is focused on testing `poll()` with loopback +devices. - CONFIG_EXAMPLES_RANDOM - Enables the /dev/random test - CONFIG_EXAMPLES_MAXSAMPLES - This is the size of the /dev/random I/O - buffer in units of 32-bit samples. Careful! This buffer is allocated - on the stack as needed! Default 64. - CONFIG_EXAMPLES_NSAMPLES; - When you execute the rand command, a number - of samples ranging from 1 to EXAMPLES_MAXSAMPLES may be specified. If - no argument is specified, this is the default number of samples that\ - will be collected and displayed. Default 8 +- `CONFIG_EXAMPLES_NETLOOP=y` – Enables the nettest example. -examples/relays -^^^^^^^^^^^^^^^ +Dependencies: - Requires CONFIG_ARCH_RELAYS. - Contributed by Darcy Gong. +- `CONFIG_NET_LOOPBACK` – Requires local loopback support. +- `CONFIG_NET_TCP` – Requires TCP support with the following: + - `CONFIG_NET_TCPBACKLOG` + - `CONFIG_NET_TCP_WRITE_BUFFERS` +- `CONFIG_NET_IPv4` – Currently supports only IPv4. - NOTE: This test exercises internal relay driver interfaces. As such, it - relies on internal OS interfaces that are not normally available to a - user-space program. As a result, this example cannot be used if a - NuttX is built as a protected, supervisor kernel (CONFIG_BUILD_PROTECTED - or CONFIG_BUILD_KERNEL). +## `nettest` Client/Server Over TCP -examples/rfid_readuid -^^^^^^^^^^^^^^^^^^^^^ +This is a simple network test for verifying client- and server- functionality in +a TCP/IP connection. - RFID READUID example +- `CONFIG_EXAMPLES_NETTEST=y` – Enables the nettest example. +- `CONFIG_EXAMPLES_NETLIB=y` – The networking library in needed. + +Configurations: + +- Server on target hardware; client on host. +- Client on target hardware; server on host. +- Server and Client on different targets. +- Loopback configuration with both client and server on the same target. + +See also `examples/tcpecho`. + +## `nrf24l01_term` NRF24L01 Wireless Connection + +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. + +## `nx` + +This directory contains a simple test of a subset of the NX APIs defined in +`include/nuttx/nx/nx.h`. The following configuration options can be selected: + +- `CONFIG_NSH_BUILTIN_APPS` – Build the NX example as a _built-in_ that can be + executed from the NSH command line +- `CONFIG_EXAMPLES_NX_BGCOLOR` – The color of the background. Default depends on + `CONFIG_EXAMPLES_NX_BPP`. +- `CONFIG_EXAMPLES_NX_COLOR1` – The color of window 1. Default depends on + `CONFIG_EXAMPLES_NX_BPP`. +- `CONFIG_EXAMPLES_NX_COLOR2` – The color of window 2. Default depends on + `CONFIG_EXAMPLES_NX_BPP`. +- `CONFIG_EXAMPLES_NX_TBCOLOR` – The color of the toolbar. Default depends on + `CONFIG_EXAMPLES_NX_BPP`. +- `CONFIG_EXAMPLES_NX_FONTID` – Selects the font (see font ID numbers in + `include/nuttx/nx/nxfonts.h`). +- `CONFIG_EXAMPLES_NX_FONTCOLOR` – The color of the fonts. Default depends on + `CONFIG_EXAMPLES_NX_BPP`. +- `CONFIG_EXAMPLES_NX_BPP` – Pixels per pixel to use. Valid options include `2`, + `4`, `8`, `16`, `24` and `32`. Default is `32`. +- `CONFIG_EXAMPLES_NX_RAWWINDOWS` – Use raw windows; Default is to use pretty, + framed NXTK windows with toolbars. +- `CONFIG_EXAMPLES_NX_STACKSIZE` – The stacksize to use when creating the NX + server. Default `2048`. +- `CONFIG_EXAMPLES_NX_CLIENTPRIO` – The client priority. Default: `100` +- `CONFIG_EXAMPLES_NX_SERVERPRIO` – The server priority. Default: `120` +- `CONFIG_EXAMPLES_NX_LISTENERPRIO` – The priority of the event listener thread. + Default `80`. +- `CONFIG_EXAMPLES_NX_NOTIFYSIGNO` – The signal number to use with + `nx_eventnotify()`. Default: `4`. + +The example also has the following settings and will generate an error if they +are not as expected: + +```conf +CONFIG_DISABLE_MQUEUE=n +CONFIG_DISABLE_PTHREAD=n +CONFIG_NX_BLOCKING=y +CONFIG_LIB_BOARDCTL=y +``` + +## `nxterm` Display NuttShell (NSH) as NX Console + +This directory contains yet another version of the NuttShell (NSH). This version +uses the NX console device defined in `include/nuttx/nx/nxterm.h` for output. +the result is that the NSH input still come from the standard console input +(probably a serial console). But the text output will go to an NX winbdow. +Prerequisite configuration settings for this test include: + +- `CONFIG_NX=y` – NX graphics must be enabled +- `CONFIG_NXTERM=y` – The NX console driver must be built +- `CONFIG_DISABLE_MQUEUE=n` – Message queue support must be available. +- `CONFIG_DISABLE_PTHREAD=n` – pthreads are needed +- `CONFIG_NX_BLOCKING=y` – pthread APIs must be blocking +- `CONFIG_NSH_CONSOLE=y` – NSH must be configured to use a console. + +The following configuration options can be selected to customize the test: + +- `CONFIG_EXAMPLES_NXTERM_BGCOLOR` – The color of the background. Default + Default is a darker royal blue. +- `CONFIG_EXAMPLES_NXTERM_WCOLOR` – The color of the window. Default is a light + slate blue. +- `CONFIG_EXAMPLES_NXTERM_FONTID` – Selects the font (see font ID numbers in + `include/nuttx/nx/nxfonts.h`). +- `CONFIG_EXAMPLES_NXTERM_FONTCOLOR` – The color of the fonts. Default is black. +- `CONFIG_EXAMPLES_NXTERM_BPP` – Pixels per pixel to use. Valid options include + `2`, `4`, `8`, `16`, `24` and `32`. Default is `32`. +- `CONFIG_EXAMPLES_NXTERM_TOOLBAR_HEIGHT` – The height of the toolbar. Default: + `16`. +- `CONFIG_EXAMPLES_NXTERM_TBCOLOR` – The color of the toolbar. Default is a + medium grey. +- `CONFIG_EXAMPLES_NXTERM_MINOR` – The NX console device minor number. Default + is `0` corresponding to `/dev/nxterm0`. +- `CONFIG_EXAMPLES_NXTERM_DEVNAME` – The quoted, full path to the NX console + device corresponding to `CONFIG_EXAMPLES_NXTERM_MINOR`. Default: + `/dev/nxterm0`. +- `CONFIG_EXAMPLES_NXTERM_PRIO` – Priority of the NxTerm task. Default: + `SCHED_PRIORITY_DEFAULT`. +- `CONFIG_EXAMPLES_NXTERM_STACKSIZE` – Stack size allocated for the NxTerm task. + Default: `2048`. +- `CONFIG_EXAMPLES_NXTERM_STACKSIZE` – The stacksize to use when creating the NX + server. Default: `2048`. +- `CONFIG_EXAMPLES_NXTERM_CLIENTPRIO` – The client priority. Default: `100`. +- `CONFIG_EXAMPLES_NXTERM_SERVERPRIO` – The server priority. Default: `120`. +- `CONFIG_EXAMPLES_NXTERM_LISTENERPRIO` – The priority of the event listener + thread. Default: `80`. +- `CONFIG_EXAMPLES_NXTERM_NOTIFYSIGNO` – The signal number to use with + `nx_eventnotify()`. Default: `4`. + +## `nxflat` NXFLAT Binary + +This example builds a small NXFLAT test case. This includes several test +programs under `examples/nxflat` tests. These tests are build using the NXFLAT +format and installed in a ROMFS file system. At run time, each program in the +ROMFS file system is executed. Requires `CONFIG_NXFLAT`. + +## `nxhello` + +A very simple graphics example that just says _Hello, World!_ in the center of +the display. + +The following configuration options can be selected: + +- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXHELLO` example as a _built-in_ that + can be executed from the NSH command line +- `CONFIG_EXAMPLES_NXHELLO_VPLANE` – The plane to select from the frame- buffer + driver for use in the test. Default: `0`. +- `CONFIG_EXAMPLES_NXHELLO_DEVNO` – The LCD device to select from the LCD driver + for use in the test. Default: `0`. +- `CONFIG_EXAMPLES_NXHELLO_BGCOLOR` – The color of the background. Default + depends on `CONFIG_EXAMPLES_NXHELLO_BPP`. +- `CONFIG_EXAMPLES_NXHELLO_FONTID` – Selects the font (see font ID numbers in + include/nuttx/nx/nxfonts.h). +- `CONFIG_EXAMPLES_NXHELLO_FONTCOLOR` – The color of the fonts used in the + background window. Default depends on `CONFIG_EXAMPLES_NXHELLO_BPP`. +- `CONFIG_EXAMPLES_NXHELLO_BPP` – Pixels per pixel to use. Valid options include + `2`, `4`, `8`, `16`, `24` and `32`. Default: `32`. + +## `nximage` Display NuttX Logo + +This is a simple example that just puts the NuttX logo image in the center of +the display. This only works for `RGB23` (`888`), `RGB16` (`656`), `RGB8` +(`332`), and 8-bit greyscale for now. + +- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXIMAGE` example as a _built-in_ that + can be executed from the NSH command line. +- `CONFIG_EXAMPLES_NXIMAGE_VPLANE` – The plane to select from the frame- buffer + driver for use in the test. Default: `0`. +- `CONFIG_EXAMPLES_NXIMAGE_DEVNO` – The LCD device to select from the LCD driver + for use in the test: Default: `0`. +- `CONFIG_EXAMPLES_NXIMAGE_BPP` – Pixels per pixel to use. Valid options include + `8`, `16` and `24`. Default is `16`. +- `CONFIG_EXAMPLES_NXIMAGE_XSCALEp5`, `CONFIG_EXAMPLES_NXIMAGE_XSCALE1p5` or + `CONFIG_EXAMPLES_NXIMAGE_XSCALE2p0` – The logo image width is 160 columns. One + of these may be defined to rescale the image horizontally by .5, 1.5 or 2.0. +- `CONFIG_EXAMPLES_NXIMAGE_YSCALEp5`, `CONFIG_EXAMPLES_NXIMAGE_YSCALE1p5` or + `CONFIG_EXAMPLES_NXIMAGE_YSCALE2p0` – The logo image height is 160 rows. One + of these may be defined to rescale the image vertically by .5, 1.5 or 2.0. +- `CONFIG_EXAMPLES_NXIMAGE_GREYSCALE` – Grey scale image. Default: `RGB`. + +How was that run-length encoded image produced? + +1. I used GIMP output the image as a `.c` file. +2. I added some C logic to palette-ize the RGB image in the GIMP `.c` file. +3. Then I add some simple run-length encoding to palette-ized image. + +But now there is a tool that can be found in the NxWidgets package at +`NxWidgets/tools/bitmap_converter.py` that can be used to convert any graphics +format to the NuttX RLE format. + +**Note**: As of this writing, most of the pixel depth, scaling options, and +combinations thereof have not been tested. + +## `nxlines` NX Line Drawing + +A very simple graphics example that just exercised the NX line drawing logic. + +The following configuration options can be selected: + +- `CONFIG_EXAMPLES_NXLINES_VPLANE` – The plane to select from the frame- buffer + driver for use in the test. Default: `0`. +- `CONFIG_EXAMPLES_NXLINES_DEVNO` – The LCD device to select from the LCD driver + for use in the test: Default: `0`. +- `CONFIG_EXAMPLES_NXLINES_BGCOLOR` – The color of the background. Default + depends on `CONFIG_EXAMPLES_NXLINES_BPP`. +- `CONFIG_EXAMPLES_NXLINES_LINEWIDTH` – Selects the width of the lines in pixels + (default: `16`). +- `CONFIG_EXAMPLES_NXLINES_LINECOLOR` – The color of the central lines drawn in + the background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP` (there + really is no meaningful default). +- `CONFIG_EXAMPLES_NXLINES_BORDERWIDTH` – The width of the circular border drawn + in the background window. (default: `16`). +- `CONFIG_EXAMPLES_NXLINES_BORDERCOLOR` – The color of the circular border drawn + in the background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP` + (there really is no meaningful default). +- `CONFIG_EXAMPLES_NXLINES_CIRCLECOLOR` – The color of the circular region + filled in the background window. Default depends on + `CONFIG_EXAMPLES_NXLINES_BPP` (there really is no meaningful default). +- `CONFIG_EXAMPLES_NXLINES_BORDERCOLOR` – The color of the lines drawn in the + background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP` (there + really is no meaningful default). +- `CONFIG_EXAMPLES_NXLINES_BPP` – Pixels per pixel to use. Valid options include + `2`, `4`, `8`, `16`, `24`, and `32`. Default is `16`. +- `CONFIG_NSH_BUILTIN_APPS` – Build the NX lines examples as an NSH built-in + function. + +## `nxtext` Display NX Text + +This directory contains another simple test of a subset of the NX APIs defined +in `include/nuttx/nx/nx.h`. This text focuses on text displays on the display +background combined with pop-up displays over the text. The text display will +continue to update while the pop-up is visible. + +**Note**: This example will **only** work with FB drivers and with LCD drivers +that support reading the contents of the internal LCD memory **unless** you +define `CONFIG_EXAMPLES_NXTEXT_NOGETRUN`. If you notice garbage on the display +or a failure at the point where the display should scroll, it is probably +because you have an LCD driver that is write-only. + +The following configuration options can be selected: + +- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXTEXT` example as a _built-in_ that + can be executed from the NSH command line. +- `CONFIG_EXAMPLES_NXTEXT_BGCOLOR` – The color of the background. Default + depends on `CONFIG_EXAMPLES_NXTEXT_BPP`. +- `CONFIG_EXAMPLES_NXTEXT_BGFONTID` – Selects the font to use in the background + text (see font ID numbers in `include/nuttx/nx/nxfonts.h`). +- `CONFIG_EXAMPLES_NXTEXT_BGFONTCOLOR` – The color of the fonts used in the + background window. Default depends on `CONFIG_EXAMPLES_NXTEXT_BPP`. +- `CONFIG_EXAMPLES_NXTEXT_PUCOLOR` – The color of the pop-up window. Default + depends on `CONFIG_EXAMPLES_NXTEXT_BPP`. +- `CONFIG_EXAMPLES_NXTEXT_PUFONTID` – Selects the font to use in the pop-up + windows (see font ID numbers in `include/nuttx/nx/nxfonts.h`). +- `CONFIG_EXAMPLES_NXTEXT_PUFONTCOLOR` – The color of the fonts used in the + background window. Default depends on `CONFIG_EXAMPLES_NXTEXT_BPP`. +- `CONFIG_EXAMPLES_NXTEXT_BPP` – Pixels per pixel to use. Valid options include + `2`, `4`, `8`, `16`, `24` and `32`. Default is `32`. +- `CONFIG_EXAMPLES_NXTEXT_NOGETRUN` – If your display is read-only OR if reading + is not reliable, then select this configuration to avoid reading from the + display. +- `CONFIG_EXAMPLES_NXTEXT_BMCACHE` – The maximum number of characters that can + be put in the background window. Default is `128`. +- `CONFIG_EXAMPLES_NXTEXT_GLCACHE` – The maximum number of pre-rendered fonts + that can be retained for the background window. +- `CONFIG_EXAMPLES_NXTEXT_STACKSIZE` – The stacksize to use when creating the NX + server. Default `2048`. +- `CONFIG_EXAMPLES_NXTEXT_CLIENTPRIO` – The client priority. Default: `100`. +- `CONFIG_EXAMPLES_NXTEXT_SERVERPRIO` – The server priority. Default: `120`. +- `CONFIG_EXAMPLES_NXTEXT_LISTENERPRIO` – The priority of the event listener + thread. Default: `80`. +- `CONFIG_EXAMPLES_NXTEXT_NOTIFYSIGNO` – The signal number to use with + `nx_eventnotify()`. Default: `4`. + +The example also expects the following settings and will generate an error if +they are not as expected: + +```conf +CONFIG_DISABLE_MQUEUE=n +CONFIG_DISABLE_PTHREAD=n +CONFIG_NX_BLOCKING=y +``` + +## `null` + +This is the do nothing application. It is only used for bringing up new NuttX +architectures in the most minimal of environments. + +## `obd2` + +A simple test of `apps/canutils/libobd2`. + +## `oneshot` Oneshot Timer + +Simple test of a oneshot driver. + +## `pca9635` `PCA9635PW` LED + +A simple test of the `PCA9635PW` LED driver. + +## `pdcurses` + +This directory contains the `demo/test` programs that accompany the public +domain cursors package (`pdcurses`) that can be found at +`apps/graphics/pdcurs34`. + +## `pipe` + +A test of the `mkfifo()` and `pipe()` APIs. Requires `CONFIG_PIPES` + +- `CONFIG_EXAMPLES_PIPE_STACKSIZE` – Sets the size of the stack to use when + creating the child tasks. The default size is `1024`. + +## `poll` + +A test of the `poll()` and `select()` APIs using FIFOs and, if available, +`stdin`, and a TCP/IP socket. In order to use the TCP/IP select test, you must +have the following things selected in your NuttX configuration file: -examples/rgbled -^^^^^^^^^^^^^^^ +- `CONFIG_NET` – Defined for general network support. +- `CONFIG_NET_TCP` – Defined for TCP/IP support. +- `CONFIG_NET_NTCP_READAHEAD_BUFFERS` – Defined to be greater than zero. +- `CONFIG_EXAMPLES_POLL_NOMAC` – (May be defined to use software assigned + MAC) +- `CONFIG_EXAMPLES_POLL_IPADDR` – Target IP address. +- `CONFIG_EXAMPLES_POLL_DRIPADDR` – Default router IP address. +- `CONFIG_EXAMPLES_POLL_NETMASK` – Network mask. - This example demonstrates the use of the RGB led driver to drive an RGB LED - with PWM outputs so that all color characteristcs of RGB LED can be controlled. +In order to for select to work with incoming connections, you must also select: -examples/romfs -^^^^^^^^^^^^^^ +- `CONFIG_NET_TCPBACKLOG` – Incoming connections pend in a backlog until + `accept()` is called. - This example exercises the romfs filesystem. Configuration options - include: +In additional to the target device-side example, there is also a host-side +application in this directory. It can be compiled under Linux or Cygwin as +follows: - * CONFIG_EXAMPLES_ROMFS_RAMDEVNO - The minor device number to use for the ROM disk. The default is - 1 (meaning /dev/ram1) +```makefile +cd examples/usbserial +make -f Makefile.host TOPDIR= TARGETIP= +``` - * CONFIG_EXAMPLES_ROMFS_SECTORSIZE - The ROM disk sector size to use. Default is 64. +Where `` is the IP address of your target board. - * CONFIG_EXAMPLES_ROMFS_MOUNTPOINT - The location to mount the ROM disk. Default: "/usr/local/share" +This will generate a small program called 'host'. Usage: -examples/sendmail -^^^^^^^^^^^^^^^^^ +1. Build the `examples/poll` target program with TCP/IP poll support and start + the target. - This examples exercises the uIP SMTP logic by sending a test message - to a selected recipient. This test can also be built to execute on - the Cygwin/Linux host environment: +2. Then start the host application: - cd examples/sendmail - make -f Makefile.host TOPDIR= + ```bash + ./host + ``` - Settings unique to this example include: +The host and target will exchange are variety of small messages. Each message +sent from the host should cause the select to return in target. The target +example should read the small message and send it back to the host. The host +should then receive the echo'ed message. - CONFIG_EXAMPLES_SENDMAIL_NOMAC - May be defined to use software assigned MAC (optional) - CONFIG_EXAMPLES_SENDMAIL_IPADDR - Target IP address (required) - CONFIG_EXAMPLES_SENDMAIL_DRIPADDR - Default router IP address (required) - CONFIG_EXAMPLES_SENDMAILT_NETMASK - Network mask (required) - CONFIG_EXAMPLES_SENDMAIL_RECIPIENT - The recipient of the email (required) - CONFIG_EXAMPLES_SENDMAIL_SENDER - Optional. Default: "nuttx-testing@example.com" - CONFIG_EXAMPLES_SENDMAIL_SUBJECT - Optional. Default: "Testing SMTP from NuttX" - CONFIG_EXAMPLES_SENDMAIL_BODY - Optional. Default: "Test message sent by NuttX" +If networking is enabled, applications using this example will need to provide +the following definition in the `defconfig` file to enable the networking +library: - NOTE: This test has not been verified on the NuttX target environment. - As of this writing, unit-tested in the Cygwin/Linux host environment. +- `CONFIG_NETUTILS_NETLIB=y` - 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. +## `posix_spawn` - Applications using this example will need to enable the following - netutils libraries in their defconfig file: +This is a simple test of the `posix_spawn()` API. The example derives from +`examples/elf`. As a result, these tests are built using the relocatable ELF +format installed in a ROMFS file system. At run time, the test program in the +ROMFS file system is spawned using `posix_spawn()`. - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_SMTP=y +Requires: -examples/serialblaster -^^^^^^^^^^^^^^^^^^^^^^ +- `CONFIG_BINFMT_DISABLE=n` – Don't disable the binary loader. +- `CONFIG_ELF=y` – Enable ELF binary loader. +- `CONFIG_LIBC_EXECFUNCS=y` – Enable support for posix_spawn. +- `CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_spawn_exports"` – The name of the symbol + table created by the test. +- `CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_spawn_nexports"` – Name of variable holding + the number of symbols. +- `CONFIG_POSIX_SPAWN_STACKSIZE=768` – This default setting. - Sends a repeating pattern (the alphabet) out a serial port continuously. - This may be useful if you are trying run down other problems that you - think might only occur when the serial port usage is high. +Test-specific configuration options: -examples/serialrx -^^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_POSIXSPAWN_DEVMINOR` – The minor device number of the ROMFS + block. driver. For example, the `N` in `/dev/ramN`. Used for registering the + RAM block driver that will hold the ROMFS file system containing the ELF + executables to be tested. Default: `0`. - Constant receives serial data. This is the complement to serialblaster. - This may be useful if you are trying run down other problems that you - think might only occur when the serial port usage is high. +- `CONFIG_EXAMPLES_POSIXSPAWN_DEVPATH` – The path to the ROMFS block driver + device. This must match `EXAMPLES_POSIXSPAWN_DEVMINOR`. Used for registering + the RAM block driver that will hold the ROMFS file system containing the ELF + executables to be tested. Default: `/dev/ram0`. -examples/serloop -^^^^^^^^^^^^^^^^ +**Notes**: - This is a mindlessly simple loopback test on the console. Useful - for testing new serial drivers. Configuration options include: +1. `CFLAGS` should be provided in `CELFFLAGS`. RAM and FLASH memory regions may + require long allcs. For ARM, this might be: - * CONFIG_EXAMPLES_SERLOOP_BUFIO - Use C buffered I/O (getchar/putchar) vs. raw console I/O - (read/read). + ```makefile + CELFFLAGS = $(CFLAGS) -mlong-calls + ``` -examples/slcd -^^^^^^^^^^^^^ - A simple test of alphanumeric, segment LCDs (SLCDs). + Similarly for C++ flags which must be provided in `CXXELFFLAGS`. - * CONFIG_EXAMPLES_SLCD - Enable the SLCD test +2. Your top-level `nuttx/Make.defs` file must also include an appropriate + definition, `LDELFFLAGS`, to generate a relocatable ELF object. With GNU LD, + this should include `-r` and `-e main` (or `_main` on some platforms). + ```makefile + LDELFFLAGS = -r -e main + ``` -examples/smps -^^^^^^^^^^^^^ + If you use GCC to link, you make also need to include `-nostdlib` or + `-nostartfiles` and `-nodefaultlibs`. - This is a SMPS (Switched-mode power supply) driver example application. +3. This example also requires `genromfs`. `genromfs` can be build as part of the + nuttx toolchain. Or can built from the `genromfs` sources that can be found + in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the + `PATH` variable must include the path to the `genromfs` executable. -examples/sotest -^^^^^^^^^^^^^^^ +4. ELF size: The ELF files in this example are, be default, quite large because + they include a lot of _build garbage_. You can greatly reduce the size of the + ELF binaries are using the `objcopy --strip-unneeded` command to remove + un-necessary information from the ELF files. - This example builds a small shared library module test case. The test - shared library is built using the relocatable ELF format and installed - in a ROMFS file system. At run time, the shared library is installed - and exercised. Requires CONFIG_LIBC_DLFCN. Other configuration options: +5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. + That is because the Cygwin GCC does not generate ELF file but rather some + Windows-native binary format. - CONFIG_EXAMPLES_SOTEST_DEVMINOR - The minor device number of the ROMFS block - driver. For example, the N in /dev/ramN. Used for registering the RAM - block driver that will hold the ROMFS file system containing the ELF - executables to be tested. Default: 0 + If you really want to do this, you can create a NuttX x86 buildroot toolchain + and use that be build the ELF executables for the ROMFS file system. - CONFIG_EXAMPLES_SOTEST_DEVPATH - The path to the ROMFS block driver device. This - must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver - that will hold the ROMFS file system containing the ELF executables to be - tested. Default: "/dev/ram0" +6. Linker scripts. You might also want to use a linker scripts to combine + sections better. An example linker script is at + `nuttx/binfmt/libelf/gnu-elf.ld`. That example might have to be tuned for + your particular linker output to position additional sections correctly. The + GNU LD `LDELFFLAGS` then might be: - NOTES: + ```makefile + LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld + ``` - 1. CFLAGS should be provided in CMODULEFLAGS. RAM and FLASH memory regions - may require long allcs. For ARM, this might be: +## `powerled` - CMODULEFLAGS = $(CFLAGS) -mlong-calls +This is a powerled driver example application. This application support three +operation modes which can be selected from NSH command line: - Similarly for C++ flags which must be provided in CXXMODULEFLAGS. +1. Demo mode. +2. Continuous mode. +3. Flash mode. - 2. Your top-level nuttx/Make.defs file must also include an appropriate definition, - LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, this should - include '-r' and '-e '. +## `pty_test` Pseudo-Terminals - LDMODULEFLAGS = -r -e module_initialize +A test of NuttX pseudo-terminals. Provided by Alan Carvalho de Assis. - If you use GCC to link, you make also need to include '-nostdlib' or - '-nostartfiles' and '-nodefaultlibs'. +## `pwfb` - 3. This example also requires genromfs. genromfs can be build as part of the - nuttx toolchain. Or can built from the genromfs sources that can be found - in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the - PATH variable must include the path to the genromfs executable. +A graphics example using pre-window frame buffers. The example shows three +windows containing text moving around, crossing each other from _above_ and from +_below_. The example application is NOT updating the windows any anyway! The +application is only changing the window position. The windows are being updated +from the per-winidow framebuffers automatically. - 4. ELF size: The ELF files in this example are, be default, quite large - because they include a lot of "build garbage". You can greatly reduce the - size of the ELF binaries are using the 'objcopy --strip-unneeded' command to - remove un-necessary information from the ELF files. +This example is reminiscent of Pong: Each window travels in straight line until +it hits an edge, then it bounces off. The window is also raised when it hits the +edge (gets _focus_). This tests all combinations of overap. - 5. Simulator. You cannot use this example with the NuttX simulator on - Cygwin. That is because the Cygwin GCC does not generate ELF file but - rather some Windows-native binary format. +**Note**: A significant amount of RAM, usually external SDRAM, is required to +run this demo. At 16bpp and a 480x272 display, each window requires about 70Kb +of RAM for its framebuffer. - If you really want to do this, you can create a NuttX x86 buildroot toolchain - and use that be build the ELF executables for the ROMFS file system. +## `pwm` General PWM - 6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at nuttx/libc/modlib/gnu-elf.ld. - That example might have to be tuned for your particular linker output to - position additional sections correctly. The GNU LD LDMODULEFLAGS then might - be: +A test of a PWM device driver. It simply enables a pulsed output for a specified +frequency and duty for a specified period of time. This example can ONLY be +built as an NSH built-in function. - LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld +This test depends on these specific PWM/NSH configurations settings (your +specific PWM settings might require additional settings). -examples/stat -^^^^^^^^^^^^^ +- `CONFIG_PWM` – Enables PWM support. +- `CONFIG_PWM_PULSECOUNT` – Enables PWM pulse count support (if the hardware + supports it). +- `CONFIG_NSH_BUILTIN_APPS` – Build the PWM test as an NSH built-in function. - A simple test of stat(), fstat(), and statfs(). This is useful primarily for - bringing up a new file system and verifying the correctness of these operations. +Specific configuration options for this example include: -examples/sx127x_demo -^^^^^^^^^^^^^ +- `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`%. +- `CONFIG_EXAMPLES_PWM_DURATION` – The initial PWM pulse train duration in + seconds. Used only if the current pulse count is zero (pulse count is only + supported if `CONFIG_PWM_PULSECOUNT` is defined). Default: `5` seconds. +- `CONFIG_EXAMPLES_PWM_PULSECOUNT` – The initial PWM pulse count. This option is + only available if `CONFIG_PWM_PULSECOUNT` is non-zero. Default: `0` (i.e., use + the duration, not the count). - This example demonstrates the use of the SX127X radio/ +## `qencoder` Quadrature Encoder -examples/system -^^^^^^^^^^^^^^^ +This example is a simple test of a Quadrature Encoder driver. It simply reads +positional data from the encoder and prints it., - This is a simple test of the system() command. The test simply executes this - system command: +This test depends on these specific QE/NSH configurations settings (your +specific PWM settings might require additional settings). - ret = system("ls -Rl /"); +- `CONFIG_SENSORS_QENCODER` – Enables quadrature encoder support (upper-half + driver). +- `CONFIG_NSH_BUILTIN_APPS` – Build the QE test as an NSH built-in function. + Default: Built as a standalone program. -examples/tcpblaster -^^^^^^^^^^^^^^^^^^ +Additional configuration options will mostly likely be required for the board- +specific lower-half driver. See the `README.txt` file in your board +configuration directory. - The tcpblaster example derives from the nettest example and basically duplicatesi - that example when the nettest PERFORMANCE option is selected. tcpblaster has a - little better reporting of performance stats, however. +Specific configuration options for this example include: -examples/tcpecho -^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_QENCODER_DEVPATH` – The path to the QE device. Default: + `/dev/qe0`. +- `CONFIG_EXAMPLES_QENCODER_NSAMPLES` – This number of samples is collected and + the program terminates. Default: Samples are collected indefinitely. +- `CONFIG_EXAMPLES_QENCODER_DELAY` – This value provides the delay (in + milliseconds) between each sample. Default: `100` milliseconds. - Simple single threaded, poll based TCP echo server. This example implements - the TCP Echo Server from W. Richard Stevens UNIX Network Programming Book. - Contributed by Max Holtberg. +## `random` Random Numbers - See also examples/nettest +This is a very simply test of `/dev/random`. It simple collects random numbers +and displays them on the console. - * CONFIG_EXAMPLES_TCPECHO =y: Enables the TCP echo server. - * CONFIG_XAMPLES_TCPECHO_PORT: Server Port, default 80 - * CONFIG_EXAMPLES_TCPECHO_BACKLOG: Listen Backlog, default 8 - * CONFIG_EXAMPLES_TCPECHO_NCONN: Number of Connections, default 8 - * CONFIG_EXAMPLES_TCPECHO_DHCPC: DHCP Client, default n - * CONFIG_EXAMPLES_TCPECHO_NOMAC: Use Canned MAC Address, default n - * CONFIG_EXAMPLES_TCPECHO_IPADDR: Target IP address, default 0x0a000002 - * CONFIG_EXAMPLES_TCPECHO_DRIPADDR: Default Router IP address (Gateway), default 0x0a000001 - * CONFIG_EXAMPLES_TCPECHO_NETMASK: Network Mask, default 0xffffff00 +Prerequistes: -examples/telnetd -^^^^^^^^^^^^^^^^ +- `CONFIG_DEV_RANDOM` – Support for `/dev/random` must be enabled in order to + select this example. - This directory contains a functional port of the tiny uIP shell. In - the NuttX environment, the NuttShell (at apps/nshlib) supersedes this - tiny shell and also supports telnetd. +Configuration: - CONFIG_EXAMPLES_TELNETD - Enable the Telnetd example - CONFIG_NETUTILS_NETLIB, 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 - Telnet daemon. Default: 2048 - CONFIG_EXAMPLES_TELNETD_CLIENTPRIO- Priority of the Telnet client. - Default: SCHED_PRIORITY_DEFAULT - CONFIG_EXAMPLES_TELNETD_CLIENTSTACKSIZE - Stack size allocated for the - Telnet client. Default: 2048 - CONFIG_EXAMPLES_TELNETD_NOMAC - If the hardware has no MAC address of its - own, define this =y to provide a bogus address for testing. - CONFIG_EXAMPLES_TELNETD_IPADDR - The target IP address. Default 10.0.0.2 - 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 +- `CONFIG_EXAMPLES_RANDOM` – Enables the `/dev/random` test. +- `CONFIG_EXAMPLES_MAXSAMPLES` – This is the size of the `/dev/random` I/O + buffer in units of 32-bit samples. Careful! This buffer is allocated on the + stack as needed! Default `64`. +- `CONFIG_EXAMPLES_NSAMPLES` – When you execute the `rand` command, a number of + samples ranging from `1` to `EXAMPLES_MAXSAMPLES` may be specified. If no + argument is specified, this is the default number of samples that will be + collected and displayed. Default `8`. - 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 - -examples/thttpd -^^^^^^^^^^^^^^^ +## `relays` Relays - An example that builds netutils/thttpd with some simple NXFLAT - CGI programs. see boards/README.txt for most THTTPD settings. - In addition to those, this example accepts: +Requires `CONFIG_ARCH_RELAYS`. Contributed by Darcy Gong. - CONFIG_EXAMPLES_THTTPD_NOMAC - (May be defined to use software assigned MAC) - CONFIG_EXAMPLES_THTTPD_DRIPADDR - Default router IP address - CONFIG_EXAMPLES_THTTPD_NETMASK - Network mask +**Note**: This test exercises internal relay driver interfaces. As such, it +relies on internal OS interfaces that are not normally available to a user-space +program. As a result, this example cannot be used if a NuttX is built as a +protected, supervisor kernel (`CONFIG_BUILD_PROTECTED` or +`CONFIG_BUILD_KERNEL`). - Applications using this example will need to enable the following - netutils libraries in the defconfig file: +## `rfid_readuid` RFID - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_THTTPD=y +RFID `READUID` example. -examples/tiff -^^^^^^^^^^^^^ +## `rgbled` RGB LED Using PWM - This is a simple unit test for the TIFF creation library at apps/graphic/tiff. - It is configured to work in the Linux user-mode simulation and has not been - tested in any other environment. +This example demonstrates the use of the RGB led driver to drive an RGB LED with +PWM outputs so that all color characteristcs of RGB LED can be controlled. - At a minimum, to run in an embedded environment, you will probably have to - change the configured paths to the TIFF files defined in the example. +## `romfs` File System - CONFIG_EXAMPLES_TIFF_OUTFILE - Name of the resulting TIFF file. Default is - "/tmp/result.tif" - CONFIG_EXAMPLES_TIFF_TMPFILE1/2 - Names of two temporaries files that - will be used in the file creation. Defaults are "/tmp/tmpfile1.dat" and - "/tmp/tmpfile2.dat" +This example exercises the romfs filesystem. Configuration options include: - The following must also be defined in your apps/ configuration file: +- `CONFIG_EXAMPLES_ROMFS_RAMDEVNO` – The minor device number to use for the ROM + disk. The default is `1` (meaning `/dev/ram1`). +- `CONFIG_EXAMPLES_ROMFS_SECTORSIZE` – The ROM disk sector size to use. Default + is `64`. +- `CONFIG_EXAMPLES_ROMFS_MOUNTPOINT` – The location to mount the ROM disk. + Default: `/usr/local/share`. - CONFIG_EXAMPLES_TIFF=y - CONFIG_GRAPHICS_TIFF=y +## `sendmail` SMTP Client -examples/timer -^^^^^^^^^^^^^^ +This examples exercises the uIP SMTP logic by sending a test message to a +selected recipient. This test can also be built to execute on the Cygwin/Linux +host environment: - This is a simple test of the timer driver (see include/nuttx/timers/timer.h). - - Dependencies: - CONFIG_TIMER - The timer driver must be selected - - Example configuration: - - CONFIG_EXAMPLES_TIMER_DEVNAME - This is the name of the timer device that - will be tested. Default: "/dev/timer0" - CONFIG_EXAMPLES_TIMER_INTERVAL - This is the timer interval in - microseconds. Default: 1000000 - CONFIG_EXAMPLES_TIMER_DELAY - This is the delay between timer samples in - microseconds. Default: 10000 - CONFIG_EXAMPLES_TIMER_STACKSIZE - This is the stack size allocated when - the timer task runs. Default: 2048 - CONFIG_EXAMPLES_TIMER_PRIORITY - This is the priority of the timer task: - Default: 100 - CONFIG_EXAMPLES_TIMER_PROGNAME - This is the name of the program that - will be used when the NSH ELF program is installed. Default: "timer" - -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 - simulated touchscreen driver. - - CONFIG_NSH_BUILTIN_APPS - Build the touchscreen test as - an NSH built-in function. Default: Built as a standalone program - CONFIG_EXAMPLES_TOUCHSCREEN_MINOR - The minor device number. Minor=N - corresponds to touchscreen device /dev/inputN. Note this value must - with CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH. Default 0. - CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH - The path to the touchscreen - device. This must be consistent with CONFIG_EXAMPLES_TOUCHSCREEN_MINOR. - Default: "/dev/input0" - CONFIG_EXAMPLES_TOUCHSCREEN_NSAMPLES - This number of samples is - collected and the program terminates. Default: Samples are collected - indefinitely. - CONFIG_EXAMPLES_TOUCHSCREEN_MOUSE - The touchscreen test can also be - configured to work with a mouse driver by setting this option. - - The following additional configurations must be set in the NuttX - configuration file: +```bash +cd examples/sendmail +make -f Makefile.host TOPDIR= +``` - CONFIG_INPUT=y - (Plus any touchscreen-specific settings). +Settings unique to this example include: - The following must also be defined in your apps configuration file: +- `CONFIG_EXAMPLES_SENDMAIL_NOMAC` – May be defined to use software assigned + MAC (optional) +- `CONFIG_EXAMPLES_SENDMAIL_IPADDR` – Target IP address (required) +- `CONFIG_EXAMPLES_SENDMAIL_DRIPADDR` – Default router IP address (required) +- `CONFIG_EXAMPLES_SENDMAILT_NETMASK` – Network mask (required) +- `CONFIG_EXAMPLES_SENDMAIL_RECIPIENT` – The recipient of the email (required) +- `CONFIG_EXAMPLES_SENDMAIL_SENDER` – Optional. Default: + `nuttx-testing@example.com` +- `CONFIG_EXAMPLES_SENDMAIL_SUBJECT` – Optional. Default: `Testing SMTP from + NuttX` +- `CONFIG_EXAMPLES_SENDMAIL_BODY` – Optional. Default: `Test message sent + by NuttX` - CONFIG_EXAMPLES_TOUCHSREEN=y +**Note 1**: This test has not been verified on the NuttX target environment. As +of this writing, unit-tested in the Cygwin/Linux host environment. - This example code will call boardctl() to setup the touchscreen driver - for texting. The implementation of boardctl() will require that board- - specific logic provide the following interfaces that will be called by - the boardctl() in order to initialize the touchscreen hardware: +**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. - int board_tsc_setup(int minor); +Applications using this example will need to enable the following netutils +libraries in their defconfig file: -examples/udp -^^^^^^^^^^^^ +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETUTILS_SMTP=y +``` - This is a simple network test for verifying client- and server- - functionality over UDP. +## `serialblaster` - Applications using this example will need to enabled the following - netutils libraries in the defconfig file: +Sends a repeating pattern (the alphabet) out a serial port continuously. This +may be useful if you are trying run down other problems that you think might +only occur when the serial port usage is high. - CONFIG_NETUTILS_NETLIB=y +## `serialrx` - Possible configurations: +Constant receives serial data. This is the complement to `serialblaster`. This +may be useful if you are trying run down other problems that you think might +only occur when the serial port usage is high. - - Server on target hardware; client on host - - Client on target hardware; Server on host - - Server and Client on different targets. +## `serloop` Serial Loopback -examples/udpblaster -^^^^^^^^^^^^^^^^^^^ +This is a mindlessly simple loopback test on the console. Useful for testing new +serial drivers. Configuration options include: - This is a simple network test for stressing UDP transfers. It simply - sends UDP packets from both the host and the target and the highest ratei - possible. +- `CONFIG_EXAMPLES_SERLOOP_BUFIO` – Use C buffered I/O (`getchar`/`putchar`) vs. + raw console I/O (read/read). +## `slcd` Alphanumeric Segment LCD -examples/unionfs -^^^^^^^^^^^^^^^^ +A simple test of alphanumeric, segment LCDs (SLCDs). - This is at trivial test of the Union File System. See - nuttx/fs/unionfs/README.txt. Dependencies: +- `CONFIG_EXAMPLES_SLCD` – Enable the SLCD test - CONFIG_DISABLE_MOUNTPOINT - Mountpoint support must not be disabled - CONFIG_NFILE_DESCRIPTORS > 4 - Some file descriptors must be allocated - CONFIG_FS_ROMFS - ROMFS support is required - CONFIG_FS_UNIONFS - Union File System support is required +## `smps` Switched-Mode Power Supply - Configuration options. Use the defaults if you are unsure of what you are doing: +This is a SMPS (Switched-mode power supply) driver example application. - CONFIG_EXAMPLES_UNIONFS - Enables the example - CONFIG_EXAMPLES_UNIONFS_MOUNTPT - Mountpoint path for the Union File System - CONFIG_EXAMPLES_UNIONFS_TMPA - Temporary mount point for file system 1 - CONFIG_EXAMPLES_UNIONFS_TMPB - Temporary mount point for file system 2 - CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_A - ROMFS file system 1 RAM disk device number - CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_B - ROMFS file system 2 RAM disk device number - CONFIG_EXAMPLES_UNIONFS_SECTORSIZE - ROM disk sector size. +## `sotest` Shared Library Module Test - See the README.txt file at nuttx/boards/sim/sim/sim/README.txt for a walk-through of - the output of this text. +This example builds a small shared library module test case. The test shared +library is built using the relocatable ELF format and installed in a ROMFS file +system. At run time, the shared library is installed and exercised. Requires +`CONFIG_LIBC_DLFCN`. Other configuration options: -examples/usbserial -^^^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_SOTEST_DEVMINOR` – The minor device number of the ROMFS block + driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM + block driver that will hold the ROMFS file system containing the ELF + executables to be tested. Default: `0`. - TARGET CONFIGURATION: +- `CONFIG_EXAMPLES_SOTEST_DEVPATH` – The path to the ROMFS block driver device. + This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block + driver that will hold the ROMFS file system containing the ELF executables to + be tested. Default: `/dev/ram0`. - This is another implementation of "Hello, World" but this one uses - a USB serial driver. Configuration options can be used to simply - the test. These options include: +**Notes**: - CONFIG_EXAMPLES_USBSERIAL_INONLY - Only verify IN (device-to-host) data transfers. Default: both - CONFIG_EXAMPLES_USBSERIAL_OUTONLY - Only verify OUT (host-to-device) data transfers. Default: both - CONFIG_EXAMPLES_USBSERIAL_ONLYSMALL - Send only small, single packet messages. Default: Send large and small. - CONFIG_EXAMPLES_USBSERIAL_ONLYBIG - Send only large, multi-packet messages. Default: Send large and small. +1. `CFLAGS` should be provided in `CMODULEFLAGS`. RAM and FLASH memory regions + may require long allcs. For ARM, this might be: - If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB), then - the example code will also manage the USB trace output. The amount of trace output - can be controlled using: + ```makefile + CMODULEFLAGS = $(CFLAGS) -mlong-calls + ``` - CONFIG_EXAMPLES_USBSERIAL_TRACEINIT - Show initialization events - CONFIG_EXAMPLES_USBSERIAL_TRACECLASS - Show class driver events - CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS - Show data transfer events - CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER - Show controller events - CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS - Show interrupt-related events. + Similarly for C++ flags which must be provided in `CXXMODULEFLAGS`. - Error results are always shown in the trace output +2. Your top-level `nuttx/Make.defs` file must also include an appropriate + definition, `LDMODULEFLAGS`, to generate a relocatable ELF object. With GNU + LD, this should include `-r` and `-e `. - HOST-SIDE TEST PROGRAM + ```makefile + LDMODULEFLAGS = -r -e module_initialize + ``` - In additional to the target device-side example, there is also a - host-side application in this directory. This host side application - must be executed on a Linux host in order to perform the USBSERIAL - test. The host application can be compiled under Linux (or Cygwin?) - as follows: + If you use GCC to link, you make also need to include `-nostdlib` or + `-nostartfiles` and `-nodefaultlibs`. - cd examples/usbserial - make -f Makefile.host TOPDIR= +3. This example also requires `genromfs`. `genromfs` can be build as part of the + nuttx toolchain. Or can built from the `genromfs` sources that can be found + in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the + `PATH` variable must include the path to the `genromfs` executable. - RUNNING THE TEST +4. ELF size: The ELF files in this example are, be default, quite large because + they include a lot of _build garbage_. You can greatly reduce the size of the + ELF binaries are using the `objcopy --strip-unneeded` command to remove + un-necessary information from the ELF files. - This will generate a small program called 'host'. Usage: +5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. + That is because the Cygwin GCC does not generate ELF file but rather some + Windows-native binary format. - 1. Build the examples/usbserial target program and start the target. + If you really want to do this, you can create a NuttX x86 buildroot toolchain + and use that be build the ELF executables for the ROMFS file system. - 2. Wait a bit, then do enter: +6. Linker scripts. You might also want to use a linker scripts to combine + sections better. An example linker script is at + `nuttx/libc/modlib/gnu-elf.ld`. That example might have to be tuned for your + particular linker output to position additional sections correctly. The GNU + LD `LDMODULEFLAGS` then might be: - dmesg +```makefile +LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld +``` - At the end of the dmesg output, you should see the serial - device was successfully idenfied and assigned to a tty device, - probably /dev/ttyUSB0 or /dev/ttyACM0 (depending on the configured - USB serial driver). +## `stat` - 3. Then start the host application: +A simple test of `stat()`, `fstat()`, and `statfs()`. This is useful primarily +for bringing up a new file system and verifying the correctness of these +operations. - ./host [] +## `sx127x_demo` `SX127X` Radio - Where: +This example demonstrates the use of the `SX127X` radio. - is the USB TTY device to use. The default is - "/dev/ttyUSB0" (for the PL2303 emulation) or "/dev/ttyACM0" (for - the CDC/ACM serial device). +## `system` - The host and target will exchange are variety of very small and very large - serial messages. +This is a simple test of the `system()` command. The test simply executes this +`system` command: -examples/userfs -^^^^^^^^^^^^^^^ +```c +ret = system("ls -Rl /"); +``` - A simple test of the UserFS file system. +## `tcpblaster` TCP Performance Test -examples/ustream -^^^^^^^^^^^^^^^^ +The `tcpblaster` example derives from the `nettest` example and basically +duplicates that example when the `nettest` PERFORMANCE option is selected. +`tcpblaster` has a little better reporting of performance stats, however. - This is the same test as examples/udp and similar to examples/ustream, - but using Unix domain datagram sockets. +## `tcpecho` TCP Echo Server - Dependencies: - CONFIG_NET_LOCAL - Depends on support for Unix domain sockets +Simple single threaded, poll based TCP echo server. This example implements the +TCP Echo Server from W. Richard Stevens _UNIX Network Programming_ Book. +Contributed by Max Holtberg. - Configuration: - CONFIG_EXAMPLES_UDGRAM - Enables the Unix domain socket example. - CONFIG_EXAMPLES_UDGRAM_ADDR - Specifics the Unix domain address. - Default "/dev/fifo". +See also `examples/nettest` -examples/ustream -^^^^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_TCPECHO=y` – Enables the TCP echo server. +- `CONFIG_XAMPLES_TCPECHO_PORT` – Server Port, default `80`. +- `CONFIG_EXAMPLES_TCPECHO_BACKLOG` – Listen Backlog, default `8`. +- `CONFIG_EXAMPLES_TCPECHO_NCONN` – Number of Connections, default `8`. +- `CONFIG_EXAMPLES_TCPECHO_DHCPC` – DHCP Client, default `n`. +- `CONFIG_EXAMPLES_TCPECHO_NOMAC` – Use Canned MAC Address, default `n`. +- `CONFIG_EXAMPLES_TCPECHO_IPADDR` – Target IP address, default `0x0a000002`. +- `CONFIG_EXAMPLES_TCPECHO_DRIPADDR` – Default Router IP address (Gateway), + default `0x0a000001`. +- `CONFIG_EXAMPLES_TCPECHO_NETMASK` – Network Mask, default `0xffffff00`. - This is the same test as examples/udp and similar to examples/udgram, - but using Unix domain stream sockets. +## `telnetd` Simple Telnet Shell - Dependencies: - CONFIG_NET_LOCAL - Depends on support for Unix domain sockets +This directory contains a functional port of the tiny uIP shell. In the NuttX +environment, the NuttShell (at `apps/nshlib`) supersedes this tiny shell and +also supports `telnetd`. - Configuration: - CONFIG_EXAMPLES_USTREAM - Enables the Unix domain socket example. - CONFIG_EXAMPLES_USTREAM_ADDR - Specifics the Unix domain address. - Default "/dev/fifo". +- `CONFIG_EXAMPLES_TELNETD` – Enable the Telnetd example. +- `CONFIG_NETUTILS_NETLIB`, `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 + Telnet daemon. Default: `2048`. +- `CONFIG_EXAMPLES_TELNETD_CLIENTPRIO` – Priority of the Telnet client. Default: + `SCHED_PRIORITY_DEFAULT`. +- `CONFIG_EXAMPLES_TELNETD_CLIENTSTACKSIZE` – Stack size allocated for the + Telnet client. Default: `2048`. +- `CONFIG_EXAMPLES_TELNETD_NOMAC` – If the hardware has no MAC address of its + own, define this `=y` to provide a bogus address for testing. +- `CONFIG_EXAMPLES_TELNETD_IPADDR` – The target IP address. Default `10.0.0.2`. +- `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`. -examples/watchdog -^^^^^^^^^^^^^^^^^ +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` + +## `thttpd` THTTPD server - A simple test of a watchdog timer driver. Initializes starts the watchdog - timer. It pings the watchdog timer for a period of time then lets the - watchdog timer expire... resetting the CPU is successful. This - example can ONLY be built as an NSH built-in function. +An example that builds `netutils/thttpd` with some simple NXFLAT CGI programs. +See `boards/README.txt` for most THTTPD settings. In addition to those, this +example accepts: - This test depends on these specific Watchdog/NSH configurations settings (your - specific watchdog hardware settings might require additional settings). +- `CONFIG_EXAMPLES_THTTPD_NOMAC` – (May be defined to use software assigned + MAC) +- `CONFIG_EXAMPLES_THTTPD_DRIPADDR` – Default router IP address. +- `CONFIG_EXAMPLES_THTTPD_NETMASK` – Network mask. - CONFIG_WATCHDOG- Enables watchdog timer support support. - CONFIG_NSH_BUILTIN_APPS - Build the watchdog time test as an NSH - built-in function. +Applications using this example will need to enable the following `netutils` +libraries in the `defconfig` file: - Specific configuration options for this example include: +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETUTILS_THTTPD=y +``` - CONFIG_EXAMPLES_WATCHDOG_DEVPATH - The path to the Watchdog device. - Default: /dev/watchdog0 - CONFIG_EXAMPLES_WATCHDOG_PINGTIME - Time in milliseconds that the example - will ping the watchdog before letting the watchdog expire. Default: 5000 - milliseconds - CONFIG_EXAMPLES_WATCHDOG_PINGDELAY - Time delay between pings in - milliseconds. Default: 500 milliseconds. - CONFIG_EXAMPLES_WATCHDOG_TIMEOUT - The watchdog timeout value in - milliseconds before the watchdog timer expires. Default: 2000 - milliseconds. +## `tiff` -examples/webserver -^^^^^^^^^^^^^^^^^^ +This is a simple unit test for the TIFF creation library at `apps/graphic/tiff`. +It is configured to work in the Linux user-mode simulation and has not been +tested in any other environment. - This is a port of uIP tiny webserver example application. Settings - specific to this example include: +At a minimum, to run in an embedded environment, you will probably have to +change the configured paths to the TIFF files defined in the example. - CONFIG_EXAMPLES_WEBSERVER_NOMAC - (May be defined to use software assigned MAC) - CONFIG_EXAMPLES_WEBSERVER_IPADDR - Target IP address - CONFIG_EXAMPLES_WEBSERVER_DRIPADDR - Default router IP address - CONFIG_EXAMPLES_WEBSERVER_NETMASK - Network mask - CONFIG_EXAMPLES_WEBSERVER_DHCPC - Select to get IP address via DHCP +- `CONFIG_EXAMPLES_TIFF_OUTFILE` – Name of the resulting TIFF file. Default is + `/tmp/result.tif`. +- `CONFIG_EXAMPLES_TIFF_TMPFILE1/2` – Names of two temporaries files that will + be used in the file creation. Defaults are `/tmp/tmpfile1.dat` and + `/tmp/tmpfile2.dat`. - If you use DHCPC, then some special configuration network options are - required. These include: +The following must also be defined in your `apps/` configuration file: - CONFIG_NET=y - Of course - CONFIG_NET_UDP=y - UDP support is required for DHCP - (as well as various other UDP-related - configuration settings). - CONFIG_NET_BROADCAST=y - UDP broadcast support is needed. - CONFIG_NET_ETH_PKTSIZE=650 - Per RFC2131 (p. 9), the DHCP client must be - (or larger) prepared to receive DHCP messages of up to - 576 bytes (excluding Ethernet, IP, or UDP - headers and FCS). - NOTE: Note that the actual MTU setting will - depend upon the specific link protocol. - Here Ethernet is indicated. +```conf +CONFIG_EXAMPLES_TIFF=y +CONFIG_GRAPHICS_TIFF=y +``` - Other configuration items apply also to the selected webserver net utility. - Additional relevant settings for the uIP webserver net utility are: +## `timer` - CONFIG_NETUTILS_HTTPDSTACKSIZE - CONFIG_NETUTILS_HTTPDFILESTATS - CONFIG_NETUTILS_HTTPDNETSTATS +This is a simple test of the timer driver (see `include/nuttx/timers/timer.h`). + +Dependencies: + +- `CONFIG_TIMER` – The timer driver must be selected + +Example configuration: + +- `CONFIG_EXAMPLES_TIMER_DEVNAME` – This is the name of the timer device that + will be tested. Default: `/dev/timer0`. +- `CONFIG_EXAMPLES_TIMER_INTERVAL` – This is the timer interval in microseconds. + Default: `1000000`. +- `CONFIG_EXAMPLES_TIMER_DELAY` – This is the delay between timer samples in + microseconds. Default: `10000`. +- `CONFIG_EXAMPLES_TIMER_STACKSIZE` – This is the stack size allocated when the + timer task runs. Default: `2048`. +- `CONFIG_EXAMPLES_TIMER_PRIORITY` – This is the priority of the timer task: + Default: `100`. +- `CONFIG_EXAMPLES_TIMER_PROGNAME` – This is the name of the program that will + be used when the NSH ELF program is installed. Default: `timer`. + +## `touchscreen` Touchscreen Events + +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 simulated touchscreen +driver. + +- `CONFIG_NSH_BUILTIN_APPS` – Build the touchscreen test as an NSH built-in + function. Default: Built as a standalone program. +- `CONFIG_EXAMPLES_TOUCHSCREEN_MINOR` – The minor device number. Minor `N` + corresponds to touchscreen device `/dev/inputN`. Note this value must with + `CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH`. Default `0`. +- `CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH` – The path to the touchscreen device. + This must be consistent with `CONFIG_EXAMPLES_TOUCHSCREEN_MINOR`. Default: + `/dev/input0`. +- `CONFIG_EXAMPLES_TOUCHSCREEN_NSAMPLES` – This number of samples is collected + and the program terminates. Default: Samples are collected indefinitely. +- `CONFIG_EXAMPLES_TOUCHSCREEN_MOUSE` – The touchscreen test can also be + configured to work with a mouse driver by setting this option. - Applications using this example will need to enable the following - netutils libraries in their defconfig file: +The following additional configurations must be set in the NuttX configuration +file: - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_DHCPC=y - CONFIG_NETDB_DNSCLIENT=y - CONFIG_NETUTILS_WEBSERVER=y +- `CONFIG_INPUT=y` (plus any touchscreen-specific settings) - NOTE: This example does depend on the perl script at - nuttx/tools/mkfsdata.pl. You must have perl installed on your - development system at /usr/bin/perl. +The following must also be defined in your apps configuration file: -examples/wget -^^^^^^^^^^^^^ +- `CONFIG_EXAMPLES_TOUCHSREEN=y` - A simple web client example. It will obtain a file from a server using the HTTP - protocol. Settings unique to this example include: +This example code will call `boardctl()` to setup the touchscreen driver for +texting. The implementation of `boardctl()` will require that board- specific +logic provide the following interfaces that will be called by the `boardctl()` +in order to initialize the touchscreen hardware: - CONFIG_EXAMPLES_WGET_URL - The URL of the file to get - CONFIG_EXAMPLES_WGET_NOMAC - (May be defined to use software assigned MAC) - CONFIG_EXAMPLES_WGET_IPADDR - Target IP address - CONFIG_EXAMPLES_WGET_DRIPADDR - Default router IP address - CONFIG_EXAMPLES_WGET_NETMASK - Network mask +```c +int board_tsc_setup(int minor); +``` - This example uses netutils/webclient. Additional configuration settings apply - to that code as follows (but built-in defaults are probably OK): - - CONFIG_WEBCLIENT_GETMIMETYPE, CONFIG_WEBCLIENT_MAXHTTPLINE, - CONFIG_WEBCLIENT_MAXMIMESIZE, CONFIG_WEBCLIENT_MAXHOSTNAME, - CONFIG_WEBCLIENT_MAXFILENAME - - Of course, the example also requires other settings including CONFIG_NET and - CONFIG_NET_TCP. The example also uses the uIP resolver which requires CONFIG_UDP. - - WARNNG: As of this writing, wget is untested on the target platform. At present - it has been tested only in the host-based configuration described in the following - note. The primary difference is that the target version will rely on the also - untested uIP name resolver. - - NOTE: For test purposes, this example can be built as a host-based wget function. - This can be built as follows: - - cd examples/wget - make -f Makefile.host +## `udp` Client/Server Over UDP - Applications using this example will need to enable the following netutils - libraries in the defconfig file: +This is a simple network test for verifying client- and server- functionality +over UDP. - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETDB_DNSCLIENT=y - CONFIG_NETUTILS_WEBCLIENT=y +Applications using this example will need to enabled the following `netutils` +libraries in the `defconfig` file: -examples/wget -^^^^^^^^^^^^^ - - Uses wget to get a JSON encoded file, then decodes the file. - - CONFIG_EXAMPLES_WDGETJSON_MAXSIZE - Max. JSON Buffer Size - CONFIG_EXAMPLES_EXAMPLES_WGETJSON_URL - wget URL +- `CONFIG_NETUTILS_NETLIB=y` -examples/xmlrpc -^^^^^^^^^^^^^^^ +Possible configurations: - This example exercises the "Embeddable Lightweight XML-RPC Server" which - is discussed at: +- Server on target hardware; client on host. +- Client on target hardware; Server on host. +- Server and Client on different targets. - http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364 +## `udpblaster` - Configuration options: +This is a simple network test for stressing UDP transfers. It simply sends UDP +packets from both the host and the target and the highest possible rate. - CONFIG_EXAMPLES_XMLRPC_BUFFERSIZE - HTTP buffer size. Default 1024 - CONFIG_EXAMPLES_XMLRPC_DHCPC - Use DHCP Client. Default n. Ignored - if CONFIG_NSH_NETINIT is selected. - CONFIG_EXAMPLES_XMLRPC_NOMAC - Use Canned MAC Address. Default n. Ignored - if CONFIG_NSH_NETINIT is selected. - CONFIG_EXAMPLES_XMLRPC_IPADDR - Target IP address. Default 0x0a000002. - Ignored if CONFIG_NSH_NETINIT is selected. - CONFIG_EXAMPLES_XMLRPC_DRIPADDR - Default Router IP address (Gateway). - Default 0x0a000001. Ignored if CONFIG_NSH_NETINIT is selected. - CONFIG_EXAMPLES_XMLRPC_NETMASK - Network Mask. Default 0xffffff00 - Ignored if CONFIG_NSH_NETINIT is selected. +## `unionfs` Union File System -examples/zerocross -^^^^^^^^^^^^^^^^^^ +This is at trivial test of the Union File System. See +`nuttx/fs/unionfs/README.txt`. Dependencies: - A simple test of the Zero Crossing device driver. +- `CONFIG_DISABLE_MOUNTPOINT` – Mountpoint support must not be + disabled. +- `CONFIG_NFILE_DESCRIPTORS > 4` – Some file descriptors must be + allocated. +- `CONFIG_FS_ROMFS` – ROMFS support is required. +- `CONFIG_FS_UNIONFS` – Union File System support is required. + +Configuration options. Use the defaults if you are unsure of what you are doing: + +- `CONFIG_EXAMPLES_UNIONFS` – Enables the example. +- `CONFIG_EXAMPLES_UNIONFS_MOUNTPT` – Mountpoint path for the Union File + System. +- `CONFIG_EXAMPLES_UNIONFS_TMPA` – Temporary mount point for file system + `1`. +- `CONFIG_EXAMPLES_UNIONFS_TMPB` – Temporary mount point for file system + `2`. +- `CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_A` – ROMFS file system `1` RAM disk device + number. +- `CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_B` – ROMFS file system `2` RAM disk device + number. +- `CONFIG_EXAMPLES_UNIONFS_SECTORSIZE` – ROM disk sector size. + +See the `README.txt` file at `nuttx/boards/sim/sim/sim/README.txt` for a +walk-through of the output of this text. + +## `usbserial` USB Serial Hello World + +### Target configuration + +This is another implementation of _Hello, World_ but this one uses a USB serial +driver. Configuration options can be used to simply the test. These options +include: + +- `CONFIG_EXAMPLES_USBSERIAL_INONLY` – Only verify IN (device-to-host) data + transfers. Default: both. +- `CONFIG_EXAMPLES_USBSERIAL_OUTONLY` – Only verify OUT (host-to-device) data + transfers. Default: both. +- `CONFIG_EXAMPLES_USBSERIAL_ONLYSMALL` – Send only small, single packet + messages. Default: Send large and small. +- `CONFIG_EXAMPLES_USBSERIAL_ONLYBIG` – Send only large, multi-packet messages. + Default: Send large and small. + +If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and +`CONFIG_DEBUG_USB`), then the example code will also manage the USB trace +output. The amount of trace output can be controlled using: + +- `CONFIG_EXAMPLES_USBSERIAL_TRACEINIT` – Show initialization events. +- `CONFIG_EXAMPLES_USBSERIAL_TRACECLASS` – Show class driver events. +- `CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS` – Show data transfer events. +- `CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER` – Show controller events. +- `CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS` – Show interrupt-related events. + +Error results are always shown in the trace output. + +### Host-side test program + +In additional to the target device-side example, there is also a host-side +application in this directory. This host side application must be executed on a +Linux host in order to perform the `USBSERIAL` test. The host application can be +compiled under Linux (or Cygwin?) as follows: + +```bash +cd examples/usbserial +make -f Makefile.host TOPDIR= +``` + +### Running the test + +This will generate a small program called `host`. Usage: + +1. Build the `examples/usbserial` target program and start the target. + +2. Wait a bit, then do enter: + + ```shell + dmesg + ``` + + At the end of the dmesg output, you should see the serial device was + successfully idenfied and assigned to a tty device, probably `/dev/ttyUSB0` + or `/dev/ttyACM0` (depending on the configured USB serial driver). + +3. Then start the host application: + + ```bash + ./host [] + ``` + + Where: + + - `` is the USB TTY device to use. The default is `/dev/ttyUSB0` + (for the PL2303 emulation) or `/dev/ttyACM0` (for the CDC/ACM serial + device). + +The host and target will exchange are variety of very small and very large +serial messages. + +## `userfs` UserFS File System + +A simple test of the UserFS file system. + +## `ustream` Unix Datagram Sockets + +This is the same test as `examples/udp` and similar to `examples/ustream`, but +using Unix domain datagram sockets. + +Dependencies: + +- `CONFIG_NET_LOCAL` – Depends on support for Unix domain sockets. + +Configuration: + +- `CONFIG_EXAMPLES_UDGRAM` – Enables the Unix domain socket example. +- `CONFIG_EXAMPLES_UDGRAM_ADDR` – Specifics the Unix domain address. Default: + `/dev/fifo`. + +## `ustream` Unix Stream Sockets + +This is the same test as `examples/udp` and similar to `examples/udgram`, but +using Unix domain stream sockets. + +Dependencies: + +- `CONFIG_NET_LOCAL` – Depends on support for Unix domain sockets. + +Configuration: + +- `CONFIG_EXAMPLES_USTREAM` – Enables the Unix domain socket example. +- `CONFIG_EXAMPLES_USTREAM_ADDR` – Specifics the Unix domain address. Default: + `/dev/fifo`. + +## `watchdog` Watchdog Timer + +A simple test of a watchdog timer driver. Initializes starts the watchdog timer. +It pings the watchdog timer for a period of time then lets the watchdog timer +expire... resetting the CPU is successful. This example can ONLY be built as an +NSH built-in function. + +This test depends on these specific Watchdog/NSH configurations settings (your +specific watchdog hardware settings might require additional settings). + +- `CONFIG_WATCHDOG` – Enables watchdog timer support support. +- `CONFIG_NSH_BUILTIN_APPS` – Build the watchdog time test as an NSH built-in + function. + +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 + will ping the watchdog before letting the watchdog expire. Default: `5000` + milliseconds. +- `CONFIG_EXAMPLES_WATCHDOG_PINGDELAY` – Time delay between pings in + milliseconds. Default: `500` milliseconds. +- `CONFIG_EXAMPLES_WATCHDOG_TIMEOUT` – The watchdog timeout value in + milliseconds before the watchdog timer expires. Default: `2000` milliseconds. + +## `webserver` Simple Webserver + +This is a port of uIP tiny webserver example application. Settings specific to +this example include: + +- `CONFIG_EXAMPLES_WEBSERVER_NOMAC` (may be defined to use software assigned + MAC) +- `CONFIG_EXAMPLES_WEBSERVER_IPADDR` – Target IP address. +- `CONFIG_EXAMPLES_WEBSERVER_DRIPADDR` – Default router IP address. +- `CONFIG_EXAMPLES_WEBSERVER_NETMASK` – Network mask. +- `CONFIG_EXAMPLES_WEBSERVER_DHCPC` – Select to get IP address via DHCP. + +If you use DHCPC, then some special configuration network options are required. +These include: + +- `CONFIG_NET=y` – of course. +- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various + other UDP-related configuration settings). +- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed. +- `CONFIG_NET_ETH_PKTSIZE=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). **Note** that the actual MTU setting + will depend upon the specific link protocol. Here Ethernet is indicated. + +Other configuration items apply also to the selected `webserver` net utility. +Additional relevant settings for the uIP `webserver` net utility are: + +- `CONFIG_NETUTILS_HTTPDSTACKSIZE` +- `CONFIG_NETUTILS_HTTPDFILESTATS` +- `CONFIG_NETUTILS_HTTPDNETSTATS` + +Applications using this example will need to enable the following `netutils` +libraries in their `defconfig` file: + +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETUTILS_DHCPC=y +CONFIG_NETDB_DNSCLIENT=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 development +system at `/usr/bin/perl`. + +## `wget` Web Client + +A simple web client example. It will obtain a file from a server using the HTTP +protocol. Settings unique to this example include: + +- `CONFIG_EXAMPLES_WGET_URL` – The URL of the file to get +- `CONFIG_EXAMPLES_WGET_NOMAC` – (May be defined to use software assigned MAC) +- `CONFIG_EXAMPLES_WGET_IPADDR` – Target IP address +- `CONFIG_EXAMPLES_WGET_DRIPADDR` – Default router IP address +- `CONFIG_EXAMPLES_WGET_NETMASK` – Network mask + +This example uses `netutils/webclient`. Additional configuration settings apply +to that code as follows (but built-in defaults are probably OK): + +- `CONFIG_WEBCLIENT_GETMIMETYPE` +- `CONFIG_WEBCLIENT_MAXHTTPLINE` +- `CONFIG_WEBCLIENT_MAXMIMESIZE` +- `CONFIG_WEBCLIENT_MAXHOSTNAME` +- `CONFIG_WEBCLIENT_MAXFILENAME` + +Of course, the example also requires other settings including `CONFIG_NET` and +`CONFIG_NET_TCP`. The example also uses the uIP resolver which requires +`CONFIG_UDP`. + +**Warning**: As of this writing, `wget` is untested on the target platform. At +present it has been tested only in the host-based configuration described in the +following note. The primary difference is that the target version will rely on +the also untested uIP name resolver. + +**Note**: For test purposes, this example can be built as a host-based `wget` +function. This can be built as follows: + +```bash +cd examples/wget +make -f Makefile.host +``` + +Applications using this example will need to enable the following `netutils` +libraries in the `defconfig` file: + +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETDB_DNSCLIENT=y +CONFIG_NETUTILS_WEBCLIENT=y +``` + +## `wgetjson` GET JSON Using `wget` + +Uses `wget` to get a JSON encoded file, then decodes the file. + +- `CONFIG_EXAMPLES_WDGETJSON_MAXSIZE` – Max. JSON Buffer Size. +- `CONFIG_EXAMPLES_EXAMPLES_WGETJSON_URL` – `wget` URL + +## `xmlrpc` XML-RPC Server + +This example exercises the _Embeddable Lightweight XML-RPC Server_ which is +discussed at: + +http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364 + +Configuration options: + +- `CONFIG_EXAMPLES_XMLRPC_BUFFERSIZE` – HTTP buffer size. Default `1024` +- `CONFIG_EXAMPLES_XMLRPC_DHCPC` – Use DHCP Client. Default `n`. Ignored if + `CONFIG_NSH_NETINIT` is selected. +- `CONFIG_EXAMPLES_XMLRPC_NOMAC` – Use Canned MAC Address. Default `n`. Ignored + if `CONFIG_NSH_NETINIT` is selected. +- `CONFIG_EXAMPLES_XMLRPC_IPADDR` – Target IP address. Default `0x0a000002`. + Ignored if `CONFIG_NSH_NETINIT` is selected. +- `CONFIG_EXAMPLES_XMLRPC_DRIPADDR` – Default Router IP address (Gateway). + Default `0x0a000001`. Ignored if `CONFIG_NSH_NETINIT` is selected. +- `CONFIG_EXAMPLES_XMLRPC_NETMASK` – Network Mask. Default `0xffffff00`. Ignored + if `CONFIG_NSH_NETINIT` is selected. + +## `zerocross` Zero Crossing Device + +A simple test of the Zero Crossing device driver. diff --git a/examples/bastest/README.md b/examples/bastest/README.md index 40c3cb16f..b4c0bafb0 100644 --- a/examples/bastest/README.md +++ b/examples/bastest/README.md @@ -1,61 +1,58 @@ -README -====== +# Examples / `bastest` Bas BASIC Tests - This directory contains a small program that will mount a ROMFS file system - containing the BASIC test files extracted from the BAS 2.4 release. +This directory contains a small program that will mount a ROMFS file system +containing the BASIC test files extracted from the BAS `2.4` release. -Background -========== - Bas is an interpreter for the classic dialect of the programming language - BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s, - unlike some other UNIX BASIC interpreters, that implement a different - syntax, breaking compatibility to existing programs. Bas offers many ANSI - BASIC statements for structured programming, such as procedures, local - variables and various loop types. Further there are matrix operations, - automatic LIST indentation and many statements and functions found in - specific classic dialects. Line numbers are not required. +## Background - The interpreter tokenises the source and resolves references to variables - and jump targets before running the program. This compilation pass - increases efficiency and catches syntax errors, type errors and references - to variables that are never initialised. Bas is written in ANSI C for - UNIX systems. +Bas is an interpreter for the classic dialect of the programming language BASIC. +It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some +other UNIX BASIC interpreters, that implement a different syntax, breaking +compatibility to existing programs. Bas offers many ANSI BASIC statements for +structured programming, such as procedures, local variables and various loop +types. Further there are matrix operations, automatic LIST indentation and many +statements and functions found in specific classic dialects. Line numbers are +not required. -License -======= - BAS 2.4 is released as part of NuttX under the standard 3-clause BSD license - use by all components of NuttX. This is not incompatible with the original - BAS 2.4 licensing +The interpreter tokenises the source and resolves references to variables and +jump targets before running the program. This compilation pass increases +efficiency and catches syntax errors, type errors and references to variables +that are never initialised. Bas is written in ANSI C for UNIX systems. - Copyright (c) 1999-2014 Michael Haardt +## License - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: +BAS `2.4` is released as part of NuttX under the standard 3-clause BSD license +use by all components of NuttX. This is not incompatible with the original BAS +`2.4` licensing - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. +Copyright (c) 1999-2014 Michael Haardt - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: -TEST OVERVIEW -============= +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +# Test Overview + +## `test01.bas` -test01.bas -========== Scalar variable assignment -Test File ---------- +### Test File + +```basic 10 a=1 20 print a 30 a$="hello" @@ -66,27 +63,31 @@ Test File 80 print a 90 a=.2e-6 100 print a +``` -Expected Result ---------------- +### Expected Result + +``` 1 hello 0.0002 0.000 0.0000020 0.0000002 +``` -Notes ------ - Output would differ on other platforms NttX does not use scientific - notation in floating point output. +### Notes + +Output would differ on other platforms NttX does not use scientific notation in +floating point output. + +## `test02.bas` -test02.bas -========== Array variable assignment -Test File ---------- +### Test File + +```basic 10 dim a(1) 20 a(0)=10 30 a(1)=11 @@ -94,19 +95,23 @@ Test File 50 print a(0) 60 print a(1) 70 print a +``` -Expected Result ---------------- +### Expected Result + +``` 10 11 12 +``` -test03.bas -========== -FOR loops +## `test03.bas` -Test File ---------- +`FOR` loops + +### Test File + +```basic 10 for i=0 to 10 20 print i 30 if i=5 then exit for @@ -123,9 +128,11 @@ Test File 140 for i$="" to "aaaaaaaaaa" step "a" 150 print i$ 160 next +``` -Expected Result ---------------- +### Expected Result + +``` 0 1 2 @@ -146,21 +153,25 @@ aaaaaaa aaaaaaaa aaaaaaaaa aaaaaaaaaa +``` -test04.bas -========== -REPEAT UNTIL loop +## `test04.bas` -Test File ---------- +`REPEAT` `UNTIL` loop + +### Test File + +```basic 10 a=1 20 repeat 30 print a 40 a=a+1 50 until a=10 +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 @@ -170,13 +181,15 @@ Expected Result 7 8 9 +``` -test05.bas -========== -GOSUB RETURN subroutines +## `test05.bas` -Test File ---------- +`GOSUB` `RETURN` subroutines + +### Test File + +```basic 10 gosub 100 20 gosub 100 30 end @@ -184,20 +197,24 @@ Test File 110 gosub 200 120 return 200 print "hello, world":return +``` -Expected Result ---------------- -hello, world -hello, world -hello, world -hello, world +### Expected Result + +``` +hello, world +hello, world +hello, world +hello, world +``` + +## `test06.bas` -test06.bas -========== Recursive function without arguments -Test File ---------- +### Test File + +```basic 10 def fnloop 20 if n=0.0 then 30 r=0.0 @@ -209,9 +226,11 @@ Test File 90 =r 100 n=10 110 print fnloop +``` -Expected Result ---------------- +### Expected Result + +``` 10 9 8 @@ -223,28 +242,34 @@ Expected Result 2 1 0 +``` + +## `test07.bas` -test07.bas -========== Recursive function with arguments -Test File ---------- +### Test File + +```basic 10 def fna(x) 20 if x=0 then r=1 else r=x*fna(x-1) 30 =r 40 print fna(7) +``` -Expected Result ---------------- - 5040 +### Expected Result -test08.bas -========== -DATA, READ and RESTORE +``` +5040 +``` -Test File ---------- +## `test08.bas` + +`DATA`, `READ` and `RESTORE` + +### Test File + +```basic 10 data "a",b 20 data "c","d 40 read j$ @@ -254,21 +279,25 @@ Test File 80 read j$,k$ 90 print "j=";j$;" k=";k$ 100 next +``` -Expected Result ---------------- +### Expected Result + +``` j=a j=c k=d Error: end of `data' in line 80 at: 80 read j$,k$ ^ +``` -test09.bas -========== -LOCAL variables +## `test09.bas` -Test File ---------- +`LOCAL` variables + +### Test File + +```basic 10 def fna(a) 20 local b 30 b=a+1 @@ -277,19 +306,23 @@ Test File 70 print b 80 print fna(4) 90 print b +``` -Expected Result ---------------- +### Expected Result + +``` 3 5 3 +``` -test10.bas -========== -PRINT USING +## `test10.bas` -Test File ---------- +`PRINT USING` + +### Test File + +```basic 10 print using "!";"abcdef" 20 print using "\ \";"abcdef" 30 print using "###-";-1 @@ -320,9 +353,11 @@ Test File 280 print using "a!b";"S","T" 290 print using "a!b!c";"S" 300 print using "a!b!c";"S","T" +``` -Expected Result ---------------- +### Expected Result + +``` a abc 1- @@ -353,33 +388,39 @@ aSb aSbaTb aSb aSbTc +``` -test11.bas -========== -OPEN and LINE INPUT +## `test11.bas` -Test File ---------- +`OPEN` and `LINE INPUT` + +### Test File + +```basic 10 open "i",1,"test.bas" 20 while not eof(1) 30 line input #1,a$ 40 print a$ 50 wend +``` -Expected Result ---------------- +### Expected Result + +```basic 10 open "i",1,"test.bas" 20 while not eof(1) 30 line input #1,a$ 40 print a$ 50 wend +``` + +## `test12.bas` -test12.bas -========== Exception handling -Test File ---------- +### Test File + +```basic 10 on error print "global handler 1 caught error in line ";erl : resume 30 20 print mid$("",-1) 30 on error print "global handler 2 caught error in line ";erl : end @@ -389,35 +430,43 @@ Test File 70 end proc 80 procx 90 print 1 mod 0 +``` -Expected Result ---------------- +### Expected Result + +``` global handler 1 caught error in line 20 local handler caught error in line 60 global handler 2 caught error in line 90 +``` + +## `test13.bas` -test01.bas -========== Unnumbered lines -Test File ---------- +### Test File + +```basic print "a" goto 20 print "b" 20 print "c" +``` -Expected Result ---------------- +### Expected Result + +``` a c +``` -test14.bas -========== -SELECT CASE +## `test14.bas` -Test File ---------- +`SELECT CASE` + +### Test File + +```basic 10 for i=0 to 9 20 for j=0 to 9 30 print i,j @@ -439,9 +488,11 @@ Test File 190 end select 200 next 210 next +``` -Expected Result ---------------- +### Expected Result + +``` 0 0 i after case 0 0 1 @@ -643,13 +694,15 @@ i after case else i after case else 9 9 i after case else +``` -test15.bas -========== -FIELD, PUT and GET +## `test15.bas` -Test File ---------- +`FIELD`, `PUT` and `GET` + +### Test File + +```basic a$="a" open "r",1,"test.dat",128 print "before field a$=";a$ @@ -667,20 +720,24 @@ get #2 print "after get b$=";b$ close #2 kill "test.dat" +``` -Expected Result ---------------- +### Expected Result + +``` before field a$=a a$=hi ya after close a$= after get b$=hi ya +``` -test16.bas -========== -SWAP +## `test16.bas` -Test File ---------- +`SWAP` + +### Test File + +```basic a=1 : b=2 print "a=";a;"b=";b swap a,b @@ -690,20 +747,24 @@ a$(1,0)="a" : b$(0,1)="b" print "a$(1,0)=";a$(1,0);"b$(0,1)=";b$(0,1) swap a$(1,0),b$(0,1) print "a$(1,0)=";a$(1,0);"b$(0,1)=";b$(0,1) +``` -Expected Result ---------------- +### Expected Result + +``` a= 1 b= 2 a= 2 b= 1 a$(1,0)=ab$(0,1)=b a$(1,0)=bb$(0,1)=a +``` -test17.bas -========== -DO, EXIT DO, LOOP +## `test17.bas` -Test File ---------- +`DO`, `EXIT DO`, `LOOP` + +### Test File + +```basic print "loop started" i=1 do @@ -712,9 +773,11 @@ do if i>10 then exit do loop print "loop ended" +``` -Expected Result ---------------- +### Expected Result + +``` loop started i is 1 i is 2 @@ -727,13 +790,15 @@ i is 8 i is 9 i is 10 loop ended +``` -test18.bas -========== -DO WHILE, LOOP +## `test18.bas` -Test File ---------- +`DO WHILE`, `LOOP` + +### Test File + +```basic print "loop started" x$="" do while len(x$)<3 @@ -746,9 +811,11 @@ do while len(x$)<3 loop loop print "loop ended" +``` -Expected Result ---------------- +### Expected Result + +``` loop started x$ is y$ is @@ -760,13 +827,15 @@ x$ is aa y$ is y$ is b loop ended +``` -test19.bas -========== -ELSEIF +## `test19.bas` -Test File ---------- +`ELSEIF` + +### Test File + +```basic for x=1 to 3 if x=1 then print "1a" @@ -786,22 +855,26 @@ for x=1 to 3 print "2b" elseif x=3 then print "3b" next +``` -Expected Result ---------------- +### Expected Result + +``` 1a 2a 3a 1b 2b 3b +``` + +## `test20.bas` -test20.bas -========== Caller trace -Test File ---------- +### Test File + +```basic 10 gosub 20 20 gosub 30 30 procb @@ -812,9 +885,11 @@ Test File 80 def procb 90 proca 100 end proc +``` -Expected Result ---------------- +### Expected Result + +``` hi Break in line 60 at: 60 stop @@ -831,13 +906,15 @@ Called in line 20 at: Called in line 10 at: 10 gosub 20 ^ +``` + +## `test21.bas` -test21.bas -========== Matrix assignment -Test File ---------- +### Test File + +```basic dim a(3,4) for i=0 to 3 for j=0 to 4 @@ -853,9 +930,11 @@ for i=0 to 3 next print next +``` -Expected Result ---------------- +### Expected Result + +``` 0 1 2 3 4 10 11 12 13 14 20 21 22 23 24 @@ -864,13 +943,15 @@ Expected Result 0 11 12 13 14 0 21 22 23 24 0 31 32 33 34 +``` -test22.bas -========== -MAT PRINT +## `test22.bas` -Test File ---------- +`MAT PRINT` + +### Test File + +```basic dim a(2,2) for i=0 to 2 for j=0 to 2 @@ -884,9 +965,11 @@ for j=1 to 2 print next mat print using " ##.##";a,a +``` -Expected Result ---------------- +### Expected Result + +``` 11.00 21.00 12.00 22.00 11.00 12.00 @@ -894,13 +977,15 @@ Expected Result 11.00 12.00 21.00 22.00 +``` + +## `test23.bas` -test23.bas -========== Matrix addition and subtraction -Test File ---------- +### Test File + +```basic dim a(2,2) a(2,2)=2.5 dim b%(2,2) @@ -913,9 +998,11 @@ c$(2,1)="hi" mat print c$ mat c$=c$+c$ mat print c$ +``` -Expected Result ---------------- +### Expected Result + +``` 0 0 0 2.5 0 0 @@ -924,13 +1011,15 @@ Expected Result hi hihi +``` + +## `test24.bas` -test24.bas -========== Matrix multiplication -Test File ---------- +### Test File + +```basic 10 dim b(2,3),c(3,2) 20 for i=1 to 2 : for j=1 to 3 : read b(i,j) : next : next 30 for i=1 to 3 : for j=1 to 2 : read c(i,j) : next : next @@ -938,9 +1027,11 @@ Test File 50 mat print b,c,a 60 data 1,2,3,3,2,1 70 data 1,2,2,1,3,3 +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 3 2 1 @@ -950,13 +1041,15 @@ Expected Result 14 13 10 11 +``` + +## `test25.bas` -test25.bas -========== Matrix scalar multiplication -Test File ---------- +### Test File + +```basic 10 dim a(3,3) 20 for i=1 to 3 : for j=1 to 3 : read a(i,j) : next : next 30 mat print a @@ -970,9 +1063,11 @@ Test File 110 mat print inch_array 120 mat cm_array=(2.54)*inch_array 130 mat print cm_array +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 4 5 6 7 8 9 @@ -990,29 +1085,35 @@ Expected Result 91.44 254 99.9998 +``` + +## `test26.bas` -test26.bas -========== MAT READ -Test File ---------- +### Test File + +```basic dim a(3,3) data 5,5,5,8,8,8,3,3 mat read a(2,3) mat print a +``` -Expected Result ---------------- +### Expected Result + +``` 5 5 5 8 8 8 +``` + +## `test27.bas` -test27.bas -========== Matrix inversion -Test File ---------- +### Test File + +```basic data 1,2,3,4 mat read a(2,2) mat print a @@ -1020,81 +1121,99 @@ mat b=inv(a) mat print b mat c=a*b mat print c +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 4 -2 1 1.5 -0.5 1 0 0 1 +``` -test28.bas -========== -TDL BASIC FNRETURN/FNEND +## `test28.bas` -Test File ---------- +TDL BASIC `FNRETURN`/`FNEND` + +### Test File + +```basic def fnfac(n) if n=1 then fnreturn 1 fnend n*fnfac(n-1) print fnfac(10) +``` -Expected Result ---------------- +### Expected Result + +``` 3628800 +``` + +## `test29.bas` -test29.bas -========== TDL INSTR -Test File ---------- +### Test File + +```basic print instr("123456789","456");" = 4?" print INSTR("123456789","654");" = 0?" print INSTR("1234512345","34");" = 3?" print INSTR("1234512345","34",6);" = 8?" print INSTR("1234512345","34",6,2);" = 0?" print INSTR("1234512345","34",6,4);" = 8?" +``` -Expected Result ---------------- +### Expected Result + +``` 4 = 4? 0 = 0? 3 = 3? 8 = 8? 0 = 0? 8 = 8? +``` + +## `test30.bas` -test30.bas -========== Type mismatch check -Test File ---------- +### Test File + +```basic print 1+"a" +``` -Expected Result ---------------- +### Expected Result + +``` Error: Invalid binary operand at: end of program +``` + +## `test31.bas` -test31.bas -========== PRINT default format -Test File ---------- +### Test File + +```basic 10 for i=-8 to 8 20 x=1+1/3 : y=1 : j=i 30 for j=i to -1 : x=x/10 : y=y/10 : next 40 for j=i to 1 step -1 : x=x*10 : y=y*10 : next 50 print x,y 60 next +``` -Expected Result ---------------- +### Expected Result + +``` 0.0000000 0.0000000 0.0000001 0.0000001 0.0000013 0.0000010 @@ -1112,18 +1231,20 @@ Expected Result 1333333 1000000 13333333.3333333 10000000.0000000 133333333.3333333 100000000.0000000 +``` -Notes ------ - Output would differ on other platforms NttX does not use scientific - notation in floating point output. +### Notes -test032.bas -========== -SUB routines +Output would differ on other platforms NttX does not use scientific notation in +floating point output. -Test File ---------- +## `test32.bas` + +`SUB` routines + +### Test File + +```basic PUTS("abc") END @@ -1131,17 +1252,21 @@ SUB PUTS(s$) FOR i=1 to LEN(s$) : print mid$(s$,i,1); : NEXT PRINT END SUB +``` -Expected Result ---------------- +### Expected Result + +``` abc +``` -test33.bas -========== -OPEN FOR BINARY +## `test33.bas` -Test File ---------- +`OPEN FOR BINARY` + +### Test File + +```basic open "/tmp/test.out" for binary as 1 put 1,1,"xy" put 1,3,"z!" @@ -1158,25 +1283,28 @@ print s$ print x print n% kill "/tmp/test.out" +``` -Expected Result ---------------- +### Expected Result + +``` xyz! 0.333333 9999 +``` -Notes ------ - The logic in this test will fail if there is no writable file system - mount at /tmp. +### Notes +The logic in this test will fail if there is no writable file system mount at +`/tmp`. -test34.bas -========== -OPTION BASE +## `test34.bas` -Test File ---------- +`OPTION BASE` + +### Test File + +```basic option base 3 dim a(3,5) a(3,3)=1 @@ -1194,22 +1322,26 @@ print a(3,3) print a(3,5) print b(-2,-2) print b(-1,2) +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 1 2 10 20 +``` + +## `test35.bas` -test35.bas -========== Real to integer conversion -Test File ---------- +### Test File + +```basic a%=1.2 print a% a%=1.7 @@ -1218,20 +1350,24 @@ a%=-0.2 print a% a%=-0.7 print a% +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 0 -1 +``` -test36.bas -========== -OPEN file locking +## `test36.bas` -Test File ---------- +`OPEN` file locking + +### Test File + +```basic on error goto 10 print "opening file" open "/tmp/test.out" for output lock write as #1 @@ -1239,52 +1375,64 @@ print "open succeeded" if command$<>"enough" then shell "sh ./test/runbas test.bas enough" end 10 print "open failed" +``` -Expected Result ---------------- +### Expected Result + +``` opening file open succeeded opening file open failed +``` + +### Notes -Notes ------ 1. The logic in this test will fail opening the test.out file if there is no - writable file system mount at /tmp. + writable file system mount at `/tmp`. 2. This test will still currently fail when try to fork the shell because - support for that feature is not implemented. The following error message + support for that feature is not implemented. The following error message should be received: -Error: Forking child process failed (Unknown error) in line 5 at: -if command$<>"enough" then shell "sh ./test/runbas test.bas enough" - ^ + ``` + Error: Forking child process failed (Unknown error) in line 5 at: + if command$<>"enough" then shell "sh ./test/runbas test.bas enough" + ^ + ``` -test37.bas -========== -LINE INPUT reaching EOF +## `test37.bas` -Test File ---------- +`LINE INPUT` reaching `EOF` + +### Test File + +```basic 10 open "i",1,"/mnt/romfs/test37.dat" 20 while not eof(1) 30 line input #1,a$ 40 if a$="abc" then print a$; else print "def" 50 wend +``` -Data file (/mnt/romfs/test37.dat) -------------------------------- +## Data file (`/mnt/romfs/test37.dat`) + +``` abc +``` -Result ------- +## Result + +``` abc +``` -test38.bas -========== -MAT REDIM +## `test38.bas` -Test File ---------- +`MAT REDIM` + +### Test File + +```basic dim x(10) mat read x mat print x @@ -1293,9 +1441,11 @@ mat print x mat redim x(12) mat print x data 1,2,3,4,5,6,7,8,9,10 +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 @@ -1325,13 +1475,15 @@ Expected Result 0 0 0 +``` + +## `test39.bas` -test39.bas -========== Nested function and procedure calls -Test File ---------- +### Test File + +```basic def proc_a(x) print fn_b(1,x) end proc @@ -1343,33 +1495,41 @@ def fn_c(b) = b+3 proc_a(2) +``` -Expected Result ---------------- +### Expected Result + +``` 6 +``` -test40.bas -========== -IMAGE +## `test40.bas` -Test File ---------- +`IMAGE` + +### Test File + +```basic d=3.1 print using "#.#";d print using 10;d 10 image #.## +``` -Expected Result ---------------- +### Expected Result + +``` 3.1 3.10 +``` -test41.bas -========== -EXIT FUNCTION +## `test41.bas` -Test File ---------- +`EXIT FUNCTION` + +### Test File + +```basic function f(c) print "f running" if (c) then f=42 : exit function @@ -1378,20 +1538,24 @@ end function print f(0) print f(1) +``` -Expected Result ---------------- +### Expected Result + +``` f running 43 f running 42 +``` + +## `test42.bas` -test42.bas -========== Arithmetic -Test File ---------- +### Test File + +```basic 10 print 4.7\3 20 print -2.3\1 30 print int(-2.3) @@ -1400,9 +1564,11 @@ Test File 60 print fix(2.3) 70 print fp(-2.3) 80 print fp(2.3) +``` -Expected Result ---------------- +### Expected Result + +``` 1 -2 -3 @@ -1411,13 +1577,15 @@ Expected Result 2 -0.3 0.3 +``` + +## `test43.bas` -test43.bas -========== Matrix multiplication size checks -Test File ---------- +### Test File + +```basic DIM a(3,3),b(3,1),c(3,3) MAT READ a MAT READ b @@ -1433,22 +1601,26 @@ MAT READ a MAT READ b MAT c=a*b MAT PRINT c +``` -Expected Result ---------------- +### Expected Result + +``` 17 47 77 Error: Dimension mismatch in line 14 at: mat c=a*b ^ +``` -test44.bas -========== -DELETE +## `test44.bas` -Test File ---------- +`DELETE` + +### Test File + +```basic 10 print 10 20 print 20 30 print 30 @@ -1456,27 +1628,33 @@ Test File 50 print 50 60 print 60 70 print 70 +``` -Usage ------ +## Usage + +```basic load "test.bas" delete -20 delete 60- delete 30-40 delete 15 list +``` -Expected Result ---------------- +### Expected Result + +``` Error: No such line at: 15 50 print 50 +``` -test45.bas -========== -MID$ on left side +## `test45.bas` -Test File ---------- +`MID$` on left side + +### Test File + +```basic 10 mid$(a$,6,4) = "ABCD" 20 print a$ 30 a$="0123456789" @@ -1485,31 +1663,39 @@ Test File 60 a$="0123456789" 70 let mid$(a$,6,4) = "ABCD" 80 print a$ +``` -Expected Result ---------------- +### Expected Result + +``` 01234ABCD9 01234ABCD9 +``` -test46.bas -========== -END used without program +## `test46.bas` -Test File ---------- +`END` used without program + +### Test File + +```basic for i=1 to 10:print i;:next i:end +``` -Expected Result ---------------- +### Expected Result + +``` 1 2 3 4 5 6 7 8 9 10 +``` -test47.bas -========== -MAT WRITE +## `test47.bas` -Test File ---------- +`MAT WRITE` + +### Test File + +```basic dim a(3,4) for i=0 to 3 for j=0 to 4 @@ -1519,9 +1705,11 @@ for i=0 to 3 print next mat write a +``` -Expected Result ---------------- +### Expected Result + +``` 0 1 2 3 4 10 11 12 13 14 20 21 22 23 24 @@ -1529,13 +1717,15 @@ Expected Result 11,12,13,14 21,22,23,24 31,32,33,34 +``` + +## `test48.bas` -test48.bas -========== Multi assignment -Test File ---------- +### Test File + +```basic a,b = 10 print a,b dim c(10) @@ -1543,19 +1733,23 @@ a,c(a) = 2 print a,c(2),c(10) a$,b$="test" print a$,b$ +``` -Expected Result ---------------- +### Expected Result + +``` 10 10 2 0 2 test test +``` + +## `test49.bas` -test49.bas -========== Matrix determinant -Test File ---------- +### Test File + +```basic width 120 dim a(7,7),b(7,7) mat read a @@ -1571,9 +1765,11 @@ data 66,72,71,38,40,27,69 mat b=inv(a) mat print b print det +``` -Expected Result ---------------- +### Expected Result + +``` 58 71 67 36 35 19 60 50 71 71 56 45 20 52 64 40 84 50 51 43 69 @@ -1593,19 +1789,20 @@ Expected Result -9.636079e+07 -320208 537452 -2323663 1.135493e+07 -3.019649e+07 9.650995e+07 1 +``` -Notes ------ - Output will differ because NuttX does not use scientific notation in - output. Some minor rounding differences may also be expected. +### Notes +Output will differ because NuttX does not use scientific notation in output. +Some minor rounding differences may also be expected. -test50.bas -========== -Min and max function +## `test50.bas` -Test File ---------- +`min` and `max` function + +### Test File + +```basic print min(1,2) print min(2,1) print min(-0.3,0.3) @@ -1614,9 +1811,11 @@ print max(1,2) print max(2,1) print max(-0.3,0.3) print max(-0.3,4) +``` -Expected Result ---------------- +### Expected Result + +``` 1 1 -0.3 @@ -1625,42 +1824,53 @@ Expected Result 2 0.3 4 +``` + +## `test51.bas` -test51.bas -========== Print items -Test File ---------- +### Test File + +```basic PRINT "Line 1";TAB(78);1.23456789 +``` -Expected Result ---------------- +### Expected Result + +``` Line 1 1.234568 +``` -test52.bas -========== -MAT INPUT +## `test52.bas` -Test File ---------- +`MAT INPUT` + +### Test File + +```basic dim a(2,2) mat input a mat print a mat input a mat print a +``` -Test File ---------- +### Test File + +```basic 1,2,3,4,5 1 3,4 +``` -Expected Result ---------------- +### Expected Result + +``` ? 1 2 3 4 ? ? 1 0 3 4 +``` diff --git a/examples/camera/README.md b/examples/camera/README.md index a2d123522..42909dae8 100644 --- a/examples/camera/README.md +++ b/examples/camera/README.md @@ -1,39 +1,42 @@ -examples/camera -^^^^^^^^^^^^^^^ +# Examples / `camera` Camera Snapshot - This sample is implemented as 'camera' command on NuttX Shell. - The synopsys of the command is as below. +This sample is implemented as `camera` command on NuttX Shell. The synopsys of +the command is as below. - nsh> camera ([-jpg]) ([capture num]) +``` +nsh> camera ([-jpg]) ([capture num]) - -jpg : this option is set for storing JPEG file into a strage. - : If this option isn't set capturing raw YUV422 data in a file. - : raw YUV422 is default. + -jpg : this option is set for storing JPEG file into a strage. + : If this option isn't set capturing raw YUV422 data in a file. + : raw YUV422 is default. - capture num : this option instructs number of taking pictures. - : 10 is default. - Storage will be selected automatically based on the available storage option. + capture num : this option instructs number of taking pictures. + : 10 is default. +``` - Execution example: +Storage will be selected automatically based on the available storage option. - nsh> camera - nximage_listener: Connected - nximage_initialize: Screen resolution (320,240) - Take 10 pictures as YUV file in /mnt/sd0 after 5000 mili-seconds. - After finishing taking pictures, this app will be finished after 10000 mili-seconds. - Expier time is pasted. - Start captureing... - FILENAME:/mnt/sd0/VIDEO001.YUV - FILENAME:/mnt/sd0/VIDEO002.YUV - FILENAME:/mnt/sd0/VIDEO003.YUV - FILENAME:/mnt/sd0/VIDEO004.YUV - FILENAME:/mnt/sd0/VIDEO005.YUV - FILENAME:/mnt/sd0/VIDEO006.YUV - FILENAME:/mnt/sd0/VIDEO007.YUV - FILENAME:/mnt/sd0/VIDEO008.YUV - FILENAME:/mnt/sd0/VIDEO009.YUV - FILENAME:/mnt/sd0/VIDEO010.YUV - Finished captureing... - Expier time is pasted. - nximage_listener: Lost server connection: 117 +Execution example: +``` +nsh> camera +nximage_listener: Connected +nximage_initialize: Screen resolution (320,240) +Take 10 pictures as YUV file in /mnt/sd0 after 5000 mili-seconds. +After finishing taking pictures, this app will be finished after 10000 mili-seconds. +Expier time is pasted. +Start capturing... +FILENAME:/mnt/sd0/VIDEO001.YUV +FILENAME:/mnt/sd0/VIDEO002.YUV +FILENAME:/mnt/sd0/VIDEO003.YUV +FILENAME:/mnt/sd0/VIDEO004.YUV +FILENAME:/mnt/sd0/VIDEO005.YUV +FILENAME:/mnt/sd0/VIDEO006.YUV +FILENAME:/mnt/sd0/VIDEO007.YUV +FILENAME:/mnt/sd0/VIDEO008.YUV +FILENAME:/mnt/sd0/VIDEO009.YUV +FILENAME:/mnt/sd0/VIDEO010.YUV +Finished capturing... +Expier time is pasted. +nximage_listener: Lost server connection: 117 +``` diff --git a/examples/camera/camera_main.c b/examples/camera/camera_main.c index caa6622f9..0da36deae 100644 --- a/examples/camera/camera_main.c +++ b/examples/camera/camera_main.c @@ -552,7 +552,7 @@ int main(int argc, FAR char *argv[]) while (1) { - printf("Start captureing...\n"); + printf("Start capturing...\n"); ret = start_stillcapture(v_fd, capture_type); if (ret != OK) { @@ -587,7 +587,7 @@ int main(int argc, FAR char *argv[]) } RESET_INITIAL_TIME(then); - printf("Finished captureing...\n"); + printf("Finished capturing...\n"); } exit_this_app: diff --git a/examples/flash_test/README.md b/examples/flash_test/README.md index 667903775..9fb2fdf3f 100644 --- a/examples/flash_test/README.md +++ b/examples/flash_test/README.md @@ -1,18 +1,23 @@ +# Examples / `flash_test` SMART Flash Device Test -Install Program -=============== +``` +Author: Ken Pettit + Date: April 24, 2013 +``` - Source: NuttX - Author: Ken Pettit - Date: April 24, 2013 +This application performs a SMART flash block device test. This test performs a +sector allocate, read, write, free and garbage collection test on a SMART MTD +block device. This test can be built only as an NSH command -This application performs a SMART flash block device test. This test performs a sector allocate, read, write, free and garbage collection test on a SMART MTD block device. This test can be built only as an NSH command - -NOTE: This test uses internal OS interfaces and so is not available in the NUTTX kernel build +**Note**: This test uses internal OS interfaces and so is not available in the +NUTTX kernel build +``` Usage: - flash_test mtdblock_device + + flash_test mtdblock_device Additional options: - --force to replace existing installation + --force to replace existing installation +``` diff --git a/examples/flowc/README.md b/examples/flowc/README.md index 051bf3cd2..6f3d23280 100644 --- a/examples/flowc/README.md +++ b/examples/flowc/README.md @@ -1,15 +1,17 @@ +# Examples / `flowc` + General Usage Instructions: -1. The receiver side enter, start the receiver program. The receiver - is now waiting to receive data on the configured serial port +1. The receiver side enter, start the receiver program. The receiver is now + waiting to receive data on the configured serial port. +2. On the sender side start the sender program. This will send data to the + receiver which will verify that no data is lost. -2. On the sender side start the sender program. This will send data to - the receiver which will verify that no data is lost. +On Linux, you can alternatively do: - On Linux, you can alternatively do: +```bash +$ stty -F /dev/ttyACM0 crtscts +$ cat testdata.dat >/dev/ttyACM0 +``` - $ stty -F /dev/ttyACM0 crtscts - $ cat testdata.dat >/dev/ttyACM0 - - where you need to replace /dev/ttyACM0 with your selected serial - device. +where you need to replace `/dev/ttyACM0` with your selected serial device. diff --git a/examples/json/README.md b/examples/json/README.md index 45682e02f..9e430c7ab 100644 --- a/examples/json/README.md +++ b/examples/json/README.md @@ -1,132 +1,155 @@ -apps/examples/json/README.txt -============================= +# Examples / `json` cJSON JSON Parser This directory contains logic taken from the cJSON project: http://sourceforge.net/projects/cjson/ -This corresponds to SVN revision r42 (with lots of changes for NuttX coding -standards). As of r42, the SVN repository was last updated on 2011-10-10 -so I presume that the code is stable and there is no risk of maintaining -duplicate logic in the NuttX repository. +This corresponds to SVN revision `r42` (with lots of changes for NuttX coding +standards). As of `r42`, the SVN repository was last updated on `2011-10-10` so +I presume that the code is stable and there is no risk of maintaining duplicate +logic in the NuttX repository. -Contents -======== +# Contents - o License - o Welcome to cJSON +- License +- Welcome to cJSON -License -======= +# License - Copyright (c) 2009 Dave Gamble +Copyright (c) 2009 Dave Gamble - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -Welcome to cJSON -================ +# Welcome to cJSON -cJSON aims to be the dumbest possible parser that you can get your job done with. -It's a single file of C, and a single header file. +cJSON aims to be the dumbest possible parser that you can get your job done +with. It's a single file of C, and a single header file. -JSON is described best here: http://www.json.org/ -It's like XML, but fat-free. You use it to move data around, store things, or just -generally represent your program's state. +JSON is described best here: http://www.json.org/ It's like XML, but fat-free. +You use it to move data around, store things, or just generally represent your +program's state. -First up, how do I build? -Add cJSON.c to your project, and put cJSON.h somewhere in the header search path. -For example, to build the test app: +First up, how do I build? Add `cJSON.c` to your project, and put `cJSON.h` +somewhere in the header search path. For example, to build the test app: +```bash gcc cJSON.c test.c -o test -lm ./test +``` -As a library, cJSON exists to take away as much legwork as it can, but not get in your way. -As a point of pragmatism (i.e. ignoring the truth), I'm going to say that you can use it -in one of two modes: Auto and Manual. Let's have a quick run-through. +As a library, cJSON exists to take away as much legwork as it can, but not get +in your way. As a point of pragmatism (i.e. ignoring the truth), I'm going to +say that you can use it in one of two modes: Auto and Manual. Let's have a quick +run-through. -I lifted some JSON from this page: http://www.json.org/fatfree.html -That page inspired me to write cJSON, which is a parser that tries to share the same +I lifted some JSON from this page: http://www.json.org/fatfree.html That page +inspired me to write cJSON, which is a parser that tries to share the same philosophy as JSON itself. Simple, dumb, out of the way. Some JSON: -{ - "name": "Jack (\"Bee\") Nimble", - "format": { - "type": "rect", - "width": 1920, - "height": 1080, - "interlace": false, - "frame rate": 24 - } -} -Assume that you got this from a file, a webserver, or magic JSON elves, whatever, -you have a char * to it. Everything is a cJSON struct. +```json +{ + "name": "Jack (\"Bee\") Nimble", + "format": { + "type": "rect", + "width": 1920, + "height": 1080, + "interlace": false, + "frame rate": 24 + } +} +``` + +Assume that you got this from a file, a webserver, or magic JSON elves, +whatever, you have a `char *` to it. Everything is a cJSON struct. + Get it parsed: - cJSON *root = cJSON_Parse(my_json_string); + +```c +cJSON *root = cJSON_Parse(my_json_string); +``` This is an object. We're in C. We don't have objects. But we do have structs. + What's the framerate? - cJSON *format = cJSON_GetObjectItem(root,"format"); - int framerate = cJSON_GetObjectItem(format,"frame rate")->valueint; +```c +cJSON *format = cJSON_GetObjectItem(root,"format"); +int framerate = cJSON_GetObjectItem(format,"frame rate")->valueint; +``` Want to change the framerate? - cJSON_GetObjectItem(format,"frame rate")->valueint=25; + +```c +cJSON_GetObjectItem(format,"frame rate")->valueint = 25; +``` Back to disk? - char *rendered=cJSON_Print(root); + +```c +char *rendered = cJSON_Print(root); +``` Finished? Delete the root (this takes care of everything else). - cJSON_Delete(root); -That's AUTO mode. If you're going to use Auto mode, you really ought to check pointers -before you dereference them. If you want to see how you'd build this struct in code? - cJSON *root,*fmt; - root=cJSON_CreateObject(); - cJSON_AddItemToObject(root, "name", cJSON_CreateString("Jack (\"Bee\") Nimble")); - cJSON_AddItemToObject(root, "format", fmt=cJSON_CreateObject()); - cJSON_AddStringToObject(fmt,"type", "rect"); - cJSON_AddNumberToObject(fmt,"width", 1920); - cJSON_AddNumberToObject(fmt,"height", 1080); - cJSON_AddFalseToObject (fmt,"interlace"); - cJSON_AddNumberToObject(fmt,"frame rate", 24); +```c +cJSON_Delete(root); +``` -Hopefully we can agree that's not a lot of code? There's no overhead, no unnecessary setup. -Look at test.c for a bunch of nice examples, mostly all ripped off the json.org site, and -a few from elsewhere. +That's AUTO mode. If you're going to use Auto mode, you really ought to check +pointers before you dereference them. If you want to see how you'd build this +struct in code? -What about manual mode? First up you need some detail. -Let's cover how the cJSON objects represent the JSON data. -cJSON doesn't distinguish arrays from objects in handling; just type. +```c +cJSON *root,*fmt; +root = cJSON_CreateObject(); + +cJSON_AddItemToObject(root, "name", cJSON_CreateString("Jack (\"Bee\") Nimble")); +cJSON_AddItemToObject(root, "format", fmt = cJSON_CreateObject()); +cJSON_AddStringToObject(fmt,"type", "rect"); +cJSON_AddNumberToObject(fmt,"width", 1920); +cJSON_AddNumberToObject(fmt,"height", 1080); +cJSON_AddFalseToObject (fmt,"interlace"); +cJSON_AddNumberToObject(fmt,"frame rate", 24); +``` + +Hopefully we can agree that's not a lot of code? There's no overhead, no +unnecessary setup. Look at test.c for a bunch of nice examples, mostly all +ripped off the json.org site, and a few from elsewhere. + +What about manual mode? First up you need some detail. +Let's cover how the cJSON objects represent the JSON data. +cJSON doesn't distinguish arrays from objects in handling; just type. Each cJSON has, potentially, a child, siblings, value, a name. -The root object has: Object Type and a Child -The Child has name "name", with value "Jack ("Bee") Nimble", and a sibling: -Sibling has type Object, name "format", and a child. -That child has type String, name "type", value "rect", and a sibling: -Sibling has type Number, name "width", value 1920, and a sibling: -Sibling has type Number, name "height", value 1080, and a sibling: -Sibling hs type False, name "interlace", and a sibling: +The root object has: Object Type and a Child +The Child has name "name", with value "Jack ("Bee") Nimble", and a sibling: +Sibling has type Object, name "format", and a child. +That child has type String, name "type", value "rect", and a sibling: +Sibling has type Number, name "width", value 1920, and a sibling: +Sibling has type Number, name "height", value 1080, and a sibling: +Sibling hs type False, name "interlace", and a sibling: Sibling has type Number, name "frame rate", value 24 Here's the structure: + +```c typedef struct cJSON { struct cJSON *next,*prev; struct cJSON *child; @@ -139,82 +162,95 @@ typedef struct cJSON { char *string; } cJSON; +``` By default all values are 0 unless set by virtue of being meaningful. next/prev is a doubly linked list of siblings. next takes you to your sibling, -prev takes you back from your sibling to you. -Only objects and arrays have a "child", and it's the head of the doubly linked list. -A "child" entry will have prev==0, but next potentially points on. The last sibling has next=0. -The type expresses Null/True/False/Number/String/Array/Object, all of which are #defined in -cJSON.h +prev takes you back from your sibling to you. Only objects and arrays have a +"child", and it's the head of the doubly linked list. A "child" entry will have +`prev==0`, but next potentially points on. The last sibling has `next=0`. The +type expresses Null/True/False/Number/String/Array/Object, all of which are +`#define`d in `cJSON.h`. -A Number has valueint and valuedouble. If you're expecting an int, read valueint, if not read -valuedouble. +A Number has `valueint` and `valuedouble`. If you're expecting an `int`, read +`valueint`, if not read `valuedouble`. -Any entry which is in the linked list which is the child of an object will have a "string" -which is the "name" of the entry. When I said "name" in the above example, that's "string". -"string" is the JSON name for the 'variable name' if you will. +Any entry which is in the linked list which is the child of an object will have +a "string" which is the "name" of the entry. When I said "name" in the above +example, that's "string". "string" is the JSON name for the 'variable name' if +you will. -Now you can trivially walk the lists, recursively, and parse as you please. -You can invoke cJSON_Parse to get cJSON to parse for you, and then you can take -the root object, and traverse the structure (which is, formally, an N-tree), -and tokenise as you please. If you wanted to build a callback style parser, this is how -you'd do it (just an example, since these things are very specific): +Now you can trivially walk the lists, recursively, and parse as you please. You +can invoke `cJSON_Parse` to get cJSON to parse for you, and then you can take +the root object, and traverse the structure (which is, formally, an N-tree), and +tokenise as you please. If you wanted to build a callback style parser, this is +how you'd do it (just an example, since these things are very specific): -void parse_and_callback(cJSON *item,const char *prefix) +```c +void parse_and_callback(cJSON *item, const char *prefix) { while (item) { - char *newprefix=malloc(strlen(prefix)+strlen(item->name)+2); - sprintf(newprefix,"%s/%s",prefix,item->name); - int dorecurse=callback(newprefix, item->type, item); - if (item->child && dorecurse) parse_and_callback(item->child,newprefix); - item=item->next; + char *newprefix = malloc(strlen(prefix) + strlen(item->name) + 2); + sprintf(newprefix, "%s/%s", prefix, item->name); + int dorecurse = callback(newprefix, item->type, item); + if (item->child && dorecurse) parse_and_callback(item->child, newprefix); + item = item->next; free(newprefix); } } +``` -The prefix process will build you a separated list, to simplify your callback handling. -The 'dorecurse' flag would let the callback decide to handle sub-arrays on it's own, or -let you invoke it per-item. For the item above, your callback might look like this: +The prefix process will build you a separated list, to simplify your callback +handling. The `dorecurse` flag would let the callback decide to handle +sub-arrays on it's own, or let you invoke it per-item. For the item above, your +callback might look like this: -int callback(const char *name,int type,cJSON *item) +```c +int callback(const char *name,int type, cJSON *item) { - if (!strcmp(name,"name")) { /* populate name */ } - else if (!strcmp(name,"format/type") { /* handle "rect" */ } - else if (!strcmp(name,"format/width") { /* 800 */ } - else if (!strcmp(name,"format/height") { /* 600 */ } - else if (!strcmp(name,"format/interlace") { /* false */ } - else if (!strcmp(name,"format/frame rate") { /* 24 */ } + if (!strcmp(name,"name")) { /* populate name */ } + else if (!strcmp(name,"format/type") { /* handle "rect" */ } + else if (!strcmp(name,"format/width") { /* 800 */ } + else if (!strcmp(name,"format/height") { /* 600 */ } + else if (!strcmp(name,"format/interlace") { /* false */ } + else if (!strcmp(name,"format/frame rate") { /* 24 */ } return 1; } +``` Alternatively, you might like to parse iteratively. + You'd use: +```c void parse_object(cJSON *item) { - int i; for (i=0;ichild; + cJSON *subitem = item->child; + while (subitem) { // handle subitem if (subitem->child) parse_object(subitem->child); - subitem=subitem->next; + subitem = subitem->next; } } +``` Of course, this should look familiar, since this is just a stripped-down version of the callback-parser. @@ -222,11 +258,12 @@ of the callback-parser. This should cover most uses you'll find for parsing. The rest should be possible to infer.. and if in doubt, read the source! There's not a lot of it! ;) -In terms of constructing JSON data, the example code above is the right way to do it. -You can, of course, hand your sub-objects to other functions to populate. -Also, if you find a use for it, you can manually build the objects. -For instance, suppose you wanted to build an array of objects? +In terms of constructing JSON data, the example code above is the right way to +do it. You can, of course, hand your sub-objects to other functions to populate. +Also, if you find a use for it, you can manually build the objects. For +instance, suppose you wanted to build an array of objects? +```c cJSON *objects[24]; cJSON *Create_array_of_anything(cJSON **items,int num) @@ -240,19 +277,21 @@ cJSON *Create_array_of_anything(cJSON **items,int num) } return root; } +``` -and simply: Create_array_of_anything(objects,24); +and simply: `Create_array_of_anything(objects,24)`; -cJSON doesn't make any assumptions about what order you create things in. -You can attach the objects, as above, and later add children to each -of those objects. +cJSON doesn't make any assumptions about what order you create things in. You +can attach the objects, as above, and later add children to each of those +objects. -As soon as you call cJSON_Print, it renders the structure to text. +As soon as you call `cJSON_Print`, it renders the structure to text. The test.c code shows how to handle a bunch of typical cases. If you uncomment the code, it'll load, parse and print a bunch of test files, also from json.org, -which are more complex than I'd care to try and stash into a const char array[]. +which are more complex than I'd care to try and stash into a `const char +array[]`. Enjoy cJSON! -- Dave Gamble, Aug 2009 +_Dave Gamble, Aug 2009_ diff --git a/examples/pdcurses/README.md b/examples/pdcurses/README.md index b7dd0e4c6..2bce03f9c 100644 --- a/examples/pdcurses/README.md +++ b/examples/pdcurses/README.md @@ -1,21 +1,17 @@ -PDCurses Demos -============== +# Examples / `pdcurses` PDCurses Demos -This directory contains demonstration programs to show and test the -capabilities of pdcurses libraries. Some of them predate PDCurses, -PCcurses or even pcurses/ncurses. Although some PDCurses-specific code -has been added, all programs remain portable to other implementations -(at a minimum, to ncurses). +This directory contains demonstration programs to show and test the capabilities +of `pdcurses` libraries. Some of them predate PDCurses, PCcurses or even +`pcurses`/`ncurses`. Although some PDCurses-specific code has been added, all +programs remain portable to other implementations (at a minimum, to `ncurses`). -Building --------- +## Building The demos are built by the platform-specific makefiles, in the platform -directories. There are no dependencies besides curses and the standard -C library, and no configuration is needed. +directories. There are no dependencies besides curses and the standard C +library, and no configuration is needed. -Distribution Status -------------------- +## Distribution Status -Public Domain, except for rain_main.c and worm_main.c, which are under -the ncurses license (MIT-like). +Public Domain, except for `rain_main.c` and `worm_main.c`, which are under the +ncurses license (MIT-like). diff --git a/examples/tcpblaster/README.md b/examples/tcpblaster/README.md index 86ff00ac6..4b699a782 100644 --- a/examples/tcpblaster/README.md +++ b/examples/tcpblaster/README.md @@ -1,40 +1,43 @@ -tcpblaster Performance Test Example -=================================== +# Examples / `tcpblaster` TCP Performance Test -To set up, do `make menuconfig` and select the Apps > Examples > tcpblaster. By default, nuttx will the be the client -which sends data; and the host computer (Linux, macOS, or Windows) will be the server. +To set up, do `make menuconfig` and select the _Apps_ → _Examples_ → +_tcpblaster_. By default, nuttx will the be the client which sends data; and the +host computer (Linux, macOS, or Windows) will be the server. -Set up networking so the nuttx computer can ping the host, and the host can ping nuttx. Now you are ready to run the -test. +Set up networking so the nuttx computer can ping the host, and the host can ping +nuttx. Now you are ready to run the test. On host: - $ ./tcpserver - Binding to IPv4 Address: 00000000 - server: Accepting connections on port 5471 +``` +$ ./tcpserver +Binding to IPv4 Address: 00000000 +server: Accepting connections on port 5471 +``` On nuttx: - nsh> tcpclient - Connecting to IPv4 Address: 0100000a - client: Connected - [2014-07-31 00:16:15.000] 0: Sent 200 4096-byte buffers: 800.0 KB (avg 4.0 KB) in 0.18 seconds ( 4444.4 KB/second) +``` +nsh> tcpclient +Connecting to IPv4 Address: 0100000a +client: Connected +[2014-07-31 00:16:15.000] 0: Sent 200 4096-byte buffers: 800.0 KB (avg 4.0 KB) in 0.18 seconds ( 4444.4 KB/second) +``` Now on the host you should see something like: - $ ./tcpserver - Binding to IPv4 Address: 00000000 - server: Accepting connections on port 5471 - server: Connection accepted -- receiving - [2020-02-22 16:17:07.000] 0: Received 200 buffers: 502.9 KB (buffer average size: 2.5 KB) in 0.12 seconds ( 4194.8 KB/second) - [2020-02-22 16:17:07.000] 1: Received 200 buffers: 393.1 KB (buffer average size: 2.0 KB) in 0.09 seconds ( 4299.4 KB/second) - - -This will tell you the link speed in KB/sec – kilobytes per second. If you want kilobits, multiply by 8. - -You can use the `make menuconfig` to reverse the setup, and have nuttx be the server, and the host be the client. If you -do that, start the server first (nuttx), then start the client (host). - - +``` +$ ./tcpserver +Binding to IPv4 Address: 00000000 +server: Accepting connections on port 5471 +server: Connection accepted -- receiving +[2020-02-22 16:17:07.000] 0: Received 200 buffers: 502.9 KB (buffer average size: 2.5 KB) in 0.12 seconds ( 4194.8 KB/second) +[2020-02-22 16:17:07.000] 1: Received 200 buffers: 393.1 KB (buffer average size: 2.0 KB) in 0.09 seconds ( 4299.4 KB/second) +``` +This will tell you the link speed in KB/sec – kilobytes per second. If you want +kilobits, multiply by `8`. +You can use the `make menuconfig` to reverse the setup, and have nuttx be the +server, and the host be the client. If you do that, start the server first +(nuttx), then start the client (host). diff --git a/examples/telnetd/README.md b/examples/telnetd/README.md index bdba71d9a..28cd2e12e 100644 --- a/examples/telnetd/README.md +++ b/examples/telnetd/README.md @@ -1,8 +1,7 @@ -README.txt -^^^^^^^^^^ +# Examples / `telnetd` Telnet Daemon -This directory contains a functional port of the tiny uIP shell. In the -NuttX environment, the NuttShell (at apps/nshlib) supersedes this tiny -shell and also supports telnetd. +This directory contains a functional port of the tiny uIP shell. In the NuttX +environment, the NuttShell (at `apps/nshlib`) supersedes this tiny shell and +also supports telnetd. This example is retained here for reference purposes only. diff --git a/fsutils/inifile/README.md b/fsutils/inifile/README.md index e015ea2f2..86590cbcb 100644 --- a/fsutils/inifile/README.md +++ b/fsutils/inifile/README.md @@ -1,46 +1,42 @@ -README.txt -========== +# File System Utilities / `inifile` INI File -Syntax -====== +## Syntax - This directory contains a very simple INI file parser. An INI file consists - of a sequence of lines up to the end of file. A line may be one of the - following: +This directory contains a very simple INI file parser. An INI file consists of a +sequence of lines up to the end of file. A line may be one of the following: - 1) A blank line. +1. A blank line. - 2) A comment line. Any line beginning with ';' +2. A comment line. Any line beginning with `;` - 3) A section header. Definitions are divided into sections. Each - section begins with a line containing the section name enclosed in - square brackets. For example, "[section1]". The left bracket must - be the first character on the line. Section names are case - insensitive, i.e., "SECTION1" and "Section1" refer to the same - section. +3. A section header. Definitions are divided into sections. Each section begins + with a line containing the section name enclosed in square brackets. For + example, `[section1]`. The left bracket must be the first character on the + line. Section names are case insensitive, i.e., `SECTION1` and `Section1` + refer to the same section. - 4) Variable assignments. A variable assignment is a variable name - followed by the '=' sign and then the value of the variable. For - example, "A=B": "A" is the variable name; "B" is the variable value. - All variables following the section header belong in the section. +4. Variable assignments. A variable assignment is a variable name followed by + the `=` sign and then the value of the variable. For example, `A=B`: `A` is + the variable name; `B` is the variable value. All variables following the + section header belong in the section. - Variable names may be preceded with white space. Whitespace is not - permitted before the '=' sign. Variable names are case insensitive, - i.e., "A" and "a" refer to the same variable name. + Variable names may be preceded with white space. Whitespace is not permitted + before the `=` sign. Variable names are case insensitive, i.e., `A` and `a` + refer to the same variable name. - Variable values may be numeric (any base) or a string. The case of - string arguments is preserved. + Variable values may be numeric (any base) or a string. The case of string + arguments is preserved. -Programming Interfaces -====================== +## Programming Interfaces - See apps/include/fsutils/inifile.h for interfaces supported by the INI file parser. +See `apps/include/fsutils/inifile.h` for interfaces supported by the INI file +parser. -Test Program -============ +## Test Program - Below is a simple test program: +Below is a simple test program: +```c int main(int argc, char *argv[]) { INIHANDLE handle; @@ -123,9 +119,11 @@ int main(int argc, char *argv[]) inifile_uninitialize(handle); return 0; } +``` Test program output: +``` Section: section2 Variable: VAR5 String: 5 Section: section1 Variable: VAR2 String: 2 Section: section3 Variable: VAR3 String: OOPS @@ -143,3 +141,4 @@ Section: section2 Variable: VAR6 Value: 6 Section: section1 Variable: VAR42 String: 0 Section: section1 Variable: VAR2 Value: 2 Section: section2 Variable: VAR4 Value: 4 +``` diff --git a/gpsutils/README.md b/gpsutils/README.md index 548f83895..e05d9a1ea 100644 --- a/gpsutils/README.md +++ b/gpsutils/README.md @@ -1,12 +1,10 @@ -External Libraries -^^^^^^^^^^^^^^^^^^ +# `gpsutils` GPS Utilities - The apps/gpsutils directory is used to include libraries from external - projects that are not part of NuttX Applications, but are useful for NuttX - developers and users. +The `gpsutils` directory is used to include libraries from external projects +that are not part of NuttX Applications, but are useful for NuttX developers and +users. -gpsutils/minmea -^^^^^^^^^^^^^^^^^^ +## `minmea` GPS NMEA 0183 parser - MINMEA is a NMEA parser developed by Kosma Moczek. Kosma is also a NuttX - contributor. +MINMEA is a NMEA parser developed by Kosma Moczek. Kosma is also a NuttX +contributor. diff --git a/gpsutils/minmea/README.md b/gpsutils/minmea/README.md index f6e35ba71..c8ac5b583 100644 --- a/gpsutils/minmea/README.md +++ b/gpsutils/minmea/README.md @@ -1,4 +1,6 @@ -# minmea, a lightweight GPS NMEA 0183 parser library +# GPS Utilities / `minmea` GPS NMEA 0183 parser + +A lightweight GPS NMEA 0183 parser library [![Build Status](https://travis-ci.org/cloudyourcar/minmea.svg?branch=master)](https://travis-ci.org/cloudyourcar/minmea) @@ -29,32 +31,35 @@ Adding support for more sentences is trivial; see ``minmea.c`` source. ## Fractional number format -Internally, minmea stores fractional numbers as pairs of two integers: ``{value, scale}``. -For example, a value of ``"-123.456"`` would be parsed as ``{-123456, 1000}``. As this -format is quite unwieldy, minmea provides the following convenience functions for converting -to either fixed-point or floating-point format: +Internally, minmea stores fractional numbers as pairs of two integers: ``{value, +scale}``. For example, a value of ``"-123.456"`` would be parsed as ``{-123456, +1000}``. As this format is quite unwieldy, minmea provides the following +convenience functions for converting to either fixed-point or floating-point +format: * ``minmea_rescale({-123456, 1000}, 10) => -1235`` * ``minmea_float({-123456, 1000}) => -123.456`` -The compound type ``struct minmea_float`` uses ``int_least32_t`` internally. Therefore, -the coordinate precision is guaranteed to be at least ``[+-]DDDMM.MMMMM`` (five decimal digits) -or ±20cm LSB at the equator. +The compound type ``struct minmea_float`` uses ``int_least32_t`` internally. +Therefore, the coordinate precision is guaranteed to be at least +``[+-]DDDMM.MMMMM`` (five decimal digits) or ±20cm LSB at the equator. ## Coordinate format -NMEA uses the clunky ``DDMM.MMMM`` format which, honestly, is not good in the internet era. -Internally, minmea stores it as a fractional number (see above); for practical uses, -the value should be probably converted to the DD.DDDDD floating point format using the -following function: +NMEA uses the clunky ``DDMM.MMMM`` format which, honestly, is not good in the +internet era. Internally, minmea stores it as a fractional number (see above); +for practical uses, the value should be probably converted to the DD.DDDDD +floating point format using the following function: * ``minmea_tocoord({-375165, 100}) => -37.860832`` -The library doesn't perform this conversion automatically for the following reasons: +The library doesn't perform this conversion automatically for the following +reasons: * The conversion is not reversible. * It requires floating point hardware. -* The user might want to perform this conversion later on or retain the original values. +* The user might want to perform this conversion later on or retain the original + values. ## Example @@ -122,9 +127,9 @@ typing ``make``. ## Limitations * Only a handful of frames is supported right now. -* There's no support for omitting parts of the library from building. As - a workaround, use the ``-ffunction-sections -Wl,--gc-sections`` linker flags - (or equivalent) to remove the unused functions (parsers) from the final image. +* There's no support for omitting parts of the library from building. As a + workaround, use the ``-ffunction-sections -Wl,--gc-sections`` linker flags (or + equivalent) to remove the unused functions (parsers) from the final image. * Some systems lack ``timegm``. On these systems, the recommended course of action is to build with ``-Dtimegm=mktime`` which will work correctly as long the system runs in the default ``UTC`` timezone. Native Windows builds should @@ -138,8 +143,10 @@ Please write unit tests for any new functions you add - it's fun! ## Licensing Minmea is open source software; see ``COPYING`` for amusement. Email me if the -license bothers you and I'll happily re-license under anything else under the sun. +license bothers you and I'll happily re-license under anything else under the +sun. ## Author -Minmea was written by Kosma Moczek <kosma@cloudyourcar.com> at Cloud Your Car. +Minmea was written by Kosma Moczek <kosma@cloudyourcar.com> at Cloud Your +Car. diff --git a/graphics/lvgl/README.md b/graphics/lvgl/README.md index d2fc977ca..a3c846a8d 100644 --- a/graphics/lvgl/README.md +++ b/graphics/lvgl/README.md @@ -1,21 +1,23 @@ -# Usage +# Graphics / `lvgl` LVGL + +## Usage Import with `#include ` or `#include `. Upstream example ported to NuttX is present at `examples/lvgldemo`. LVGL can be used with framebuffer device. To find example boards with this -preconfigured, search for `CONFIG_GRAPHICS_LVGL=y` in `defconfig` files. -All of them have also `CONFIG_VIDEO_FB=y` present. +preconfigured, search for `CONFIG_GRAPHICS_LVGL=y` in `defconfig` files. All of +them have also `CONFIG_VIDEO_FB=y` present. -As a second option, LVGL can talk to a display driver and explicitly draw line by line. -For this case, there is no preconfigured board present. Go to _Porting_ section -of upstream documentation for more hints. +As a second option, LVGL can talk to a display driver and explicitly draw line +by line. For this case, there is no preconfigured board present. Go to _Porting_ +section of upstream documentation for more hints. -# Resources +## Resources -* [API documentation with examples](https://docs.lvgl.io/latest/en/html/index.html) -* [GitHub / LVGL / LVGL library](https://github.com/lvgl/lvgl) -* [GitHub / LVGL / Examples, tutorials, applications](https://github.com/lvgl/lv_examples) -* [GitHub / LVGL / Desktop simulator](https://github.com/lvgl/lv_sim_eclipse_sdl) -* [GitHub / LVGL / Web simulator](https://github.com/lvgl/lv_sim_emscripten) +- [API documentation with examples](https://docs.lvgl.io/latest/en/html/index.html) +- [GitHub / LVGL / LVGL library](https://github.com/lvgl/lvgl) +- [GitHub / LVGL / Examples, tutorials, applications](https://github.com/lvgl/lv_examples) +- [GitHub / LVGL / Desktop simulator](https://github.com/lvgl/lv_sim_eclipse_sdl) +- [GitHub / LVGL / Web simulator](https://github.com/lvgl/lv_sim_emscripten) diff --git a/graphics/nxwidgets/Doxygen/README.md b/graphics/nxwidgets/Doxygen/README.md index 26d76ce4b..dc38ed5da 100644 --- a/graphics/nxwidgets/Doxygen/README.md +++ b/graphics/nxwidgets/Doxygen/README.md @@ -1,64 +1,68 @@ -README -====== +# Graphics / `nxwidgets` NXWidgets / Doxygen This directory contains the documentation automatically generated by Doxygen. -Contents -======== +## Contents - o Installing the necessary packages in Ubuntu - o Generating documentation - o References +- Installing the necessary packages in Ubuntu +- Generating documentation +- References -Installing the necessary packages in Ubuntu -=========================================== +## Installing the Necessary Packages in Ubuntu 1. Install the following packages. - $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz + ```bash + $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz + ``` 2. (Optional) Install Doxygen from the latest sourcode. - The Ubuntu package is outdated. The newer the version of Doxygen, the better - the documentation looks. + The Ubuntu package is outdated. The newer the version of Doxygen, the better + the documentation looks. - Place yourself in some temporary folder where you can download the source, - and run [1]: + Place yourself in some temporary folder where you can download the source, + and run [1]: - $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn - $ cd doxygen-svn - $ ./configure - $ make - $ make install + ```bash + $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn + $ cd doxygen-svn + $ ./configure + $ make + $ make install + ``` -Generating documentation -======================== +## Generating Documentation Two ways described here: -1. Use the provided gendoc.sh script. +1. Use the provided `gendoc.sh` script. - trunk/NXWidgets/Doxygen/gendoc.sh + ```bash + trunk/NXWidgets/Doxygen/gendoc.sh + ``` - The script only needs the argument to the absolute path where to place the - generated documentation. I.e.: + The script only needs the argument to the absolute path where to place the + generated documentation. I.e.: - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ mkdir doc - $ ./gendoc.sh $PWD/doc + ```bash + $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ + $ mkdir doc + $ ./gendoc.sh $PWD/doc + ``` +2. Using the `Doxyfile` directly: -2. Using the Doxyfile directly: - - The file "Doxyfile" contains the configuration of the Doxygen settings - for the run, edit only if necessary. + The file `Doxyfile` contains the configuration of the Doxygen settings for + the run, edit only if necessary. To generate the documentation type: - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ doxygen Doxyfile + ```bash + $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ + $ doxygen Doxyfile + ``` -References -========== +## References [1] http://www.stack.nl/~dimitri/doxygen/download.html diff --git a/graphics/nxwidgets/README.md b/graphics/nxwidgets/README.md index a146b6040..5fc93f371 100644 --- a/graphics/nxwidgets/README.md +++ b/graphics/nxwidgets/README.md @@ -1,70 +1,68 @@ -NXWidgets -========= +# Graphics / `nxwidgets` NXWidgets In order to better support NuttX based platforms, a special graphical user -interface has been created called NXWidgets. NXWidgets is written in C++ -and integrates seamlessly with the NuttX NX graphics subsystem in order -to provide graphic objects, or "widgets," in the NX Graphics Subsystem +interface has been created called NXWidgets. NXWidgets is written in C++ and +integrates seamlessly with the NuttX NX graphics subsystem in order to provide +graphic objects, or _widgets_, in the NX Graphics Subsystem Some of the features of NXWidgets include: -o Conservative C++ +- Conservative C++ - NXWidgets is written entirely in C++ but using only selected “embedded - friendly” C++ constructs that are fully supported under NuttX. No - additional C++ support libraries are required. + NXWidgets is written entirely in C++ but using only selected _embedded + friendly_ C++ constructs that are fully supported under NuttX. No additional + C++ support libraries are required. -o NX Integration +- NX Integration - NXWidgets integrate seamlessly with the NX graphics system. Think of the - X server under Linux … the NX graphics system is like a tiny X server - that provides windowing under NuttX. By adding NXWidgets, you can support - graphics objects like buttons and text boxes in the NX windows and toolbars. + NXWidgets integrate seamlessly with the NX graphics system. Think of the X + server under Linux – the NX graphics system is like a tiny X server that + provides windowing under NuttX. By adding NXWidgets, you can support graphics + objects like buttons and text boxes in the NX windows and toolbars. -o Small Footprint +- Small Footprint NXWidgets is tailored for use MCUs in embedded applications. It is ideally - suited for mid- and upper-range of most MCU families. A complete NXWidgets - is possible in as little as 40Kb of FLASH and maybe 4Kb of SRAM. + suited for mid- and upper-range of most MCU families. A complete NXWidgets is + possible in as little as 40Kb of FLASH and maybe 4Kb of SRAM. -o Output Devices +- Output Devices NXWidgets will work on the high-end frame buffer devices as well as on LCDs connected via serial or parallel ports to a small MCU. -o Input Devices +- Input Devices NXWidgets will accept position and selection inputs from a mouse or a touchscreen. It will also support character input from a keyboard such as a - USB keyboard. NXWidgets supports on very special widget called CKeypad that - will provide keyboard input via an on-screen keypad that can be operated - via mouse or touchscreen inputs. + USB keyboard. NXWidgets supports on very special widget called `CKeypad` that + will provide keyboard input via an on-screen keypad that can be operated via + mouse or touchscreen inputs. -o Many Graphic Objects +- Many Graphic Objects Some of the graphic objects supported by NXWidgets include labels, buttons, text boxes, button arrays, check boxes, cycle buttons, images, sliders, scrollable list boxes, progress bars, and more. -Note: Many of the fundamental classed in NxWidgets derive from the Antony -Dzeryn's "Woopsi" project: http://woopsi.org/ which also has a BSD style -license. See the COPYING file for details. +**Note**: Many of the fundamental classed in NxWidgets derive from the Antony +Dzeryn's _Woopsi_ project: http://woopsi.org/ which also has a BSD style +license. See the `COPYING` file for details. -Directory Structure -=================== +## Directory Structure -Kconfig +- `Kconfig` - This is a Kconfig file that should be provided at apps/NxWidgets/Kconfig. + This is a `Kconfig` file that should be provided at `apps/NxWidgets/Kconfig`. When copied to that location, it will be used by the NuttX configuration systems to configure settings for NxWidgets and NxWM -nxwidgets +- `nxwidgets` - The source code, header files, and build environment for NxWidgets is - provided in this directory. + The source code, header files, and build environment for NxWidgets is provided + in this directory. -UnitTests +- `UnitTests` - Provides a collection of unit-level tests for many of the individual - widgets provided by nxwidgets. + Provides a collection of unit-level tests for many of the individual widgets + provided by `nxwidgets`. diff --git a/graphics/nxwidgets/UnitTests/README.md b/graphics/nxwidgets/UnitTests/README.md index a93bc306d..d376801df 100644 --- a/graphics/nxwidgets/UnitTests/README.md +++ b/graphics/nxwidgets/UnitTests/README.md @@ -1,241 +1,259 @@ -README -====== +# Graphics / NXWidgets / Unit Tests This directory contains a collection of Unit Tests that can be used to verify NXWidgets.: -Contents -======== - o Building the Unit Tests - 1. Setup NuttX - a) Configure NuttX - b) Enable C++ Support - c) Enable Debug Options - d) NxWM - e) Other Possible .config file changes - f) Other Possible .config file changes - 2. Configure in the Selected Unit Test - o Work-Arounds - 1. Build Issues - 2. Stack Size Issues with the X11 Simulation - o Unit Test Directories +## Contents -Installing and Building the Unit Tests -====================================== +**Installing and Building the Unit Tests** + +1. Setup NuttX + 1. Configure NuttX + 2. Enable C++ Support + 3. Enable Debug Options + 4. Special configuration requirements for the nxwm unit test + 5. Other `.config` file changes – NSH configurations only + 6. Other `.config` file changes – NON-NSH configurations only +2. Adjust the Stack Size +3. Build NuttX including the unit test and the NXWidgets library + +**Work-Arounds** + +1. Build Issues + +**Unit Test Directories** + +## Installing and Building the Unit Tests 1. Setup NuttX - a) Configure NuttX + 1. Configure NuttX - Configure NuttX to run one of the target configurations. For example, - let's assume that you are using the sim/nsh2 configuration. The sim/nsh2 - configuration was specially created for use NXWidgets on the simulation - platform. A similar, special configuration stm3210e-eval/nsh2 is also - for the STM3210E-EVAL available. However, the unit test can be run on - other configurations (see steps d and e below). + Configure NuttX to run one of the target configurations. For example, + let's assume that you are using the `sim/nsh2` configuration. The + `sim/nsh2` configuration was specially created for use NXWidgets on the + simulation platform. A similar, special configuration `stm3210e-eval/nsh2` + is also for the `STM3210E-EVAL` available. However, the unit test can be + run on other configurations (see steps d and e below). - NOTE: There are some other special configurationsrecommended for unit-leveling - testing of NxWM because the configuration is more complex in that case. These - are: + **Note**: There are some other special configurationsrecommended for + unit-leveling testing of NxWM because the configuration is more complex in + that case. These are: - 1) sim/nxwmm, or the simulated platform (no touchscreen), and - 2) stm3240g-evel, for the STM3240G-EVAL board (with the STMPE11 touchscreen) + 1) `sim/nxwmm`, or the simulated platform (no touchscreen), and + 2) `stm3240g-evel`, for the `STM3240G-EVAL` board (with the STMPE11 + touchscreen) - We will assume the sim/nsh2 configuration in this discussion. The - sim/nsh2 configuration is installed as follows: + We will assume the `sim/nsh2` configuration in this discussion. The + `sim/nsh2` configuration is installed as follows: - cd - make distclean - tools/configure.sh sim:nsh2 + ```bash + cd + make distclean + tools/configure.sh sim:nsh2 + ``` - Where: + Where: - is the full, absolute path to the NuttX build directory + `` is the full, absolute path to the NuttX build + directory - If you are using the sim/nsh2 or stm3210e-eval configurations, then skip - to step 2 (Hmmm.. better check 1d) too). + If you are using the `sim/nsh2` or `stm3210e-eval` configurations, then + skip to step 2 (Hmmm.. better check 1d) too). - There may be certain requirements for the configuration that you select... - for example, certain widget tests may require touchscreen support or special - font selections. These test-specific requirements are addressed below under - "Unit Test Directories" + There may be certain requirements for the configuration that you select... + for example, certain widget tests may require touchscreen support or + special font selections. These test-specific requirements are addressed + below under _Unit Test Directories_ - b) Enable C++ Support + 2. Enable C++ Support - If you are not using the sim/nsh2 or stm3210e-eval, you will need to add - the following definitions to the NuttX configuration at nuttx/.config to - enable C++ support: + If you are not using the `sim/nsh2` or `stm3210e-eval`, you will need to + add the following definitions to the NuttX configuration at + `nuttx/.config` to enable C++ support: - CONFIG_HAVE_CXX=y + ```conf + CONFIG_HAVE_CXX=y + ``` - Check first, some configurations already have C++ support enabled (As of this - writing *ONLY* the sim/nsh2 and stm321-e-eval configurations have C++ support - pre-enabled). + Check first, some configurations already have C++ support enabled (As of + this writing **ONLY** the `sim/nsh2` and `stm321-e-eval` configurations + have C++ support pre-enabled). - c) Enable Debug Options + 3. Enable Debug Options - If you are running on a simulated target, then you might also want to - enable debug symbols: + If you are running on a simulated target, then you might also want to + enable debug symbols: - CONFIG_DEBUG_SYMBOLS=y + ```conf + CONFIG_DEBUG_SYMBOLS=y + ``` - Then you can run the simulation using GDB or DDD which is a very powerful - debugging environment! + Then you can run the simulation using GDB or DDD which is a very powerful + debugging environment! - d) Special configuration requirements for the nxwm unit test: + 4. Special configuration requirements for the nxwm unit test. - CONFIG_NXTERM=y + ```conf + CONFIG_NXTERM=y + ``` - e) Other .config file changes -- NSH configurations only. + 5. Other `.config` file changes – NSH configurations only. - If the configuration that you are using supports NSH and NSH built-in tasks - then all is well. If it is an NSH configuration, then you will have to define - the following in your nuttx/.config file as well (if it is not already defined): + If the configuration that you are using supports NSH and NSH built-in + tasks then all is well. If it is an NSH configuration, then you will have + to define the following in your `nuttx/.config` file as well (if it is not + already defined): - CONFIG_NSH_BUILTIN_APPS=y + ```conf + CONFIG_NSH_BUILTIN_APPS=y + ``` - sim/nsh2 and stm3210e-eval/nsh2 already has this setting. You do not need - to change anything further in the nuttx/.config file if you are using either - of these configurations. + `sim/nsh2` and `stm3210e-eval/nsh2` already has this setting. You do not + need to change anything further in the `nuttx/.config` file if you are + using either of these configurations. - f) Other .config file changes -- NON-NSH configurations only. + 6. Other `.config` file changes – NON-NSH configurations only. - Entry Point. You will need to set the entry point in the .config file. - For NSH configurations, the entry point will always be "nsh_main" and you - will see that setting like: + Entry Point. You will need to set the entry point in the .config file. For + NSH configurations, the entry point will always be `nsh_main` and you will + see that setting like: - CONFIG_USER_ENTRYPOINT="nsh_main" + ```conf + CONFIG_USER_ENTRYPOINT="nsh_main" + ``` - If you are not using in NSH, then each unit test has a unique entry point. - That entry point is the name of the unit test directory in all lower case - plus the suffix "_main". So, for example, the correct entry for the - UnitTests/CButton would be: + If you are not using in NSH, then each unit test has a unique entry point. + That entry point is the name of the unit test directory in all lower case + plus the suffix `_main`. So, for example, the correct entry for the + `UnitTests/CButton` would be: - CONFIG_USER_ENTRYPOINT="cbutton_main" + ```conf + CONFIG_USER_ENTRYPOINT="cbutton_main" + ``` - And the correct entry point for UnitTests/nxwm would be: + And the correct entry point for `UnitTests/nxwm` would be: - CONFIG_USER_ENTRYPOINT="nxwm_main" + ```conf + CONFIG_USER_ENTRYPOINT="nxwm_main" + ``` - etc. + etc. - For non-NSH configurations (such as the sim/touchscreen) you will have to - remove the configuration setting that provided the "main" function so - that you use the "main" in the unit test code instead. So, for example, - with the sim/touchscreen configuration you need to remove the following from - the NuttX configuration file (.config): + For non-NSH configurations (such as the `sim/touchscreen`) you will have + to remove the configuration setting that provided the `main` function so + that you use the `main` in the unit test code instead. So, for example, + with the `sim/touchscreen` configuration you need to remove the following + from the NuttX configuration file (`.config`): - CONFIG_EXAMPLES_TOUSCHCREEN=y ## REMOVE (provided "tc_main") + ```conf + CONFIG_EXAMPLES_TOUSCHCREEN=y ## REMOVE (provided "tc_main") + ``` 2. Adjust the Stack Size - If using an simulation configuration (like sim/nsh2) and your unit test - uses X11 as its display device, then you would have to increase the size - of unit test stack as described below under "Stack Size Issues with the - X11 Simulation." + If using an simulation configuration (like `sim/nsh2`) and your unit test + uses X11 as its display device, then you would have to increase the size of + unit test stack as described below under _Stack Size Issues with the X11 + Simulation_. 3. Build NuttX including the unit test and the NXWidgets library - cd - . ./setenv.sh - make + ```bash + cd + . ./setenv.sh + make + ``` -Work-Arounds -============ +## Work-Arounds + +### Build Issues -Build Issues ------------- 1. I have seen this error on Cygwin building C++ code: + ``` LD: nuttx.rel ld: skipping incompatible /home/patacongo/projects/nuttx/nuttx/trunk/nuttx/libxx//liblibxx.a when searching for -llibxx ld: cannot find -llibxx + ``` - The problem seems to be caused because gcc build code for 32-bit mode and g++ builds code for 64-bit mode. Add the -m32 option to the g++ command line seems to fix the problem. In Make.defs: + The problem seems to be caused because `gcc` build code for 32-bit mode and + `g++` builds code for 64-bit mode. Add the `-m32` option to the `g++` command + line seems to fix the problem. In `Make.defs`: + ```makefile CXXFLAGS = -m32 $(ARCHWARNINGSXX) $(ARCHOPTIMIZATION) \ $(ARCHCPUFLAGSXX) $(ARCHINCLUDESXX) $(ARCHDEFINES) $(EXTRADEFINES) -pipe + ``` 2. Stack Size Issues with the X11 Simulation When you run the NuttX simulation, it uses stacks allocated by NuttX from the - NuttX heap. The memory management model is exactly the same in the simulation - as it is real, target system. This is good because this produces a higher + NuttX heap. The memory management model is exactly the same in the simulation + as it is real, target system. This is good because this produces a higher fidelity simulation. However, when the simulation calls into Linux/Cygwin libraries, it will still - use these small simulation stacks. This happens, for example, when you call + use these small simulation stacks. This happens, for example, when you call into the system to get and put characters to the console window or when you - make x11 calls into the system. The programming model within those libraries + make x11 calls into the system. The programming model within those libraries will assume a Linux/Cygwin environment where the stack size grows dynamically As a consequence, those system libraries may allocate large data structures - on the stack and overflow the small NuttX stacks. X11, in particular, - requires large stacks. If you are using X11 in the simulation, make sure - that you set aside a "lot" of stack for the X11 system calls (maybe 8 or 16Kb). - The stack size for the thread that begins with user start is controlled - by the configuration setting CONFIG_USERMAIN_STACKSIZE; you may need to + on the stack and overflow the small NuttX stacks. X11, in particular, + requires large stacks. If you are using X11 in the simulation, make sure that + you set aside a "lot" of stack for the X11 system calls (maybe 8 or 16Kb). + The stack size for the thread that begins with user start is controlled by + the configuration setting `CONFIG_USERMAIN_STACKSIZE`; you may need to increase this value to larger number to survive the X11 system calls. If you are running X11 applications as NSH add-on programs, then the stack - size of the add-on program is controlled in another way. Here are the - steps for increasing the stack size in that case: + size of the add-on program is controlled in another way. Here are the steps + for increasing the stack size in that case: - cd ../apps/namedapps # Go to the namedapps directory - vi namedapps_list.h # Edit this file and increase the stack size of the add-on - rm .built *.o # This will force the namedapps logic to rebuild + ```bash + cd ../apps/namedapps # Go to the namedapps directory + vi namedapps_list.h # Edit this file and increase the stack size of the add-on + rm .built *.o # This will force the namedapps logic to rebuild + ``` -UnitTests -========= +## Unit Tests -The following provide simple unit tests for each of the NXWidgets. In -addition, these unit tests provide examples for the use of each widget -type. +The following provide simple unit tests for each of the NXWidgets. In addition, +these unit tests provide examples for the use of each widget type. -CButton - Exercises the CButton widget - Depends on CLabel - -CButtonArray - Exercises the CButtonArray widget - -CCheckBox - Exercises the CCheckBox widget - Depends on CLabel and CButton. - -CGlyphButton - Exercises the CGlyphButton widget. - Depends on CLabel and CButton. - -CImage - Exercises the CImage widget - -CLabel - Exercises the CLabel widget - -CProgressBar - Exercises the CProgressBar widget - -CRadioButton - Exercises the CRadioButton and CRadioButtonGroup widgets. - Depends on CLabel and CButton - -CScrollBarHorizontal - Exercises the ScrollbarHorizontal - Depends on CSliderHorizontal and CGlyphButton - -CScrollBarVertical - Exercises the ScrollbarHorizontal - Depends on CSliderVertical and CGlyphButton - -CSliderHorizontal - Exercises the CSliderHorizontal - Depends on CSliderHorizontalGrip - -CSliderVertical - Exercises the CSliderVertical - Depends on CSliderVerticalGrip - -CTextBox - Exercises the CTextBox widget - Depends on CLabel +- `CButton` + - Exercises the `CButton` widget. + - Depends on `CLabel`. +- `CButtonArray` + - Exercises the `CButtonArray` widget. +- `CCheckBox` + - Exercises the `CCheckBox` widget. + - Depends on `CLabel` and `CButton`. +- `CGlyphButton` + - Exercises the `CGlyphButton` widget. + - Depends on `CLabel` and `CButton`. +- `CImage` + - Exercises the `CImage` widget. +- `CLabel` + - Exercises the `CLabel` widget. +- `CProgressBar` + - Exercises the `CProgressBar` widget. +- `CRadioButton` + - Exercises the `CRadioButton` and `CRadioButtonGroup` widgets. + - Depends on `CLabel` and `CButton`. +- `CScrollBarHorizontal` + - Exercises the `ScrollbarHorizontal`. + - Depends on `CSliderHorizontal` and `CGlyphButton`. +- `CScrollBarVertical` + - Exercises the `ScrollbarHorizontal`. + - Depends on `CSliderVertical` and `CGlyphButton`. +- `CSliderHorizontal` + - Exercises the `CSliderHorizontal`. + - Depends on `CSliderHorizontalGrip`. +- `CSliderVertical` + - Exercises the `CSliderVertical`. + - Depends on `CSliderVerticalGrip`. +- `CTextBox` + - Exercises the `CTextBox` widget. + - Depends on `CLabel`. diff --git a/graphics/nxwm/Doxygen/README.md b/graphics/nxwm/Doxygen/README.md index 26d76ce4b..cf4436347 100644 --- a/graphics/nxwm/Doxygen/README.md +++ b/graphics/nxwm/Doxygen/README.md @@ -1,64 +1,68 @@ -README -====== +# Graphics / `nxwm` NxWM / Doxygen This directory contains the documentation automatically generated by Doxygen. -Contents -======== +## Contents - o Installing the necessary packages in Ubuntu - o Generating documentation - o References +- Installing the necessary packages in Ubuntu +- Generating documentation +- References -Installing the necessary packages in Ubuntu -=========================================== +## Installing the necessary packages in Ubuntu 1. Install the following packages. - $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz + ```bash + $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz + ``` 2. (Optional) Install Doxygen from the latest sourcode. - The Ubuntu package is outdated. The newer the version of Doxygen, the better - the documentation looks. + The Ubuntu package is outdated. The newer the version of Doxygen, the better + the documentation looks. - Place yourself in some temporary folder where you can download the source, - and run [1]: + Place yourself in some temporary folder where you can download the source, + and run [1]: - $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn - $ cd doxygen-svn - $ ./configure - $ make - $ make install + ```bash + $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn + $ cd doxygen-svn + $ ./configure + $ make + $ make install + ``` -Generating documentation -======================== +## Generating documentation Two ways described here: -1. Use the provided gendoc.sh script. +1. Use the provided `gendoc.sh` script. - trunk/NXWidgets/Doxygen/gendoc.sh + ```bash + trunk/NXWidgets/Doxygen/gendoc.sh + ``` - The script only needs the argument to the absolute path where to place the - generated documentation. I.e.: + The script only needs the argument to the absolute path where to place the + generated documentation. I.e.: - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ mkdir doc - $ ./gendoc.sh $PWD/doc + ```bash + $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ + $ mkdir doc + $ ./gendoc.sh $PWD/doc + ``` +2. Using the `Doxyfile` directly: -2. Using the Doxyfile directly: - - The file "Doxyfile" contains the configuration of the Doxygen settings - for the run, edit only if necessary. + The file `Doxyfile` contains the configuration of the Doxygen settings for + the run, edit only if necessary. To generate the documentation type: - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ doxygen Doxyfile + ```bash + $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ + $ doxygen Doxyfile + ``` -References -========== +## References [1] http://www.stack.nl/~dimitri/doxygen/download.html diff --git a/graphics/nxwm/README.md b/graphics/nxwm/README.md index 497b01222..2578a46f2 100644 --- a/graphics/nxwm/README.md +++ b/graphics/nxwm/README.md @@ -1,30 +1,27 @@ -nxwm -==== +# Graphics / `nxwm` NxWM - This directory holds a tiny desktop for small embedded devices with a - touchscreen,. NxWM. NxWM is true multiple window manager but only one - window is displayed at a time. This simplification helps performance on - LCD based products (in the same way that a tiled window manager helps) - and also makes the best use of small displays. It is awkward from a - human factors point-of-view trying to manage multiple windows on a - small display. +This directory holds a tiny desktop for small embedded devices with a +touchscreen,. NxWM. NxWM is true multiple window manager but only one window is +displayed at a time. This simplification helps performance on LCD based products +(in the same way that a tiled window manager helps) and also makes the best use +of small displays. It is awkward from a human factors point-of-view trying to +manage multiple windows on a small display. - The window manager consists of a task bar with icons representing the - running tasks. If you touch the task's icon, it comes to the top. Each - window has a toolbar with (1) a title, (2) a minimize button, and (3) a - stop application button using the standard icons for these things. +The window manager consists of a task bar with icons representing the running +tasks. If you touch the task's icon, it comes to the top. Each window has a +toolbar with (1) a title, (2) a minimize button, and (3) a stop application +button using the standard icons for these things. - There is always a start window that is available in the task bar. When - you touch the start window icon, it brings up the start window containing - icons representing all of the available applications. If you touch an - icon in the start window, it will be started and added to the task bar. +There is always a start window that is available in the task bar. When you touch +the start window icon, it brings up the start window containing icons +representing all of the available applications. If you touch an icon in the +start window, it will be started and added to the task bar. - There is a base class that defines an add-on application and an - interface that supports incorporation of new application. The only - application that is provided is NxTerm. This is an NSH session - running in a window. You should be able to select the NX icon in the start - menu and create as many NSH sessions in windows as you want. (keybard input - still comes through serial). +There is a base class that defines an add-on application and an interface that +supports incorporation of new application. The only application that is provided +is NxTerm. This is an NSH session running in a window. You should be able to +select the NX icon in the start menu and create as many NSH sessions in windows +as you want. (keybard input still comes through serial). - Note 1: NwWM requires NuttX-7.19 or above to work with the current - NxWidgets-1.18 release. +Note 1: NwWM requires `NuttX-7.19` or above to work with the current +`NxWidgets-1.18` release. diff --git a/graphics/pdcurs34/README.md b/graphics/pdcurs34/README.md index ae03c09cb..85451a8b6 100644 --- a/graphics/pdcurs34/README.md +++ b/graphics/pdcurs34/README.md @@ -1,48 +1,39 @@ -Welcome to PDCurses! -==================== +# Graphics / `pdcurs34` PDCurses -Public Domain Curses, aka PDCurses, is an implementation of X/Open -curses for multiple platforms. The latest version can be found at: +**Welcome to PDCurses!** - http://pdcurses.sourceforge.net/ +Public Domain Curses, aka PDCurses, is an implementation of X/Open curses for +multiple platforms. The latest version can be found at: -For changes, see the HISTORY file. +[pdcurses.sourceforge.net](http://pdcurses.sourceforge.net) +For changes, see the `HISTORY` file. -Legal Stuff ------------ +## Legal Stuff -The core package is in the public domain, but small portions of PDCurses -are subject to copyright under various licenses. Each directory -contains a README file, with a section titled "Distribution Status" -which describes the status of the files in that directory. +The core package is in the public domain, but small portions of PDCurses are +subject to copyright under various licenses. Each directory contains a `README` +file, with a section titled _Distribution Status_ which describes the status of +the files in that directory. -If you use PDCurses in an application, an acknowledgement would be -appreciated, but is not mandatory. If you make corrections or -enhancements to PDCurses, please forward them to the current maintainer -for the benefit of other users. +If you use PDCurses in an application, an acknowledgement would be appreciated, +but is not mandatory. If you make corrections or enhancements to PDCurses, +please forward them to the current maintainer for the benefit of other users. This software is provided AS IS with NO WARRANTY whatsoever. - -Ports ------ +## Ports PDCurses has been ported to DOS, OS/2, Win32, X11 and SDL. A directory -containing the port-specific source files exists for each of these -platforms. Build instructions are in the README file for each platform. +containing the port-specific source files exists for each of these platforms. +Build instructions are in the `README` file for each platform. +## Distribution Status -Distribution Status -------------------- +All files in this directory except configure, `config.guess` and `config.sub` +are released to the Public Domain. `config.guess` and `config.sub` are under the +GPL; configure is under a free license described within it. -All files in this directory except configure, config.guess and -config.sub are released to the Public Domain. config.guess and -config.sub are under the GPL; configure is under a free license -described within it. - - -Maintainer ----------- +## Maintainer William McBrine diff --git a/graphics/pdcurs34/pdcurses/README.md b/graphics/pdcurs34/pdcurses/README.md index a6a7ee8fe..2e217111a 100644 --- a/graphics/pdcurs34/pdcurses/README.md +++ b/graphics/pdcurs34/pdcurses/README.md @@ -1,25 +1,17 @@ -PDCurses Portable Core -====================== +# Graphics / `pdcurs34` PDCurses / `pdcurses` Portable Core -This directory contains core PDCurses source code files common to all -platforms. +This directory contains core PDCurses source code files common to all platforms. +## Building -Building --------- +These modules are built by the platform-specific makefiles, in the platform +directories. -These modules are built by the platform-specific makefiles, in the -platform directories. - - -Distribution Status -------------------- +## Distribution Status The files in this directory are released to the Public Domain. +## Acknowledgements -Acknowledgements ----------------- - -The panel library was originally provided by +The panel library was originally provided by Warren Tucker diff --git a/graphics/tiff/README.md b/graphics/tiff/README.md index b414107ff..dd4620715 100644 --- a/graphics/tiff/README.md +++ b/graphics/tiff/README.md @@ -1,15 +1,12 @@ -README for the TIFF Creation Library -===================================== +# Graphics / `tiff` TIFF Creation Library -This directory contains a library that can be used to create TIFF image -files. This file was created for the purpose of supporting screen dumps -from an LCD. Howeve, the logic is general and could be used for most -any purpose. +This directory contains a library that can be used to create TIFF image files. +This file was created for the purpose of supporting screen dumps from an LCD. +Howeve, the logic is general and could be used for most any purpose. -The only usage documentation is in the (rather extensive) comments in -the file apps/include/tiff.h +The only usage documentation is in the (rather extensive) comments in the file +`apps/include/tiff.h`. -Unit Test -========= +## Unit Test -See apps/examples/tiff +See `apps/examples/tiff`. diff --git a/graphics/twm4nx/README.md b/graphics/twm4nx/README.md index a1de5ffef..5c594b94d 100644 --- a/graphics/twm4nx/README.md +++ b/graphics/twm4nx/README.md @@ -1,385 +1,386 @@ -README -====== +# Graphics / `twm4nx` Tab Window Manager (TWM) -Twm4Nx is a port of twm, Tab Window Manager (or Tom's Window Manager) -version 1.0.10 to NuttX NX windows server. No, a port is not the right -word. It is a re-design of TWM from the inside out to work with the NuttX -NX server. The name Twm4Nx reflects this legacy. But Twm4Nx is more a -homage to TWM than a port of TWM. +Twm4Nx is a port of twm, Tab Window Manager (or Tom's Window Manager) version +`1.0.10` to NuttX NX windows server. No, a port is not the right word. It is a +re-design of TWM from the inside out to work with the NuttX NX server. The name +Twm4Nx reflects this legacy. But Twm4Nx is more a homage to TWM than a port of +TWM. -The original TWM was based on X11 which provides a rich set of features. -TWM provided titlebars, shaped windows, several forms of icon management, -user-defined macro functions, click-to-type and pointer-driven keyboard -focus, graphic contexts, and user-specified key and pointer button bindings, -etc. +The original TWM was based on X11 which provides a rich set of features. TWM +provided titlebars, shaped windows, several forms of icon management, +user-defined macro functions, click-to-type and pointer-driven keyboard focus, +graphic contexts, and user-specified key and pointer button bindings, etc. Twm4Nx, on the other hand is based on the NuttX NX server which provides -comparatively minimal support. Additional drawing support comes from -the NuttX NxWidgets library (which necessitated the change to C++). +comparatively minimal support. Additional drawing support comes from the NuttX +NxWidgets library (which necessitated the change to C++). -Twm4Nx is greatly stripped down and targeted on small embedded systems -with minimal resources. For example, no assumption is made about the -availability of a file system; no .twmrc file is used. Bitmaps are not -used (other than for fonts). +Twm4Nx is greatly stripped down and targeted on small embedded systems with +minimal resources. For example, no assumption is made about the availability of +a file system; no `.twmrc` file is used. Bitmaps are not used (other than for +fonts). -The TWM license is, I believe compatible with the BSD license used by NuttX. -The origin TWM license required notice of copyrights within each file and -a full copy of the original license which you can find in the COPYING file. -within this directory. +The TWM license is, I believe compatible with the BSD license used by NuttX. The +origin TWM license required notice of copyrights within each file and a full +copy of the original license which you can find in the `COPYING` file. within +this directory. -STATUS -====== +## Status -Progress: - 2019-04-28: This port was brutal. Much TWM logic was removed because it - depended on X11 features (or just because I could not understand how to - use it). The replacement logic is only mostly in place but more - needs to be done to have a complete system (hence, it is marked - EXPERIMENTAL). The kinds of things that need to done are: +### Progress - 1. Right click should bring up a window list (like the icon manager???) - 2. For TWM-like behavior, a window frame and toolbar should be highlighted - when the window has focus. - 3. A right click on the toolbar should bring up a window-specific menu. - 2019-05-02: Some testing progress. The system comes up, connects to and - initializes the VNC window. For some reason, the VNC client breaks the - connection. The server is no longer connected so Twm4Nx constipates and - and eventually hangs. - 2019-05-08: I abandoned the VNC interface and found that things are much - better using a direct, hardware framebuffer. The background comes up - properly and the Icon Manager appears properly in the upper right hand - corner. The Icon Manager Window can be iconified or de-iconified. - The Icon Manager window can be grabbed by the toolbar title and moved - about on the window (the movement is not very smooth on the particular - hardware that I am working with). - 2019-05-10: A left click on the background brings up the main menu. At - present there are only two options: "Desktop" which will iconify all - windows and "Twm4Nx Icon Manager" which will de-iconify and/or raise - the Icon Manager window to the top of the hierarchy. That latter option - is only meaningful when the desktop is very crowded. - 2019-05-13: Added the NxTerm application. If enabled via - CONFIG_TWM4XN_NXTERM, there will now be a "NuttShell" entry in the Main - Menu. When pressed, this will bring up an NSH session in a Twm4Nx - window. - 2019-05-14: We can now move an icon on the desktop. Includes logic to - avoid collisions with other icons and with the background image. That - later is an issue. The background image image widget needs to be - removed; it can occlude a desktop icon. We need to paint the image - directly on the background without the use of a widget. - 2019-05-15: Resizing now seems to work correctly in Twm4Nx. - 2019-05-20: Calibration screen is now in place. - 2019-05-21: A "CONTEMPORARY" theme was added. Still has a few glitches. - 2019-06-01: A retro, emulated segment LCD clock is now in place. +- `2019-04-28` This port was brutal. Much TWM logic was removed because it + depended on X11 features (or just because I could not understand how to use + it). The replacement logic is only mostly in place but more needs to be done + to have a complete system (hence, it is marked `EXPERIMENTAL`). The kinds of + things that need to done are: -How To: + 1. Right click should bring up a window list (like the icon manager???) + 2. For TWM-like behavior, a window frame and toolbar should be highlighted + when the window has focus. + 3. A right click on the toolbar should bring up a window-specific menu. - Icon Manager - - At start up, only the Icon Manager window is shown. The Icon Manager - is a TWM alternative to more common desktop icons. Currently Twm4Nx - supports both desktop icons and the Icon Manager. +- `2019-05-02` Some testing progress. The system comes up, connects to and + initializes the VNC window. For some reason, the VNC client breaks the + connection. The server is no longer connected so Twm4Nx constipates and and + eventually hangs. - Whenever a new application is started from the Main Menu, its name - shows up in the Icon Manager. Selecting the name will either de- - iconify the window, or just raise it to the top of the display. +- `2019-05-08` I abandoned the VNC interface and found that things are much + better using a direct, hardware framebuffer. The background comes up properly + and the Icon Manager appears properly in the upper right hand corner. The Icon + Manager Window can be iconified or de-iconified. The Icon Manager window can + be grabbed by the toolbar title and moved about on the window (the movement is + not very smooth on the particular hardware that I am working with). - Main Menu: - - A touch/click at any open location on the background (except the - image at the center or on another icon) will bring up the Main Menu. - Options: +- `2019-05-10` A left click on the background brings up the main menu. At + present there are only two options: _Desktop_ which will iconify all windows + and _Twm4Nx Icon Manager_ which will de-iconify and/or raise the Icon Manager + window to the top of the hierarchy. That latter option is only meaningful when + the desktop is very crowded. - o Desktop. Iconify all windows and show the desktop - o Twm4Nx Icom Manager. De-iconify and/or raise the Icon Manager to - the top of the display. - o Calibration. Perform touchscreen re-calibration. - o Clock. Start and instance of clock in the window. The uses the - the retro, LCD emulation of apps/graphics/slcd. - o NuttShell. Start and instance of NSH running in an NxTerm. +- `2019-05-13` Added the NxTerm application. If enabled via + `CONFIG_TWM4XN_NXTERM`, there will now be a _NuttShell_ entry in the Main + Menu. When pressed, this will bring up an NSH session in a Twm4Nx window. - - All windows close after the terminal menu option is selected. +- `2019-05-14` We can now move an icon on the desktop. Includes logic to avoid + collisions with other icons and with the background image. That later is an + issue. The background image image widget needs to be removed; it can occlude a + desktop icon. We need to paint the image directly on the background without + the use of a widget. - Window Toolbar - - Most windows have a toolbar at the top. It is optional but used - in most windows. - - The toolbar contains window title and from zero to 4 buttons: +- `2019-05-15` Resizing now seems to work correctly in Twm4Nx. - o Right side: A menu button may be presented. The menu button - is not used by anything in the current implementation and is - always suppressed - o Left side: The far left is (1)the terminate button (if present). - If present, it will close window when selected. Not all windows can - be closed. You can't close the Icon Manager or menu windows, for - example. Then (2) a resize button. If presented and is selected, - then the resize sequence described below it started. This may - the be preceded by a minimize button that iconifies the window. +- `2019-05-20` Calibration screen is now in place. - Moving a Window: - - Grab the title in the toolbar and move the window to the desired - position. +- `2019-05-21` A `CONTEMPORARY` theme was added. Still has a few glitches. - Resizing a Window: - - A window must have the green resize button with the square or it - cannot be resized. - - Press resize button. A small window should pop-up in the upper - left hand corner showing the current window size. - - Touch anywhere in window (not the toolbar) and slide your finger. - The resize window will show the new size but there will be no other - update to the display. It is thought that continuous size updates - would overwhelm lower end MCUs. Movements support include: +- `2019-06-01` A retro, emulated segment LCD clock is now in place. - o Move toward the right increases the width of the window - o Move toward the left decreases the width of the window - o Move toward the bottom increases the height of the window - o Move toward the top decreases the height of the Window - o Other moves will affect both the height and width of the window. +## How To - - NOTE: While resizing, non-critical events from all other windows - are ignored. +### Icon Manager - Themes - - There are two themes support by the configuration system: - o CONFIG_TWM4NX_CLASSIC. Strong bordered windows with dark primary - colors. Reminiscent of Windows 98. - o CONFIG_TWM4NX_CONTEMPORARY. Border-less windows in pastel shades - for a more contemporary look. +- At start up, only the Icon Manager window is shown. The Icon Manager is a TWM + alternative to more common desktop icons. Currently Twm4Nx supports both + desktop icons and the Icon Manager. -Issues: + Whenever a new application is started from the Main Menu, its name shows up in + the Icon Manager. Selecting the name will either de-iconify the window, or + just raise it to the top of the display. - 2019-05-16: - Twm4Nx is in a very complete state but only at perhaps "alpha" in its - maturity. You should expect to see some undocumented problems. If - you see such problems and can describe a sequence to actions to - reproduce the problem, let me know and I will try to resolve the - problems. +### Main Menu: - Here are all known issues and features that are missing: +- A touch/click at any open location on the background (except the image at the + center or on another icon) will bring up the Main Menu. Options: + - Desktop. Iconify all windows and show the desktop + - Twm4Nx Icom Manager. De-iconify and/or raise the Icon Manager to the top of + the display. + - Calibration. Perform touchscreen re-calibration. + - Clock. Start and instance of clock in the window. The uses the the retro, + LCD emulation of `apps/graphics/slcd`. + - NuttShell. Start and instance of NSH running in an NxTerm. +- All windows close after the terminal menu option is selected. - TWM Compatibilities Issues: - 1. Resizing works a little differently in Twm4Nx. - 2. Right click should bring up a window list - 3. For TWM-like behavior, a window frame and toolbar should be highlighted - when the window has focus. - 4. A right click on the toolbar should bring up a window-specific menu. +### Window Toolbar - There are no near-term plans to address these compatibility issues. +- Most windows have a toolbar at the top. It is optional but used in most + windows. +- The toolbar contains window title and from zero to 4 buttons: + - Right side: A menu button may be presented. The menu button is not used by + anything in the current implementation and is always suppressed + - Left side: The far left is (1) the terminate button (if present). If + present, it will close window when selected. Not all windows can be closed. + You can't close the Icon Manager or menu windows, for example. Then (2) a + resize button. If presented and is selected, then the resize sequence + described below it started. This may the be preceded by a minimize button + that iconifies the window. - Other issues/bugs. All-in-all, I would say that Twm4Nx is maturing well - and is attaining stability. That being said, there are some issues and - untested functionality that should be addressed: +### Moving a Window: - 1. Icon drag movement includes logic to avoid collisions with other - icons and with the background image. That later is an issue. We - need to paint the image directly on the background without the - use of a widget. - 2. There are a few color artifacts in the toolbar of the CONTEMPORARY - theme. These look like borders are being drawn around the toolbar - widgets (even though the are configured to be borderless). - 3. Most Twm4Nx configuration settings are hard-coded in *_config.hxx header - files. These all need to be brought out and made accessible via Kconfig - files - 4. I have seen some odd behavior when many NxTerm windows have been - opened (around 15). Specifically, I see failures to start NSH in the - windows so they come up blank. All other behaviors seem normal. Most - likely, some NxTerm resource allocation is failing silently and leaving - things in an unusable state. The board I am using has 128Mb of SDRAM - so I can't believe that memory is the limiting factor. These are, - however, RAM-backed windows and will use significant amounts of memory. - The primary issue is that the number of windows should probably be - managed in some way to assure that the end-user does not experience - odd behaviors when resource usage is high. - 5. Menus with sub-menus have not been verified. There is no use of sub- - menus in the current code base so I expect that there are issues when, - for example, and item from a sub-menu item: That menu and all of its - antecedent menus should be closed. - 6. There is an optional MENU button that may appear at the far left on - the toolbar. It is not used by any window in the current code base - and, hence, is unverified. I would expect some issues with generating - and routing the MENU button events to applications. There are likely - other unverified features. - 7. X/Y input may be either via a touchscreen or a mouse. Only - touchscreen input has been verified. There is, however, very little - difference. The primary issue is in cursor support: Cursors are - needed with a mouse. Cursor images also change depending on the - state (like grabbing and dragging or resizing). There is also a - possibility of using auto-raise with a mouse as well. All of this - logic is in place, but none has been verified. - 8. NxTerm windows really need to be scrollable. They are difficult to - use with only a few lines on a small display. A related usability - issue is the font height: The fonts report a maximum font height - that results in a large line spacing on the display and, hence, - fewer lines visible in the small window. This is latter issues is - a problem with the fonts not Twm4Nx, however. - 9. There is a trivial rounding error in the calculation of the LCD - width in SLcd::CSLcd::getWidth(). It currently truncates down. - It needs to round up. This sometimes leaves a small, one-pixel- - wide sliver on the clock display. This display always recovers and - this only cosmetic. +- Grab the title in the toolbar and move the window to the desired position. -Adding Twm4Nx Applications -========================== +### Resizing a Window: - Application Factories and the Main Menu - --------------------------------------- - The original TWM supported a .twmrc in which you could describe application - programs supported on the desktop. Currently no such start-up file is - available for Twm4Nx. Rather, all applications must be added via run-time - interfaces. And overview of these interfaces is provided in this - paragraph. +- A window must have the green resize button with the square or it cannot be + resized. +- Press resize button. A small window should pop-up in the upper left hand + corner showing the current window size. +- Touch anywhere in window (not the toolbar) and slide your finger. The resize + window will show the new size but there will be no other update to the + display. It is thought that continuous size updates would overwhelm lower end + MCUs. Movements support include: + - Move toward the right increases the width of the window + - Move toward the left decreases the width of the window + - Move toward the bottom increases the height of the window + - Move toward the top decreases the height of the Window + - Other moves will affect both the height and width of the window. +- **Note**: While resizing, non-critical events from all other windows are + ignored. - Currently, there are only two applications developed for Twm4Nx: (1) An - NxTerm hosting NSH that is analogous to an XTerm hosting the Bash shell - in a Unix environment, and (2) a touchscreen calibration application. - Let's focus instead on the NxTerm application as an example because the - touchscreen calibration is a rather unusual beast. +### Themes - These example applications can be found at: apps/graphics/twm4nx/apps and - apps/include/graphics/twm4nx/apps +- There are two themes support by the configuration system: + - `CONFIG_TWM4NX_CLASSIC` – Strong bordered windows with dark primary colors. + Reminiscent of Windows 98. + - `CONFIG_TWM4NX_CONTEMPORARY` – Border-less windows in pastel shades for a + more contemporary look. - In short, adding an application involves a "Factory Object" that is - hooked into the Main Menu. A Factory Object is an object that is used - to create other object instances. The way in which the Factory Object - is represented is purely a decision of the application developer. One - option, however, is to use the pure virtual base class IApplicationFactory - as defined in apps/include/graphics/twm4nx/iapplication.hxx. This base - class provides only a single method: +## Issues: - bool initialize(FAR CTwm4Nx *twm4nx); +`2019-05-16` Twm4Nx is in a very complete state but only at perhaps _alpha_ in +its maturity. You should expect to see some undocumented problems. If you see +such problems and can describe a sequence to actions to reproduce the problem, +let me know and I will try to resolve the problems. - where CTwm4Nx is the Twm4NX session instance that allows the class - implementation to interact with session specific resources. Multiple - sessions would be required, for example, if the platform supported - multiple displays. +Here are all known issues and features that are missing: - In practice, the application factory implementation class inherits from - the following base classes: +TWM Compatibilities Issues: +1. Resizing works a little differently in Twm4Nx. +2. Right click should bring up a window list +3. For TWM-like behavior, a window frame and toolbar should be highlighted when + the window has focus. +4. A right click on the toolbar should bring up a window-specific menu. - 1. IApplicationFactory. Provides the common initialize() method. - 2. IApplication. Provides the information for the application's entry - in the Main Menu - 3. CTwm4NxEvent. Hooks the application factory into the Twm4Nx event - notification system. +There are no near-term plans to address these compatibility issues. - Initialization consists of instantiating the application factory instance - and calling its IApplicationFactory::initialize() method. The application - factory instance is a singleton that must persist for the life of the - session. For the NxTerm application factory, this is done in - apps/graphics/twm4nx/src/twm4nx_main.c like: +Other issues/bugs. All-in-all, I would say that Twm4Nx is maturing well and is +attaining stability. That being said, there are some issues and untested +functionality that should be addressed: - CNxTermFactory nxtermFactory; - success = nxtermFactory.initialize(twm4nx); +1. Icon drag movement includes logic to avoid collisions with other icons and + with the background image. That later is an issue. We need to paint the image + directly on the background without the use of a widget. +2. There are a few color artifacts in the toolbar of the `CONTEMPORARY` theme. + These look like borders are being drawn around the toolbar widgets (even + though the are configured to be borderless). +3. Most Twm4Nx configuration settings are hard-coded in `*_config.hxx` header + files. These all need to be brought out and made accessible via Kconfig files +4. I have seen some odd behavior when many NxTerm windows have been opened + (around 15). Specifically, I see failures to start NSH in the windows so they + come up blank. All other behaviors seem normal. Most likely, some NxTerm + resource allocation is failing silently and leaving things in an unusable + state. The board I am using has 128Mb of SDRAM so I can't believe that memory + is the limiting factor. These are, however, RAM-backed windows and will use + significant amounts of memory. The primary issue is that the number of + windows should probably be managed in some way to assure that the end-user + does not experience odd behaviors when resource usage is high. +5. Menus with sub-menus have not been verified. There is no use of sub- menus in + the current code base so I expect that there are issues when, for example, + and item from a sub-menu item: That menu and all of its antecedent menus + should be closed. +6. There is an optional MENU button that may appear at the far left on the + toolbar. It is not used by any window in the current code base and, hence, is + unverified. I would expect some issues with generating and routing the MENU + button events to applications. There are likely other unverified features. +7. X/Y input may be either via a touchscreen or a mouse. Only touchscreen input + has been verified. There is, however, very little difference. The primary + issue is in cursor support: Cursors are needed with a mouse. Cursor images + also change depending on the state (like grabbing and dragging or resizing). + There is also a possibility of using auto-raise with a mouse as well. All of + this logic is in place, but none has been verified. +8. NxTerm windows really need to be scrollable. They are difficult to use with + only a few lines on a small display. A related usability issue is the font + height: The fonts report a maximum font height that results in a large line + spacing on the display and, hence, fewer lines visible in the small window. + This is latter issues is a problem with the fonts not Twm4Nx, however. +9. There is a trivial rounding error in the calculation of the LCD width in + `SLcd::CSLcd::getWidth()`. It currently truncates down. It needs to round up. + This sometimes leaves a small, one-pixel- wide sliver on the clock display. + This display always recovers and this only cosmetic. - In addition to general initialization, the IApplicationFactory::initialize() - method must register a new entry with the main menu. You can see an - example of this in apps/graphics/twm4nx/apps/cnxterm.c: +## Adding Twm4Nx Applications - FAR CMainMenu *cmain = twm4nx->getMainMenu(); - return cmain->addApplication(this); +### Application Factories and the Main Menu - The argument to the CMainMenu::addApplication() method is of type - IApplication *. Remember, however, that our application implementation - class inherited from IApplication. +The original TWM supported a .twmrc in which you could describe application +programs supported on the desktop. Currently no such start-up file is available +for Twm4Nx. Rather, all applications must be added via run-time interfaces. And +overview of these interfaces is provided in this paragraph. - The IApplication pure virtual base class is also defined in - apps/include/graphics/twm4nx/iapplication.hxx. It essentially describes - what the Main Menu logic should do when the menu item is selected. It - includes these methods: +Currently, there are only two applications developed for Twm4Nx: (1) An NxTerm +hosting NSH that is analogous to an XTerm hosting the Bash shell in a Unix +environment, and (2) a touchscreen calibration application. Let's focus instead +on the NxTerm application as an example because the touchscreen calibration is a +rather unusual beast. - 1. getName(). Provides the name string that will be shown in the - Main Menu for this selection. - 2. getSubMenu(). One possibility is that selecting the Main Menu item - is that it may bring up yet another sub-menu of options. - 3. getEventHandler(). Returns an instance of CTwm4NxEvent that is used - to route menu selection events. Remember that our application - factory inherits from CTwm4NxEvent so this function only needs to - return the 'this' pointer. - 4. getEvent(). Provides the event ID that will be used in the event - notification. The returned value must conform to the description - in apps/include/graphics/twm4nx/twm4nx_events.hxx. In particular, - the recipient of the event must be EVENT_RECIPIENT_APP. +These example applications can be found at: `apps/graphics/twm4nx/apps` and +`apps/include/graphics/twm4nx/apps` - The Twm4Nx application is then started when the application factory's - CTwm4NxEvent::event() method is called with the specified event. +In short, adding an application involves a _Factory Object_ that is hooked into +the Main Menu. A Factory Object is an object that is used to create other object +instances. The way in which the Factory Object is represented is purely a +decision of the application developer. One option, however, is to use the pure +virtual base class `IApplicationFactory` as defined in +`apps/include/graphics/twm4nx/iapplication.hxx`. This base class provides only a +single method: - Application Windows - ------------------- - How the application factory starts an application instance is purely up - to the application designer. Typically this would include starting a - new application task. General characteristics of an application include: +```cpp +bool initialize(FAR CTwm4Nx *twm4nx); +``` - 1. It probably should inherit from CTwm4NxEvent so that it can receive - events from the system. - 2. To create the window, it must instantiate and initialize an instance - of CWindow. - 3. It must configure application events to receive notifications from - Twm4Nx. +where CTwm4Nx is the Twm4NX session instance that allows the class +implementation to interact with session specific resources. Multiple sessions +would be required, for example, if the platform supported multiple displays. - To create an application window, the application must call the - CWindowFactory::createWindow() method. For the NxTerm example, this looks - like: +In practice, the application factory implementation class inherits from the +following base classes: - NXWidgets::CNxString name("NuttShell"); +1. `IApplicationFactory`. Provides the common `initialize()` method. +2. `IApplication`. Provides the information for the application's entry in the + Main Menu +3. `CTwm4NxEvent`. Hooks the application factory into the Twm4Nx event + notification system. - uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN); +Initialization consists of instantiating the application factory instance and +calling its `IApplicationFactory::initialize()` method. The application factory +instance is a singleton that must persist for the life of the session. For the +NxTerm application factory, this is done in +`apps/graphics/twm4nx/src/twm4nx_main.c` like: - FAR CWindowFactory *factory = m_twm4nx->getWindowFactory(); - m_nxtermWindow = factory->createWindow(name, &CONFIG_TWM4NX_NXTERM_ICON, - (FAR CIconMgr *)0, wflags); +```cpp +CNxTermFactory nxtermFactory; +success = nxtermFactory.initialize(twm4nx); +``` - The window factory is another factory that creates and manages window - instance. The createWindow() method requires four parameters: +In addition to general initialization, the `IApplicationFactory::initialize()` +method must register a new entry with the main menu. You can see an example of +this in `apps/graphics/twm4nx/apps/cnxterm.c`: - 1. The name of the window. This is the name that is show in the window - toolbar and may be the same name as was used in the Main Menu entry. - 2. A reference to the the Icon image associated with the window. This - is the image that is show on the desktop when the window is - iconified. It is of type NXWidgets::SRlePaletteBitmap. - 3. A pointer to the Icon Manager instance that this window belongs with. - This can be NULL to use the default Twm4Nx Icon Manager. - 4. A set of flags that describe properties of the windows. +```cpp +FAR CMainMenu *cmain = twm4nx->getMainMenu(); +return cmain->addApplication(this); +``` - The flag values are defined byte WFLAGS_* definitions provided in - apps/include/graphics/twm4nx/cwindow.hxx: +The argument to the `CMainMenu::addApplication()` method is of type +`IApplication *`. Remember, however, that our application implementation `class` +inherited from `IApplication`. - 1. WFLAGS_NO_MENU_BUTTON Omit the menu button from the toolbar - 2. WFLAGS_NO_DELETE_BUTTON Omit the delete button from the toolbar - 3. WFLAGS_NO_RESIZE_BUTTON Omit the resize button from the toolbar - 4. WFLAGS_NO_MINIMIZE_BUTTON Omit the minimize button from the toolbar - 5. WFLAGS_NO_TOOLBAR Omit the toolbar altogether - 6. WFLAGS_ICONMGR This window is an icon manager - 7. WFLAGS_MENU This window is a menu window - 8. WFLAGS_HIDDEN Start with the window hidden +The IApplication pure virtual base class is also defined in +`apps/include/graphics/twm4nx/iapplication.hxx`. It essentially describes what +the Main Menu logic should do when the menu item is selected. It includes these +methods: - Once the CWindow is instantiated, events needed by the application can - be configured as is done in the NxTerm application: +1. `getName()`. Provides the name string that will be shown in the Main Menu for + this selection. +2. `getSubMenu()`. One possibility is that selecting the Main Menu item is that + it may bring up yet another sub-menu of options. +3. `getEventHandler()`. Returns an instance of `CTwm4NxEvent` that is used to + route menu selection events. Remember that our application factory inherits + from `CTwm4NxEvent` so this function only needs to return the 'this' + pointer. +4. `getEvent()`. Provides the event ID that will be used in the event + notification. The returned value must conform to the description in + `apps/include/graphics/twm4nx/twm4nx_events.hxx`. In particular, the + recipient of the event must be `EVENT_RECIPIENT_APP`. - struct SAppEvents events; - events.eventObj = (FAR void *)this; - events.redrawEvent = EVENT_NXTERM_REDRAW; - events.resizeEvent = EVENT_NXTERM_RESIZE; - events.mouseEvent = EVENT_NXTERM_XYINPUT; - events.kbdEvent = EVENT_NXTERM_KBDINPUT; - events.closeEvent = EVENT_NXTERM_CLOSE; - events.deleteEvent = EVENT_NXTERM_DELETE; +The Twm4Nx application is then started when the application factory's +`CTwm4NxEvent::event()` method is called with the specified event. - bool success = m_nxtermWindow->configureEvents(events); +### Application Windows - Again, recall that the application inherits from CTwm4NxEvent. So passing - 'this' as the event object above assures that the specific events are - routed to the application instance. +How the application factory starts an application instance is purely up to the +application designer. Typically this would include starting a new application +task. General characteristics of an application include: - Drawing in the application window can be performed using that facilities - of NXWidgets using the NXWidgets::CGraphicsPort associated with the - window. The NxTerm application does not perform any drawing, however; - that drawing is performed by the NxTerm driver. +1. It probably should inherit from `CTwm4NxEvent` so that it can receive events + from the system. +2. To create the window, it must instantiate and initialize an instance of + `CWindow`. +3. It must configure application events to receive notifications from Twm4Nx. - The NXWidgets::CGraphicsPort can be obtained from a CWindow instance, - say m_window, like: +To create an application window, the application must call the +`CWindowFactory::createWindow()` method. For the NxTerm example, this looks +like: - FAR NXWidgets::CWidgetControl *control = m_window->getWidgetControl(); - NXWidgets::CGraphicsPort *port = control->getGraphicsPort(); +```cpp +NXWidgets::CNxString name("NuttShell"); - That CGraphicsPort is then passed to the widget constructor, binding the - widget to that window and forcing all widget drawing to occur within the - window. +uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN); - Obviously, a lot more could be written about drawing, much more than can - be addressed in this README file. +FAR CWindowFactory *factory = m_twm4nx->getWindowFactory(); +m_nxtermWindow = factory->createWindow(name, &CONFIG_TWM4NX_NXTERM_ICON, + (FAR CIconMgr *)0, wflags); +``` + +The window factory is another factory that creates and manages window instance. +The `createWindow()` method requires four parameters: + +1. The name of the window. This is the name that is show in the window toolbar + and may be the same name as was used in the Main Menu entry. +2. A reference to the the Icon image associated with the window. This is the + image that is show on the desktop when the window is iconified. It is of + type `NXWidgets::SRlePaletteBitmap`. +3. A pointer to the Icon Manager instance that this window belongs with. This + can be NULL to use the default Twm4Nx Icon Manager. +4. A set of flags that describe properties of the windows. + + The flag values are defined byte `WFLAGS_*` definitions provided in + `apps/include/graphics/twm4nx/cwindow.hxx`: + + - `WFLAGS_NO_MENU_BUTTON` – Omit the menu button from the toolbar. + - `WFLAGS_NO_DELETE_BUTTON` – Omit the delete button from the toolbar. + - `WFLAGS_NO_RESIZE_BUTTON` – Omit the resize button from the toolbar. + - `WFLAGS_NO_MINIMIZE_BUTTON` – Omit the minimize button from the toolbar. + - `WFLAGS_NO_TOOLBAR` – Omit the toolbar altogether. + - `WFLAGS_ICONMGR` – This window is an icon manager. + - `WFLAGS_MENU` – This window is a menu window. + - `WFLAGS_HIDDEN` – Start with the window hidden. + +Once the `CWindow` is instantiated, events needed by the application can be +configured as is done in the NxTerm application: + +```cpp +struct SAppEvents events; +events.eventObj = (FAR void *)this; +events.redrawEvent = EVENT_NXTERM_REDRAW; +events.resizeEvent = EVENT_NXTERM_RESIZE; +events.mouseEvent = EVENT_NXTERM_XYINPUT; +events.kbdEvent = EVENT_NXTERM_KBDINPUT; +events.closeEvent = EVENT_NXTERM_CLOSE; +events.deleteEvent = EVENT_NXTERM_DELETE; + +bool success = m_nxtermWindow->configureEvents(events); +``` + +Again, recall that the application inherits from `CTwm4NxEvent`. So passing +`this` as the event object above assures that the specific events are routed to +the application instance. + +Drawing in the application window can be performed using that facilities of +NXWidgets using the `NXWidgets::CGraphicsPort` associated with the window. The +NxTerm application does not perform any drawing, however; that drawing is +performed by the NxTerm driver. + +The `NXWidgets::CGraphicsPort` can be obtained from a `CWindow` instance, say +`m_window`, like: + +```cpp +FAR NXWidgets::CWidgetControl *control = m_window->getWidgetControl(); +NXWidgets::CGraphicsPort *port = control->getGraphicsPort(); +``` + +That `CGraphicsPort` is then passed to the widget constructor, binding the +widget to that window and forcing all widget drawing to occur within the window. + +Obviously, a lot more could be written about drawing, much more than can be +addressed in this README file. diff --git a/industry/abnt_codi/README.md b/industry/abnt_codi/README.md index e1f008f57..849e2dc96 100644 --- a/industry/abnt_codi/README.md +++ b/industry/abnt_codi/README.md @@ -1,67 +1,27 @@ +# Industry / `abnt_codi` ABNT CODI + The ABNT CODI is an old energy meter standard used in Brazil. This code interprets the end user serial output existent in the energy meter. That output externalizes its data blinking an LED as a serial protocol at the -baudrate of 110 BPS and uses 8 octects: - _____________________________________________________________________________ -| | | | -| OCTET | bits | Description | -|________|______|_____________________________________________________________| -| | | | -| 001 | 0-7 | Number of seconds to the end of current active demand (LSB) | -|________|______|_____________________________________________________________| -| | | | -| 002 | 0-3 | Number of seconds to the end of current active demand (MSB) | -|________|______|_____________________________________________________________| -| | | | -| | 4 | Bill indicator. It is inverted at each demand replenishment | -|________|______|_____________________________________________________________| -| | | | -| | 5 | Reactive Interval Indicator. Inverted at end react interval | -|________|______|_____________________________________________________________| -| | | | -| | 6 | If 1 means the reactive-capacitive is used to calculate UFER| -|________|______|_____________________________________________________________| -| | | | -| | 7 | If 1 means the reactive-inductive is used to calculate UFER | -|________|______|_____________________________________________________________| -| | | | -| 003 | 0-3 | Current seasonal segment: | -| | | 0001 - tip | -| | | 0010 - out of tip | -| | | 1000 - reserved | -|________|______|_____________________________________________________________| -| | | | -| | 4-5 | Type of charging indicator (flag): | -| | | 00 - Blue | -| | | 01 - Green | -| | | 10 - Irrigators | -| | | 11 - Other | -|________|______|_____________________________________________________________| -| | | | -| | 6 | Not used | -|________|______|_____________________________________________________________| -| | | | -| | 7 | If equal 1 means reactive rate is enabled | -|________|______|_____________________________________________________________| -| | | | -| 004 | 0-7 | Number of pulses for active energy of cur dem interv (LSB) | -|________|______|_____________________________________________________________| -| | | | -| 005 | 0-6 | Number of pulses for active energy of cur dem interv (MSB) | -|________|______|_____________________________________________________________| -| | | | -| | 7 | Not used | -|________|______|_____________________________________________________________| -| | | | -| 006 | 0-7 | Number of pulses for reactive energy of cur dem interv (LSB)| -|________|______|_____________________________________________________________| -| | | | -| 007 | 0-6 | Number of pulses for reactive energy of cur dem interv (MSB)| -|________|______|_____________________________________________________________| -| | | | -| | 7 | Not used | -|________|______|_____________________________________________________________| -| | | | -| 008 | 0-7 | Inverted bits of "xor" from previous octects | -|________|______|_____________________________________________________________| +baudrate of `110 BPS` and uses `8` octects: + +| Octet | Bits | Description +|:-----:|------:|------------- +| `001` | `0-7` | Number of seconds to the end of current active demand (`LSB`) +| `002` | `0-3` | Number of seconds to the end of current active demand (`MSB`) +| | `4` | Bill indicator. It is inverted at each demand replenishment +| | `5` | Reactive Interval Indicator. Inverted at end react interval +| | `6` | If `1` means the reactive-capacitive is used to calculate `UFER` +| | `7` | If `1` means the reactive-inductive is used to calculate `UFER` +| `003` | `0-3` | Current seasonal segment:
`0001` – tip
`0010` – out of tip
`1000` – reserved +| | `4-5` | Type of charging indicator (flag):
`00` – Blue
`01` – Green
`10` – Irrigators
`11` – Other +| | `6` | Not used +| | `7` | If equal `1` means reactive rate is enabled +| `004` | `0-7` | Number of pulses for active energy of cur dem interv (`LSB`) +| `005` | `0-6` | Number of pulses for active energy of cur dem interv (`MSB`) +| | `7` | Not used +| `006` | `0-7` | Number of pulses for reactive energy of cur dem interv (`LSB`) +| `007` | `0-6` | Number of pulses for reactive energy of cur dem interv (`MSB`) +| | `7` | Not used +| `008` | `0-7` | Inverted bits of _xor_ from previous octects diff --git a/interpreters/README.md b/interpreters/README.md index 8d40078b9..0379e1eee 100644 --- a/interpreters/README.md +++ b/interpreters/README.md @@ -1,24 +1,21 @@ -apps/interpreters README file -============================= +# Interpreters -This apps/ directory is set aside to hold interpreters that may be +This `apps/` directory is set aside to hold interpreters that may be incorporated into NuttX. -ficl ----- +## Ficl - This is DIY port of Ficl (the "Forth Inspired Command Language"). See - http://ficl.sourceforge.net/. It is a "DIY" port because the Ficl source - is not in that directory, only an environment and instructions that will - let you build Ficl under NuttX. The rest is up to you. +This is DIY port of Ficl (the _Forth Inspired Command Language_). See +http://ficl.sourceforge.net/. It is a _DIY_ port because the Ficl source is not +in that directory, only an environment and instructions that will let you build +Ficl under NuttX. The rest is up to you. -minibasic ---------- +## Mini Basic - The Mini Basic implementation at apps/interpreters derives from version 1.0 - by Malcolm McLean, Leeds University, and was released under the Creative - Commons Attibution license. I am not legal expert, but this license - appears to be compatible with the NuttX BSD license see: - https://creativecommons.org/licenses/ . I, however, cannot take - responsibility for any actions that you might take based on my - understanding. Please use your own legal judgement. +The Mini Basic implementation at `apps/interpreters` derives from version `1.0` +by Malcolm McLean, Leeds University, and was released under the Creative Commons +Attibution license. I am not legal expert, but this license appears to be +compatible with the NuttX BSD license see: +https://creativecommons.org/licenses/. I, however, cannot take responsibility +for any actions that you might take based on my understanding. Please use your +own legal judgement. diff --git a/interpreters/bas/README.md b/interpreters/bas/README.md index d8435930e..be3f431eb 100644 --- a/interpreters/bas/README.md +++ b/interpreters/bas/README.md @@ -1,63 +1,59 @@ -README -====== +# Interpreters / `bas` Bas BASIC -Introduction -============ - Bas is an interpreter for the classic dialect of the programming language - BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s, - unlike some other UNIX BASIC interpreters, that implement a different - syntax, breaking compatibility to existing programs. Bas offers many ANSI - BASIC statements for structured programming, such as procedures, local - variables and various loop types. Further there are matrix operations, - automatic LIST indentation and many statements and functions found in - specific classic dialects. Line numbers are not required. +## Introduction - The interpreter tokenises the source and resolves references to variables - and jump targets before running the program. This compilation pass - increases efficiency and catches syntax errors, type errors and references - to variables that are never initialised. Bas is written in ANSI C for - UNIX systems. +Bas is an interpreter for the classic dialect of the programming language BASIC. +It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some +other UNIX BASIC interpreters, that implement a different syntax, breaking +compatibility to existing programs. Bas offers many ANSI BASIC statements for +structured programming, such as procedures, local variables and various loop +types. Further there are matrix operations, automatic LIST indentation and many +statements and functions found in specific classic dialects. Line numbers are +not required. -License -======= - BAS 2.4 is released as part of NuttX under the standard 3-clause BSD license - use by all components of NuttX. This is not incompatible with the original - BAS 2.4 licensing +The interpreter tokenises the source and resolves references to variables and +jump targets before running the program. This compilation pass increases +efficiency and catches syntax errors, type errors and references to variables +that are never initialised. Bas is written in ANSI C for UNIX systems. - Copyright (c) 1999-2014 Michael Haardt +## License - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: +BAS 2.4 is released as part of NuttX under the standard 3-clause BSD license use +by all components of NuttX. This is not incompatible with the original BAS 2.4 +licensing - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. +Copyright (c) 1999-2014 Michael Haardt - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: -Bas 2.4 Release Notes -===================== - Changes compared to version 2.3 +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. - o Matrix inversion on integer arrays with option base 1 fixed - o PRINT USING behaviour for ! fixed - o PRINT , separator should advance to the next zone, even if the current - position is at the start of a zone - o Added ip(), frac(), fp(), log10(), log2(), min() and max() - o Fixed NEXT checking the variable case sensitive - o Use terminfo capability cr to make use of its padding - o LET segmentation fault fixed - o PRINT now uses print items - o -r for restricted operation - o MAT INPUT does not drop excess arguments, but uses them for the - next row - o License changed to MIT +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +## Bas 2.4 Release Notes + +Changes compared to version `2.3` + +- Matrix inversion on integer arrays with option base 1 fixed. +- `PRINT USING` behaviour for `!` fixed. +- `PRINT`, separator should advance to the next zone, even if the current + position is at the start of a zone. +- Added `ip()`, `frac()`, `fp()`, `log10()`, `log2()`, `min()` and `max()`. +- Fixed `NEXT` checking the variable case sensitive. +- Use `terminfo` capability cr to make use of its padding. +- `LET` segmentation fault fixed. +- `PRINT` now uses print items. +- `-r` for restricted operation. +- `MAT INPUT` does not drop excess arguments, but uses them for the next row. +- License changed to MIT. diff --git a/interpreters/ficl/README.md b/interpreters/ficl/README.md index 73ed9006f..743a1ee63 100644 --- a/interpreters/ficl/README.md +++ b/interpreters/ficl/README.md @@ -1,40 +1,39 @@ -apps/interpreter/README.txt -=========================== +# Interpreters / `ficl` Ficl -Ficl is a programming language interpreter designed to be embedded into -other systems as a command, macro, and development prototyping language. -Ficl is an acronym for "Forth Inspired Command Language". See -http://ficl.sourceforge.net/ +Ficl is a programming language interpreter designed to be embedded into other +systems as a command, macro, and development prototyping language. Ficl is an +acronym for _Forth Inspired Command Language_. See http://ficl.sourceforge.net/ -Build Instructions ------------------- +## Build Instructions -Disclaimer: This installation steps have only been exercised using Ficl -4.1.0. With new versions you will likely have to make some adjustments -to this instructtions or to the files within this directory. Think of this -information as "recommendations" -- not necessarily proven instructions. +Disclaimer: This installation steps have only been exercised using Ficl 4.1.0. +With new versions you will likely have to make some adjustments to this +instructtions or to the files within this directory. Think of this information +as _recommendations_ - not necessarily proven instructions. -1. CD to apps/interpreters/ficl +1. `cd` to `interpreters/ficl` 2. Download Ficl: http://sourceforge.net/projects/ficl/files/ 3. Uznip the Ficl compressed file. - For example, 'unzip ficl-4.1.0.zip' will leave the file - apps/interpreters/ficl/ficl-4.1.0 + For example, `unzip ficl-4.1.0.zip` will leave the file + `interpreters/ficl/ficl-4.1.0`. -4. Configure to build Ficl in the apps/interpreters/ficl directory using - the configure.sh script. +4. Configure to build Ficl in the `interpreters/ficl` directory using the + `configure.sh` script. - For example, './configure.sh ficl-4.1.0' will leave the Makefile - fragment 'Make.srcs' in the ficl build directory. + 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. Using the 'make menuconfig', you - should select: +5. Create your NuttX configuration. Using the `make menuconfig`, you should + select: - CONFIG_INTERPRETERS_FICL=y + ```conf + CONFIG_INTERPRETERS_FICL=y + ``` -6. Configure and build NuttX. On successful completion, the Ficl objects - will be available in apps/libapps.a and that NuttX binary will be - linked against that file. Of course, Ficl will do nothing unless - you have written some application code that uses it! +6. Configure and build NuttX. On successful completion, the Ficl objects will be + available in `apps/libapps.a` and that NuttX binary will be linked against + that file. Of course, Ficl will do nothing unless you have written some + application code that uses it! diff --git a/modbus/README.md b/modbus/README.md index 1d3e9c734..9fe4cc93b 100644 --- a/modbus/README.md +++ b/modbus/README.md @@ -1,123 +1,121 @@ -apps/modbus README -================== +# Modbus -This directory contains a port of last open source version of FreeModBus -(BSD license). The code in this directory is a subset of FreeModBus version -1.5.0 (June 6, 2010) that can be downloaded in its entirety from http://developer.berlios.de/project/showfiles.php?group_id=6120. +This directory contains a port of last open source version of FreeModBus (BSD +license). The code in this directory is a subset of FreeModBus version 1.5.0 +(June 6, 2010) that can be downloaded in its entirety from +http://developer.berlios.de/project/showfiles.php?group_id=6120. Includes extensions to support RTU master mode by Armink(383016632@qq.com): -https://github.com/armink/FreeModbus_Slave-Master-RTT-STM32. Ported to -NuttX by Darcy Gong. +https://github.com/armink/FreeModbus_Slave-Master-RTT-STM32. Ported to NuttX by +Darcy Gong. -Directory Structure/Relation to freemodbus-v1.5.0 -------------------------------------------------- +## Directory Structure / Relation to freemodbus-v1.5.0 -The original FreeModBus download consists of several directories. This -subset takes only the contents of one directory, modbus/, that implements -the core modbus logic and integrates that directory into the NuttX build -system. The mapping between freemodbus-v1.5.0 and the nuttx directories -is shown below: +The original FreeModBus download consists of several directories. This subset +takes only the contents of one directory, `modbus/`, that implements the core +modbus logic and integrates that directory into the NuttX build system. The +mapping between `freemodbus-v1.5.0` and the nuttx directories is shown below: - --------------------------- ---------------------------------------------- - freemodbus-v1.5.0 NuttX - --------------------------- ---------------------------------------------- - All top level .txt files Not included - demo/ Not included. This directory contains demo - and porting code for a variety of platforms. - The NuttX demo was ported from the LINUX - demo in this directory and can be found at - apps/examples/modbus. - doc/ Not included. This directory contains Doxygen - support files. - modbus/ Included in its entirety in various locations: - ascii apps/modbus/ascii - functions apps/modbus/functions - include apps/include/modbus - mb.c apps/modbus/mb.c - rtu apps/modbus/rtu - tcp apps/modbus/tcp - tools/ Not included. This directory contains Doxygen - tools. - --------------------------- ---------------------------------------------- +``` +--------------------------- ---------------------------------------------- +freemodbus-v1.5.0 NuttX +--------------------------- ---------------------------------------------- +All top level .txt files Not included +demo/ Not included. This directory contains demo + and porting code for a variety of platforms. + The NuttX demo was ported from the LINUX + demo in this directory and can be found at + apps/examples/modbus. +doc/ Not included. This directory contains Doxygen + support files. +modbus/ Included in its entirety in various locations: + ascii apps/modbus/ascii + functions apps/modbus/functions + include apps/include/modbus + mb.c apps/modbus/mb.c + rtu apps/modbus/rtu + tcp apps/modbus/tcp +tools/ Not included. This directory contains Doxygen + tools. +--------------------------- ---------------------------------------------- +``` -So this directory is equivalent to the freemodbus-v1.5.0/modbus -directory except that (1) it may include modifications for the integration -with NuttX and (2) the modbus/include directory was moved to apps/modbus. +So this directory is equivalent to the `freemodbus-v1.5.0/modbus` directory +except that (1) it may include modifications for the integration with NuttX and +(2) the modbus/include directory was moved to `apps/modbus`. -The original, unmodified freemodbus-v1.5.0 was checked in as SVN revision -4960. +The original, unmodified `freemodbus-v1.5.0` was checked in as SVN revision +`4960`. -The other directory here, nuttx/, implements the NuttX modbus interface. -It derives from the freemodbus-v1.5.0/demo/LINUX/port directory. +The other directory here, `nuttx/`, implements the NuttX modbus interface. It +derives from the `freemodbus-v1.5.0/demo/LINUX/port` directory. -Configuration Options -===================== +## Configuration Options -In the original freemodbus-v1.5.0 release, the FreeModBus configuration -was controlled by the header file mbconfig.h. This header file was -eliminated (post revision 4960) and the FreeModBus configuration -was integrated into the NuttX configuration system. +In the original `freemodbus-v1.5.0` release, the FreeModBus configuration was +controlled by the header file `mbconfig.h`. This header file was eliminated +(post revision `4960`) and the FreeModBus configuration was integrated into the +NuttX configuration system. The NuttX-named configuration options that are available include: - CONFIG_MODBUS - General ModBus support - CONFIG_MB_ASCII_ENABLED - Modbus ASCII support - CONFIG_MB_ASCII_MASTER - Modbus ASCII master support - CONFIG_MB_RTU_ENABLED - Modbus RTU support - CONFIG_MB_RTU_MASTER - Modbus RTU master support - CONFIG_MB_TCP_ENABLED - Modbus TCP support - CONFIG_MB_ASCII_TIMEOUT_SEC - Character timeout value for Modbus ASCII. The - character timeout value is not fixed for Modbus ASCII and is therefore - a configuration option. It should be set to the maximum expected delay - time of the network. Default 1 - CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS - Timeout to wait in ASCII prior - to enabling transmitter. If defined the function calls - vMBPortSerialDelay with the argument CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS - to allow for a delay before the serial transmitter is enabled. This is - required because some targets are so fast that there is no time between - receiving and transmitting the frame. If the master is too slow with - enabling its receiver then it will not receive the response correctly. - CONFIG_MB_FUNC_HANDLERS_MAX - Maximum number of Modbus functions codes the - protocol stack should support. The maximum number of supported Modbus - functions must be greater than the sum of all enabled functions in this - file and custom function handlers. If set too small, adding more - functions will fail. - CONFIG_MB_FUNC_OTHER_REP_SLAVEID_BUF - Number of bytes which should be - allocated for the Report Slave ID command. This number limits the - maximum size of the additional segment in the report slave id function. - See eMBSetSlaveID() for more information on how to set this value. It - is only used if CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED is set to 1. - CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED - If the Report Slave ID - function should be enabled. - CONFIG_MB_FUNC_READ_INPUT_ENABLED - If the Read Input Registers function - should be enabled. - CONFIG_MB_FUNC_READ_HOLDING_ENABLED - If the Read Holding Registers - function should be enabled. - CONFIG_MB_FUNC_WRITE_HOLDING_ENABLED - If the Write Single Register - function should be enabled. - CONFIG_MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED - If the Write Multiple - registers function should be enabled. - CONFIG_MB_FUNC_READ_COILS_ENABLED - If the Read Coils function should - be enabled. - CONFIG_MB_FUNC_WRITE_COIL_ENABLED - If the Write Coils function should - be enabled. - CONFIG_MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED - If the Write Multiple Coils - function should be enabled. - CONFIG_MB_FUNC_READ_DISCRETE_INPUTS_ENABLED - If the Read Discrete Inputs - function should be enabled. - CONFIG_MB_FUNC_READWRITE_HOLDING_ENABLED - If the Read/Write Multiple - Registers function should be enabled. +- `CONFIG_MODBUS` – General ModBus support. +- `CONFIG_MB_ASCII_ENABLED` – Modbus ASCII support. +- `CONFIG_MB_ASCII_MASTER` – Modbus ASCII master support. +- `CONFIG_MB_RTU_ENABLED` – Modbus RTU support. +- `CONFIG_MB_RTU_MASTER` – Modbus RTU master support. +- `CONFIG_MB_TCP_ENABLED` – Modbus TCP support. +- `CONFIG_MB_ASCII_TIMEOUT_SEC` – Character timeout value for Modbus ASCII. The + character timeout value is not fixed for Modbus ASCII and is therefore a + configuration option. It should be set to the maximum expected delay time of + the network. Default: `1`. +- `CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS` – Timeout to wait in ASCII prior + to enabling transmitter. If defined the function calls `vMBPortSerialDelay` + with the argument `CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS` to allow for a + delay before the serial transmitter is enabled. This is required because some + targets are so fast that there is no time between receiving and transmitting + the frame. If the master is too slow with enabling its receiver then it will + not receive the response correctly. +- `CONFIG_MB_FUNC_HANDLERS_MAX` – Maximum number of Modbus functions codes the + protocol stack should support. The maximum number of supported Modbus + functions must be greater than the sum of all enabled functions in this file + and custom function handlers. If set too small, adding more functions will + fail. +- `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_BUF` – Number of bytes which should be + allocated for the Report Slave ID command. This number limits the maximum size + of the additional segment in the report slave id function. See + `eMBSetSlaveID()` for more information on how to set this value. It is only + used if `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED` is set to `1`. +- `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED` – If the Report Slave ID function + should be enabled. +- `CONFIG_MB_FUNC_READ_INPUT_ENABLED` – If the Read Input Registers function + should be enabled. +- `CONFIG_MB_FUNC_READ_HOLDING_ENABLED` – If the Read Holding Registers function + should be enabled. +- `CONFIG_MB_FUNC_WRITE_HOLDING_ENABLED` – If the Write Single Register function + should be enabled. +- `CONFIG_MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED` – If the Write Multiple + registers function should be enabled. +- `CONFIG_MB_FUNC_READ_COILS_ENABLED` – If the Read Coils function should be + enabled. +- `CONFIG_MB_FUNC_WRITE_COIL_ENABLED` – If the Write Coils function should be + enabled. +- `CONFIG_MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED` – If the Write Multiple Coils + function should be enabled. +- `CONFIG_MB_FUNC_READ_DISCRETE_INPUTS_ENABLED` – If the Read Discrete Inputs + function should be enabled. +- `CONFIG_MB_FUNC_READWRITE_HOLDING_ENABLED` – If the Read/Write Multiple + Registers function should be enabled. See also other serial settings, in particular: - CONFIG_SERIAL_TERMIOS - Serial driver supports termios.h interfaces (tcsetattr, - tcflush, etc.). If this is not defined, then the terminal settings (baud, - parity, etc.) are not configurable at runtime; serial streams will not be - flushed when closed. +- `CONFIG_SERIAL_TERMIOS` – Serial driver supports `termios.h` interfaces + (`tcsetattr`, `tcflush`, etc.). If this is not defined, then the terminal + settings (baud, parity, etc.) are not configurable at runtime; serial streams + will not be flushed when closed. -Note -==== +## Note The developer of FreeModBus, Christian Walter, is still developing Modbus -libraries, although they are now commercial. See +libraries, although they are now commercial. See http://www.embedded-solutions.at/ for further information. diff --git a/netutils/README.md b/netutils/README.md index c6fef25a8..3ddf9a93f 100644 --- a/netutils/README.md +++ b/netutils/README.md @@ -1,138 +1,138 @@ -netutils README.txt -^^^^^^^^^^^^^^^^^^^ +# Network Utilities -Contents --------- +## Contents - - uIP Applications - - Other Network Applications - - Tips for Using Telnetd - - Tips for Using DHCPC +- uIP Applications +- Other Network Applications +- Tips for Using Telnetd +- Tips for Using DHCPC -uIP Applications -^^^^^^^^^^^^^^^^ +## uIP Applications -This directory contains most of the network applications contained -under the uIP-1.0 apps directory. As the uIP apps/README says, -these applications "are not all heavily tested." These uIP-based -apps include: +This directory contains most of the network applications contained under the +`uIP-1.0` apps directory. As the uIP `apps/README.md` says, these applications +_are not all heavily tested_. These uIP-based apps include: - dhcpc - Dynamic Host Configuration Protocol (DHCP) client. See - apps/include/netutils/dhcpc.h for interface information. - smtp - Simple Mail Transfer Protocol (SMTP) client. See - apps/include/netutils/smtp.h for interface information. - webclient - HTTP web client. See apps/include/netutils/webclient.h - for interface information. - webserver - HTTP web server. See apps/include/netutils/httpd.h - for interface information. +- `dhcpc` – Dynamic Host Configuration Protocol (DHCP) client. See + `apps/include/netutils/dhcpc.h` for interface information. -You may find additional information on these apps in the uIP forum -accessible through: http://www.sics.se/~adam/uip/index.php/Main_Page . -Some of these (such as the uIP web server) have grown some additional -functionality due primarily to NuttX user contributions. +- `smtp` – Simple Mail Transfer Protocol (SMTP) client. See + `apps/include/netutils/smtp.h` for interface information. -Other Network Applications -^^^^^^^^^^^^^^^^^^^^^^^^^^ +- `webclient` – HTTP web client. See `apps/include/netutils/webclient.h` for + interface information. -Additional applications that were not part of uIP (but which are -highly influenced by uIP) include: +- `webserver` – HTTP web server. See `apps/include/netutils/httpd.h` for + interface information. - dhcpd - Dynamic Host Configuration Protocol (DHCP) server. See - apps/include/netutils/dhcpd.h for interface information. - discover - This daemon is useful for discovering devices in local - networks, especially with DHCP configured devices. It - listens for UDP broadcasts which also can include a - device class so that groups of devices can be discovered. - It is also possible to address all classes with a kind of - broadcast discover. (Contributed by Max Holtzberg). - esp8266 - An ESP8266 networking layer contributed by Pierre-noel - Bouteville - json - cJSON is an ultra-lightweight, portable, single-file, - simple-as-can-be ANSI-C compliant JSON parser, under MIT - license. Embeddable Lightweight XML-RPC Server discussed at - http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364. - This code was taken from http://sourceforge.net/projects/cjson/ - and adapted for NuttX by Darcy Gong. - tftpc - TFTP client. See apps/include/netutils/tftp.h - for interface information. - telnetc - This is a port of libtelnet to NuttX. This is a public domain - Telnet client library available from - https://github.com/seanmiddleditch/libtelnet modified for use - with NuttX. Original Authors: Sean Middleditch , - Jack Kelly , and Katherine Flavel - - telnetd - TELNET server. This is the Telnet logic adapted from - uIP and generalized for use as the front end to any - shell. The telnet daemon creates sessions that are - "wrapped" as character devices and mapped to stdin, - stdout, and stderr. Now the telnet session can be - inherited by spawned tasks. - ftpc - FTP client. See apps/include/netutils/ftpc.h for interface - information. - ftpd - FTP server. See apps/include/netutils/ftpd.h for interface - information. - ntpclient - This is a fragmentary NTP client. It neither well-tested - nor mature nor complete at this point in time. - thttpd - This is a port of Jef Poskanzer's THTTPD HTPPD server. - 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 the following definitions in the - defconfig file to select the appropriate netutils - libraries: +You may find additional information on these apps in the uIP forum accessible +through: http://www.sics.se/~adam/uip/index.php/Main_Page. Some of these (such +as the uIP web server) have grown some additional functionality due primarily to +NuttX user contributions. - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_THTTPD=y +## Other Network Applications - xmlrpc - The Embeddable Lightweight XML-RPC Server discussed at - http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364 +Additional applications that were not part of uIP (but which are highly +influenced by uIP) include: - ping - This is an unfinished implementation of ping and ping6 using - raw sockets. It is not yet hooked into the configuration or - build systems. +- `dhcpd` – Dynamic Host Configuration Protocol (DHCP) server. See + `apps/include/netutils/dhcpd.h` for interface information. - Current ping/ping6 logic in NSH makes illegal calls into the - OS in order to implement ping/ping6. One correct - implementation would be to use raw sockets to implement ping/ - ping6 as a user application. This is a first cut at such an - implementation. +- `discover` – This daemon is useful for discovering devices in local networks, + especially with DHCP configured devices. It listens for UDP broadcasts which + also can include a device class so that groups of devices can be discovered. + It is also possible to address all classes with a kind of broadcast discover. + (Contributed by Max Holtzberg). -Tips for Using Telnetd -^^^^^^^^^^^^^^^^^^^^^^ +- `esp8266` – An ESP8266 networking layer contributed by Pierre-Noel Bouteville. -Telnetd is set up to be the front end for a shell. The primary use of -Telnetd in NuttX is to support the NuttShell (NSH) Telnet front end. See -apps/include/netutils/telnetd.h for information about how to incorporate +- `json` – cJSON is an ultra-lightweight, portable, single-file, + simple-as-can-be ANSI-C compliant JSON parser, under MIT license. Embeddable + Lightweight XML-RPC Server discussed at + http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364. + + This code was taken from http://sourceforge.net/projects/cjson/ and adapted + for NuttX by Darcy Gong. + +- `tftpc` – TFTP client. See `apps/include/netutils/tftp.h` for interface + information. + +- `telnetc` – This is a port of libtelnet to NuttX. This is a public domain + Telnet client library available from + https://github.com/seanmiddleditch/libtelnet modified for use with NuttX. + Original Authors: Sean Middleditch , Jack Kelly + and Katherine Flavel + +- `telnetd` – TELNET server. This is the Telnet logic adapted from uIP and + generalized for use as the front end to any shell. The telnet daemon creates + sessions that are _wrapped_ as character devices and mapped to `stdin`, + `stdout` and `stderr`. Now the telnet session can be inherited by spawned + tasks. + +- `ftpc` – FTP client. See `apps/include/netutils/ftpc.h` for interface + information. + +- `ftpd` – FTP server. See `apps/include/netutils/ftpd.h` for interface + information. + +- `ntpclient` – This is a fragmentary NTP client. It neither well-tested nor + mature nor complete at this point in time. + +- `thttpd` – This is a port of Jef Poskanzer's THTTPD HTPPD server. 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 the following definitions in the + `defconfig` file to select the appropriate `netutils` libraries: + + ```conf + CONFIG_NETUTILS_NETLIB=y + CONFIG_NETUTILS_THTTPD=y + ``` + +- `xmlrpc` – The Embeddable Lightweight XML-RPC Server discussed at + http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364 + +- `ping` – This is an unfinished implementation of ping and ping6 using raw + sockets. It is not yet hooked into the configuration or build systems. + + Current `ping`/`ping6` logic in NSH makes illegal calls into the OS in order + to implement `ping`/`ping6`. One correct implementation would be to use raw + sockets to implement `ping`/`ping6` as a user application. This is a first cut + at such an implementation. + +## Tips for Using Telnetd + +Telnetd is set up to be the front end for a shell. The primary use of 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 defconfig file: +To enable and link the Telnetd daemon, you need to include the following in in +your defconfig file: - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_TELNETD=y +```conf +CONFIG_NETUTILS_NETLIB=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 +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. +- `CONFIG_STDIO_BUFFER_SIZE` – Some value `>= 64`. +- `CONFIG_STDIO_LINEBUFFER=y` – Since Telnetd is line oriented, line buffering + is optimal. -Tips for Using DHCPC -^^^^^^^^^^^^^^^^^^^^ +## Tips for Using DHCPC If you use DHCPC/D, then some special configuration network options are -required. These include: +required. These include: - CONFIG_NET=y Of course - CONFIG_NET_UDP=y UDP support is required for DHCP - (as well as various other UDP-related - configuration settings). - CONFIG_NET_BROADCAST=y UDP broadcast support is needed. - CONFIG_NET_ETH_PKTSIZE=650 The client must be prepared to receive - (or larger) DHCP messages of up to 576 bytes (excluding - Ethernet, IP, or UDP headers and FCS). - NOTE: Note that the actual MTU setting will - depend upon the specific link protocol. - Here Ethernet is indicated. +- `CONFIG_NET=y` +- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various + other UDP-related configuration settings). +- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed. +- `CONFIG_NET_ETH_PKTSIZE=650` or larger. The client must be prepared to receive + DHCP messages of up to `576` bytes (excluding Ethernet, IP or UDP headers and + FCS). **Note**: Note that the actual MTU setting will depend upon the specific + link protocol. Here Ethernet is indicated. diff --git a/netutils/discover/README.md b/netutils/discover/README.md index 11aab8bf3..f5516a7e3 100644 --- a/netutils/discover/README.md +++ b/netutils/discover/README.md @@ -1,9 +1,8 @@ -apps/netutils/discover README.txt -================================= +# Network Utilities / `discover` -This daemon is useful for discovering devices in local networks, especially -with DHCP configured devices. It listens for UDP broadcasts which also can -include a device class so that groups of devices can be discovered. It is -also possible to address all classes with a kind of broadcast discover. +This daemon is useful for discovering devices in local networks, especially with +DHCP configured devices. It listens for UDP broadcasts which also can include a +device class so that groups of devices can be discovered. It is also possible to +address all classes with a kind of broadcast discover. -See nuttx/tools/discover.py for a client example. +See `nuttx/tools/discover.py` for a client example. diff --git a/netutils/ftpc/README.md b/netutils/ftpc/README.md index d995227c7..b84980720 100644 --- a/netutils/ftpc/README.md +++ b/netutils/ftpc/README.md @@ -1,81 +1,81 @@ -/* FTP Commands *************************************************************/ -/* Command summary: - * - * ABOR - abort a file transfer - * ACCT - send account information - * APPE - append to a remote file - * CDUP - CWD to the parent of the current directory - * CWD - change working directory - * DELE - delete a remote file - * HELP - return help on using the server - * LIST - list remote files - * MDTM - return the modification time of a file - * MKD - make a remote directory - * MLSD - Standardized directory listing (instead of LIST) - * MLST - Standardized object listing (instead of LIST) - * MODE - set transfer mode - * NLST - name list of remote directory - * NOOP - do nothing - * PASS - send password - * PASV - enter passive mode - * PORT - open a data port - * PWD - print working directory - * QUIT - terminate the connection - * REIN - reinitialize the connection - * RETR - retrieve a remote file - * REST - Sets the point at which a file transfer should start - * RMD - remove a remote directory - * RNFR - rename from - * RNTO - rename to - * SITE - site-specific commands - * SIZE - return the size of a file - * STOR - store a file on the remote host - * STOU - store a file uniquely - * STRU - set file transfer structure - * STAT - return server status - * SYST - return system type - * TYPE - set transfer type - * USER - send username - * -/* FTP Replies **************************************************************/ - * - * 110 - Restart marker reply. - * 120 - Service ready in nnn minutes. - * 125 - Data connection already open; transfer starting. - * 150 - File status okay; about to open data connection. - * 200 - Command okay. - * 202 - Command not implemented, superfluous at this site. - * 211 - System status, or system help reply. - * 212 - Directory status. - * 213 - File status. - * 214 - Help message. - * 215 - NAME system type. - * 220 - Service ready for new user. - * 221 - Service closing control connection. - * 225 - Data connection open; no transfer in progress. - * 226 - Closing data connection. - * 227 - Entering Passive Mode (h1,h2,h3,h4,p1,p2). - * 230 - User logged in, proceed. - * 250 - Requested file action okay, completed. - * 257 - "PATHNAME" created. - * 331 - User name okay, need password. - * 332 - Need account for login. - * 350 - Requested file action pending further information. - * 421 - Service not available, closing control connection. - * 425 - Can't open data connection. - * 426 - Connection closed; transfer aborted. - * 450 - Requested file action not taken. - * 451 - Requested action aborted: local error in processing. - * 452 - Requested action not taken. - * 500 - Syntax error, command unrecognized. - * 501 - Syntax error in parameters or arguments. - * 502 - Command not implemented. - * 503 - Bad sequence of commands. - * 504 - Command not implemented for that parameter. - * 530 - Not logged in. - * 532 - Need account for storing files. - * 550 - Requested action not taken. - * 551 - Requested action aborted: page type unknown. - * 552 - Requested file action aborted. - * 553 - Requested action not taken. - */ +# Network Utilities / `ftpc` FTP Client + +## FTP Commands + +- `ABOR` – abort a file transfer +- `ACCT` – send account information +- `APPE` – append to a remote file +- `CDUP` – CWD to the parent of the current directory +- `CWD` – change working directory +- `DELE` – delete a remote file +- `HELP` – return help on using the server +- `LIST` – list remote files +- `MDTM` – return the modification time of a file +- `MKD` – make a remote directory +- `MLSD` – Standardized directory listing (instead of `LIST`) +- `MLST` – Standardized object listing (instead of `LIST`) +- `MODE` – set transfer mode +- `NLST` – name list of remote directory +- `NOOP` – do nothing +- `PASS` – send password +- `PASV` – enter passive mode +- `PORT` – open a data port +- `PWD` – print working directory +- `QUIT` – terminate the connection +- `REIN` – reinitialize the connection +- `RETR` – retrieve a remote file +- `REST` – Sets the point at which a file transfer should start +- `RMD` – remove a remote directory +- `RNFR` – rename from +- `RNTO` – rename to +- `SITE` – site-specific commands +- `SIZE` – return the size of a file +- `STOR` – store a file on the remote host +- `STOU` – store a file uniquely +- `STRU` – set file transfer structure +- `STAT` – return server status +- `SYST` – return system type +- `TYPE` – set transfer type +- `USER` – send username + +## FTP Replies + +- `110` – Restart marker reply. +- `120` – Service ready in nnn minutes. +- `125` – Data connection already open; transfer starting. +- `150` – File status okay; about to open data connection. +- `200` – Command okay. +- `202` – Command not implemented, superfluous at this site. +- `211` – System status, or system help reply. +- `212` – Directory status. +- `213` – File status. +- `214` – Help message. +- `215` – NAME system type. +- `220` – Service ready for new user. +- `221` – Service closing control connection. +- `225` – Data connection open; no transfer in progress. +- `226` – Closing data connection. +- `227` – Entering Passive Mode (`h1`, `h2`, `h3`, `h4`, `p1`, `p2`). +- `230` – User logged in, proceed. +- `250` – Requested file action okay, completed. +- `257` – `PATHNAME` created. +- `331` – User name okay, need password. +- `332` – Need account for login. +- `350` – Requested file action pending further information. +- `421` – Service not available, closing control connection. +- `425` – Can't open data connection. +- `426` – Connection closed; transfer aborted. +- `450` – Requested file action not taken. +- `451` – Requested action aborted: local error in processing. +- `452` – Requested action not taken. +- `500` – Syntax error, command unrecognized. +- `501` – Syntax error in parameters or arguments. +- `502` – Command not implemented. +- `503` – Bad sequence of commands. +- `504` – Command not implemented for that parameter. +- `530` – Not logged in. +- `532` – Need account for storing files. +- `550` – Requested action not taken. +- `551` – Requested action aborted: page type unknown. +- `552` – Requested file action aborted. +- `553` – Requested action not taken. diff --git a/netutils/telnetd/README.md b/netutils/telnetd/README.md index 367cef0a2..30135542e 100644 --- a/netutils/telnetd/README.md +++ b/netutils/telnetd/README.md @@ -1,4 +1,3 @@ -README.txt -^^^^^^^^^^ +# Network Utilities / `telnetd` Telnet Daemon This directly contains a generic Telnet daemon. diff --git a/nshlib/README.md b/nshlib/README.md index a6379d1e1..c711e16c4 100644 --- a/nshlib/README.md +++ b/nshlib/README.md @@ -1,213 +1,235 @@ -apps/nshlib -^^^^^^^^^^^ +# `nshlib` NuttShell (NSH) - This directory contains the NuttShell (NSH) library. This library can be - linked with other logic to provide a simple shell application for NuttX. +This directory contains the NuttShell (NSH) library. This library can be linked +with other logic to provide a simple shell application for NuttX. - - Console/NSH Front End - - Command Overview - - Conditional Command Execution - - Looping - - Built-In Variables - - Current Working Directory - Environment Variables - - NSH Start-Up Script - - Simple Commands - - Built-In Applications - - NSH Configuration Settings - Command Dependencies on Configuration Settings - Built-in Application Configuration Settings - NSH-Specific Configuration Settings - - Common Problems +- Console/NSH Front End +- Command Overview +- Conditional Command Execution +- Looping +- Built-In Variables +- Current Working Directory + - Environment Variables +- NSH Start-Up Script +- Simple Commands +- Built-In Applications +- NSH Configuration Settings + - Command Dependencies on Configuration Settings + - Built-in Application Configuration Settings + - NSH-Specific Configuration Settings +- Common Problems -Console/NSH Front End -^^^^^^^^^^^^^^^^^^^^^ +## Console / NSH Front End - Using settings in the configuration file, NSH may be configured to - use either the serial stdin/out or a telnet connection as the console - or BOTH. When NSH is started, you will see the following welcome on - either console: +Using settings in the configuration file, NSH may be configured to use either +the serial `stdin`/`out` or a telnet connection as the console or BOTH. When NSH +is started, you will see the following welcome on either console: - NuttShell (NSH) - nsh> +``` +NuttShell (NSH) +nsh> +``` - 'nsh>' is the NSH prompt and indicates that you may enter a command - from the console. +`nsh>` is the NSH prompt and indicates that you may enter a command from the +console. -Command Overview -^^^^^^^^^^^^^^^^ +## Command Overview - This directory contains the NuttShell (NSH). This is a simple - shell-like application. At present, NSH supports the following commands - forms: +This directory contains the NuttShell (NSH). This is a simple shell-like +application. At present, NSH supports the following commands forms: - Simple command: - Command with re-directed output: > - >> - Background command: & - Re-directed background command: > & - >> & +- Simple command: - Where: + ``` + + ``` - is any one of the simple commands listed later. - is the full or relative path to any writeable object - in the file system name space (file or character driver). - Such objects will be referred to simply as files throughout - this README. +- Command with re-directed output: - NSH executes at the mid-priority (128). Backgrounded commands can - be made to execute at higher or lower priorities using nice: + ``` + > + >> + ``` - [nice [-d >]] [> |>> ] [&] +- Background command: - Where is any value between -20 and 19 where lower - (more negative values) correspond to higher priorities. The - default niceness is 10. + ``` + & + ``` - Multiple commands per line. NSH will accept multiple commands per - command line with each command separated with the semi-colon character (;). +- Re-directed background command: - If CONFIG_NSH_CMDPARMS is selected, then the output from commands, from - file applications, and from NSH built-in commands can be used as arguments - to other commands. The entity to be executed is identified by enclosing - the command line in back quotes. For example, + ``` + > & + >> & + ``` - set FOO `myprogram $BAR` +Where: - Will execute the program named myprogram passing it the value of the - environment variable BAR. The value of the environment variable FOO - is then set output of myprogram on stdout. Because this feature commits - significant resources, it is disabled by default. +- `` - is any one of the simple commands listed later. +- `` - is the full or relative path to any writeable object in the file + system name space (file or character driver). Such objects will be referred to + simply as files throughout this README. - If CONFIG_NSH_ARGCAT is selected, the support concatenation of strings - with environment variables or command output. For example: +NSH executes at the mid-priority (`128`). Backgrounded commands can be made to +execute at higher or lower priorities using nice: - set FOO XYZ - set BAR 123 - set FOOBAR ABC_${FOO}_${BAR} +``` +[nice [-d >]] [> |>> ] [&] +``` - would set the environment variable FOO to XYZ, BAR to 123 and FOOBAR - to ABC_XYZ_123. If NSH_ARGCAT is not selected, then a slightly small - FLASH footprint results but then also only simple environment - variables like $FOO can be used on the command line. +Where `` is any value between `-20` and `19` where lower (more +negative values) correspond to higher priorities. The default niceness is `10`. - CONFIG_NSH_QUOTE enables back-slash quoting of certain characters within - the command. This option is useful for the case where an NSH script is - used to dynamically generate a new NSH script. In that case, commands - must be treated as simple text strings without interpretation of any - special characters. Special characters such as $, `, ", and others must - be retained intact as part of the test string. This option is currently - only available is CONFIG_NSH_ARGCAT is also selected. +Multiple commands per line. NSH will accept multiple commands per command line +with each command separated with the semi-colon character (`;`). -Conditional Command Execution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If `CONFIG_NSH_CMDPARMS` is selected, then the output from commands, from file +applications, and from NSH built-in commands can be used as arguments to other +commands. The entity to be executed is identified by enclosing the command line +in back quotes. For example, - An if-then[-else]-fi construct is also supported in order to - support conditional execution of commands. This works from the - command line but is primarily intended for use within NSH scripts - (see the sh command). The syntax is as follows: +```shell +set FOO `myprogram $BAR` +``` - if [!] - then - [sequence of ] - else - [sequence of ] - fi +Will execute the program named myprogram passing it the value of the environment +variable `BAR`. The value of the environment variable `FOO` is then set output +of myprogram on stdout. Because this feature commits significant resources, it +is disabled by default. -Looping -^^^^^^^ +If `CONFIG_NSH_ARGCAT` is selected, the support concatenation of strings with +environment variables or command output. For example: - while-do-done and until-do-done looping constructs are also supported. - These works from the command line but are primarily intended for use - within NSH scripts (see the sh command). The syntax is as follows: +```shell +set FOO XYZ +set BAR 123 +set FOOBAR ABC_${FOO}_${BAR} +``` - while ; do ; done +would set the environment variable `FOO` to `XYZ`, `BAR` to `123` and `FOOBAR` +to `ABC_XYZ_123`. If `NSH_ARGCAT` is not selected, then a slightly small FLASH +footprint results but then also only simple environment variables like `$FOO` +can be used on the command line. - Execute as long as has an exit status of - zero. +`CONFIG_NSH_QUOTE` enables back-slash quoting of certain characters within the +command. This option is useful for the case where an NSH script is used to +dynamically generate a new NSH script. In that case, commands must be treated as +simple text strings without interpretation of any special characters. Special +characters such as `$`, `` ` ``, `"`, and others must be retained intact as part of +the test string. This option is currently only available is `CONFIG_NSH_ARGCAT` +is also selected. - until ; do ; done +## Conditional Command Execution - Execute as long as has a non-zero exit - status. +An `if-then[-else]-fi` construct is also supported in order to support +conditional execution of commands. This works from the command line but is +primarily intended for use within NSH scripts (see the `sh` command). The syntax +is as follows: - A break command is also supported. The break command is only meaningful - within the body of the a while or until loop, between the do and done - tokens. If the break command is executed within the body of a loop, the - loop will immediately terminate and execution will continue with the - next command immediately following the done token. +``` +if [!] +then + [sequence of ] +else + [sequence of ] +fi +``` -Built-In Variables -^^^^^^^^^^^^^^^^^^ +## Looping - $? - The result of the last simple command execution +`while-do-done` and `until-do-done` looping constructs are also supported. These +works from the command line but are primarily intended for use within NSH +scripts (see the `sh` command). The syntax is as follows: -Current Working Directory -^^^^^^^^^^^^^^^^^^^^^^^^^ +``` +while ; do ; done +``` - All path arguments to commands may be either an absolute path or a - path relative to the current working directory. The current working - directory is set using the 'cd' command and can be queried either - by using the 'pwd' command or by using the 'echo $PWD' command. +(Execute `` as long as `` has an exit status of zero.) - Environment Variables: - ---------------------- +``` +until ; do ; done +``` - PWD - The current working directory - OLDPWD - The previous working directory +(Execute `` as long as `` has a non-zero exit status.) -NSH Start-Up Script -^^^^^^^^^^^^^^^^^^^ +A break command is also supported. The break command is only meaningful within +the body of the a `while` or `until` loop, between the do and done tokens. If +the break command is executed within the body of a loop, the loop will +immediately terminate and execution will continue with the next command +immediately following the done token. -NSH supports options to provide a start up script for NSH. In general -this capability is enabled with CONFIG_NSH_ROMFSETC, but has -several other related configuration options as described in the final -section of this README. This capability also depends on: +## Built-In Variables - - CONFIG_DISABLE_MOUNTPOINT not set - - CONFIG_NFILE_DESCRIPTORS > 4 - - CONFIG_FS_ROMFS +- `$?` - The result of the last simple command execution. -Default Start-Up Behavior -------------------------- +## Current Working Directory -The implementation that is provided is intended to provide great flexibility -for the use of Start-Up files. This paragraph will discuss the general -behavior when all of the configuration options are set to the default -values. +All path arguments to commands may be either an absolute path or a path relative +to the current working directory. The current working directory is set using the +`cd` command and can be queried either by using the `pwd` command or by using +the `echo $PWD` command. -In this default case, enabling CONFIG_NSH_ROMFSETC will cause -NSH to behave as follows at NSH startup time: +### Environment Variables: -- NSH will create a read-only RAM disk (a ROM disk), containing a tiny - ROMFS file system containing the following: +- `PWD` - The current working directory +- `OLDPWD` - The previous working directory - |--init.d/ - `-- rcS +## NSH Start-Up Script - Where rcS is the NSH start-up script +NSH supports options to provide a start up script for NSH. In general this +capability is enabled with `CONFIG_NSH_ROMFSETC`, but has several other related +configuration options as described in the final section of this README. This +capability also depends on: -- NSH will then mount the ROMFS file system at /etc, resulting in: +- `CONFIG_DISABLE_MOUNTPOINT` not set +- `CONFIG_NFILE_DESCRIPTORS > 4` +- `CONFIG_FS_ROMFS` +### Default Start-Up Behavior + +The implementation that is provided is intended to provide great flexibility for +the use of Start-Up files. This paragraph will discuss the general behavior when +all of the configuration options are set to the default values. + +In this default case, enabling `CONFIG_NSH_ROMFSETC` will cause NSH to behave as +follows at NSH startup time: + +- NSH will create a read-only RAM disk (a ROM disk), containing a tiny ROMFS + file system containing the following: + + ``` + | `--init.d/ + `-- rcS + ```` + + Where `rcS` is the NSH start-up script + +- NSH will then mount the ROMFS file system at `/etc`, resulting in: + + ``` |--dev/ | `-- ram0 `--etc/ `--init.d/ `-- rcS + ``` -- By default, the contents of rcS script are: +- By default, the contents of `rcS` script are: - # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX + ```shell + # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX - mkrd -m 1 -s 512 1024 - mkfatfs /dev/ram1 - mount -t vfat /dev/ram1 /tmp + mkrd -m 1 -s 512 1024 + mkfatfs /dev/ram1 + mount -t vfat /dev/ram1 /tmp + ``` -- NSH will execute the script at /etc/init.d/rcS at start-up (before the - first NSH prompt. After execution of the script, the root FS will look - like: +- NSH will execute the script at `/etc/init.d/rcS` at start-up (before the first + NSH prompt. After execution of the script, the root FS will look like: + ``` |--dev/ | |-- ram0 | `-- ram1 @@ -215,295 +237,306 @@ NSH to behave as follows at NSH startup time: | `--init.d/ | `-- rcS `--tmp/ + ``` -Modifying the ROMFS Image -------------------------- +### Modifying the ROMFS Image -The contents of the /etc directory are retained in the file -apps/nshlib/nsh_romfsimg.h (OR, if CONFIG_NSH_ARCHROMFS -is defined, include/arch/board/rcS.template). In order to modify -the start-up behavior, there are three things to study: +The contents of the `/etc` directory are retained in the file +`apps/nshlib/nsh_romfsimg.h` (OR, if `CONFIG_NSH_ARCHROMFS` is defined, +`include/arch/board/rcS.template`). In order to modify the start-up behavior, +there are three things to study: -1. Configuration Options. - The additional CONFIG_NSH_ROMFSETC configuration options - discussed in the final section of this README. +1. Configuration Options. + The additional `CONFIG_NSH_ROMFSETC` configuration options discussed in the + final section of this README. -2. tools/mkromfsimg.sh Script. - The script tools/mkromfsimg.sh creates nsh_romfsimg.h. - It is not automatically executed. If you want to change the - configuration settings associated with creating and mounting - the /tmp directory, then it will be necessary to re-generate - this header file using the mkromfsimg.sh script. +2. `tools/mkromfsimg.sh` Script. + The script `tools/mkromfsimg.sh` creates `nsh_romfsimg.h`. It is not + automatically executed. If you want to change the configuration settings + associated with creating and mounting the `/tmp` directory, then it will be + necessary to re-generate this header file using the `mkromfsimg.sh` script. The behavior of this script depends upon three things: - The configuration settings of the installed NuttX configuration. - The genromfs tool (available from http://romfs.sourceforge.net). - - The file apps/nshlib/rcS.template (OR, if - CONFIG_NSH_ARCHROMFS is defined, include/arch/board/rcs.template) + - The file `apps/nshlib/rcS.template` (OR, if `CONFIG_NSH_ARCHROMFS` is + defined, `include/arch/board/rcs.template`) -3. rcS.template. - The file apps/nshlib/rcS.template contains the general form - of the rcS file; configured values are plugged into this - template file to produce the final rcS file. +3. `rcS.template`. The file `apps/nshlib/rcS.template` contains the general form + of the `rcS` file; configured values are plugged into this template file to + produce the final `rcS` file. -NOTE: +**Note**: `apps/nshlib/rcS.template` generates the standard, default +`nsh_romfsimg.h` file. If `CONFIG_NSH_ARCHROMFS` is defined in the NuttX +configuration file, then a custom, board-specific `nsh_romfsimg.h` file residing +in `boards////include` will be used. **Note** when the OS is +configured, `include/arch/board` will be linked to +`boards////include`. - apps/nshlib/rcS.template generates the standard, default - nsh_romfsimg.h file. If CONFIG_NSH_ARCHROMFS is defined - in the NuttX configuration file, then a custom, board-specific - nsh_romfsimg.h file residing in boards////include - will be used. NOTE when the OS is configured, include/arch/board will - be linked to boards////include. +All of the startup-behavior is contained in `rcS.template`. The role of +`mkromfsimg.sh` is to (1) apply the specific configuration settings to +`rcS.template` to create the final `rcS`, and (2) to generate the header file +`nsh_romfsimg.h` containing the ROMFS file system image. -All of the startup-behavior is contained in rcS.template. The -role of mkromfsimg.sh is to (1) apply the specific configuration -settings to rcS.template to create the final rcS, and (2) to -generate the header file nsh_romfsimg.h containing the ROMFS -file system image. +## Simple Commands -Simple Commands -^^^^^^^^^^^^^^^ +- `[ ]` + `test ` -o [ ] -o test + These are two alternative forms of the same command. They support evaluation + of a boolean expression which sets `$?`. This command is used most frequently + as the conditional command following the `if` in the `if-then[-else]-fi` + construct. - These are two alternative forms of the same command. They support - evaluation of a boolean expression which sets $?. This command - is used most frequently as the conditional command following the - 'if' in the if-then[-else]-fi construct. + **Expression Syntax**: - Expression Syntax: - ------------------ + ``` + expression = simple-expression | !expression | + expression -o expression | expression -a expression - expression = simple-expression | !expression | - expression -o expression | expression -a expression + simple-expression = unary-expression | binary-expression - simple-expression = unary-expression | binary-expression + unary-expression = string-unary | file-unary - unary-expression = string-unary | file-unary + string-unary = -n string | -z string - string-unary = -n string | -z string + file-unary = -b file | -c file | -d file | -e file | -f file | + -r file | -s file | -w file - file-unary = -b file | -c file | -d file | -e file | -f file | - -r file | -s file | -w file + binary-expression = string-binary | numeric-binary - binary-expression = string-binary | numeric-binary + string-binary = string = string | string == string | string != string - string-binary = string = string | string == string | string != string + numeric-binary = integer -eq integer | integer -ge integer | + integer -gt integer | integer -le integer | + integer -lt integer | integer -ne integer + ``` - numeric-binary = integer -eq integer | integer -ge integer | - integer -gt integer | integer -le integer | - integer -lt integer | integer -ne integer +- `addroute [] ` + `addroute default ` -o addroute [] - addroute default - - This command adds an entry in the routing table. The new entry - will map the IP address of a router on a local network() - to an external network characterized by the IP address and - a network mask + This command adds an entry in the routing table. The new entry + will map the IP address of a router on a local network(``) + to an external network characterized by the `` IP address and + a network mask `` The netmask may also be expressed using IPv4 CIDR or IPv6 slash - notation. In that case, the netmask need not be provided. + notation. In that case, the netmask need not be provided. - Example: + **Example**: - nsh> addroute 11.0.0.0 255.255.255.0 10.0.0.2 + ``` + nsh> addroute 11.0.0.0 255.255.255.0 10.0.0.2 + ``` which is equivalent to - nsh> addroute 11.0.0.0/24 10.0.0.2 + ``` + nsh> addroute 11.0.0.0/24 10.0.0.2 + ``` - The second form of the addroute command can be used to set the default + The second form of the `addroute` command can be used to set the default gateway. -o arp [-t|-a |-d |-s ] +- `arp [-t|-a |-d |-s ]` Access the OS ARP table. - -a - Will show the hardware address that the IP address is mapped to. + - `-a ` + Will show the hardware address that the IP address `` is mapped to. - -d - Will delete the mapping for the IP address from the ARP table. + - `-d ` + Will delete the mapping for the IP address `` from the ARP table. - -s - Will set (or replace) the mapping of the IP address to the - hardware address . + - `-s ` + Will set (or replace) the mapping of the IP address `` to the + hardware address ``. - -t - Will dump the entire content of the ARP table. This option is only - available if CONFIG_NETLINK_ROUTE is enabled. + - `-t` + Will dump the entire content of the ARP table. This option is only + available if `CONFIG_NETLINK_ROUTE` is enabled. - Example: + **Example**: - nsh> arp -a 10.0.0.1 - nsh: arp: no such ARP entry: 10.0.0.1 + ``` + nsh> arp -a 10.0.0.1 + nsh: arp: no such ARP entry: 10.0.0.1 - nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6 - nsh> arp -a 10.0.0.1 - HWAddr: 00:13:3b:12:73:e6 + nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6 + nsh> arp -a 10.0.0.1 + HWAddr: 00:13:3b:12:73:e6 - nsh> arp -d 10.0.0.1 - nsh> arp -a 10.0.0.1 - nsh: arp: no such ARP entry: 10.0.0.1 + nsh> arp -d 10.0.0.1 + nsh> arp -a 10.0.0.1 + nsh: arp: no such ARP entry: 10.0.0.1 + ``` -o base64dec [-w] [-f] +- `base64dec [-w] [-f] ` -o base64dec [-w] [-f] +- `base64dec [-w] [-f] ` -o basename [] +- `basename []` - Extract the final string from a by removing the preceding path - segments and (optionally) removing any trailing . + Extract the final string from a `` by removing the preceding path + segments and (optionally) removing any trailing ``. -o break +- `break` - The break command is only meaningful within the body of the a while or - until loop, between the do and done tokens. Outside of a loop, break - command does nothing. If the break command is executed within the body - of a loop, the loop will immediately terminate and execution will - continue with the next command immediately following the done token. + The `break` command is only meaningful within the body of the a `while` or + `until` loop, between the do and done tokens. Outside of a loop, `break` + command does nothing. If the break command is executed within the body of a + loop, the loop will immediately terminate and execution will continue with the + next command immediately following the done token. -o cat [ [ ...]] +- `cat [ [ ...]]` - This command copies and concatenates all of the files at - to the console (or to another file if the output is redirected). + This command copies and concatenates all of the files at `` to the + console (or to another file if the output is redirected). -o cd [|-|~|..] +- `cd [|-|~|..]` - Changes the current working directory (PWD). Also sets the - previous working directory environment variable (OLDPWD). + Changes the current working directory (`PWD`). Also sets the previous working + directory environment variable (`OLDPWD`). - FORMS: - ------ + **Forms**: - 'cd ' sets the current working directory to . - 'cd -' sets the current working directory to the previous - working directory ($OLDPWD). Equivalent to 'cd $OLDPWD'. - 'cd' or 'cd ~' set the current working directory to the 'home' - directory. The 'home' directory can be configured by setting - CONFIG_LIB_HOMEDIR in the configuration file. The default - 'home' directory is '/'. - 'cd ..' sets the current working directory to the parent directory. + - `cd ` sets the current working directory to ``. + - `cd -` sets the current working directory to the previous working directory + (`$OLDPWD`). Equivalent to `cd $OLDPWD`. + - `cd` or `cd ~` set the current working directory to the _home_ directory. + The _home_ directory can be configured by setting `CONFIG_LIB_HOMEDIR` in + the configuration file. The default _home_ directory is `/`. + - `cd ..` sets the current working directory to the parent directory. -o cmp +- `cmp ` - Compare of the contents of the file at with the contents of - the file at . Returns an indication only if the files differ. + Compare of the contents of the file at `` with the contents of the file + at ``. Returns an indication only if the files differ. -o cp +- `cp ` - Copy of the contents of the file at to the location - in the file system indicated by + Copy of the contents of the file at `` to the location in the + file system indicated by `` -o date [-s "MMM DD HH:MM:SS YYYY"] +- `date [-s "MMM DD HH:MM:SS YYYY"]` Show or set the current date and time. Only one format is used both on display and when setting the date/time: - MMM DD HH:MM:SS YYYY. For example, + `MMM DD HH:MM:SS YYYY`. For example, - data -s "Sep 1 11:30:00 2011" + ```shell + data -s "Sep 1 11:30:00 2011" + ``` 24-hour time format is assumed. -o dd if= of= [bs=] [count=] [skip=] +- `dd if= of= [bs=] [count=] [skip=]` - Copy blocks from to . or may - be the path to a standard file, a character device, or a block device. + Copy blocks from `` to ``. `` or `` may be + the path to a standard file, a character device, or a block device. - Examples: + **Examples**: - 1. Read from character device, write to regular file. This will - create a new file of the specified size filled with zero. + 1. Read from character device, write to regular file. This will create a new + file of the specified size filled with zero. - nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16 - nsh> ls -l /tmp - /tmp: + ```shell + nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16 + nsh> ls -l /tmp + /tmp: -rw-rw-rw- 1024 ZEROS + ``` - 2. Read from character device, write to block device. This will - fill the entire block device with zeros. + 2. Read from character device, write to block device. This will fill the + entire block device with zeros. - nsh> ls -l /dev - /dev: - brw-rw-rw- 0 ram0 - crw-rw-rw- 0 zero - nsh> dd if=/dev/zero of=/dev/ram0 + ```shell + nsh> ls -l /dev + /dev: + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 zero + nsh> dd if=/dev/zero of=/dev/ram0 + ``` - 3. Read from a block device, write to a character device. This - will read the entire block device and dump the contents in - the bit bucket. + 3. Read from a block device, write to a character device. This will read the + entire block device and dump the contents in the bit bucket. - nsh> ls -l /dev - /dev: - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - nsh> dd if=/dev/ram0 of=/dev/null + ```shell + nsh> ls -l /dev + /dev: + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + nsh> dd if=/dev/ram0 of=/dev/null + ``` -o delroute [] +- `delroute []` - This command removes an entry from the routing table. The entry - removed will be the first entry in the routing table that matches - the external network characterized by the IP address and - the network mask + This command removes an entry from the routing table. The entry removed will + be the first entry in the routing table that matches the external network + characterized by the `` IP address and the network mask `` - The netmask may also be expressed using IPv4 CIDR or IPv6 slash - notation. In that case, the netmask need not be provided. + The netmask may also be expressed using IPv4 CIDR or IPv6 slash notation. In + that case, the netmask need not be provided. - Example: + **Example**: - nsh> delroute 11.0.0.0 255.255.255.0 + ``` + nsh> delroute 11.0.0.0 255.255.255.0 + ``` which is equivalent to - nsh> delroute 11.0.0.0/24 + ``` + nsh> delroute 11.0.0.0/24 + ``` -o df +- `df` Show the state of each mounted volume. - Example: + **Example**: + ``` nsh> mount - /etc type romfs - /tmp type vfat + /etc type romfs + /tmp type vfat nsh> df Block Number Size Blocks Used Available Mounted on 64 6 6 0 /etc 512 985 2 983 /tmp nsh> + ``` -o dirname +- `dirname ` - Extract the path string leading up to the full by removing - the final directory or file name. + Extract the path string leading up to the full `` by removing the final + directory or file name. -o dmesg +- `dmesg` - This command can be used to dump (and clear) the content of any - buffered syslog output messages. This command is only available - if CONFIG_RAMLOG_SYSLOG is enabled. In that case, syslog output - will be collected in an in-memory, circular buffer. Entering the - 'dmesg' command will dump the content of that in-memory, circular - buffer to the NSH console output. 'dmesg' has the side effect of - clearing the buffered data so that entering 'dmesg' again will - show only newly buffered data. + This command can be used to dump (and clear) the content of any buffered + syslog output messages. This command is only available if + `CONFIG_RAMLOG_SYSLOG` is enabled. In that case, syslog output will be + collected in an in-memory, circular buffer. Entering the `dmesg` command will + dump the content of that in-memory, circular buffer to the NSH console output. + `dmesg` has the side effect of clearing the buffered data so that entering + `dmesg` again will show only newly buffered data. -o echo [-n] [ [...]] +- `echo [-n] [ [...]]` - Copy the sequence of strings and expanded environment variables to - console out (or to a file if the output is re-directed). + Copy the sequence of strings and expanded environment variables to console out + (or to a file if the output is re-directed). - The -n option will suppress the trailing newline character. + The `-n` option will suppress the trailing newline character. -o env +- `env` - Show the current name-value pairs in the environment. Example: + Show the current name-value pairs in the environment. **Example**: + ``` nsh> env PATH=/bin @@ -517,1446 +550,1441 @@ o env foo=bar nsh> + ``` - NOTE: NSH variables are *not* shown by the env command. + **Note**: NSH variables are **not** shown by the `env` command. -o exec +- `exec ` - Execute the user logic at address . NSH will pause - until the execution unless the user logic is executed in background - via 'exec &' + Execute the user logic at address ``. NSH will pause until the + execution unless the user logic is executed in background via + `exec &` -o exit +- `exit` - Exit NSH. Only useful if you have started some other tasks (perhaps - using the 'exec' command') and you would like to have NSH out of the - way. + Exit NSH. Only useful if you have started some other tasks (perhaps using the + `exec` command) and you would like to have NSH out of the way. -o export [] +- `export []` - The 'export' command sets an environment variable, or promotes an - NSH variable to an environment variable. As examples: + The `export` command sets an environment variable, or promotes an NSH variable + to an environment variable. As examples: - 1. Using 'export' to promote an NSH variable to an environment variable. + 1. Using `export` to promote an NSH variable to an environment variable. - nsh> env - PATH=/bin + ``` + nsh> env + PATH=/bin - nsh> set foo bar - nsh> env - PATH=/bin + nsh> set foo bar + nsh> env + PATH=/bin - nsh> export foo - nsh> env - PATH=/bin - foo=bar + nsh> export foo + nsh> env + PATH=/bin + foo=bar + ``` A group-wide environment variable is created with the same value as the local NSH variable; the local NSH variable is removed. - NOTE: This behavior differs from the Bash shell. Bash will retain the - local Bash variable which will shadow the environment variable of the - same name and same value. + **Note**: This behavior differs from the Bash shell. Bash will retain the + local Bash variable which will shadow the environment variable of the same + name and same value. - 2. Using 'export' to set an environment variable + 2. Using `export` to set an environment variable - nsh> export dog poop - nsh> env - PATH=/bin - foo=bar - dog=poop + ``` + nsh> export dog poop + nsh> env + PATH=/bin + foo=bar + dog=poop + ``` - The export command is not supported by NSH unless both CONFIG_NSH_VARS=y - and CONFIG_DISABLE_ENVIRON is not set. + The export command is not supported by NSH unless both `CONFIG_NSH_VARS=y` and + `CONFIG_DISABLE_ENVIRON` is not set. -o free +- `free` - Show the current state of the memory allocator. For example, + Show the current state of the memory allocator. For example, + ``` nsh> free free total used free largest Mem: 4194288 1591552 2602736 2601584 + ``` Where: - total - This is the total size of memory allocated for use - by malloc in bytes. - used - This is the total size of memory occupied by - chunks handed out by malloc. - free - This is the total size of memory occupied by + + - total - This is the total size of memory allocated for use + by `malloc` in bytes. + - used - This is the total size of memory occupied by + chunks handed out by `malloc`. + - free - This is the total size of memory occupied by free (not in use) chunks. - largest - Size of the largest free (not in use) chunk + - largest - Size of the largest free (not in use) chunk. -o get [-b|-n] [-f ] -h +- `get [-b|-n] [-f ] -h ` - Use TFTP to copy the file at from the host whose IP - address is identified by . Other options: + Use TFTP to copy the file at `` from the host whose IP + address is identified by ``. Other options: - -f - The file will be saved relative to the current working directory - unless is provided. - -b|-n - Selects either binary ("octet") or test ("netascii") transfer - mode. Default: text. + - `-f ` + The file will be saved relative to the current working directory unless + `` is provided. + - `-b|-n` + Selects either binary (_octet_) or text (_netascii_) transfer mode. Default: + text. -o help [-v] [] +- `help [-v] []` Presents summary information about NSH commands to console. Options: - -v - Show verbose output will full command usage + - `-v` + Show verbose output will full command usage. - - Show full command usage only for this command + - `` + Show full command usage only for this command. -o hexdump +- `hexdump ` Dump data in hexadecimal format from a file or character device. -o ifconfig [nic_name [|dhcp]] [dr|gw|gateway ] [netmask ] [dns ] [hw ] +- `ifconfig [nic_name [|dhcp]] [dr|gw|gateway ] [netmask ] [dns ] [hw ]` Show the current configuration of the network, for example: - nsh> ifconfig - eth0 HWaddr 00:18:11:80:10:06 - IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 + ``` + nsh> ifconfig + eth0 HWaddr 00:18:11:80:10:06 + IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 + ``` - if networking statistics are enabled (CONFIG_NET_STATISTICS), then + if networking statistics are enabled (`CONFIG_NET_STATISTICS`), then this command will also show the detailed state of transfers by protocol. - NOTE: This commands depends upon having the procfs file system configured - into the system. The procfs file system must also have been mounted + **Note**: This commands depends upon having the `procfs` file system configured + into the system. The `procfs` file system must also have been mounted with a command like: - nsh> mount -t procfs /proc + ``` + nsh> mount -t procfs /proc + ``` -o ifdown +- `ifdown ` - Take down the interface identified by the name . + Take down the interface identified by the name ``. - Example: + **Example**: - ifdown eth0 + ``` + ifdown eth0 + ``` -o ifup +- `ifup ` - Bring up down the interface identified by the name . + Bring up down the interface identified by the name ``. - Example: + **Example**: - ifup eth0 + ``` + ifup eth0 + ``` -o insmod +- `insmod ` - Install the loadable OS module at as module + Install the loadable OS module at `` as module `` - Example: + **Example**: - nsh> ls -l /mnt/romfs - /mnt/romfs: - dr-xr-xr-x 0 . - -r-xr-xr-x 9153 chardev - nsh> ls -l /dev - /dev: - crw-rw-rw- 0 console - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - crw-rw-rw- 0 ttyS0 - nsh> insmod /mnt/romfs/chardev mydriver - nsh> ls -l /dev - /dev: - crw-rw-rw- 0 chardev - crw-rw-rw- 0 console - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - crw-rw-rw- 0 ttyS0 - nsh> lsmod - NAME INIT UNINIT ARG TEXT SIZE DATA SIZE - mydriver 20404659 20404625 0 20404580 552 204047a8 0 + ``` + nsh> ls -l /mnt/romfs + /mnt/romfs: + dr-xr-xr-x 0 . + -r-xr-xr-x 9153 chardev + nsh> ls -l /dev + /dev: + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 ttyS0 + nsh> insmod /mnt/romfs/chardev mydriver + nsh> ls -l /dev + /dev: + crw-rw-rw- 0 chardev + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 ttyS0 + nsh> lsmod + NAME INIT UNINIT ARG TEXT SIZE DATA SIZE + mydriver 20404659 20404625 0 20404580 552 204047a8 0 + ``` -o irqinfo +- `irqinfo` Show the current count of interrupts taken on all attached interrupts. - Example: + **Example**: - nsh> irqinfo - IRQ HANDLER ARGUMENT COUNT RATE - 3 00001b3d 00000000 156 19.122 - 15 0000800d 00000000 817 100.000 - 30 00000fd5 20000018 20 2.490 + ``` + nsh> irqinfo + IRQ HANDLER ARGUMENT COUNT RATE + 3 00001b3d 00000000 156 19.122 + 15 0000800d 00000000 817 100.000 + 30 00000fd5 20000018 20 2.490 + ``` -o kill - +- `kill - ` - Send the to the task identified by . + Send the `` to the task identified by ``. -o losetup [-d ] | [[-o ] [-r] ] +- `losetup [-d ] | [[-o ] [-r] ]` Setup or teardown the loop device: - 1. Teardown the setup for the loop device at : + 1. Teardown the setup for the loop device at ``: - losetup d + ```shell + losetup d + ``` - 2. Setup the loop device at to access the file at + 2. Setup the loop device at `` to access the file at `` as a block device: - losetup [-o ] [-r] + ```shell + losetup [-o ] [-r] + ``` - Example: + **Example**: - nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512 - nsh> ls -l /tmp - /tmp: - -rw-rw-rw- 262144 IMAGE - nsh> losetup /dev/loop0 /tmp/image - nsh> ls -l /dev - /dev: - brw-rw-rw- 0 loop0 - nsh> mkfatfs /dev/loop0 - nsh> mount -t vfat /dev/loop0 /mnt/example - nsh> ls -l /mnt - ls -l /mnt - /mnt: - drw-rw-rw- 0 example/ - nsh> echo "This is a test" >/mnt/example/atest.txt - nsh> ls -l /mnt/example - /mnt/example: - -rw-rw-rw- 16 ATEST.TXT - nsh> cat /mnt/example/atest.txt - This is a test - nsh> + ``` + nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512 + nsh> ls -l /tmp + /tmp: + -rw-rw-rw- 262144 IMAGE + nsh> losetup /dev/loop0 /tmp/image + nsh> ls -l /dev + /dev: + brw-rw-rw- 0 loop0 + nsh> mkfatfs /dev/loop0 + nsh> mount -t vfat /dev/loop0 /mnt/example + nsh> ls -l /mnt + ls -l /mnt + /mnt: + drw-rw-rw- 0 example/ + nsh> echo "This is a test" >/mnt/example/atest.txt + nsh> ls -l /mnt/example + /mnt/example: + -rw-rw-rw- 16 ATEST.TXT + nsh> cat /mnt/example/atest.txt + This is a test + nsh> + ``` -o ln [-s] +- `ln [-s] ` - The link command will create a new symbolic link at for the - existing file or directory, . This implementation is simplied + The link command will create a new symbolic link at `` for the + existing file or directory, ``. This implementation is simplied for use with NuttX in these ways: - Links may be created only within the NuttX top-level, pseudo file - system. No file system currently supported by NuttX provides + system. No file system currently supported by NuttX provides symbolic links. - For the same reason, only soft links are implemented. - File privileges are ignored. - - c_time is not updated. + - `c_time` is not updated. -o ls [-lRs] +- `ls [-lRs] ` - Show the contents of the directory at . NOTE: - must refer to a directory and no other file system + Show the contents of the directory at ``. **Note**: + `` must refer to a directory and no other file system object. Options: - -------- - -R Show the constents of specified directory and all of its - sub-directories. - -s Show the size of the files along with the filenames in the - listing - -l Show size and mode information along with the filenames - in the listing. + - `-R` Show the constents of specified directory and all of its + sub-directories. + - `-s` Show the size of the files along with the filenames in the listing. + - `-l` Show size and mode information along with the filenames in the listing. -o lsmod +- `lsmod` - Show information about the currently installed OS modules. This information includes: + Show information about the currently installed OS modules. This information + includes: - - The module name assigned to the module when it was installed (NAME, string). - - The address of the module initialization function (INIT, hexadecimal). - - The address of the module un-initialization function (UNINIT, hexadecimal). - - An argument that will be passed to the module un-initialization function (ARG, hexadecimal). - - The start of the .text memory region (TEXT, hexadecimal). - - The size of the .text memory region size (SIZE, decimal). - - The start of the .bss/.data memory region (DATA, hexadecimal). - - The size of the .bss/.data memory region size (SIZE, decimal). + - The module name assigned to the module when it was installed (`NAME`, + string). + - The address of the module initialization function (`INIT`, hexadecimal). + - The address of the module un-initialization function (`UNINIT`, + hexadecimal). + - An argument that will be passed to the module un-initialization function + (`ARG`, hexadecimal). + - The start of the `.text` memory region (`TEXT`, hexadecimal). + - The size of the `.text` memory region size (`SIZE`, decimal). + - The start of the `.bss`/`.data` memory region (`DATA`, hexadecimal). + - The size of the `.bss`/`.data` memory region size (`SIZE`, decimal). - Example: + **Example**: - nsh> lsmod - NAME INIT UNINIT ARG TEXT SIZE DATA SIZE - mydriver 20404659 20404625 0 20404580 552 204047a8 0 + ``` + nsh> lsmod + NAME INIT UNINIT ARG TEXT SIZE DATA SIZE + mydriver 20404659 20404625 0 20404580 552 204047a8 0 + ``` -o md5 [-f] +- `md5 [-f] ` -o mb [=][ ] -o mh [=][ ] -o mw [=][ ] +- `mb [=][ ]` + `mh [=][ ]` + `mw [=][ ]` - Access memory using byte size access (mb), 16-bit accesses (mh), - or 32-bit access (mw). In each case, + Access memory using byte size access (`mb`), 16-bit accesses (`mh`), + or 32-bit access (`mw`). In each case, - . Specifies the address to be accessed. The current - value at that address will always be read and displayed. - =. Read the value, then write - to the location. - . Perform the mb, mh, or mw operation on a total - of bytes, increment the appropriately + - ``. Specifies the address to be accessed. The current value at + that address will always be read and displayed. + - `=`. Read the value, then write `` to the + location. + - ``. Perform the `mb`, `mh`, or `mw` operation on a total of + `` bytes, increment the `` appropriately after each access - Example + **Example**: - nsh> mh 0 16 - 0 = 0x0c1e - 2 = 0x0100 - 4 = 0x0c1e - 6 = 0x0110 - 8 = 0x0c1e - a = 0x0120 - c = 0x0c1e - e = 0x0130 - 10 = 0x0c1e - 12 = 0x0140 - 14 = 0x0c1e - nsh> + ``` + nsh> mh 0 16 + 0 = 0x0c1e + 2 = 0x0100 + 4 = 0x0c1e + 6 = 0x0110 + 8 = 0x0c1e + a = 0x0120 + c = 0x0c1e + e = 0x0130 + 10 = 0x0c1e + 12 = 0x0140 + 14 = 0x0c1e + nsh> + ``` -o mkdir +- `mkdir ` - Create the directory at . All components of of - except the final directory name must exist on a mounted file - system; the final directory must not. + Create the directory at ``. All components of of `` except the + final directory name must exist on a mounted file system; the final directory + must not. - Recall that NuttX uses a pseudo file system for its root file system. - The mkdir command can only be used to create directories in volumes - set up with the mount command; it cannot be used to create directories - in the pseudo file system. + Recall that NuttX uses a pseudo file system for its root file system. The + `mkdir` command can only be used to create directories in volumes set up with + the `mount` command; it cannot be used to create directories in the pseudo file + system. - Example: - ^^^^^^^^ + **Example**: - nsh> mkdir /mnt/fs/tmp - nsh> ls -l /mnt/fs - /mnt/fs: - drw-rw-rw- 0 TESTDIR/ - drw-rw-rw- 0 TMP/ - nsh> + ``` + nsh> mkdir /mnt/fs/tmp + nsh> ls -l /mnt/fs + /mnt/fs: + drw-rw-rw- 0 TESTDIR/ + drw-rw-rw- 0 TMP/ + nsh> + ``` -o mkfatfs [-F ] [-r ] +- `mkfatfs [-F ] [-r ] ` - Format a fat file system on the block device specified by - path. The FAT size may be provided as an option. Without the - option, mkfatfs will select either the FAT12 or FAT16 format. For - historical reasons, if you want the FAT32 format, it must be explicitly - specified on the command line. + Format a `fat` file system on the block device specified by `` + path. The FAT size may be provided as an option. Without the `` + option, mkfatfs will select either the FAT12 or FAT16 format. For historical + reasons, if you want the FAT32 format, it must be explicitly specified on the + command line. - The -r option may be specified to select the the number of entries in - the root directory. Typical values for small volumes would be 112 or 224; - 512 should be used for large volumes, such as hard disks or very large - SD cards. The default is 512 entries in all cases. + The `-r` option may be specified to select the the number of entries in the + root directory. Typical values for small volumes would be `112` or `224`; + `512` should be used for large volumes, such as hard disks or very large SD + cards. The default is `512` entries in all cases. - The reported number of root directory entries used with FAT32 is zero - because the FAT32 root directory is a cluster chain. + The reported number of root directory entries used with FAT32 is zero because + the FAT32 root directory is a cluster chain. - NSH provides this command to access the mkfatfs() NuttX API. - This block device must reside in the NuttX pseudo file system and - must have been created by some call to register_blockdriver() (see - include/nuttx/fs/fs.h). + NSH provides this command to access the `mkfatfs()` NuttX API. This block + device must reside in the NuttX pseudo file system and must have been created + by some call to `register_blockdriver()` (see `include/nuttx/fs/fs.h`). -o mkfifo +- `mkfifo ` - Creates a FIFO character device anywhere in the pseudo file system, - creating whatever pseudo directories that may be needed to complete - the full path. By convention, however, device drivers are place in - the standard /dev directory. After it is created, the FIFO device - may be used as any other device driver. NSH provides this command - to access the mkfifo() NuttX API. + Creates a FIFO character device anywhere in the pseudo file system, creating + whatever pseudo directories that may be needed to complete the full path. By + convention, however, device drivers are place in the standard `/dev` + directory. After it is created, the FIFO device may be used as any other + device driver. NSH provides this command to access the `mkfifo()` NuttX API. - Example: - ^^^^^^^^ + **Example**: + + ``` + nsh> ls -l /dev + /dev: + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + nsh> mkfifo /dev/fifo + nsh> ls -l /dev + ls -l /dev + /dev: + crw-rw-rw- 0 console + crw-rw-rw- 0 fifo + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + nsh> + ``` - nsh> ls -l /dev - /dev: - crw-rw-rw- 0 console - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - nsh> mkfifo /dev/fifo - nsh> ls -l /dev - ls -l /dev - /dev: - crw-rw-rw- 0 console - crw-rw-rw- 0 fifo - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - nsh> +- `mkrd [-m ] [-s ] ` -o mkrd [-m ] [-s ] + Create a ramdisk consisting of ``, each of size `` (or + `512` bytes if `` is not specified). The ramdisk will be + registered as `/dev/ram`. If `` is not specified, mkrd will + attempt to register the ramdisk as `/dev/ram0`. - Create a ramdisk consisting of , each of size - (or 512 bytes if is not specified). - The ramdisk will be registered as /dev/ram. If is - not specified, mkrd will attempt to register the ramdisk as - /dev/ram0. + **Example**: - Example: - ^^^^^^^^ + ``` + nsh> ls /dev + /dev: + console + null + ttyS0 + ttyS1 + nsh> mkrd 1024 + nsh> ls /dev + /dev: + console + null + ram0 + ttyS0 + ttyS1 + nsh> + ``` - nsh> ls /dev - /dev: - console - null - ttyS0 - ttyS1 - nsh> mkrd 1024 - nsh> ls /dev - /dev: - console - null - ram0 - ttyS0 - ttyS1 - nsh> + Once the ramdisk has been created, it may be formatted using the `mkfatfs` + command and mounted using the `mount` command. - Once the ramdisk has been created, it may be formatted using - the mkfatfs command and mounted using the mount command. + **Example**: + + ``` + nsh> mkrd 1024 + nsh> mkfatfs /dev/ram0 + nsh> mount -t vfat /dev/ram0 /tmp + nsh> ls /tmp + /tmp: + nsh> + ``` - Example: - ^^^^^^^^ - nsh> mkrd 1024 - nsh> mkfatfs /dev/ram0 - nsh> mount -t vfat /dev/ram0 /tmp - nsh> ls /tmp - /tmp: - nsh> +- `mount [-t [-o ] ]` -o mount [-t [-o ] ] + The `mount` command performs one of two different operations. If no parameters + are provided on the command line after the `mount` command, then the `mount` + command will enumerate all of the current mountpoints on the console. - The mount command performs one of two different operations. If no - parameters are provided on the command line after the mount command, - then the 'mount' command will enumerate all of the current - mountpoints on the console. + If the mount parameters are provied on the command after the `mount` command, + then the `mount` command will mount a file system in the NuttX pseudo-file + system. `mount` performs a three way association, binding: - If the mount parameters are provied on the command after the 'mount' - command, then the 'mount' command will mount a file system in the - NuttX pseudo-file system. 'mount' performs a three way association, - binding: + - File system. The `-t ` option identifies the type of file system + that has been formatted on the ``. As of this writing, `vfat` + is the only supported value for `` - File system. The '-t ' option identifies the type of - file system that has been formatted on the . As - of this writing, vfat is the only supported value for + - Block Device. The `` argument is the full or relative path to + a block driver inode in the pseudo file system. By convention, this is a + name under the `/dev` sub-directory. This `` must have been + previously formatted with the same file system type as specified by + `` - Block Device. The argument is the full or relative - path to a block driver inode in the pseudo file system. By convention, - this is a name under the /dev sub-directory. This - must have been previously formatted with the same file system - type as specified by + - Mount Point. The mount point is the location in the pseudo file system where + the mounted volume will appear. This mount point can only reside in the + NuttX pseudo file system. By convention, this mount point is a subdirectory + under `/mnt`. The `mount` command will create whatever pseudo directories + that may be needed to complete the full path but the full path must not + already exist. - Mount Point. The mount point is the location in the pseudo file - system where the mounted volume will appear. This mount point - can only reside in the NuttX pseudo file system. By convention, this - mount point is a subdirectory under /mnt. The mount command will - create whatever pseudo directories that may be needed to complete - the full path but the full path must not already exist. + After the volume has been mounted in the NuttX pseudo file system, it may be + access in the same way as other objects in the file system. - After the volume has been mounted in the NuttX pseudo file - system, it may be access in the same way as other objects in the - file system. + **Examples**: - Examples: - ^^^^^^^^^ - - nsh> ls -l /dev - /dev: - crw-rw-rw- 0 console - crw-rw-rw- 0 null - brw-rw-rw- 0 ram0 - nsh> ls /mnt - nsh: ls: no such directory: /mnt - nsh> mount -t vfat /dev/ram0 /mnt/fs - nsh> ls -l /mnt/fs/testdir - /mnt/fs/testdir: - -rw-rw-rw- 15 TESTFILE.TXT - nsh> echo "This is a test" >/mnt/fs/testdir/example.txt - nsh> ls -l /mnt/fs/testdir - /mnt/fs/testdir: + ``` + nsh> ls -l /dev + /dev: + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + nsh> ls /mnt + nsh: ls: no such directory: /mnt + nsh> mount -t vfat /dev/ram0 /mnt/fs + nsh> ls -l /mnt/fs/testdir + /mnt/fs/testdir: -rw-rw-rw- 15 TESTFILE.TXT - -rw-rw-rw- 16 EXAMPLE.TXT - nsh> cat /mnt/fs/testdir/example.txt - This is a test - nsh> + nsh> echo "This is a test" >/mnt/fs/testdir/example.txt + nsh> ls -l /mnt/fs/testdir + /mnt/fs/testdir: + -rw-rw-rw- 15 TESTFILE.TXT + -rw-rw-rw- 16 EXAMPLE.TXT + nsh> cat /mnt/fs/testdir/example.txt + This is a test + nsh> - nsh> mount - /etc type romfs - /tmp type vfat - /mnt/fs type vfat + nsh> mount + /etc type romfs + /tmp type vfat + /mnt/fs type vfat + ``` -o mv +- `mv ` - Rename the file object at to . Both paths must + Rename the file object at `` to ``. Both paths must reside in the same mounted file system. -o nfsmount +- `nfsmount ` - Mount the remote NFS server directory at on the target machine. - is the IP address of the remote server. + Mount the remote NFS server directory `` at `` on + the target machine. `` is the IP address of the remote server. -o nslookup +- `nslookup ` - Lookup and print the IP address associated with + Lookup and print the IP address associated with `` -o passwd +- `passwd ` - Set the password for the existing user to + Set the password for the existing user `` to `` -o pmconfig [stay|relax] [normal|idle|standby|sleep] +- `pmconfig [stay|relax] [normal|idle|standby|sleep]` Control power management subsystem. -o poweroff [] +- `poweroff []` - Shutdown and power off the system. This command depends on board- - specific hardware support to power down the system. The optional, - decimal numeric argument may be included to provide power off - mode to board-specific power off logic. + Shutdown and power off the system. This command depends on board- specific + hardware support to power down the system. The optional, decimal numeric + argument `` may be included to provide power off mode to board-specific + power off logic. - NOTE: Supporting both the poweroff and shutdown commands is redundant. + **Note**: Supporting both the `poweroff` and `shutdown` commands is redundant. -o printf [\xNN] [\n\r\t] [ [...]] +- `printf [\xNN] [\n\r\t] [ [...]]` - Copy the sequence of strings, characters and expanded environment - variables to console out (or to a file if the output is re-directed). + Copy the sequence of strings, characters and expanded environment variables to + console out (or to a file if the output is re-directed). - No trailing newline character is added. The escape sequences \n, \r - or \t can be used to add line feed, carriage return or tab character - to output, respectively. + No trailing newline character is added. The escape sequences `\n`, `\r` or + `\t` can be used to add line feed, carriage return or tab character to output, + respectively. - The hexadecimal escape sequence \xNN takes up to two hexadesimal digits - to specify the printed character. + The hexadecimal escape sequence `\xNN` takes up to two hexadesimal digits to + specify the printed character. -o ps +- `ps` - Show the currently active threads and tasks. For example, + Show the currently active threads and tasks. For example: - nsh> ps - PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND - 0 0 FIFO Kthread --- Ready 00000000 Idle Task - 1 128 RR Task --- Running 00000000 init - 2 128 FIFO Task --- Waiting Semaphore 00000000 nsh_telnetmain() - 3 100 RR pthread --- Waiting Semaphore 00000000 (21) - nsh> + ``` + nsh> ps + PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND + 0 0 FIFO Kthread --- Ready 00000000 Idle Task + 1 128 RR Task --- Running 00000000 init + 2 128 FIFO Task --- Waiting Semaphore 00000000 nsh_telnetmain() + 3 100 RR pthread --- Waiting Semaphore 00000000 (21) + nsh> + ``` - NOTE: This commands depends upon having the procfs file system configured - into the system. The procfs file system must also have been mounted + **Note**: This commands depends upon having the `procfs` file system + configured into the system. The procfs file system must also have been mounted with a command like: - nsh> mount -t procfs /proc + ```shell + nsh> mount -t procfs /proc + ``` -o put [-b|-n] [-f ] -h +- `put [-b|-n] [-f ] -h ` Copy the file at to the host whose IP address is - identified by . Other options: + identified by . Other options: - -f - The file will be saved with the same name on the host unless - unless is provided. - -b|-n - Selects either binary ("octet") or test ("netascii") transfer - mode. Default: text. + - `-f ` + The file will be saved with the same name on the host unless + unless `` is provided. -o pwd + - `-b|-n` + Selects either binary (_octet_) or test (_netascii_) transfer + mode. Default: text. + +- `pwd` Show the current working directory. - nsh> cd /dev - nsh> pwd - /dev - nsh> + ``` + nsh> cd /dev + nsh> pwd + /dev + nsh> + ``` - Same as 'echo $PWD' + Same as `echo $PWD` - nsh> echo $PWD - /dev - nsh> + ``` + nsh> echo $PWD + /dev + nsh> + ``` -o readlink +- `readlink ` Show target of a soft link. -o reboot [] +- `reboot []` - Reset and reboot the system immediately. This command depends on hardware - support to reset the system. The optional, decimal numeric argument - may be included to provide reboot mode to board-specific reboot - logic. + Reset and reboot the system immediately. This command depends on hardware + support to reset the system. The optional, decimal numeric argument `` may + be included to provide reboot mode to board-specific reboot logic. - NOTE: Supporting both the reboot and shutdown commands is redundant. + **Note**: Supporting both the `reboot` and `shutdown` commands is redundant. -o rm +- `rm ` - Remove the specified name from the mounted file system. - Recall that NuttX uses a pseudo file system for its root file system. - The rm command can only be used to remove (unlink) files in volumes - set up with the mount command; it cannot be used to remove names from - the pseudo file system. + Remove the specified `` name from the mounted file system. Recall + that NuttX uses a pseudo file system for its root file system. The `rm` + command can only be used to remove (`unlink`) files in volumes set up with the + `mount` command; it cannot be used to remove names from the pseudo file + system. - Example: - ^^^^^^^^ + **Example**: - nsh> ls /mnt/fs/testdir - /mnt/fs/testdir: - TESTFILE.TXT - EXAMPLE.TXT - nsh> rm /mnt/fs/testdir/example.txt - nsh> ls /mnt/fs/testdir - /mnt/fs/testdir: - TESTFILE.TXT - nsh> + ``` + nsh> ls /mnt/fs/testdir + /mnt/fs/testdir: + TESTFILE.TXT + EXAMPLE.TXT + nsh> rm /mnt/fs/testdir/example.txt + nsh> ls /mnt/fs/testdir + /mnt/fs/testdir: + TESTFILE.TXT + nsh> + ``` -o rmdir +- `rmdir ` - Remove the specified directory from the mounted file system. + Remove the specified `` directory from the mounted file system. Recall that NuttX uses a pseudo file system 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 + `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 file system. - Example: - ^^^^^^^^ + **Example**: - nsh> mkdir /mnt/fs/tmp - nsh> ls -l /mnt/fs - /mnt/fs: - drw-rw-rw- 0 TESTDIR/ - drw-rw-rw- 0 TMP/ - nsh> rmdir /mnt/fs/tmp - nsh> ls -l /mnt/fs - ls -l /mnt/fs - /mnt/fs: - drw-rw-rw- 0 TESTDIR/ - nsh> + ``` + nsh> mkdir /mnt/fs/tmp + nsh> ls -l /mnt/fs + /mnt/fs: + drw-rw-rw- 0 TESTDIR/ + drw-rw-rw- 0 TMP/ + nsh> rmdir /mnt/fs/tmp + nsh> ls -l /mnt/fs + ls -l /mnt/fs + /mnt/fs: + drw-rw-rw- 0 TESTDIR/ + nsh> + ``` -o rmmod +- `rmmod ` - Remove the loadable OS module with the . NOTE: An OS module + Remove the loadable OS module with the ``. **Note**: An OS module can only be removed if it is not busy. - Example: + **Example**: - nsh> lsmod - NAME INIT UNINIT ARG TEXT SIZE DATA SIZE - mydriver 20404659 20404625 0 20404580 552 204047a8 0 - nsh> rmmod mydriver - nsh> lsmod - NAME INIT UNINIT ARG TEXT SIZE DATA SIZE - nsh> + ``` + nsh> lsmod + NAME INIT UNINIT ARG TEXT SIZE DATA SIZE + mydriver 20404659 20404625 0 20404580 552 204047a8 0 + nsh> rmmod mydriver + nsh> lsmod + NAME INIT UNINIT ARG TEXT SIZE DATA SIZE + nsh> + ``` -o route ipv4|ipv6 +- `route ipv4|ipv6` Show the contents of routing table for IPv4 or IPv6. - If only IPv4 or IPv6 is enabled, then the argument is optional but, if provided, - must match the enabled internet protocol version. + If only IPv4 or IPv6 is enabled, then the argument is optional but, if + provided, must match the enabled internet protocol version. -o rptun start|stop +- `rptun start|stop ` - Start or stop the OpenAMP RPC tunnel device at . + Start or stop the OpenAMP RPC tunnel device at ``. -o set [{+|-}{e|x|xe|ex}] [ ] +- `set [{+|-}{e|x|xe|ex}] [ ]` - Set the variable to the string and or set NSH parser control - options. + Set the variable `` to the string `` and or set NSH parser + control options. For example, a variable may be set like this: - nsh> echo $foobar + ``` + nsh> echo $foobar - nsh> set foobar foovalue - nsh> echo $foobar - foovalue - nsh> + nsh> set foobar foovalue + nsh> echo $foobar + foovalue + nsh> + ``` - If CONFIG_NSH_VARS is selected, the effect of this 'set' command is to set - the local NSH variable. Otherwise, the group-wide environment variable - will be set. + If `CONFIG_NSH_VARS` is selected, the effect of this `set` command is to set + the local NSH variable. Otherwise, the group-wide environment variable will be + set. If the local NSH variable has already been 'promoted' to an environment - variable, then the 'set' command will set the value of the environment + variable, then the `set` command will set the value of the environment variable rather than the local NSH variable. - NOTE: The Bash shell does not work this way. Bash would set the value of - both the local Bash variable and of the environment variable of the same - name to the same value. + **Note**: The Bash shell does not work this way. Bash would set the value of + both the local Bash variable and of the environment variable of the same name + to the same value. - If CONFIG_NSH_VARS is selected and no arguments are provided, then the - 'set' command will list all list all NSH variables. + If `CONFIG_NSH_VARS` is selected and no arguments are provided, then the `set` + command will list all list all NSH variables. - nsh> set - foolbar=foovalue + ``` + nsh> set + foolbar=foovalue + ``` - Set the 'exit on error control' and/or 'print a trace' of commands when parsing - scripts in NSH. The settinngs are in effect from the point of execution, until - they are changed again, or in the case of the init script, the settings are - returned to the default settings when it exits. Included child scripts will run - with the parents settings and changes made in the child script will effect the - parent on return. + Set the _exit on error control_ and/or _print a trace_ of commands when + parsing scripts in NSH. The settinngs are in effect from the point of + execution, until they are changed again, or in the case of the init script, + the settings are returned to the default settings when it exits. Included + child scripts will run with the parents settings and changes made in the child + script will effect the parent on return. - Use 'set -e' to enable and 'set +e' to disable (ignore) the exit condition on commands. - The default is -e. Errors cause script to exit. + Use `set -e` to enable and `set +e` to disable (ignore) the exit condition + on commands. The default is `-e`. Errors cause script to exit. - Use 'set -x' to enable and 'set +x' to disable (silence) printing a trace of the script - commands as they are ececuted. - The default is +x. No printing of a trace of script commands as they are executed. + Use `set -x` to enable and `set +x` to disable (silence) printing a trace of + the script commands as they are ececuted. The default is `+x`. No printing of + a trace of script commands as they are executed. - Example 1 - no exit on command not found + - Example 1 - no exit on command not found + + ``` set +e notacommand + ``` - Example 2 - will exit on command not found + - Example 2 - will exit on command not found + + ``` set -e notacommand + ``` - Example 3 - will exit on command not found, and print a trace of the script commands + - Example 3 - will exit on command not found, and print a trace of the script commands + + ``` set -ex + ``` - Example 4 - will exit on command not found, and print a trace of the script commands + - Example 4 - will exit on command not found, and print a trace of the script commands and set foobar to foovalue. + + ``` set -ex foobar foovalue nsh> echo $foobar foovalue + ``` -o shutdown [--reboot] +- `shutdown [--reboot]` - Shutdown and power off the system or, optionally, reset and reboot the - system immediately. This command depends on hardware support to power - down or reset the system; one, both, or neither behavior may be - supported. + Shutdown and power off the system or, optionally, reset and reboot the system + immediately. This command depends on hardware support to power down or reset + the system; one, both, or neither behavior may be supported. - NOTE: The shutdown command duplicates the behavior of the poweroff and - reboot commands. + **Note**: The `shutdown` command duplicates the behavior of the `poweroff` and + `reboot` commands. -o sleep +- `sleep ` - Pause execution (sleep) of seconds. + Pause execution (sleep) of `` seconds. -o source +- `source ` - Execute the sequence of NSH commands in the file referred - to by . + Execute the sequence of NSH commands in the file referred to by + ``. -o telnetd +- `telnetd` The Telnet daemon may be started either programmatically by calling - nsh_telnetstart() or it may be started from the NSH command line using - this telnetd command. + `nsh_telnetstart()` or it may be started from the NSH command line using this + `telnetd` command. - Normally this command would be suppressed with CONFIG_NSH_DISABLE_TELNETD - because the Telnet daemon is automatically started in nsh_main.c. The - exception is when CONFIG_NETINIT_NETLOCAL is selected. IN that case, the - network is not enabled at initialization but rather must be enabled from - the NSH command line or via other applications. + Normally this command would be suppressed with `CONFIG_NSH_DISABLE_TELNETD` + because the Telnet daemon is automatically started in `nsh_main.c`. The + exception is when `CONFIG_NETINIT_NETLOCAL` is selected. IN that case, the + network is not enabled at initialization but rather must be enabled from the + NSH command line or via other applications. - In that case, calling nsh_telnetstart() before the the network is + In that case, calling `nsh_telnetstart()` before the the network is initialized will fail. -o time "" +- `time ""` - Perform command timing. This command will execute the following - string and then show how much time was required to execute the command. - Time is shown with a resolution of 100 microseconds which may be beyond - the resolution of many configurations. Note that the must be - enclosed in quotation marks if it contains spaces or other - delimiters. + Perform command timing. This command will execute the following `` + string and then show how much time was required to execute the command. Time + is shown with a resolution of 100 microseconds which may be beyond the + resolution of many configurations. Note that the `` must be enclosed + in quotation marks if it contains spaces or other delimiters. - Example: + **Example**: - nsh> time "sleep 2" + ``` + nsh> time "sleep 2" - 2.0100 sec - nsh> + 2.0100 sec + nsh> + ``` The additional 10 milliseconds in this example is due to the way that the - sleep command works: It always waits one system clock tick longer than - requested and this test setup used a 10 millisecond periodic system - timer. Sources of error could include various quantization errors, - competing CPU usage, and the additional overhead of the time command - execution itself which is included in the total. + `sleep` command works: It always waits one system clock tick longer than + requested and this test setup used a 10 millisecond periodic system timer. + Sources of error could include various quantization errors, competing CPU + usage, and the additional overhead of the `time` command execution itself + which is included in the total. The reported time is the elapsed time from starting of the command to - completion of the command. This elapsed time may not necessarily be - just the processing time for the command. It may included interrupt - level processing, for example. In a busy system, command processing could - be delayed if pre-empted by other, higher priority threads competing for - CPU time. So the reported time includes all CPU processing from the start - of the command to its finish possibly including unrelated processing time - during that interval. + completion of the command. This elapsed time may not necessarily be just the + processing time for the command. It may included interrupt level processing, + for example. In a busy system, command processing could be delayed if + pre-empted by other, higher priority threads competing for CPU time. So the + reported time includes all CPU processing from the start of the command to its + finish possibly including unrelated processing time during that interval. Notice that: - nsh> time "sleep 2 &" - sleep [3:100] + ``` + nsh> time "sleep 2 &" + sleep [3:100] - 0.0000 sec - nsh> + 0.0000 sec + nsh> + ``` - Since the sleep command is executed in background, the sleep command - completes almost immediately. As opposed to the following where the - time command is run in background with the sleep command: + Since the `sleep` command is executed in background, the `sleep` command + completes almost immediately. As opposed to the following where the `time` + command is run in background with the `sleep` command: - nsh> time "sleep 2" & - time [3:100] - nsh> - 2.0100 sec + ``` + nsh> time "sleep 2" & + time [3:100] + nsh> + 2.0100 sec + ``` -o truncate -s +- `truncate -s ` - Shrink or extend the size of the regular file at to the - specified . + Shrink or extend the size of the regular file at `` to the + specified ``. - A argument that does not exist is created. The - option is NOT optional. + A `` argument that does not exist is created. The `` option + is NOT optional. - If a is larger than the specified size, the extra data is - lost. If a is shorter, it is extended and the extended part - reads as zero bytes. + If a `` is larger than the specified size, the extra data is lost. + If a `` is shorter, it is extended and the extended part reads as + zero bytes. -o umount +- `umount ` - Un-mount the file system at mount point . The umount command - can only be used to un-mount volumes previously mounted using mount - command. + Un-mount the file system at mount point ``. The `umount` command can + only be used to un-mount volumes previously mounted using `mount` command. - Example: - nsh> ls /mnt/fs - /mnt/fs: - TESTDIR/ - nsh> umount /mnt/fs - nsh> ls /mnt/fs - /mnt/fs: - nsh: ls: no such directory: /mnt/fs - nsh> + **Example**: -o unset + ``` + nsh> ls /mnt/fs + /mnt/fs: + TESTDIR/ + nsh> umount /mnt/fs + nsh> ls /mnt/fs + /mnt/fs: + nsh: ls: no such directory: /mnt/fs + nsh> + ``` - Remove the value associated with the variable . This will remove - the name-value pair from both the NSH local variables and the group-wide - environment variables. For example: +- `unset ` - nsh> echo $foobar - foovalue - nsh> unset foobar - nsh> echo $foobar + Remove the value associated with the variable ``. This will remove the + name-value pair from both the NSH local variables and the group-wide + environment variables. For example: - nsh> + ``` + nsh> echo $foobar + foovalue + nsh> unset foobar + nsh> echo $foobar -o urldecode [-f] + nsh> + ``` -o urlencode [-f] +- `urldecode [-f] ` -o uname [-a | -imnoprsv] +- `urlencode [-f] ` - Print certain system information. With no options, the output is the same as -s. +- `uname [-a | -imnoprsv]` - -a Print all information, in the following order, except omit -p and -i if unknown: + Print certain system information. With no options, the output is the same as + `-s`. - -s, -o, Print the operating system name (NuttX) + - `-a` Print all information, in the following order, except omit `-p` and + `-i` if unknown: + - `-s`, `-o`, Print the operating system name (NuttX) + - `-n` Print the network node hostname (only available if `CONFIG_NET=y`) + - `-r` Print the kernel release + - `-v` Print the kernel version + - `-m` Print the machine hardware name + - `-i` Print the machine platform name + - `-p` Print "unknown" - -n Print the network node hostname (only available if CONFIG_NET=y) +- `useradd ` - -r Print the kernel release + Add a new user with `` and `` - -v Print the kernel version +- `userdel ` - -m Print the machine hardware name + Delete the user with the name `` - -i Print the machine platform name +- `usleep ` - -p Print "unknown" + Pause execution (sleep) of `` microseconds. -o useradd +- `wget [-o ] ` - Add a new user with and + Use HTTP to copy the file at `` to the current directory. Options: -o userdel + - `-o ` The file will be saved relative to the current working + directory and with the same name as on the HTTP server unless `` + is provided. - Delete the user with the name +- `xd ` -o usleep + Dump bytes of data from address `` - Pause execution (sleep) of microseconds. + **Example**: -o wget [-o ] + ``` + nsh> xd 410e0 512 + Hex dump: + 0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................ + 0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$ + ... + 01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I.......... + nsh> + ``` - Use HTTP to copy the file at to the current directory. - Options: +## Built-In Commands - -o - The file will be saved relative to the current working directory - and with the same name as on the HTTP server unless - is provided. - -o xd - - Dump bytes of data from address - - Example: - ^^^^^^^^ - - nsh> xd 410e0 512 - Hex dump: - 0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................ - 0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$ - ... - 01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I.......... - nsh> - -Built-In Commands -^^^^^^^^^^^^^^^^^ In addition to the commands that are part of NSH listed above, there can be -additional, external "built-in" applications that can be added to NSH. -These are separately excecuble programs but will appear much like the -commands that are a part of NSH. The primary difference from the user's -perspective is that help information about the built-in applications is not -directly available from NSH. Rather, you will need to execute the -application with the -h option to get help about using the built-in -applications. - -There are several built-in appliations in the apps/ repository. No attempt -is made here to enumerate all of them. But a few of the more common built- -in applications are listed below. - -o ping [-c ] [-i ] - ping6 [-c ] [-i ] - - Test the network communication with a remote peer. Example, - - nsh> 10.0.0.1 - PING 10.0.0.1 56 bytes of data - 56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms - 56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms - 10 packets transmitted, 10 received, 0% packet loss, time 10190 ms - nsh> - - ping6 differs from ping in that it uses IPv6 addressing. - -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 -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 -as discussed at the bottom of this README file. - -Command Dependencies on Configuration Settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Command Depends on Configuration - ---------- -------------------------- - [ !CONFIG_NSH_DISABLESCRIPT - addroute CONFIG_NET && CONFIG_NET_ROUTE - arp CONFIG_NET && CONFIG_NET_ARP - base64dec CONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64 - base64enc CONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64 - basename -- - break !CONFIG_NSH_DISABLESCRIPT && !CONFIG_NSH_DISABLE_LOOPS - cat -- - cd !CONFIG_DISABLE_ENVIRON - cp -- - dd -- - delroute CONFIG_NET && CONFIG_NET_ROUTE - df !CONFIG_DISABLE_MOUNTPOINT - dirname -- - dmesg CONFIG_RAMLOG_SYSLOG - echo -- - env CONFIG_FS_PROCFS && !CONFIG_DISABLE_ENVIRON && !CONFIG_PROCFS_EXCLUDE_ENVIRON - exec -- - exit -- - export CONFIG_NSH_VARS && !CONFIG_DISABLE_ENVIRON - free -- - get CONFIG_NET && CONFIG_NET_UDP && MTU >= 558 (see note 1) - help -- - hexdump -- - ifconfig CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET - ifdown CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET - ifup CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET - insmod CONFIG_MODULE - irqinfo CONFIG_FS_PROCFS && CONFIG_SCHED_IRQMONITOR - kill -- - losetup !CONFIG_DISABLE_MOUNTPOINT && CONFIG_DEV_LOOP - ln CONFIG_PSEUDOFS_SOFTLINK - ls -- - lsmod CONFIG_MODULE && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_MODULE - md5 CONFIG_NETUTILS_CODECS && CONFIG_CODECS_HASH_MD5 - mb,mh,mw -- - mkdir !CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS - mkfatfs !CONFIG_DISABLE_MOUNTPOINT && CONFIG_FSUTILS_MKFATFS - mkfifo CONFIG_PIPES && CONFIG_DEV_FIFO_SIZE > 0 - mkrd !CONFIG_DISABLE_MOUNTPOINT - mount !CONFIG_DISABLE_MOUNTPOINT - mv !CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS - nfsmount !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NET && CONFIG_NFS - nslookup CONFIG_LIBC_NETDB && CONFIG_NETDB_DNSCLIENT - password !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWD - pmconfig CONFIG_PM && !CONFIG_NSH_DISABLE_PMCONFIG - poweroff CONFIG_BOARDCTL_POWEROFF - printf -- - ps CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_PROC - put CONFIG_NET && CONFIG_NET_UDP && MTU >= 558 (see note 1,2) - pwd !CONFIG_DISABLE_ENVIRON - readlink CONFIG_PSEUDOFS_SOFTLINK - reboot CONFIG_BOARDCTL_RESET - rm !CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS - rmdir !CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS - rmmod CONFIG_MODULE - route CONFIG_FS_PROCFS && CONFIG_FS_PROCFS_EXCLUDE_NET && - !CONFIG_FS_PROCFS_EXCLUDE_ROUTE && CONFIG_NET_ROUTE && - !CONFIG_NSH_DISABLE_ROUTE && (CONFIG_NET_IPv4 || CONFIG_NET_IPv6) - rptun CONFIG_RPTUN - set CONFIG_NSH_VARS || !CONFIG_DISABLE_ENVIRON - shutdown CONFIG_BOARDCTL_POWEROFF || CONFIG_BOARDCTL_RESET - sleep -- - source CONFIG_NFILE_STREAMS > 0 && !CONFIG_NSH_DISABLESCRIPT - test !CONFIG_NSH_DISABLESCRIPT - telnetd CONFIG_NSH_TELNET && !CONFIG_NSH_DISABLE_TELNETD - time -- - truncate !CONFIG_DISABLE_MOUNTPOINT - umount !CONFIG_DISABLE_MOUNTPOINT - uname !CONFIG_NSH_DISABLE_UNAME - unset CONFIG_NSH_VARS || !CONFIG_DISABLE_ENVIRON - urldecode CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE - urlencode CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE - useradd !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWD - userdel !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWD - usleep -- - get CONFIG_NET && CONFIG_NET_TCP - xd -- - -* NOTES: - 1. Because of hardware padding, the actual MTU required for put and get - operations size may be larger. - 2. Special TFTP server start-up options will probably be required to permit - creation of file for the correct operation of the put command. - -In addition, each NSH command can be individually disabled via one of the following -settings. All of these settings make the configuration of NSH potentially complex but -also allow it to squeeze into very small memory footprints. - - CONFIG_NSH_DISABLE_ADDROUTE, CONFIG_NSH_DISABLE_BASE64DEC, CONFIG_NSH_DISABLE_BASE64ENC, - CONFIG_NSH_DISABLE_BASENAME, CONFIG_NSH_DISABLE_CAT, CONFIG_NSH_DISABLE_CD, - CONFIG_NSH_DISABLE_CP, CONFIG_NSH_DISABLE_DD, CONFIG_NSH_DISABLE_DELROUTE, - CONFIG_NSH_DISABLE_DF, CONFIG_NSH_DISABLE_DIRNAME, CONFIG_NSH_DISABLE_DMESG, - CONFIG_NSH_DISABLE_ECHO, CONFIG_NSH_DISABLE_ENV, CONFIG_NSH_DISABLE_EXEC, - CONFIG_NSH_DISABLE_EXIT, CONFIG_NSH_DISABLE_EXPORT, CONFIG_NSH_DISABLE_FREE, - CONFIG_NSH_DISABLE_GET, CONFIG_NSH_DISABLE_HELP, CONFIG_NSH_DISABLE_HEXDUMP, - CONFIG_NSH_DISABLE_IFCONFIG, CONFIG_NSH_DISABLE_IFUPDOWN, CONFIG_NSH_DISABLE_KILL, - CONFIG_NSH_DISABLE_LOSETUP, CONFIG_NSH_DISABLE_LN, CONFIG_NSH_DISABLE_LS, - CONFIG_NSH_DISABLE_MD5, CONFIG_NSH_DISABLE_MB, CONFIG_NSH_DISABLE_MKDIR, - CONFIG_NSH_DISABLE_MKFATFS, CONFIG_NSH_DISABLE_MKFIFO, CONFIG_NSH_DISABLE_MKRD, - CONFIG_NSH_DISABLE_MH, CONFIG_NSH_DISABLE_MODCMDS, CONFIG_NSH_DISABLE_MOUNT, - CONFIG_NSH_DISABLE_MW, CONFIG_NSH_DISABLE_MV, CONFIG_NSH_DISABLE_NFSMOUNT, - CONFIG_NSH_DISABLE_NSLOOKUP, CONFIG_NSH_DISABLE_PASSWD, CONFIG_NSH_DISABLE_PING6, - CONFIG_NSH_DISABLE_POWEROFF, CONFIG_NSH_DISABLE_PRINTF, CONFIG_NSH_DISABLE_PS, - CONFIG_NSH_DISABLE_PUT, CONFIG_NSH_DISABLE_PWD, CONFIG_NSH_DISABLE_READLINK, - CONFIG_NSH_DISABLE_REBOOT, CONFIG_NSH_DISABLE_RM, CONFIG_NSH_DISABLE_RPTUN, - CONFIG_NSH_DISABLE_RMDIR, CONFIG_NSH_DISABLE_ROUTE, CONFIG_NSH_DISABLE_SET, - CONFIG_NSH_DISABLE_SHUTDOWN, CONFIG_NSH_DISABLE_SLEEP, CONFIG_NSH_DISABLE_SOURCE, - CONFIG_NSH_DISABLE_TEST, CONFIG_NSH_DISABLE_TIME, CONFIG_NSH_DISABLE_TRUNCATE, - CONFIG_NSH_DISABLE_UMOUNT, CONFIG_NSH_DISABLE_UNSET, CONFIG_NSH_DISABLE_URLDECODE, - CONFIG_NSH_DISABLE_URLENCODE, CONFIG_NSH_DISABLE_USERADD, CONFIG_NSH_DISABLE_USERDEL, - CONFIG_NSH_DISABLE_USLEEP, CONFIG_NSH_DISABLE_WGET, CONFIG_NSH_DISABLE_XD - -Verbose help output can be suppressed by defining CONFIG_NSH_HELP_TERSE. In that -case, the help command is still available but will be slightly smaller. - -Built-in Application Configuration Settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All built-in applications require that support for NSH built-in applications has been enabled. This support is enabled with CONFIG_BUILTIN=y and CONFIG_NSH_BUILTIN_APPS=y. - - Application Depends on Configuration - ----------- -------------------------- - ping CONFIG_NET && CONFIG_NET_ICMP && CONFIG_NET_ICMP_SOCKET && - CONFIG_SYSTEM_PING - ping6 CONFIG_NET && CONFIG_NET_ICMPv6 && CONFIG_NET_ICMPv6_SOCKET && - CONFIG_SYSTEM_PING6 - -NSH-Specific Configuration Settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - The behavior of NSH can be modified with the following settings in - the boards////configs//defconfig file: - - * CONFIG_NSH_READLINE - Selects the minimal implementation of readline(). This minimal - implementation provides on backspace for command line editing. - - * CONFIG_NSH_CLE - Selects the more extensive, EMACS-like command line editor. - Select this option only if (1) you don't mind a modest increase - in the FLASH footprint, and (2) you work with a terminal that - support VT100 editing commands. - - Selecting this option will add probably 1.5-2KB to the FLASH - footprint. - - * CONFIG_NSH_BUILTIN_APPS - 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 file system). Default is 1024. - - * CONFIG_NSH_STRERROR - strerror(errno) makes more readable output but strerror() is - very large and will not be used unless this setting is 'y'. - This setting depends upon the strerror() having been enabled - with CONFIG_LIBC_STRERROR. - - * CONFIG_NSH_LINELEN - The maximum length of one command line and of one output line. - Default: 80 - - * CONFIG_NSH_DISABLE_SEMICOLON - By default, you can enter multiple NSH commands on a line with - each command separated by a semicolon. You can disable this - feature to save a little memory on FLASH challenged platforms. - Default: n - - * CONFIG_NSH_CMDPARMS - If selected, then the output from commands, from file applications, and - from NSH built-in commands can be used as arguments to other - commands. The entity to be executed is identified by enclosing the - command line in back quotes. For example, - - set FOO `myprogram $BAR` - - Will execute the program named myprogram passing it the value of the - environment variable BAR. The value of the environment variable FOO - is then set output of myprogram on stdout. Because this feature commits - significant resources, it is disabled by default. - - The CONFIG_NSH_CMDPARMS interim output will be retained in a temporary - file. Full path to a directory where temporary files can be created is - taken from CONFIG_LIBC_TMPDIR and it defaults to /tmp if - CONFIG_LIBC_TMPDIR is not set. - - * CONFIG_NSH_MAXARGUMENTS - The maximum number of NSH command arguments. Default: 6 - - * CONFIG_NSH_ARGCAT - Support concatenation of strings with environment variables or command - output. For example: - - set FOO XYZ - set BAR 123 - set FOOBAR ABC_${FOO}_${BAR} - - would set the environment variable FOO to XYZ, BAR to 123 and FOOBAR - to ABC_XYZ_123. If NSH_ARGCAT is not selected, then a slightly small - FLASH footprint results but then also only simple environment - variables like $FOO can be used on the command line. - - * CONFIG_NSH_VARS - By default, there are no internal NSH variables. NSH will use OS - environment variables for all variable storage. If this option, NSH - will also support local NSH variables. These variables are, for the - most part, transparent and work just like the OS environment - variables. The difference is that when you create new tasks, all of - environment variables are inherited by the created tasks. NSH local - variables are not. - - If this option is enabled (and CONFIG_DISABLE_ENVIRON is not), then a - new command called 'export' is enabled. The export command works very - must like the set command except that is operates on environment - variables. When CONFIG_NSH_VARS is enabled, there are changes in the - behavior of certain commands - - ============== =========================== =========================== - CMD w/o CONFIG_NSH_VARS w/CONFIG_NSH_VARS - ============== =========================== =========================== - set Set environment var a to b Set NSH var a to b - set Causes an error Lists all NSH variables - unset Unsets environment var a Unsets both environment var - and NSH var a - export Causes an error Unsets NSH var a. Sets - environment var a to b. - export Causes an error Sets environment var a to - NSH var b (or ""). Unsets - local var a. - env Lists all environment Lists all environment - variables variables (only) - ============== =========================== =========================== - - * CONFIG_NSH_QUOTE - Enables back-slash quoting of certain characters within the command. - This option is useful for the case where an NSH script is used to - dynamically generate a new NSH script. In that case, commands must - be treated as simple text strings without interpretation of any - special characters. Special characters such as $, `, ", and others - must be retained intact as part of the test string. This option is - currently only available is CONFIG_NSH_ARGCAT is also selected. - - * CONFIG_NSH_NESTDEPTH - The maximum number of nested if-then[-else]-fi sequences that - are permissible. Default: 3 - - * CONFIG_NSH_DISABLESCRIPT - This can be set to 'y' to suppress support for scripting. This - setting disables the 'sh', 'test', and '[' commands and the - if-then[-else]-fi construct. This would only be set on systems - where a minimal footprint is a necessity and scripting is not. - - * CONFIG_NSH_DISABLE_ITEF - - If scripting is enabled, then then this option can be selected to - suppress support for if-then-else-fi sequences in scripts. This would - only be set on systems where some minimal scripting is required but - if-then-else-fi is not. - - * CONFIG_NSH_DISABLE_LOOPS - - If scripting is enabled, then then this option can be selected - suppress support for while-do-done and until-do-done sequences in - scripts. This would only be set on systems where some minimal - scripting is required but looping is not. - - * CONFIG_NSH_DISABLEBG - This can be set to 'y' to suppress support for background - commands. This setting disables the 'nice' command prefix and - the '&' command suffix. This would only be set on systems - where a minimal footprint is a necessity and background command - execution is not. - - * CONFIG_NSH_MMCSDMINOR - If the architecture supports an MMC/SD slot and if the NSH - architecture specific logic is present, this option will provide - the MMC/SD minor number, i.e., the MMC/SD block driver will - be registered as /dev/mmcsdN where N is the minor number. - Default is zero. - - * CONFIG_NSH_ROMFSETC - Mount a ROMFS file system at /etc and provide a startup script - at /etc/init.d/rcS. The default startup script will mount - a FAT FS RAMDISK at /tmp but the logic is easily extensible. - - * CONFIG_NSH_CONSOLE - If CONFIG_NSH_CONSOLE is set to 'y', then a serial - console front-end is selected. - - Normally, the serial console device is a UART and RS-232 - interface. However, if CONFIG_USBDEV is defined, then a USB - serial device may, instead, be used if the one of - the following are defined: - - CONFIG_PL2303 and CONFIG_PL2303_CONSOLE - Sets up the - Prolifics PL2303 emulation as a console device - at /dev/console. - - CONFIG_CDCACM and CONFIG_CDCACM_CONSOLE - Sets up the - CDC/ACM serial device as a console device at - dev/console. - - CONFIG_NSH_USBCONSOLE - If defined, then the an arbitrary USB device may be used - to as the NSH console. In this case, CONFIG_NSH_USBCONDEV - must be defined to indicate which USB device to use as - the console. - - CONFIG_NSH_USBCONDEV - If CONFIG_NSH_USBCONSOLE is set to 'y', then CONFIG_NSH_USBCONDEV - must also be set to select the USB device used to support - the NSH console. This should be set to the quoted name of a - read-/write-able USB driver. Default: "/dev/ttyACM0". - - If there are more than one USB devices, then a USB device - minor number may also need to be provided: - - CONFIG_NSH_USBDEV_MINOR - The minor device number of the USB device. Default: 0 - - CONFIG_NSH_USBKBD - Normally NSH uses the same device for stdin, stdout, and stderr. By - default, that device is /dev/console. If this option is selected, - then NSH will use a USB HID keyboard for stdin. In this case, the - keyboard is connected directly to the target (via a USB host - interface) and the data from the keyboard will drive NSH. NSH - output (stdout and stderr) will still go to /dev/console. - - CONFIG_NSH_USBKBD_DEVNAME - If NSH_USBKBD is set to 'y', then NSH_USBKBD_DEVNAME must also be - set to select the USB keyboard device used to support the NSH - console input. This should be set to the quoted name of a read- - able keyboard driver. Default: "/dev/kbda". - - CONFIG_NSH_USBDEV_TRACE - If USB tracing is enabled (CONFIG_USBDEV_TRACE), then NSH can - be configured to show the buffered USB trace data after each - NSH command: - - If CONFIG_NSH_USBDEV_TRACE is selected, then USB trace data - can be filtered as follows. Default: Only USB errors are traced. - - CONFIG_NSH_USBDEV_TRACEINIT - Show initialization events - CONFIG_NSH_USBDEV_TRACECLASS - Show class driver events - CONFIG_NSH_USBDEV_TRACETRANSFERS - Show data transfer events - CONFIG_NSH_USBDEV_TRACECONTROLLER - Show controller events - CONFIG_NSH_USBDEV_TRACEINTERRUPTS - Show interrupt-related events. - - * CONFIG_NSH_ALTCONDEV and CONFIG_NSH_CONDEV - If CONFIG_NSH_CONSOLE is set to 'y', then CONFIG_NSH_ALTCONDEV may also - be selected to enable use of an alternate character device to support - the NSH console. If CONFIG_NSH_ALTCONDEV is selected, then - CONFIG_NSH_CONDEV holds the quoted name of a readable/write-able - character driver such as: CONFIG_NSH_CONDEV="/dev/ttyS1". This is - useful, for example, to separate the NSH command line from the system - console when the system console is used to provide debug output. - Default: stdin and stdout (probably "/dev/console") - - NOTE 1: When any other device other than /dev/console is used for a - user interface, (1) linefeeds (\n) will not be expanded to carriage - return / linefeeds (\r\n). You will need to configure your terminal - program to account for this. And (2) input is not automatically - echoed so you will have to turn local echo on. - - NOTE 2: This option forces the console of all sessions to use - NSH_CONDEV. Hence, this option only makes sense for a system that - supports only a single session. This option is, in particular, - incompatible with Telnet sessions because each Telnet session must - use a different console device. - - * CONFIG_NSH_TELNET - If CONFIG_NSH_TELNET is set to 'y', then a TELENET - server front-end is selected. When this option is provided, - you may log into NuttX remotely using telnet in order to - access NSH. - - * CONFIG_NSH_ARCHINIT - Set if your board provides architecture specific initialization - via the board-interface function boardctl(). This function will - be called early in NSH initialization to allow board logic to - do such things as configure MMC/SD slots. - - If Telnet is selected for the NSH console, then we must configure - the resources used by the Telnet daemon and by the Telnet clients. - - * CONFIG_NSH_TELNETD_PORT - The telnet daemon will listen on this - TCP port number for connections. Default: 23 - - * CONFIG_NSH_TELNETD_DAEMONPRIO - Priority of the Telnet daemon. - Default: SCHED_PRIORITY_DEFAULT - - * CONFIG_NSH_TELNETD_DAEMONSTACKSIZE - Stack size allocated for the - Telnet daemon. Default: 2048 - - * CONFIG_NSH_TELNETD_CLIENTPRIO- Priority of the Telnet client. - Default: SCHED_PRIORITY_DEFAULT - - * CONFIG_NSH_TELNETD_CLIENTSTACKSIZE - Stack size allocated for the - Telnet client. Default: 2048 - - One or both of CONFIG_NSH_CONSOLE and CONFIG_NSH_TELNET - must be defined. If CONFIG_NSH_TELNET is selected, then there some - other configuration settings that apply: - - * CONFIG_NET=y - Of course, networking must be enabled - - * CONFIG_NET_TCP=y - TCP/IP support is required for telnet (as well as various other TCP-related - configuration settings). - - * CONFIG_NSH_IOBUFFER_SIZE - Determines the size of the I/O buffer to use for sending/ - receiving TELNET commands/responses - - * CONFIG_NETINIT_DHCPC - Obtain the IP address via DHCP. - - * CONFIG_NETINIT_IPADDR - If CONFIG_NETINIT_DHCPC is NOT set, then the static IP - address must be provided. - - * CONFIG_NETINIT_DRIPADDR - Default router IP address - - * CONFIG_NETINIT_NETMASK - Network mask - - * CONFIG_NETINIT_NOMAC - Set if your ethernet hardware has no built-in MAC address. - If set, a bogus MAC will be assigned. - - If you use DHCPC, then some special configuration network options are - required. These include: - - * CONFIG_NET=y - Of course, networking must be enabled - - * CONFIG_NET_UDP=y - UDP support is required for DHCP (as well as various other UDP-related - configuration settings) - - * CONFIG_NET_BROADCAST=y - UDP broadcast support is needed. - - * CONFIG_NET_ETH_PKTSIZE=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). - NOTE: Note that the actual MTU setting will depend upon the specific - link protocol. Here Ethernet is indicated. - - If CONFIG_NSH_ROMFSETC is selected, then the following additional - configuration setting apply: - - * CONFIG_NSH_ROMFSMOUNTPT - The default mountpoint for the ROMFS volume is /etc, but that - can be changed with this setting. This must be a absolute path - beginning with '/'. - - * CONFIG_NSH_INITSCRIPT - This is the relative path to the startup script within the mountpoint. - The default is init.d/rcS. This is a relative path and must not - start with '/'. - - * CONFIG_NSH_ROMFSDEVNO - This is the minor number of the ROMFS block device. The default is - '0' corresponding to /dev/ram0. - - * CONFIG_NSH_ROMFSSECTSIZE - This is the sector size to use with the ROMFS volume. Since the - default volume is very small, this defaults to 64 but should be - increased if the ROMFS volume were to be become large. Any value - selected must be a power of 2. - - When the default rcS file used when CONFIG_NSH_ROMFSETC is - selected, it will mount a FAT FS under /tmp. The following selections - describe that FAT FS. - - * CONFIG_NSH_FATDEVNO - This is the minor number of the FAT FS block device. The default is - '1' corresponding to /dev/ram1. - - * CONFIG_NSH_FATSECTSIZE - This is the sector size use with the FAT FS. Default is 512. - - * CONFIG_NSH_FATNSECTORS - This is the number of sectors to use with the FAT FS. Default is - 1024. The amount of memory used by the FAT FS will be - CONFIG_NSH_FATSECTSIZE * CONFIG_NSH_FATNSECTORS - bytes. - - * CONFIG_NSH_FATMOUNTPT - This is the location where the FAT FS will be mounted. Default - is /tmp. - -Common Problems -^^^^^^^^^^^^^^^ - - Problem: - The function 'readline' is undefined. - Usual Cause: - The following is missing from your defconfig file: - - CONFIG_SYSTEM_READLINE=y +additional, external _built-in_ applications that can be added to NSH. These are +separately excecuble programs but will appear much like the commands that are a +part of NSH. The primary difference from the user's perspective is that help +information about the built-in applications is not directly available from NSH. +Rather, you will need to execute the application with the -h option to get help +about using the built-in applications. + +There are several built-in appliations in the `apps/` repository. No attempt is +made here to enumerate all of them. But a few of the more common built- in +applications are listed below. + +- `ping [-c ] [-i ] ` + `ping6 [-c ] [-i ] ` + + Test the network communication with a remote peer. Example: + + ``` + nsh> 10.0.0.1 + PING 10.0.0.1 56 bytes of data + 56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms + 56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms + 10 packets transmitted, 10 received, 0% packet loss, time 10190 ms + nsh> + ``` + + `ping6` differs from `ping` in that it uses IPv6 addressing. + +## 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 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 as discussed at the bottom of this README file. + +## Command Dependencies on Configuration Settings + + Command | Depends on Configuration +----------|-------------------------- +[ | !`CONFIG_NSH_DISABLESCRIPT` +addroute | `CONFIG_NET` && `CONFIG_NET_ROUTE` +arp | `CONFIG_NET` && `CONFIG_NET_ARP` +base64dec | `CONFIG_NETUTILS_CODECS` && `CONFIG_CODECS_BASE64` +base64enc | `CONFIG_NETUTILS_CODECS` && `CONFIG_CODECS_BASE64` +basename | - +break | !`CONFIG_NSH_DISABLESCRIPT` && !`CONFIG_NSH_DISABLE_LOOPS` +cat | - +cd | !`CONFIG_DISABLE_ENVIRON` +cp | - +dd | - +delroute | `CONFIG_NET` && `CONFIG_NET_ROUTE` +df | !`CONFIG_DISABLE_MOUNTPOINT` +dirname | - +dmesg | `CONFIG_RAMLOG_SYSLOG` +echo | - +env | `CONFIG_FS_PROCFS` && !`CONFIG_DISABLE_ENVIRON` && !`CONFIG_PROCFS_EXCLUDE_ENVIRON` +exec | - +exit | - +export | `CONFIG_NSH_VARS` && !`CONFIG_DISABLE_ENVIRON` +free | - +get | `CONFIG_NET` && `CONFIG_NET_UDP` && MTU >= 558 (see note 1) +help | - +hexdump | - +ifconfig | `CONFIG_NET` && `CONFIG_FS_PROCFS` && !`CONFIG_FS_PROCFS_EXCLUDE_NET` +ifdown | `CONFIG_NET` && `CONFIG_FS_PROCFS` && !`CONFIG_FS_PROCFS_EXCLUDE_NET` +ifup | `CONFIG_NET` && `CONFIG_FS_PROCFS` && !`CONFIG_FS_PROCFS_EXCLUDE_NET` +insmod | `CONFIG_MODULE` +irqinfo | `CONFIG_FS_PROCFS` && `CONFIG_SCHED_IRQMONITOR` +kill | - +losetup | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_DEV_LOOP` +ln | `CONFIG_PSEUDOFS_SOFTLINK` +ls | - +lsmod | `CONFIG_MODULE` && `CONFIG_FS_PROCFS` && !`CONFIG_FS_PROCFS_EXCLUDE_MODULE` +md5 | `CONFIG_NETUTILS_CODECS` && `CONFIG_CODECS_HASH_MD5` +mb,mh,mw | - +mkdir | !`CONFIG_DISABLE_MOUNTPOINT` || !`CONFIG_DISABLE_PSEUDOFS_OPERATIONS` +mkfatfs | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_FSUTILS_MKFATFS` +mkfifo | `CONFIG_PIPES` && `CONFIG_DEV_FIFO_SIZE` > 0 +mkrd | !`CONFIG_DISABLE_MOUNTPOINT` +mount | !`CONFIG_DISABLE_MOUNTPOINT` +mv | !`CONFIG_DISABLE_MOUNTPOINT` || !`CONFIG_DISABLE_PSEUDOFS_OPERATIONS` +nfsmount | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_NET` && `CONFIG_NFS` +nslookup | `CONFIG_LIBC_NETDB` && `CONFIG_NETDB_DNSCLIENT` +password | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_NSH_LOGIN_PASSWD` +pmconfig | `CONFIG_PM` && !`CONFIG_NSH_DISABLE_PMCONFIG` +poweroff | `CONFIG_BOARDCTL_POWEROFF` +printf | - +ps | `CONFIG_FS_PROCFS` && !`CONFIG_FS_PROCFS_EXCLUDE_PROC` +put | `CONFIG_NET` && `CONFIG_NET_UDP` && MTU >= 558 (see note 1,2) +pwd | !`CONFIG_DISABLE_ENVIRON` +readlink | `CONFIG_PSEUDOFS_SOFTLINK` +reboot | `CONFIG_BOARDCTL_RESET` +rm | !`CONFIG_DISABLE_MOUNTPOINT` || !`CONFIG_DISABLE_PSEUDOFS_OPERATIONS` +rmdir | !`CONFIG_DISABLE_MOUNTPOINT` || !`CONFIG_DISABLE_PSEUDOFS_OPERATIONS` +rmmod | `CONFIG_MODULE` +route | `CONFIG_FS_PROCFS` && `CONFIG_FS_PROCFS_EXCLUDE_NET` &&
!`CONFIG_FS_PROCFS_EXCLUDE_ROUTE` && `CONFIG_NET_ROUTE` &&
!`CONFIG_NSH_DISABLE_ROUTE` && (`CONFIG_NET_IPv4` || `CONFIG_NET_IPv6`) +rptun | `CONFIG_RPTUN` +set | `CONFIG_NSH_VARS` || !`CONFIG_DISABLE_ENVIRON` +shutdown | `CONFIG_BOARDCTL_POWEROFF` || `CONFIG_BOARDCTL_RESET` +sleep | - +source | `CONFIG_NFILE_STREAMS` > 0 && !`CONFIG_NSH_DISABLESCRIPT` +test | !`CONFIG_NSH_DISABLESCRIPT` +telnetd | `CONFIG_NSH_TELNET` && !`CONFIG_NSH_DISABLE_TELNETD` +time | - +truncate | !`CONFIG_DISABLE_MOUNTPOINT` +umount | !`CONFIG_DISABLE_MOUNTPOINT` +uname | !`CONFIG_NSH_DISABLE_UNAME` +unset | `CONFIG_NSH_VARS` || !`CONFIG_DISABLE_ENVIRON` +urldecode | `CONFIG_NETUTILS_CODECS` && `CONFIG_CODECS_URLCODE` +urlencode | `CONFIG_NETUTILS_CODECS` && `CONFIG_CODECS_URLCODE` +useradd | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_NSH_LOGIN_PASSWD` +userdel | !`CONFIG_DISABLE_MOUNTPOINT` && `CONFIG_NSH_LOGIN_PASSWD` +usleep | - +get | `CONFIG_NET` && `CONFIG_NET_TCP` +xd | - + +**Notes**: + +1. Because of hardware padding, the actual MTU required for `put` and `get` + operations size may be larger. +2. Special TFTP server start-up options will probably be required to permit + creation of file for the correct operation of the `put` command. + +In addition, each NSH command can be individually disabled via one of the +following settings. All of these settings make the configuration of NSH +potentially complex but also allow it to squeeze into very small memory +footprints. + +``` +CONFIG_NSH_DISABLE_ADDROUTE, CONFIG_NSH_DISABLE_BASE64DEC, CONFIG_NSH_DISABLE_BASE64ENC, +CONFIG_NSH_DISABLE_BASENAME, CONFIG_NSH_DISABLE_CAT, CONFIG_NSH_DISABLE_CD, +CONFIG_NSH_DISABLE_CP, CONFIG_NSH_DISABLE_DD, CONFIG_NSH_DISABLE_DELROUTE, +CONFIG_NSH_DISABLE_DF, CONFIG_NSH_DISABLE_DIRNAME, CONFIG_NSH_DISABLE_DMESG, +CONFIG_NSH_DISABLE_ECHO, CONFIG_NSH_DISABLE_ENV, CONFIG_NSH_DISABLE_EXEC, +CONFIG_NSH_DISABLE_EXIT, CONFIG_NSH_DISABLE_EXPORT, CONFIG_NSH_DISABLE_FREE, +CONFIG_NSH_DISABLE_GET, CONFIG_NSH_DISABLE_HELP, CONFIG_NSH_DISABLE_HEXDUMP, +CONFIG_NSH_DISABLE_IFCONFIG, CONFIG_NSH_DISABLE_IFUPDOWN, CONFIG_NSH_DISABLE_KILL, +CONFIG_NSH_DISABLE_LOSETUP, CONFIG_NSH_DISABLE_LN, CONFIG_NSH_DISABLE_LS, +CONFIG_NSH_DISABLE_MD5, CONFIG_NSH_DISABLE_MB, CONFIG_NSH_DISABLE_MKDIR, +CONFIG_NSH_DISABLE_MKFATFS, CONFIG_NSH_DISABLE_MKFIFO, CONFIG_NSH_DISABLE_MKRD, +CONFIG_NSH_DISABLE_MH, CONFIG_NSH_DISABLE_MODCMDS, CONFIG_NSH_DISABLE_MOUNT, +CONFIG_NSH_DISABLE_MW, CONFIG_NSH_DISABLE_MV, CONFIG_NSH_DISABLE_NFSMOUNT, +CONFIG_NSH_DISABLE_NSLOOKUP, CONFIG_NSH_DISABLE_PASSWD, CONFIG_NSH_DISABLE_PING6, +CONFIG_NSH_DISABLE_POWEROFF, CONFIG_NSH_DISABLE_PRINTF, CONFIG_NSH_DISABLE_PS, +CONFIG_NSH_DISABLE_PUT, CONFIG_NSH_DISABLE_PWD, CONFIG_NSH_DISABLE_READLINK, +CONFIG_NSH_DISABLE_REBOOT, CONFIG_NSH_DISABLE_RM, CONFIG_NSH_DISABLE_RPTUN, +CONFIG_NSH_DISABLE_RMDIR, CONFIG_NSH_DISABLE_ROUTE, CONFIG_NSH_DISABLE_SET, +CONFIG_NSH_DISABLE_SHUTDOWN, CONFIG_NSH_DISABLE_SLEEP, CONFIG_NSH_DISABLE_SOURCE, +CONFIG_NSH_DISABLE_TEST, CONFIG_NSH_DISABLE_TIME, CONFIG_NSH_DISABLE_TRUNCATE, +CONFIG_NSH_DISABLE_UMOUNT, CONFIG_NSH_DISABLE_UNSET, CONFIG_NSH_DISABLE_URLDECODE, +CONFIG_NSH_DISABLE_URLENCODE, CONFIG_NSH_DISABLE_USERADD, CONFIG_NSH_DISABLE_USERDEL, +CONFIG_NSH_DISABLE_USLEEP, CONFIG_NSH_DISABLE_WGET, CONFIG_NSH_DISABLE_XD +``` + +Verbose help output can be suppressed by defining `CONFIG_NSH_HELP_TERSE`. In +that case, the `help` command is still available but will be slightly smaller. + +## Built-in Application Configuration Settings + +All built-in applications require that support for NSH built-in applications has +been enabled. This support is enabled with `CONFIG_BUILTIN=y` and +`CONFIG_NSH_BUILTIN_APPS=y`. + +Application | Depends on Configuration +------------|-------------------------- +ping | `CONFIG_NET` && `CONFIG_NET_ICMP` && `CONFIG_NET_ICMP_SOCKET` &&
`CONFIG_SYSTEM_PING` +ping6 | `CONFIG_NET` && `CONFIG_NET_ICMPv6` && `CONFIG_NET_ICMPv6_SOCKET` &&
`CONFIG_SYSTEM_PING6` + +## NSH-Specific Configuration Settings + +The behavior of NSH can be modified with the following settings in the +`boards////configs//defconfig` file: + +- `CONFIG_NSH_READLINE` – Selects the minimal implementation of `readline()`. + This minimal implementation provides on backspace for command line editing. + +- `CONFIG_NSH_CLE` + + Selects the more extensive, EMACS-like command line editor. Select this option + only if (1) you don't mind a modest increase in the FLASH footprint, and (2) + you work with a terminal that support VT100 editing commands. + + Selecting this option will add probably 1.5-2KB to the FLASH footprint. + +- `CONFIG_NSH_BUILTIN_APPS` – Support external registered, _builtin_ + applications that can be executed from the NSH command line (see + `apps/README.md` for more information). + +- `CONFIG_NSH_FILEIOSIZE` – Size of a static I/O buffer used for file access + (ignored if there is no file system). Default is `1024`. + +- `CONFIG_NSH_STRERROR` – `strerror(errno)` makes more readable output but + `strerror()` is very large and will not be used unless this setting is `y`. + This setting depends upon the `strerror()` having been enabled with + `CONFIG_LIBC_STRERROR`. + +- `CONFIG_NSH_LINELEN` – The maximum length of one command line and of one + output line. Default: `80` + +- `CONFIG_NSH_DISABLE_SEMICOLON` – By default, you can enter multiple NSH + commands on a line with each command separated by a semicolon. You can disable + this feature to save a little memory on FLASH challenged platforms. Default: + `n` + +- `CONFIG_NSH_CMDPARMS` + + If selected, then the output from commands, from file applications, and from + NSH built-in commands can be used as arguments to other commands. The entity + to be executed is identified by enclosing the command line in back quotes. For + example, + + ```shell + set FOO `myprogram $BAR` + ``` + + Will execute the program named myprogram passing it the value of the + environment variable `BAR`. The value of the environment variable FOO is then + set output of myprogram on stdout. Because this feature commits significant + resources, it is disabled by default. + + The `CONFIG_NSH_CMDPARMS` interim output will be retained in a temporary file. + Full path to a directory where temporary files can be created is taken from + `CONFIG_LIBC_TMPDIR` and it defaults to `/tmp` if `CONFIG_LIBC_TMPDIR` is not + set. + +- `CONFIG_NSH_MAXARGUMENTS` – The maximum number of NSH command arguments. + Default: `6` + +- `CONFIG_NSH_ARGCAT` + + Support concatenation of strings with environment variables or command + output. For example: + + ```shell + set FOO XYZ + set BAR 123 + set FOOBAR ABC_${FOO}_${BAR} + ``` + + would set the environment variable `FOO` to `XYZ`, `BAR` to `123` and `FOOBAR` + to `ABC_XYZ_123`. If `NSH_ARGCAT` is not selected, then a slightly small FLASH + footprint results but then also only simple environment variables like `$FOO` + can be used on the command line. + +- `CONFIG_NSH_VARS` + + By default, there are no internal NSH variables. NSH will use OS environment + variables for all variable storage. If this option, NSH will also support + local NSH variables. These variables are, for the most part, transparent and + work just like the OS environment variables. The difference is that when you + create new tasks, all of environment variables are inherited by the created + tasks. NSH local variables are not. + + If this option is enabled (and `CONFIG_DISABLE_ENVIRON` is not), then a new + command called 'export' is enabled. The export command works very must like + the set command except that is operates on environment variables. When + `CONFIG_NSH_VARS` is enabled, there are changes in the behavior of certain + commands + + Command | w/o `CONFIG_NSH_VARS` | w/`CONFIG_NSH_VARS` + -----------------|----------------------------------|--------------------- + `set ` | Set environment var `a` to `b`. | Set NSH var `a` to `b`. + `set` | Causes an error. | Lists all NSH variables. + `unset ` | Unsets environment var `a`. | Unsets both environment var and NSH var `a`. + `export ` | Causes an error. | Unsets NSH var `a`. Sets environment var `a` to `b`. + `export ` | Causes an error. | Sets environment var `a` to NSH var `b` (or `""`).
Unsets local var `a`. + `env` | Lists all environment variables. | Lists all environment variables (only). + +- `CONFIG_NSH_QUOTE` – Enables back-slash quoting of certain characters within + the command. This option is useful for the case where an NSH script is used to + dynamically generate a new NSH script. In that case, commands must be treated + as simple text strings without interpretation of any special characters. + Special characters such as `$`, `` ` ``, `"`, and others must be retained + intact as part of the test string. This option is currently only available is + `CONFIG_NSH_ARGCAT` is also selected. + +- `CONFIG_NSH_NESTDEPTH` – The maximum number of nested `if-then[-else]-fi` + sequences that are permissible. Default: `3` + +- `CONFIG_NSH_DISABLESCRIPT` – This can be set to `y` to suppress support for + scripting. This setting disables the `sh`, `test`, and `[` commands and the + `if-then[-else]-fi` construct. This would only be set on systems where a + minimal footprint is a necessity and scripting is not. + +- `CONFIG_NSH_DISABLE_ITEF` – If scripting is enabled, then then this option can + be selected to suppress support for `if-then-else-fi` sequences in scripts. + This would only be set on systems where some minimal scripting is required but + `if-then-else-fi` is not. + +- `CONFIG_NSH_DISABLE_LOOPS` – If scripting is enabled, then then this option + can be selected suppress support for `while-do-done` and `until-do-done` + sequences in scripts. This would only be set on systems where some minimal + scripting is required but looping is not. + +- `CONFIG_NSH_DISABLEBG` – This can be set to `y` to suppress support for + background commands. This setting disables the `nice` command prefix and the + `&` command suffix. This would only be set on systems where a minimal + footprint is a necessity and background command execution is not. + +- `CONFIG_NSH_MMCSDMINOR` – If the architecture supports an MMC/SD slot and if + the NSH architecture specific logic is present, this option will provide the + MMC/SD minor number, i.e., the MMC/SD block driver will be registered as + `/dev/mmcsdN` where `N` is the minor number. Default is zero. + +- `CONFIG_NSH_ROMFSETC` – Mount a ROMFS file system at `/etc` and provide a + startup script at `/etc/init.d/rcS`. The default startup script will mount a + FAT FS RAMDISK at `/tmp` but the logic is easily extensible. + +- `CONFIG_NSH_CONSOLE` + + If `CONFIG_NSH_CONSOLE` is set to `y`, then a serial console front-end is + selected. + + Normally, the serial console device is a UART and RS-232 interface. However, + if `CONFIG_USBDEV` is defined, then a USB serial device may, instead, be used + if the one of the following are defined: + + - `CONFIG_PL2303` and `CONFIG_PL2303_CONSOLE` + Sets up the Prolifics PL2303 emulation as a console device at + `/dev/console`. + + - `CONFIG_CDCACM` and `CONFIG_CDCACM_CONSOLE` + Sets up the CDC/ACM serial device as a console device at `/dev/console`. + + - `CONFIG_NSH_USBCONSOLE` – If defined, then the an arbitrary USB device may + be used to as the NSH console. In this case, `CONFIG_NSH_USBCONDEV` must be + defined to indicate which USB device to use as the console. + + - `CONFIG_NSH_USBCONDEV` – If `CONFIG_NSH_USBCONSOLE` is set to `y`, then + `CONFIG_NSH_USBCONDEV` must also be set to select the USB device used to + support the NSH console. This should be set to the quoted name of a + read-/write-able USB driver. Default: `/dev/ttyACM0`. + + If there are more than one USB devices, then a USB device minor number may + also need to be provided: + + - `CONFIG_NSH_USBDEV_MINOR` – The minor device number of the USB device. + Default: `0` + + - `CONFIG_NSH_USBKBD` – Normally NSH uses the same device for `stdin`, + `stdout`, and `stderr`. By default, that device is `/dev/console`. If this + option is selected, then NSH will use a USB HID keyboard for stdin. In this + case, the keyboard is connected directly to the target (via a USB host + interface) and the data from the keyboard will drive NSH. NSH output + (`stdout` and `stderr`) will still go to `/dev/console`. + + - `CONFIG_NSH_USBKBD_DEVNAME` – If `NSH_USBKBD` is set to `y`, then + `NSH_USBKBD_DEVNAME` must also be set to select the USB keyboard device used + to support the NSH console input. This should be set to the quoted name of a + read- able keyboard driver. Default: `/dev/kbda`. + + - `CONFIG_NSH_USBDEV_TRACE` – If USB tracing is enabled + (`CONFIG_USBDEV_TRACE`), then NSH can be configured to show the buffered USB + trace data after each NSH command: + + If `CONFIG_NSH_USBDEV_TRACE` is selected, then USB trace data can be + filtered as follows. Default: Only USB errors are traced. + + - `CONFIG_NSH_USBDEV_TRACEINIT` - Show initialization events + - `CONFIG_NSH_USBDEV_TRACECLASS` - Show class driver events + - `CONFIG_NSH_USBDEV_TRACETRANSFERS` - Show data transfer events + - `CONFIG_NSH_USBDEV_TRACECONTROLLER` - Show controller events + - `CONFIG_NSH_USBDEV_TRACEINTERRUPTS` - Show interrupt-related events. + +- `CONFIG_NSH_ALTCONDEV` and `CONFIG_NSH_CONDEV` + + If `CONFIG_NSH_CONSOLE` is set to `y`, then `CONFIG_NSH_ALTCONDEV` may also be + selected to enable use of an alternate character device to support the NSH + console. If `CONFIG_NSH_ALTCONDEV` is selected, then `CONFIG_NSH_CONDEV` holds + the quoted name of a readable/write-able character driver such as: + `CONFIG_NSH_CONDEV="/dev/ttyS1"`. This is useful, for example, to separate the + NSH command line from the system console when the system console is used to + provide debug output. Default: stdin and stdout (probably `/dev/console`) + + **Note 1**: When any other device other than `/dev/console` is used for a + user interface, (1) linefeeds (`\n`) will not be expanded to carriage return + / linefeeds (`\r\n`). You will need to configure your terminal program to + account for this. And (2) input is not automatically echoed so you will have + to turn local echo on. + + **Note 2**: This option forces the console of all sessions to use + `NSH_CONDEV`. Hence, this option only makes sense for a system that supports + only a single session. This option is, in particular, incompatible with + Telnet sessions because each Telnet session must use a different console + device. + +- `CONFIG_NSH_TELNET` – If `CONFIG_NSH_TELNET` is set to `y`, then a TELENET + server front-end is selected. When this option is provided, you may log into + NuttX remotely using telnet in order to access NSH. + +- `CONFIG_NSH_ARCHINIT` – Set if your board provides architecture specific + initialization via the board-interface function `boardctl()`. This function + will be called early in NSH initialization to allow board logic to do such + things as configure MMC/SD slots. + +If Telnet is selected for the NSH console, then we must configure the resources +used by the Telnet daemon and by the Telnet clients. + +- `CONFIG_NSH_TELNETD_PORT` – The telnet daemon will listen on this TCP port + number for connections. Default: `23` +- `CONFIG_NSH_TELNETD_DAEMONPRIO` – Priority of the Telnet daemon. Default: + `SCHED_PRIORITY_DEFAULT` +- `CONFIG_NSH_TELNETD_DAEMONSTACKSIZE` – Stack size allocated for the Telnet + daemon. Default: `2048` +- `CONFIG_NSH_TELNETD_CLIENTPRIO` – Priority of the Telnet client. Default: + `SCHED_PRIORITY_DEFAULT` +- `CONFIG_NSH_TELNETD_CLIENTSTACKSIZE` – Stack size allocated for the Telnet + client. Default: `2048` + +One or both of CONFIG_NSH_CONSOLE and `CONFIG_NSH_TELNET` must be defined. If +`CONFIG_NSH_TELNET` is selected, then there some other configuration settings +that apply: + +- `CONFIG_NET=y` – Of course, networking must be enabled +- `CONFIG_NET_TCP=y` – TCP/IP support is required for telnet (as well as various + other TCP-related configuration settings). +- `CONFIG_NSH_IOBUFFER_SIZE` – Determines the size of the I/O buffer to use for + sending/ receiving TELNET commands/responses. +- `CONFIG_NETINIT_DHCPC` – Obtain the IP address via DHCP. +- `CONFIG_NETINIT_IPADDR` – If `CONFIG_NETINIT_DHCPC` is NOT set, then the + static IP address must be provided. +- `CONFIG_NETINIT_DRIPADDR` – Default router IP address. +- `CONFIG_NETINIT_NETMASK` – Network mask. +- `CONFIG_NETINIT_NOMAC` – Set if your ethernet hardware has no built-in MAC + address. If set, a bogus MAC will be assigned. + +If you use DHCPC, then some special configuration network options are required. +These include: + +- `CONFIG_NET=y` – Of course, networking must be enabled. +- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various other + UDP-related configuration settings). +- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed. +- `CONFIG_NET_ETH_PKTSIZE=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). **Note**: Note that the actual MTU + setting will depend upon the specific link protocol. Here Ethernet is + indicated. + +If `CONFIG_NSH_ROMFSETC` is selected, then the following additional +configuration setting apply: + +- `CONFIG_NSH_ROMFSMOUNTPT` – The default mountpoint for the ROMFS volume is + `/etc`, but that can be changed with this setting. This must be a absolute + path beginning with `/`. + +- `CONFIG_NSH_INITSCRIPT` – This is the relative path to the startup script + within the mountpoint. The default is `init.d/rcS`. This is a relative path + and must not start with `/`. + +- `CONFIG_NSH_ROMFSDEVNO` – This is the minor number of the ROMFS block device. + The default is `0` corresponding to `/dev/ram0`. + +- `CONFIG_NSH_ROMFSSECTSIZE` – This is the sector size to use with the ROMFS + volume. Since the default volume is very small, this defaults to `64` but + should be increased if the ROMFS volume were to be become large. Any value + selected must be a power of `2`. + +When the default rcS file used when `CONFIG_NSH_ROMFSETC` is selected, it will +mount a FAT FS under `/tmp`. The following selections describe that FAT FS. + +- `CONFIG_NSH_FATDEVNO` – This is the minor number of the FAT FS block device. + The default is `1` corresponding to `/dev/ram1`. + +- `CONFIG_NSH_FATSECTSIZE` – This is the sector size use with the FAT FS. + Default is `512`. + +- `CONFIG_NSH_FATNSECTORS` – This is the number of sectors to use with the FAT + FS. Default is `1024`. The amount of memory used by the FAT FS will be + `CONFIG_NSH_FATSECTSIZE` * `CONFIG_NSH_FATNSECTORS` bytes. + +- `CONFIG_NSH_FATMOUNTPT` – This is the location where the FAT FS will be + mounted. Default is `/tmp`. + +## Common Problems + +Problem: + +``` +The function 'readline' is undefined. +``` + +Usual Cause: + +The following is missing from your `defconfig` file: + +```conf +CONFIG_SYSTEM_READLINE=y +``` diff --git a/system/cdcacm/README.md b/system/cdcacm/README.md index e89181c4e..61fc9cab6 100644 --- a/system/cdcacm/README.md +++ b/system/cdcacm/README.md @@ -1,42 +1,36 @@ -system/cdcacm -^^^^^^^^^^^^^^^ +# System / `cdcacm` USB CDC/ACM serial - This very simple add-on allows the USB CDC/ACM serial device can be dynamically - connected and disconnected from a host. This add-on can only be used as - an NSH built-in command. If built-in, then two new NSH commands will be - supported: +This very simple add-on allows the USB CDC/ACM serial device can be dynamically +connected and disconnected from a host. This add-on can only be used as an NSH +built-in command. If built-in, then two new NSH commands will be supported: - 1. sercon - Connect the CDC/ACM serial device - 2. serdis - Disconnect the CDC/ACM serial device +1. `sercon` – Connect the CDC/ACM serial device +2. `serdis` – Disconnect the CDC/ACM serial device - Configuration prerequisites (not complete): +Configuration prerequisites (not complete): - CONFIG_USBDEV=y : USB device support must be enabled - CONFIG_CDCACM=y : The CDC/ACM driver must be built +- `CONFIG_USBDEV=y` – USB device support must be enabled +- `CONFIG_CDCACM=y` – The CDC/ACM driver must be built - Configuration options specific to this add-on: +Configuration options specific to this add-on: - CONFIG_SYSTEM_CDCACM_DEVMINOR : The minor number of the CDC/ACM device. - : i.e., the 'x' in /dev/ttyACMx +- `CONFIG_SYSTEM_CDCACM_DEVMINOR` – The minor number of the CDC/ACM device, + i.e., the `x` in `/dev/ttyACMx`. - If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB, or - CONFIG_USBDEV_TRACE), then the add-on code will also initialize the USB trace - output. The amount of trace output can be controlled using: +If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and +`CONFIG_DEBUG_USB`, or `CONFIG_USBDEV_TRACE`), then the add-on code will also +initialize the USB trace output. The amount of trace output can be controlled +using: - CONFIG_SYSTEM_CDCACM_TRACEINIT - Show initialization events - CONFIG_SYSTEM_CDCACM_TRACECLASS - Show class driver events - CONFIG_SYSTEM_CDCACM_TRACETRANSFERS - Show data transfer events - CONFIG_SYSTEM_CDCACM_TRACECONTROLLER - Show controller events - CONFIG_SYSTEM_CDCACM_TRACEINTERRUPTS - Show interrupt-related events. +- `CONFIG_SYSTEM_CDCACM_TRACEINIT` – Show initialization events. +- `CONFIG_SYSTEM_CDCACM_TRACECLASS` – Show class driver events. +- `CONFIG_SYSTEM_CDCACM_TRACETRANSFERS` – Show data transfer events. +- `CONFIG_SYSTEM_CDCACM_TRACECONTROLLER` – Show controller events. +- `CONFIG_SYSTEM_CDCACM_TRACEINTERRUPTS` – Show interrupt-related events. - Note: This add-on is only enables or disable USB CDC/ACM via the NSH - 'sercon' and 'serdis' command. It will enable and disable tracing per - the settings before enabling and after disabling the CDC/ACM device. It - will not, however, monitor buffered trace data in the interim. If - CONFIG_USBDEV_TRACE is defined (and the debug options are not), other - application logic will need to monitor the buffered trace data. +**Note**: This add-on is only enables or disable USB CDC/ACM via the NSH +`sercon` and `serdis` command. It will enable and disable tracing per the +settings before enabling and after disabling the CDC/ACM device. It will not, +however, monitor buffered trace data in the interim. If `CONFIG_USBDEV_TRACE` is +defined (and the debug options are not), other application logic will need to +monitor the buffered trace data. diff --git a/system/cfgdata/README.md b/system/cfgdata/README.md index a298633ab..f3768019f 100644 --- a/system/cfgdata/README.md +++ b/system/cfgdata/README.md @@ -1,17 +1,22 @@ -Cfgdata Tool -=============== +# System / `cfgdata` - Source: NuttX - Author: Ken Pettit - Date: 18 December 2018 +``` +Author: Ken Pettit + Date: 18 December 2018 +``` -This application provides a command line interface for managing -platform specific configdata within the /dev/config device. +This application provides a command line interface for managing platform +specific configdata within the `/dev/config` device. -Usage: config [arguments] +**Usage**: - Where is one of: - all: show all config entries - print: display a specific config entry - set: set or change a config entry - unset: delete a config entry +```shell +config [arguments] +``` + +Where `` is one of: + +- `all` – show all config entries +- `print` – display a specific config entry +- `set` – set or change a config entry +- `unset` – delete a config entry diff --git a/system/composite/README.md b/system/composite/README.md index 1bb677c6a..6e4d89bb8 100644 --- a/system/composite/README.md +++ b/system/composite/README.md @@ -1,76 +1,69 @@ -system/composite -^^^^^^^^^^^^^^^^^^ +# System / `composite` USB Composite - This logic adds a NSH command to control a USB composite device. The only - supported devices in the composite are CDC/ACM serial and a USB mass storage - device. Which devices are enclosed in a composite device is configured with - an array of configuration-structs, handed over to the function - composite_initialize(). +This logic adds a NSH command to control a USB composite device. The only +supported devices in the composite are CDC/ACM serial and a USB mass storage +device. Which devices are enclosed in a composite device is configured with an +array of configuration-structs, handed over to the function +`composite_initialize()`. - Required overall configuration: +Required overall configuration: - Enable the USB Support of your Hardware / Processor e.g. SAMV7_USBDEVHS=y +Enable the USB Support of your Hardware / Processor e.g. `SAMV7_USBDEVHS=y` - CONFIG_USBDEV=y - USB device support - CONFIG_USBDEV_COMPOSITE=y - USB composite device support - CONFIG_COMPOSITE_IAD=y - Interface associate descriptor needed +- `CONFIG_USBDEV=y` – USB device support. +- `CONFIG_USBDEV_COMPOSITE=y` – USB composite device support. +- `CONFIG_COMPOSITE_IAD=y` – Interface associate descriptor needed. +- `CONFIG_CDCACM=y` – USB CDC/ACM serial device support. +- `CONFIG_CDCACM_COMPOSITE=y` – USB CDC/ACM serial composite device support. - CONFIG_CDCACM=y - USB CDC/ACM serial device support - CONFIG_CDCACM_COMPOSITE=y - USB CDC/ACM serial composite device support +The interface-, string-descriptor- and endpoint-numbers are configured via the +configuration-structs as noted above. The CDC/ACM serial device needs three +endpoints; one interrupt-driven and two bulk endpoints. - The interface-, string-descriptor- and endpoint-numbers are configured via the - configuration-structs as noted above. The CDC/ACM serial device needs three - endpoints; one interrupt-driven and two bulk endpoints. +- `CONFIG_USBMSC=y` – USB mass storage device support. +- `CONFIG_USBMSC_COMPOSITE=y` – USB mass storage composite device support. - CONFIG_USBMSC=y - USB mass storage device support - CONFIG_USBMSC_COMPOSITE=y - USB mass storage composite device support +Like the configuration for the CDC/ACM, the descriptor- and endpoint-numbers are +configured via the configuration struct. - Like the configuration for the CDC/ACM, the descriptor- and endpoint-numbers - are configured via the configuration struct. +Depending on the configuration struct you need to configure different vendor- +and product-IDs. Each `VID`/`PID` is unique to a device and thus to a dedicated +configuration. - Depending on the configuration struct you need to configure different vendor- - and product-IDs. Each VID/PID is unique to a device and thus to a dedicated - configuration. +Linux tries to detect the device types and installs default drivers if the +`VID`/`PID` pair is unknown. - Linux tries to detect the device types and installs default drivers if the - VID/PID pair is unknown. +Windows insists on a known and installed configuration. With an Atmel hardware +and Atmel-Studio or the Atmel-USB-drivers installed, you can test your +configuration with Atmel Example Vendor- and Product-IDs. - Windows insists on a known and installed configuration. With an Atmel - hardware and Atmel-Studio or the Atmel-USB-drivers installed, you can test - your configuration with Atmel Example Vendor- and Product-IDs. +If you have a USBMSC and a CDC/ACM configured in your combo, then you can try to +use - If you have a USBMSC and a CDC/ACM configured in your combo, then you can try - to use +- `VID = 0x03EB` (ATMEL) +- `PID = 0x2424` (ASF Example with MSC and CDC) - - VID = 0x03EB (ATMEL) - - PID = 0x2424 (ASF Example with MSC and CDC) +If for example you try to test a configuration with up to seven CDCs, then - If for example you try to test a configuration with up to seven CDCs, then +- `VID = 0x03EB` (ATMEL) +- `PID = 0x2426` (ASF Example with up to seven CDCs) - - VID = 0x03EB (ATMEL) - - PID = 0x2426 (ASF Example with up to seven CDCs) +This add-on can be built as two NSH _built-in_ commands: - CONFIG_NSH_BUILTIN_APPS - This add-on can be built as two NSH "built-in" commands if this option - is selected: 'conn' will connect the USB composite device; 'disconn' - will disconnect the USB composite device. +- `CONFIG_NSH_BUILTIN_APPS` – if this option is selected: `conn` will connect + the USB composite device; `disconn` will disconnect the USB composite device. - Configuration options unique to this add-on: +Configuration options unique to this add-on: - CONFIG_SYSTEM_COMPOSITE_DEBUGMM - Enables some debug tests to check for memory usage and memory leaks. +- `CONFIG_SYSTEM_COMPOSITE_DEBUGMM` – Enables some debug tests to check for + memory usage and memory leaks. - If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB), then - the add-on code will also manage the USB trace output. The amount of trace output - can be controlled using: +If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and +`CONFIG_DEBUG_USB`), then the add-on code will also manage the USB trace output. +The amount of trace output can be controlled using: - CONFIG_SYSTEM_COMPOSITE_TRACEINIT - Show initialization events - CONFIG_SYSTEM_COMPOSITE_TRACECLASS - Show class driver events - CONFIG_SYSTEM_COMPOSITE_TRACETRANSFERS - Show data transfer events - CONFIG_SYSTEM_COMPOSITE_TRACECONTROLLER - Show controller events - CONFIG_SYSTEM_COMPOSITE_TRACEINTERRUPTS - Show interrupt-related events. +- `CONFIG_SYSTEM_COMPOSITE_TRACEINIT` – Show initialization events. +- `CONFIG_SYSTEM_COMPOSITE_TRACECLASS` – Show class driver events. +- `CONFIG_SYSTEM_COMPOSITE_TRACETRANSFERS` – Show data transfer events. +- `CONFIG_SYSTEM_COMPOSITE_TRACECONTROLLER` – Show controller events. +- `CONFIG_SYSTEM_COMPOSITE_TRACEINTERRUPTS` – Show interrupt-related events. diff --git a/system/flash_eraseall/README.md b/system/flash_eraseall/README.md index 0b90d7f22..64d485def 100644 --- a/system/flash_eraseall/README.md +++ b/system/flash_eraseall/README.md @@ -1,12 +1,15 @@ -Flash Erase-all -=============== +# System / `flash_eraseall` Flash Erase-All - Source: NuttX - Author: Ken Pettit - Date: 5 May 2013 +``` +Author: Ken Pettit + Date: 5 May 2013 +``` -This application erases the FLASH of an MTD flash block. It is simply -a wrapper that calls the NuttX flash_eraseall interface. +This application erases the FLASH of an MTD flash block. It is simply a wrapper +that calls the NuttX `flash_eraseall` interface. -Usage: - flash_eraseall +**Usage**: + +```shell +flash_eraseall +``` diff --git a/system/i2c/README.md b/system/i2c/README.md index 0c44e1415..a1f921ec8 100644 --- a/system/i2c/README.md +++ b/system/i2c/README.md @@ -1,77 +1,80 @@ -README File for the I2C Tool -============================ +# System / `i2c` I2C Tool -The I2C tool provides a way to debug I2C related problems. This README file -will provide usage information for the I2C tools. +The I2C tool provides a way to debug I2C related problems. This README file will +provide usage information for the I2C tools. -CONTENTS -======== +## 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 + - Configuration Options +- Help +- Common Line Form +- Common Command Options + - _Sticky_ Options + - Environment variables + - Common Option Summary +- Command summary + - `bus` + - `dev` + - `get` + - `set` + - `verf` +- I2C Build Configuration + - NuttX Configuration Requirements + - I2C Tool Configuration Options -System Requirements -=================== +## System Requirements -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. +The I2C tool is designed to be implemented as a NuttShell (NSH) add-on. Read the +`apps/nshlib/README.md` file for information about add-ons. -Configuration Options ---------------------- -CONFIG_NSH_BUILTIN_APPS - 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 - Minimum 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) +### Configuration Options -HELP -==== +- `CONFIG_NSH_BUILTIN_APPS` – 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` – Minimum 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`). -First of all, the I2C tools supports a pretty extensive help output. That -help output can be view by entering either: +## Help - nsh> i2c 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 ? +``` +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. +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 [arguments] - Where is one of: +``` +nsh> i2c help - Show help : ? - List buses : bus - List devices : dev [OPTIONS] - Read register : get [OPTIONS] [] - Show help : help - Write register: set [OPTIONS] [] - Verify access : verf [OPTIONS] [] +Usage: i2c [arguments] +Where is one of: - Where common "sticky" OPTIONS include: + Show help : ? + List buses : bus + List devices : dev [OPTIONS] + Read register : get [OPTIONS] [] + Show help : help + Write register: set [OPTIONS] [] + Verify access : verf [OPTIONS] [] + + 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 @@ -79,297 +82,306 @@ options. [-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. +**Notes**: - WARNING: - o The I2C dev command may have bad side effects on your I2C devices. - Use only at your own risk. +- An environment variable like `$PATH` may be used for any argument. +- Arguments are _sticky_. For example, once the I2C address is specified, that + address will be re-used until it is changed. -COMMAND LINE FORM -================= +**Warning**: -The I2C is started from NSH by invoking the 'i2c' command from the NSH -command line. The general form of the 'i2c' command is: +- The I2C dev command may have bad side effects on your I2C devices. Use only at + your own risk. - i2c [arguments] +## Command Line Form -Where 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: +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 [OPTIONS] [arguments] +```shell +i2c [arguments] +``` -Where [OPTIONS] represents the common options and and arguments represent -the operation-specific arguments. +Where `` 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: -COMMON COMMAND OPTIONS -====================== +```shell +i2c [OPTIONS] [arguments] +``` -"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. +Where `[OPTIONS]` represents the common options and and arguments represent the +operation-specific 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). +## Common Command Options -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. +### _Sticky_ Options -Common Option Summary ---------------------- +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. -[-a addr] is the I2C device address (hex). Default: 03 Current: 03 +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). - 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 +### 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 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 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. + **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 +- `[-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. + 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 +- `[-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 + 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. + 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 +- `[-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. + 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 +- `[-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. + 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 +- `[-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 repetition. + On commands that take a optional number of repetitions, the option can be used + to temporarily increment the `regaddr` value by one on each repetition. -[-f freq] I2C frequency. Default: 400000 Current: 400000 +- `[-f freq]` I2C frequency. Default: `400000` Current: `400000` - The [-f freq] sets the frequency of the I2C device. + The `[-f freq]` sets the frequency of the I2C device. -COMMAND SUMMARY -=============== +## Command Summary -We have already seen the I2C help (or ?) commands above. This section will +We have already seen the I2C help (or `?`) commands above. This section will discuss the remaining commands. -List buses: bus [OPTIONS] --------------------------- +### 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: +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 +``` +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. +`CONFIG_I2CTOOL_MINBUS` and `CONFIG_I2CTOOL_MAXBUS`. -List devices: dev [OPTIONS] ------------------------------------------- +### List devices: `dev [OPTIONS] ` -The 'dev' command will attempt to identify all of the I2C devices on the -selected bus. The and arguments are 7-bit, hexadecimal -I2C addresses. This command will examine a range of addresses beginning -with and continuing through . It will request the value -of register address zero from each device. +The `dev` command will attempt to identify all of the I2C devices on the +selected bus. The `` and `` arguments are 7-bit, hexadecimal I2C +addresses. This command will examine a range of addresses beginning with +`` and continuing through ``. It will request the value of register +address zero from each device. -The register address of zero is always used by default. The previous -"sticky" register address is ignored. Some devices may not respond to -ergister address zero, however. To work around this, you can provide a -new "sticky" register address on the command as an option to the 'dev' -command. Then that new "sticky" register address will be used instead -of the address zero. +The register address of zero is always used by default. The previous _sticky_ +register address is ignored. Some devices may not respond to ergister address +zero, however. To work around this, you can provide a new _sticky_ register +address on the command as an option to the 'dev' command. Then that new _sticky_ +register address will be used instead of the address zero. -If the device at an I2C address responds to the read request, then the -'dev' command will display the I2C address of the device. If the device -does not respond, this command will display "--". The resulting display -looks like: +If the device at an I2C address responds to the read request, then the `dev` +command will display the I2C address of the device. If the device does not +respond, this command will display `--`. The resulting display looks like: +```shell nsh> i2c dev 03 77 +``` + +``` 0 1 2 3 4 5 6 7 8 9 a b c d e f -00: -- -- -- -- -- -- -- -- -- -- -- -- -- +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? +Warnings: +- The I2C dev command may have bad side effects on certain I2C devices. For + example, if could cause data loss in an EEPROM device. +- 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] ----------------------------- +### 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 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. +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 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. +An optional `` 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). +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 +``` +READ Bus: 1 Addr: 49 Subaddr: 04 Value: 96 +``` - All values (except the bus numbers) are hexadecimal. +All values (except the bus numbers) are hexadecimal. -Write register: set [OPTIONS] -------------------------------------- +### Write register: `set [OPTIONS] ` - 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 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. +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 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. +An optional `` 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). +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 +``` +WROTE Bus: 1 Addr: 49 Subaddr: 04 Value: 96 +``` - All values (except the bus numbers) are hexadecimal. +All values (except the bus numbers) are hexadecimal. -Verify access : verf [OPTIONS] [] ------------------------------------------------------- +### Verify access: `verf [OPTIONS] []` - 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. +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. - An optional 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. +If no value is provided, then this command will use the register address itself +as the data, providing for a address-in-address test. - 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). +An optional `` 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. - VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE +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). - All values (except the bus numbers) are hexadecimal. +``` +VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE +``` -I2C BUILD CONFIGURATION -======================= +All values (except the bus numbers) are hexadecimal. + +## I2C Build Configuration + +### NuttX Configuration Requirements -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: + Using `make menuconfig`, select the i2c tool. The following definition should + appear in your `.config` file: - CONFIG_SYSTEM_I2C=y + ```conf + CONFIG_SYSTEM_I2C=y + ``` 2. Device-specific I2C driver support must be enabled: - CONFIG_I2C_DRIVER=y + ```conf + CONFIG_I2C_DRIVER=y + ``` - The I2C tool will then use the I2C character driver to access the I2C - bus. These devices will reside at /dev/i2cN where N is the I2C bus - number. + The I2C tool will then use the I2C character driver to access the I2C bus. + These devices will reside at `/dev/i2cN` where `N` is the I2C bus number. - NOTE 1: The I2C driver ioctl interface is defined in - include/nuttx/i2c/i2c_master.h. + **Note**: The I2C driver `ioctl` interface is defined in + `include/nuttx/i2c/i2c_master.h`. -I2C Tool Configuration Options ------------------------------- +### 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. +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_NSH_BUILTIN_APPS: 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: Minimum 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) +- `CONFIG_NSH_BUILTIN_APPS` – 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` – Minimum 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`). diff --git a/system/nsh/README.md b/system/nsh/README.md index 81bbc23d5..8d3998b01 100644 --- a/system/nsh/README.md +++ b/system/nsh/README.md @@ -1,45 +1,50 @@ -README -====== +# System / `nsh` NuttShell (NSH) - Basic Configuration - ------------------- - This directory provides an example of how to configure and use - the NuttShell (NSH) application. NSH is a simple shell - application. NSH is described in its own README located at - apps/nshlib/README.txt. This function is enabled with: +## Basic Configuration - CONFIG_SYSTEM_NSH=y +This directory provides an example of how to configure and use the NuttShell +(NSH) application. NSH is a simple shell application. NSH is described in its +own README located at `apps/nshlib/README.md`. This function is enabled with: - Applications using this example will need to provide an defconfig - file in the configuration directory with instruction to build - the NSH library like: +```conf +CONFIG_SYSTEM_NSH=y +``` - CONFIG_NSH_LIBRARY=y +Applications using this example will need to provide an `defconfig` file in the +configuration directory with instruction to build the NSH library like: - Other Configuration Requirements - -------------------------------- - NOTE: If the NSH serial console is used, then following is also - required to build the readline() library: +```conf +CONFIG_NSH_LIBRARY=y +``` - CONFIG_SYSTEM_READLINE=y +## Other Configuration Requirements - And if networking is included: +**Note**: If the NSH serial console is used, then following is also required to +build the `readline()` library: - CONFIG_NETUTILS_NETLIB=y - CONFIG_NETUTILS_DHCPC=y - CONFIG_NETDB_DNSCLIENT=y - CONFIG_NETUTILS_TFTPC=y - CONFIG_NETUTILS_WEBCLIENT=y +```conf +CONFIG_SYSTEM_READLINE=y +``` - If the Telnet console is enabled, then the defconfig file should - also include: +And if networking is included: - CONFIG_NETUTILS_TELNETD=y +```conf +CONFIG_NETUTILS_NETLIB=y +CONFIG_NETUTILS_DHCPC=y +CONFIG_NETDB_DNSCLIENT=y +CONFIG_NETUTILS_TFTPC=y +CONFIG_NETUTILS_WEBCLIENT=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): +If the Telnet console is enabled, then the defconfig file should also include: - CONFIG_STDIO_BUFFER_SIZE - Some value >= 64 - CONFIG_STDIO_LINEBUFFER=y +```conf +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` diff --git a/system/nxplayer/README.md b/system/nxplayer/README.md index 32d1f20fc..a17730d53 100644 --- a/system/nxplayer/README.md +++ b/system/nxplayer/README.md @@ -1,17 +1,18 @@ -NXPlayer -======== +# System / `nxplayer` NXPlayer - Source: NuttX - Author: Ken Pettit - Date: 11 Sept 2013 +``` +Author: Ken Pettit + Date: 11 Sept 2013 +``` -This application implements a command-line media player -which uses the NuttX Audio system to play files (mp3, -wav, etc.) from the file system. +This application implements a command-line media player which uses the NuttX +Audio system to play files (`mp3`, `wav`, etc.) from the file system. Usage: - nxplayer -The application presents an command line for specifying -player commands, such as "play filename", "pause", -"volume 50%", etc. +```shell +nxplayer +``` + +The application presents an command line for specifying player commands, such as +`play filename`, `pause`, `volume 50%`, etc. diff --git a/system/psmq/README.md b/system/psmq/README.md index 5c74f8a4e..1846cce26 100644 --- a/system/psmq/README.md +++ b/system/psmq/README.md @@ -1,47 +1,59 @@ -README.txt -========== +# System / `psmq` Publish Subscribe Message Queue -psmq is publish subscribe message queue. It's a set of programs and libraries -to implement publish/subscribe way of inter process communication on top of +`psmq` is publish subscribe message queue. It's a set of programs and libraries +to implement publish/subscribe way of inter-process communication on top of POSIX message queue. -Manuals, source code and more info at: -https://psmq.kurwinet.pl +Manuals, source code and more info at: https://psmq.kurwinet.pl +Little demo using `psmqd` broker, `psmq_pub` and `psmq_sub`: -Little demo using psmqd broker, psmq_pub and psmq_sub: +Start broker and make it log to file -# start broker and make it log to file - nsh> psmqd -b/brok -p/sd/psmqd/psmqd.log +``` +nsh> psmqd -b/brok -p/sd/psmqd/psmqd.log +``` -# start subscribe thread that will read all messages send on /can/* topic - nsh> psmq_sub -n/sub -b/brok -t/can/* -o/sd/psmq-sub/can.log - n/connected to broker /brok - n/subscribed to /can/* - n/start receiving data +Start subscribe thread that will read all messages send on `/can/*` topic -# publish some messages - nsh> psmq_pub -b/brok -t/can/engine/rpm -m50 - nsh> psmq_pub -b/brok -t/adc/volt -m30 - nsh> psmq_pub -b/brok -t/can/room/10/temp -m23 - nsh> psmq_pub -b/brok -t/pwm/fan1/speed -m300 +``` +nsh> psmq_sub -n/sub -b/brok -t/can/* -o/sd/psmq-sub/can.log +n/connected to broker /brok +n/subscribed to /can/* +n/start receiving data +``` -# check out subscribe thread logs - nsh> cat /sd/psmq-sub/can.log - [1970-01-01 00:00:53] topic: /can/engine/rpm, priority: 0, paylen: 3, payload: - [1970-01-01 00:00:53] 0x0000 35 30 00 50. - [1970-01-01 00:00:58] topic: /can/room/10/temp, priority: 0, paylen: 3, payload: - [1970-01-01 00:00:58] 0x0000 32 33 00 23. +Publish some messages -As you can see /adc/volt and /pwm/fan1/speed haven't been received by subscribe -thread. +``` +nsh> psmq_pub -b/brok -t/can/engine/rpm -m50 +nsh> psmq_pub -b/brok -t/adc/volt -m30 +nsh> psmq_pub -b/brok -t/can/room/10/temp -m23 +nsh> psmq_pub -b/brok -t/pwm/fan1/speed -m300 +``` + +Check out subscribe thread logs + +``` +nsh> cat /sd/psmq-sub/can.log +``` + +``` +[1970-01-01 00:00:53] topic: /can/engine/rpm, priority: 0, paylen: 3, payload: +[1970-01-01 00:00:53] 0x0000 35 30 00 50. +[1970-01-01 00:00:58] topic: /can/room/10/temp, priority: 0, paylen: 3, payload: +[1970-01-01 00:00:58] 0x0000 32 33 00 23. +``` + +As you can see `/adc/volt` and `/pwm/fan1/speed` haven't been received by +subscribe thread. Content: -* psmqd - broker, relays messages between clients -* psmq_sub - listens to specified topics, can be used as logger for - communication (optional) -* psmq_pub - publishes messages directly from shell. Can send binary data, but +- `psmqd` – broker, relays messages between clients. +- `psmq_sub` – listens to specified topics, can be used as logger for + communication (optional). +- `psmq_pub` – publishes messages directly from shell. Can send binary data, but requires pipes, so on nuttx it can only send ASCII. -* libpsmq - library used to communicate with the broker and send/receive - messages +- `libpsmq` – library used to communicate with the broker and send/receive + messages. diff --git a/system/spi/README.md b/system/spi/README.md index c4d7be9e9..17c7b679c 100644 --- a/system/spi/README.md +++ b/system/spi/README.md @@ -1,226 +1,246 @@ -README File for the SPI Tool -============================ +# System / `spi` SPI Tool -The I2C tool provides a way to debug SPI related problems. This README file -will provide usage information for the SPI tools. +The I2C tool provides a way to debug SPI related problems. This README file will +provide usage information for the SPI tools. -CONTENTS -======== +## Contents - o System Requirements - - SPI 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 + - SPI Driver + - Configuration Options +- Help +- Common Line Form +- Common Command Options + - _Sticky_ Options + - Environment variables + - Common Option Summary +- Command summary + - `bus` + - `dev` + - `get` + - `set` + - `verf` +- I2C Build Configuration + - NuttX Configuration Requirements + - I2C Tool Configuration Options -System Requirements -=================== +## System Requirements -The SPI tool is designed to be implemented as a NuttShell (NSH) add-on. Read -the apps/nshlib/README.txt file for information about add-ons. +The SPI tool is designed to be implemented as a NuttShell (NSH) add-on. Read the +`apps/nshlib/README.md` file for information about add-ons. -Configuration Options ---------------------- -CONFIG_NSH_BUILTIN_APPS - Build the tools as an NSH built-in command -CONFIG_SPITOOL_MINBUS - Smallest bus index supported by the hardware (default 0). -CONFIG_SPITOOL_MAXBUS - Largest bus index supported by the hardware (default 3) -CONFIG_SPITOOL_DEFFREQ - Default frequency (default: 40000000) -CONFIG_SPITOOL_DEFMODE - Default mode, where; - 0 = CPOL=0, CHPHA=0 - 1 = CPOL=0, CHPHA=1 - 2 = CPOL=1, CHPHA=0 - 3 = CPOL=1, CHPHA=1 -CONFIG_SPITOOL_DEFWIDTH - Default bit width (default 8) -CONFIG_SPITOOL_DEFWORDS - Default number of words to exchange (default 1) +### Configuration Options -HELP -==== +- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command. +- `CONFIG_SPITOOL_MINBUS` – Smallest bus index supported by the hardware + (default `0`). +- `CONFIG_SPITOOL_MAXBUS` – Largest bus index supported by the hardware + (default `3`). +- `CONFIG_SPITOOL_DEFFREQ` – Default frequency (default: `40000000`). +- `CONFIG_SPITOOL_DEFMODE` – Default mode, where + ``` + 0 = CPOL=0, CHPHA=0 + 1 = CPOL=0, CHPHA=1 + 2 = CPOL=1, CHPHA=0 + 3 = CPOL=1, CHPHA=1 + ``` +- `CONFIG_SPITOOL_DEFWIDTH` – Default bit width (default `8`). +- `CONFIG_SPITOOL_DEFWORDS` – Default number of words to exchange (default `1`). -he SPI tools supports some help output. That help output can be view -by entering either: +## Help - nsh> spi help +The SPI tools supports some help output. That help output can be view by +entering either: + +``` +nsh> spi help +``` or - nsh> spi ? +``` +nsh> spi ? +``` -Here is an example of the help output. I shows the general form of the -command line, the various SPI commands supported with their unique command -line options, and a more detailed summary of the command SPI command -options. +Here is an example of the help output. I shows the general form of the command +line, the various SPI commands supported with their unique command line options, +and a more detailed summary of the command SPI command options. +``` nsh> Usage: spi [arguments] + Where is one of: Show help : ? - List buses : bus + List buses : bus SPI Exchange : exch [OPTIONS] [] Show help : help -Where common "sticky" OPTIONS include: +Where common _sticky_ OPTIONS include: [-b bus] is the SPI bus number (decimal). Default: 0 Current: 2 [-f freq] SPI frequency. Default: 4000000 Current: 4000000 [-m mode] Mode for transfer. Default: 0 Current: 0 [-u udelay] Delay after transfer in uS. Default: 0 Current: 0 [-w width] Width of bus. Default: 8 Current: 8 - [-x count] Words to exchange Default: 1 Current: 4 + [-x count] Words to exchange. Default: 1 Current: 4 +``` -NOTES: -o An environment variable like $PATH may be used for any argument. -o Arguments are "sticky". For example, once the SPI address is - specified, that address will be re-used until it is changed. +**Notes**: -WARNING: -o The SPI commands may have bad side effects on your SPI devices. - Use only at your own risk. +- An environment variable like $PATH may be used for any argument. +- Arguments are _sticky_. For example, once the SPI address is specified, that + address will be re-used until it is changed. -COMMAND LINE FORM -================= +**Warning**: -The SPI is started from NSH by invoking the 'spi' command from the NSH -command line. The general form of the 'spi' command is: +- The SPI commands may have bad side effects on your SPI devices. Use only at + your own risk. - spi [arguments] +## Command Line Form -Where is a "sub-command" and identifies one SPI operation supported -by the tool. [arguments] represents the list of arguments needed to perform -the SPI 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 SPI command would be: +The SPI is started from NSH by invoking the `spi` command from the NSH command +line. The general form of the `spi` command is: - i2c [OPTIONS] [arguments] +```shell +spi [arguments] +``` -Where [OPTIONS] represents the common options and and arguments represent -the operation-specific arguments. +Where `` is a _sub-command_ and identifies one SPI operation supported by +the tool. `[arguments]` represents the list of arguments needed to perform the +SPI 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 SPI command would be: -COMMON COMMAND OPTIONS -====================== +```shell +i2c [OPTIONS] [arguments] +``` -"Sticky" Options ----------------- -In order to interact with SPI devices, there are a number of SPI 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 SPI parameter. The SPI tool -takes a different approach, instead: The SPI configuration can be specified -as a (potentially long) sequence of command line arguments. +Where `[OPTIONS]` represents the common options and and arguments represent the +operation-specific arguments. -These arguments, however, are "sticky." They are sticky in the sense that -once you set the SPI parameter, that value will remain until it is reset -with a new value (or until you reset the board). +## Common Command Options -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 -SPI commands. +### _Sticky_ Options -Common Option Summary ---------------------- +In order to interact with SPI devices, there are a number of SPI 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 SPI parameter. The SPI tool takes a different +approach, instead: The SPI configuration can be specified as a (potentially +long) sequence of command line arguments. -[-b bus] is the SPI bus number (decimal). Default: 0 - Which SPI bus to commiuncate on. The bus must have been initialised - as a character device in the config in the form /dev/spiX (e.g. /dev/spi2). +These arguments, however, are _sticky_. They are sticky in the sense that once +you set the SPI 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 SPI commands. + +### Common Option Summary + +- `[-b bus]` is the SPI bus number (decimal). Default: `0` + + Which SPI bus to commiuncate on. The bus must have been initialised as a + character device in the config in the form `/dev/spiX` (e.g. `/dev/spi2`). The valid range of bus numbers is controlled by the configuration settings - CONFIG_SPITOOL_MINBUS and CONFIG_SPITOOL_MAXBUS. + `CONFIG_SPITOOL_MINBUS` and `CONFIG_SPITOOL_MAXBUS`. The bus numbers are small, decimal numbers. -[-m mode] SPI Mode for transfer. +- `[-m mode]` SPI Mode for transfer. + Which of the available SPI modes is to be used. Options are; - 0 = CPOL=0, CHPHA=0 - 1 = CPOL=0, CHPHA=1 - 2 = CPOL=1, CHPHA=0 - 3 = CPOL=1, CHPHA=1 - [-u udelay] Delay after transfer in uS. Default: 0 - Any extra delay to be provided after the transfer. Not normally needed - from the command line. + ``` + 0 = CPOL=0, CHPHA=0 + 1 = CPOL=0, CHPHA=1 + 2 = CPOL=1, CHPHA=0 + 3 = CPOL=1, CHPHA=1 + ``` + +- `[-u udelay]` Delay after transfer in uS. Default: `0` + + Any extra delay to be provided after the transfer. Not normally needed from + the command line. + +- `[-x count]` Words to exchange Default: `1` -[-x count] Words to exchange Default: 1 The number of words to be transited over the bus. For sanitys sake this is - limited to a relatively small number (40 by default). Any data on the - command line is sent first, padded by 0xFF's while any remaining data - are received. + limited to a relatively small number (`40` by default). Any data on the + command line is sent first, padded by `0xFF`'s while any remaining data are + received. -[-w width] is the data width (varies according to target). Default: 8 +- `[-w width]` is the data width (varies according to target). Default: `8` Various SPI devices support different data widths. This option is untested. -[-f freq] I2C frequency. Default: 4000000 Current: 4000000 +- `[-f freq]` I2C frequency. Default: `4000000` Current: `4000000` - The [-f freq] sets the frequency of the SPI device. The default is very conservative. + The `[-f freq]` sets the frequency of the SPI device. The default is very + conservative. -COMMAND SUMMARY -=============== +## Command Summary -List buses: bus [OPTIONS] --------------------------- +### List buses: `bus [OPTIONS]` -This command will simply list all of the configured SPI buses and indicate -which are supported by the driver and which are not: +This command will simply list all of the configured SPI buses and indicate which +are supported by the driver and which are not: - BUS EXISTS? - Bus 1: YES - Bus 2: NO +``` +BUS EXISTS? +Bus 1: YES +Bus 2: NO +``` The valid range of bus numbers is controlled by the configuration settings -CONFIG_SPITOOL_MINBUS and CONFIG_SPITOOL_MAXBUS. +`CONFIG_SPITOOL_MINBUS` and `CONFIG_SPITOOL_MAXBUS`. -Exchange data: exch [OPTIONS] ------------------------------------------------- +### Exchange data: `exch [OPTIONS] ` This command triggers an SPI transfer, returning the data back from the far end. As an example (with MOSI looped back to MISO); -nsh>spi exch -b 2 -x 4 aabbccdd +```shell +nsh> spi exch -b 2 -x 4 aabbccdd +``` + +``` Received: AA BB CC DD -nsh> +``` -Note that the TXData are always specified in hex, and are always two digits each, -case insensitive. +Note that the `TX Data` are always specified in hex, and are always two digits +each, case insensitive. -I2C BUILD CONFIGURATION -======================= +## I2C Build Configuration + +### NuttX Configuration Requirements -NuttX Configuration Requirements --------------------------------- The SPI tools requires the following in your NuttX configuration: 1. Application configuration. - Using 'make menuconfig', select the SPI tool. The following - definition should appear in your .config file: + Using `make menuconfig`, select the SPI tool. The following definition should + appear in your `.config` file: - CONFIG_SYSTEM_SPI=y + ```conf + CONFIG_SYSTEM_SPI=y + ``` 2. Device-specific SPI driver support must be enabled: - CONFIG_SPI_DRIVER=y + ```conf + CONFIG_SPI_DRIVER=y + ``` - The SPI tool will then use the SPI character driver to access the SPI - bus. These devices will reside at /dev/spiN where N is the I2C bus - number. + The SPI tool will then use the SPI character driver to access the SPI bus. + These devices will reside at `/dev/spiN` where `N` is the I2C bus number. - NOTE 1: The SPI driver ioctl interface is defined in - include/nuttx/spi/spi.h. + **Note**: The SPI driver `ioctl` interface is defined in + `include/nuttx/spi/spi.h`. diff --git a/system/termcurses/README.md b/system/termcurses/README.md index 541abbf77..9a23cf9b0 100644 --- a/system/termcurses/README.md +++ b/system/termcurses/README.md @@ -1,49 +1,50 @@ -Termcurses -========== +# System / `termcurses` Termcurses - Terminal emulation library for NuttX - Author: Ken Pettit - 2018-2019 +Terminal emulation library for NuttX + +``` +Author: Ken Pettit + Date: 2018-2019 +``` The Termcurses library provides terminal emulation support for performing common screen actions such as cursor movement, foreground / background color control -and keyboard escape sequence mapping. The initial release supports only vt100 / -ansi terminal types, but the library architecture has an extensible interface -to allow support for additional emulation types if needed. +and keyboard escape sequence mapping. The initial release supports only `vt100` +/ `ansi` terminal types, but the library architecture has an extensible +interface to allow support for additional emulation types if needed. -The library can be used standalone or in conjunction with the apps/graphics/pdcurses -libraries. The pdcurses libraries have been updated with a "termcurses" config -option which fully integrates the termcurses library automatically. +The library can be used standalone or in conjunction with the +`apps/graphics/pdcurses` libraries. The pdcurses libraries have been updated +with a _termcurses_ config option which fully integrates the termcurses library +automatically. -Usage -===== +## Usage To use the termcurses library, the routines must be initialized by calling the -termcurses_initterm() function. This routine accepts a terminal type string -identifying the type of terminal emulation support requested. If a NULL pointer -is passed, then the routine will check for a "TERM" environment variable and set -the terminal type based on that string. If the emulation type still cannot be -determined, the routine will default to "vt100" emulation type. +`termcurses_initterm()` function. This routine accepts a terminal type string +identifying the type of terminal emulation support requested. If a `NULL` +pointer is passed, then the routine will check for a `TERM` environment variable +and set the terminal type based on that string. If the emulation type still +cannot be determined, the routine will default to `vt100` emulation type. -Upon successful initialization, the termcurses_initterm() function will allocate -an new terminal context which must be passed with all future termcurses library -functions. When this context is no longer needed, the termcurses_deinitterm() -routine should be called for proper freeing and terminal teardown. +Upon successful initialization, the `termcurses_initterm()` function will +allocate an new terminal context which must be passed with all future termcurses +library functions. When this context is no longer needed, the +`termcurses_deinitterm()` routine should be called for proper freeing and +terminal teardown. -Use with telnetd -================ +## Use with `telnetd` When using termcurses with the telnet daemon, the telnet config option -CONFIG_TELNET_SUPPORT_NAWS should be enabled. This option adds code to the -telnet library for terminal size negotiation. Without this option, the telnet +`CONFIG_TELNET_SUPPORT_NAWS` should be enabled. This option adds code to the +telnet library for terminal size negotiation. Without this option, the telnet routines have no concept of the terminal size, and therefore the termcurses -routines must default to 80x24 screen mode. +routines must default to `80x24` screen mode. -Use with pdcurses -================= +## Use with `pdcurses` When using the pdcurses termcurses support (i.e you have enabled both the -CONFIG_PDCURSES and CONFIG_TERMCURSES options),, the pdcurses input device should -be selected to be "TERMINPUT" (i.e. set CONFIG_PDCURSES_TERMINPUT=y). This -causes the pdcurses keyboard input logic to use termcurses_getkeycode() routine -for curses input. +`CONFIG_PDCURSES` and `CONFIG_TERMCURSES` options),, the pdcurses input device +should be selected to be `TERMINPUT` (i.e. set `CONFIG_PDCURSES_TERMINPUT=y`). +This causes the pdcurses keyboard input logic to use `termcurses_getkeycode()` +routine for curses input. diff --git a/system/usbmsc/README.md b/system/usbmsc/README.md index 04c68fdda..6ad4bdc8c 100644 --- a/system/usbmsc/README.md +++ b/system/usbmsc/README.md @@ -1,82 +1,85 @@ -system/usbmsc -^^^^^^^^^^^^^^^ +# System / `usbmsc` USB storage driver - This add-on registers a block device driver, then exports the block - the device using the USB storage class driver. In order to use this - add-on, your board-specific logic must provide the function: +This add-on registers a block device driver, then exports the block the device +using the USB storage class driver. In order to use this add-on, your +board-specific logic must provide the function: - void board_usbmsc_initialize(void); +```c +void board_usbmsc_initialize(void); +``` - This function will be called by the system/usbmsc indirectly via the - boarctl BOARDIOC_USBDEV_CONTROL command in order to do the actual - registration of the block device drivers. For examples of the - implementation of board_usbmsc_initialize() see - boards/arm/lpc214x/mcu123-lpc214x/src/up_usbmsc.c or - boards/arm/stm32/stm3210e-eval/src/usbmsc.c +This function will be called by the `system/usbmsc` indirectly via the `boarctl` +`BOARDIOC_USBDEV_CONTROL` command in order to do the actual registration of the +block device drivers. For examples of the implementation of +`board_usbmsc_initialize()` see +`boards/arm/lpc214x/mcu123-lpc214x/src/up_usbmsc.c` or +`boards/arm/stm32/stm3210e-eval/src/usbmsc.c`. - Configuration options: +Configuration options: - CONFIG_NSH_BUILTIN_APPS - This add-on can be built as two NSH "built-in" commands if this option - is selected: 'msconn' will connect the USB mass storage device; 'msdis' - will disconnect the USB storage device. - CONFIG_LIB_BOARDCTL - Enables the boardctl() interfaces. - CONFIG_BOARDCTL_USBDEVCTRL - Enables the BOARDIOC_USBDEV_CONTROL boardctl() command. - CONFIG_SYSTEM_USBMSC_NLUNS - Defines the number of logical units (LUNs) exported by the USB storage - driver. Each LUN corresponds to one exported block driver (or partition - of a block driver). May be 1, 2, or 3. Default is 1. - CONFIG_SYSTEM_USBMSC_DEVMINOR1 - The minor device number of the block driver for the first LUN. For - example, N in /dev/mmcsdN. Used for registering the block driver. Default - is zero. - CONFIG_SYSTEM_USBMSC_DEVPATH1 - The full path to the registered block driver. Default is "/dev/mmcsd0" - CONFIG_SYSTEM_USBMSC_DEVMINOR2 and CONFIG_SYSTEM_USBMSC_DEVPATH2 - Similar parameters that would have to be provided if CONFIG_SYSTEM_USBMSC_NLUNS - is 2 or 3. No defaults. - CONFIG_SYSTEM_USBMSC_DEVMINOR3 and CONFIG_SYSTEM_USBMSC_DEVPATH3 - Similar parameters that would have to be provided if CONFIG_SYSTEM_USBMSC_NLUNS - is 3. No defaults. - CONFIG_SYSTEM_USBMSC_DEBUGMM - Enables some debug tests to check for memory usage and memory leaks. +- `CONFIG_NSH_BUILTIN_APPS` – This add-on can be built as two NSH _built-in_ + commands if this option is selected: `msconn` will connect the USB mass + storage device; `msdis` will disconnect the USB storage device. - If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB), then - the code will also manage the USB trace output. The amount of trace output - can be controlled using: +- `CONFIG_LIB_BOARDCTL` – Enables the `boardctl()` interfaces. - CONFIG_SYSTEM_USBMSC_TRACEINIT - Show initialization events - CONFIG_SYSTEM_USBMSC_TRACECLASS - Show class driver events - CONFIG_SYSTEM_USBMSC_TRACETRANSFERS - Show data transfer events - CONFIG_SYSTEM_USBMSC_TRACECONTROLLER - Show controller events - CONFIG_SYSTEM_USBMSC_TRACEINTERRUPTS - Show interrupt-related events. +- `CONFIG_BOARDCTL_USBDEVCTRL` – Enables the `BOARDIOC_USBDEV_CONTROL` + `boardctl()` command. - Error results are always shown in the trace output +- `CONFIG_SYSTEM_USBMSC_NLUNS` – Defines the number of logical units (LUNs) + exported by the USB storage driver. Each LUN corresponds to one exported block + driver (or partition of a block driver). May be `1`, `2`, or `3`. Default is + `1`. - NOTE 1: When built as an NSH add-on command (CONFIG_NSH_BUILTIN_APPS=y), - Caution should be used to assure that the SD drive (or other storage device) is - not in use when the USB storage device is configured. Specifically, the SD - driver should be unmounted like: +- `CONFIG_SYSTEM_USBMSC_DEVMINOR1` – The minor device number of the block driver + for the first LUN. For example, `N` in `/dev/mmcsdN`. Used for registering the + block driver. Default is zero. - nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH - ... - nsh> umount /mnd/sdcard # Unmount before connecting USB!!! - nsh> msconn # Connect the USB storage device - ... - nsh> msdis # Disconnect USB storate device - nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount +- `CONFIG_SYSTEM_USBMSC_DEVPATH1` – The full path to the registered block + driver. Default is `/dev/mmcsd0` - Failure to do this could result in corruption of the SD card format. +- `CONFIG_SYSTEM_USBMSC_DEVMINOR2` and `CONFIG_SYSTEM_USBMSC_DEVPATH2` + Similar parameters that would have to be provided if + `CONFIG_SYSTEM_USBMSC_NLUNS` is `2` or `3`. No defaults. - NOTE 2: This add-on used internal USB device driver interfaces. As such, - it relies on internal OS interfaces that are not normally available to a - user-space program. As a result, this add-on cannot be used if a - NuttX is built as a protected, supervisor kernel (CONFIG_BUILD_PROTECTED - or CONFIG_BUILD_KERNEL). +- `CONFIG_SYSTEM_USBMSC_DEVMINOR3` and `CONFIG_SYSTEM_USBMSC_DEVPATH3` + Similar parameters that would have to be provided if + `CONFIG_SYSTEM_USBMSC_NLUNS` is `3`. No defaults. + +- `CONFIG_SYSTEM_USBMSC_DEBUGMM` – Enables some debug tests to check for memory + usage and memory leaks. + +If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and +`CONFIG_DEBUG_USB`), then the code will also manage the USB trace output. The +amount of trace output can be controlled using: + +- `CONFIG_SYSTEM_USBMSC_TRACEINIT` – Show initialization events. +- `CONFIG_SYSTEM_USBMSC_TRACECLASS` – Show class driver events. +- `CONFIG_SYSTEM_USBMSC_TRACETRANSFERS` – Show data transfer events. +- `CONFIG_SYSTEM_USBMSC_TRACECONTROLLER` – Show controller events. +- `CONFIG_SYSTEM_USBMSC_TRACEINTERRUPTS` – Show interrupt-related events. + +Error results are always shown in the trace output + +**Note 1**: When built as an NSH add-on command (`CONFIG_NSH_BUILTIN_APPS=y`), +Caution should be used to assure that the SD drive (or other storage device) is +not in use when the USB storage device is configured. Specifically, the SD +driver should be unmounted like: + +```shell +nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH +... +nsh> umount /mnd/sdcard # Unmount before connecting USB!!! +nsh> msconn # Connect the USB storage device +... +nsh> msdis # Disconnect USB storate device +nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount +``` + +Failure to do this could result in corruption of the SD card format. + +**Note 2**: This add-on used internal USB device driver interfaces. As such, it +relies on internal OS interfaces that are not normally available to a user-space +program. As a result, this add-on cannot be used if a NuttX is built as a +protected, supervisor kernel (`CONFIG_BUILD_PROTECTED` or +`CONFIG_BUILD_KERNEL`). diff --git a/system/zmodem/README.md b/system/zmodem/README.md index 2b71ef0d3..a48f67b8f 100644 --- a/system/zmodem/README.md +++ b/system/zmodem/README.md @@ -1,271 +1,280 @@ -README -====== +# System / `zmodem` -Contents -======== +## Contents - o Buffering Notes - - Hardware Flow Control - - RX Buffer Size - - Buffer Recommendations - o Using NuttX ZModem with a Linux Host - - Sending Files from the Target to the Linux Host PC - - Receiving Files on the Target from the Linux Host PC - o Building the ZModem Tools to Run Under Linux - o Status +- Buffering Notes + - Hardware Flow Control + - RX Buffer Size + - Buffer Recommendations +- Using NuttX ZModem with a Linux Host + - Sending Files from the Target to the Linux Host PC + - Receiving Files on the Target from the Linux Host PC +- Building the ZModem Tools to Run Under Linux +- Status -Buffering Notes -=============== +## Buffering Notes - Hardware Flow Control - --------------------- - Hardware flow control must be enabled in serial drivers in order to - prevent data overrun. However, in the most NuttX serial drivers, hardware - flow control only protects the hardware RX FIFO: Data will not be lost in - the hardware FIFO but can still be lost when it is taken from the FIFO. - We can still overflow the serial driver's RX buffer even with hardware - flow control enabled! That is probably a bug. But the workaround solution - that I have used is to use lower data rates and a large serial driver RX - buffer. +### Hardware Flow Control - Those measures should be unnecessary if buffering and hardware flow - control are set up and working correctly. +Hardware flow control must be enabled in serial drivers in order to prevent data +overrun. However, in the most NuttX serial drivers, hardware flow control only +protects the hardware RX FIFO: Data will not be lost in the hardware FIFO but +can still be lost when it is taken from the FIFO. We can still overflow the +serial driver's RX buffer even with hardware flow control enabled! That is +probably a bug. But the workaround solution that I have used is to use lower +data rates and a large serial driver RX buffer. - Software Flow Control - --------------------- - The ZModem protocol has XON/XOFF flow control built into it. The protocol - permits XON or XOFF characters placed at certain parts of messages. If - software flow control is enabled on the receiving end it will consume the - XONs and XOFFs. Otherwise they will be ignored in the data by the ZModem - logic. +Those measures should be unnecessary if buffering and hardware flow control are +set up and working correctly. - NuttX, however, does not implement XON/XOFF flow control so these do - nothing. On NuttX you will have to use hardware flow control in most cases. +### Software Flow Control - The XON/XOFF controls built into ZModem could be used if you enabled - software flow control in the host. But that would only work in one - direction: If would prevent the host from overrunning the the target Rx - buffering. So you should be able to do host-to-target software flow - control. But there would still be no target-to-host flow control. That - might not be an issue because the host is usually so much faster than - that target. +The ZModem protocol has `XON/XOFF` flow control built into it. The protocol +permits `XON` or `XOFF` characters placed at certain parts of messages. If +software flow control is enabled on the receiving end it will consume the `XON`s +and `XOFF`s. Otherwise they will be ignored in the data by the ZModem logic. - RX Buffer Size - -------------- - The ZModem protocol supports a message that informs the file sender of - the maximum size of data that you can buffer (ZRINIT). However, my - experience is that the Linux sz ignores this setting and always sends file - data at the maximum size (1024) no matter what size of buffer you report. - That is unfortunate because that, combined with the possibilities of data - overrun mean that you must use quite large buffering for ZModem file - receipt to be reliable (none of these issues effect sending of files). +NuttX, however, does not implement `XON/XOFF` flow control so these do nothing. +On NuttX you will have to use hardware flow control in most cases. - Buffer Recommendations - ---------------------- - Based on the limitations of NuttX hardware flow control and of the Linux - sz behavior, I have been testing with the following configuration - (assuming UART1 is the ZModem device): +The `XON`/`XOFF` controls built into ZModem could be used if you enabled +software flow control in the host. But that would only work in one direction: If +would prevent the host from overrunning the the target Rx buffering. So you +should be able to do host-to-target software flow control. But there would still +be no target-to-host flow control. That might not be an issue because the host +is usually so much faster than that target. - 1) This setting determines that maximum size of a data packet frame: +### RX Buffer Size - CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE=1024 +The ZModem protocol supports a message that informs the file sender of the +maximum size of data that you can buffer (`ZRINIT`). However, my experience is +that the Linux sz ignores this setting and always sends file data at the maximum +size (`1024`) no matter what size of buffer you report. That is unfortunate +because that, combined with the possibilities of data overrun mean that you must +use quite large buffering for ZModem file receipt to be reliable (none of these +issues effect sending of files). - 2) Input Buffering. If the input buffering is set to a full frame, then - data overflow is less likely. +### Buffer Recommendations - CONFIG_UART1_RXBUFSIZE=1024 +Based on the limitations of NuttX hardware flow control and of the Linux sz +behavior, I have been testing with the following configuration (assuming `UART1` +is the ZModem device): - 3) With a larger driver input buffer, the ZModem receive I/O buffer can be - smaller: +1) This setting determines that maximum size of a data packet frame: - CONFIG_SYSTEM_ZMODEM_RCVBUFSIZE=256 + ```conf + CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE=1024 + ``` - 4) Output buffering. Overrun cannot occur on output (on the NuttX side) - so there is no need to be so careful: +2) Input Buffering. If the input buffering is set to a full frame, then data + overflow is less likely. - CONFIG_SYSTEM_ZMODEM_SNDBUFSIZE=512 - CONFIG_UART1_TXBUFSIZE=256 + ```conf + CONFIG_UART1_RXBUFSIZE=1024` + ``` -Using NuttX ZModem with a Linux Host -==================================== +3) With a larger driver input buffer, the ZModem receive I/O buffer can be + smaller: - Sending Files from the Target to the Linux Host PC - -------------------------------------------------- - The NuttX ZModem commands have been verified against the rzsz programs - running on a Linux PC. To send a file to the PC, first make sure that - the serial port is configured to work with the board (Assuming you are - using 9600 baud for the data transfers -- high rates may result in data - overruns): + ```conf + CONFIG_SYSTEM_ZMODEM_RCVBUFSIZE=256 + ``` - $ sudo stty -F /dev/ttyS0 9600 # Select 9600 BAUD - $ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * - $ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode - $ sudo stty -F /dev/ttyS0 # Show the TTY configuration +4) Output buffering. Overrun cannot occur on output (on the NuttX side) so there + is no need to be so careful: - * Only if hardware flow control is enabled. + ```conf + CONFIG_SYSTEM_ZMODEM_SNDBUFSIZE=512 + CONFIG_UART1_TXBUFSIZE=256 + ``` - Start rz on the Linux host (using /dev/ttyS0 as an example): +## Using NuttX ZModem with a Linux Host - $ sudo rz /dev/ttyS0 +### Sending Files from the Target to the Linux Host PC - You can add the rz -v option multiple times, each increases the level - of debug output. If you want to capture the Linux rz output, then - re-direct stderr to a log file by adding 2>rz.log to the end of the - rz command. +The NuttX ZModem commands have been verified against the rzsz programs running +on a Linux PC. To send a file to the PC, first make sure that the serial port is +configured to work with the board (Assuming you are using 9600 baud for the data +transfers - high rates may result in data overruns): - NOTE: The NuttX ZModem does sends rz\n when it starts in compliance with - the ZModem specification. On Linux this, however, seems to start some - other, incompatible version of rz. You need to start rz manually to - make sure that the correct version is selected. You can tell when this - evil rz/sz has inserted itself because you will see the '^' (0x5e) - character replacing the standard ZModem ZDLE character (0x19) in the - binary data stream. +```bash +$ sudo stty -F /dev/ttyS0 9600 # Select 9600 BAUD +$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * +$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode +$ sudo stty -F /dev/ttyS0 # Show the TTY configuration +``` - If you don't have the rz command on your Linux box, the package to - install rzsz (or possibly lrzsz). +\* Only if hardware flow control is enabled. - Then on the target (using /dev/ttyS1 as an example). +Start `rz` on the Linux host (using `/dev/ttyS0` as an example): - > sz -d /dev/ttyS1 +```bash +$ sudo rz < /dev/ttyS0 > /dev/ttyS0 +``` - Where filename is the full path to the file to send (i.e., it begins - with the '/' character). /dev/ttyS1 or whatever device you select - *MUST* support Hardware flow control in order to throttle therates of - data transfer to fit within the allocated buffers. +You can add the `rz -v` option multiple times, each increases the level of debug +output. If you want to capture the Linux `rz` output, then re-direct `stderr` to +a log file by adding `2>rz.log` to the end of the `rz` command. - Receiving Files on the Target from the Linux Host PC - ---------------------------------------------------- - NOTE: There are issues with using the Linux sz command with the NuttX - rz command. See "Status" below. It is recommended that you use the - NuttX sz command on Linux as described in the next paragraph. +**Note**: The NuttX ZModem does sends `rz\n` when it starts in compliance with +the ZModem specification. On Linux this, however, seems to start some other, +incompatible version of `rz`. You need to start `rz` manually to make sure that +the correct version is selected. You can tell when this evil `rz`/`sz` has +inserted itself because you will see the `^` (`0x5e`) character replacing the +standard ZModem `ZDLE` character (`0x19`) in the binary data stream. - To send a file to the target, first make sure that the serial port on the - host is configured to work with the board (Assuming that you are using - 9600 baud for the data transfers -- high rates may result in data - overruns): +If you don't have the `rz` command on your Linux box, the package to install +`rzsz` (or possibly `lrzsz`). - $ sudo stty -F /dev/ttyS0 9600 # Select 9600 (or other) BAUD - $ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * - $ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode - $ sudo stty -F /dev/ttyS0 # Show the TTY configuration +Then on the target (using `/dev/ttyS1` as an example). - * Only is hardware flow control is enabled. +``` +nsh> sz -d /dev/ttyS1 +``` - Start rz on the on the target. Here, in this example, we are using - /dev/ttyS1 to perform the transfer +Where filename is the full path to the file to send (i.e., it begins with the +`/` character). `/dev/ttyS1` or whatever device you select **must** support +Hardware flow control in order to throttle therates of data transfer to fit +within the allocated buffers. - nsh> rz -d /dev/ttyS1 +### Receiving Files on the Target from the Linux Host PC - /dev/ttyS1 or whatever device you select *MUST* support Hardware flow - control in order to throttle therates of data transfer to fit within the - allocated buffers. +**Note**: There are issues with using the Linux `sz` command with the NuttX `rz` +command. See _Status_ below. It is recommended that you use the NuttX `sz` +command on Linux as described in the next paragraph. - Then use the sz command on Linux to send the file to the target: +To send a file to the target, first make sure that the serial port on the host +is configured to work with the board (Assuming that you are using `9600` baud +for the data transfers - high rates may result in data overruns): - $ sudo sz [-l nnnn] [-w nnnn] /dev/ttyS0 +```bash +$ sudo stty -F /dev/ttyS0 9600 # Select 9600 (or other) BAUD +$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * +$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode +$ sudo stty -F /dev/ttyS0 # Show the TTY configuration +``` - Where is the file that you want to send. If -l nnnn and -w nnnn - is not specified, then there will likely be packet buffer overflow errors. - nnnn should be set to a value less than or equal to - CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE +\* Only is hardware flow control is enabled. - The resulting file will be found where you have configured the ZModem - "sandbox" via CONFIG_SYSTEM_ZMODEM_MOUNTPOINT. +Start `rz` on the on the target. Here, in this example, we are using +`/dev/ttyS1` to perform the transfer - You can add the sz -v option multiple times, each increases the level - of debug output. If you want to capture the Linux sz output, then - re-direct stderr to a log file by adding 2>sz.log to the end of the - sz command. +```shell +nsh> rz -d /dev/ttyS1 +``` - If you don't have the sz command on your Linux box, the package to - install rzsz (or possibly lrzsz). +`/dev/ttyS1` or whatever device you select **must** support Hardware flow +control in order to throttle therates of data transfer to fit within the +allocated buffers. -Building the ZModem Tools to Run Under Linux -============================================ +Then use the `sz` command on Linux to send the file to the target: - Build support has been added so that the NuttX ZModem implementation - can be executed on a Linux host PC. This can be done by +```bash +$ sudo sz [-l nnnn] [-w nnnn] /dev/ttyS0 +``` - - Change to the apps/systems/zmodem directory - - Make using the special makefile, Makefile.host +Where `` is the file that you want to send. If `-l nnnn` and `-w nnnn` +is not specified, then there will likely be packet buffer overflow errors. +`nnnn` should be set to a value less than or equal to +`CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE`. - NOTES: +The resulting file will be found where you have configured the ZModem +**sandbox** via `CONFIG_SYSTEM_ZMODEM_MOUNTPOINT`. - 1. TOPDIR and APPDIR must be defined on the make command line: TOPDIR is - the full path to the nuttx/ directory; APPDIR is the full path to the - apps/ directory. For example, if you installed nuttx at - /home/me/projects/nuttx and apps at /home/me/projects/apps, then the - correct make command line would be: +You can add the `sz -v` option multiple times, each increases the level of debug +output. If you want to capture the Linux `sz` output, then re-direct `stderr` to +a log file by adding `2>sz.log` to the end of the `sz` command. - make -f Makefile.host TOPDIR=/home/me/projects/nuttx APPDIR=/home/me/projects/apps +If you don't have the sz command on your Linux box, the package to install +`rzsz` (or possibly `lrzsz`). - 2. Add CONFIG_DEBUG_FEATURES=1 to the make command line to enable debug output - 3. Make sure to clean old target .o files before making new host .o files. +## Building the ZModem Tools to Run Under Linux - This build is has been verified as of 2013-7-16 using Linux to transfer - files with an Olimex LPC1766STK board. It works great and seems to solve - all of the problems found with the Linux sz/rz implementation. +Build support has been added so that the NuttX ZModem implementation can be +executed on a Linux host PC. This can be done by -Status -====== - 2013-7-15: Testing against the Linux rz/sz commands. +- Change to the `apps/systems/zmodem` directory +- Make using the special makefile, `Makefile.host` - I have tested with the boards/arm/lpc17xx_40xx/olimex-lpc1766stk - configuration. I have been able to send large and small files with - the target sz command. I have been able to receive small files, but - there are problems receiving large files using the Linux sz command: - The Linux sz does not obey the buffering limits and continues to send - data while rz is writing the previously received data to the file and - the serial driver's RX buffer is overrun by a few bytes while the - write is in progress. As a result, when it reads the next buffer of - data, a few bytes may be missing. The symptom of this missing data is - a CRC check failure. +**Notes**: - Either (1) we need a more courteous host application, or (2) we - need to greatly improve the target side buffering capability! +1. `TOPDIR` and `APPDIR` must be defined on the make command line: `TOPDIR` is + the full path to the `nuttx/` directory; `APPDIR` is the full path to the + `apps/` directory. For example, if you installed nuttx at + `/home/me/projects/nuttx` and apps at `/home/me/projects/apps`, then the + correct make command line would be: - My thought now is to implement the NuttX sz and rz commands as - PC side applications as well. Matching both sides and obeying - the handshaking will solve the issues. Another option might be - to fix the serial driver hardware flow control somehow. + ```bash + make -f Makefile.host TOPDIR=/home/me/projects/nuttx APPDIR=/home/me/projects/apps + ``` - 2013-7-16. More Testing against the Linux rz/sz commands. +2. Add `CONFIG_DEBUG_FEATURES=1` to the make command line to enable debug output +3. Make sure to clean old target `.o` files before making new host `.o` files. - I have verified that with debug off and at lower serial BAUD - (2400), the transfers of large files succeed without errors. I do - not consider this a "solution" to the problem. I also found that - the LPC17xx hardware flow control caused strange hangs; ZModem - works better with hardware flow control disabled on the LPC17xx. +This build is has been verified as of `2013-7-16` using Linux to transfer files +with an Olimex LPC1766STK board. It works great and seems to solve all of the +problems found with the Linux `sz`/`rz` implementation. - At this lower BAUD, RX buffer sizes could probably be reduced; Or - perhaps the BAUD could be increased. My thought, however, is that - tuning in such an unhealthy situation is not the approach: The - best thing to do would be to use the matching NuttX sz on the Linux - host side. +## Status - 2013-7-16. More Testing against the NuttX rz/sz on Both Ends. +- `2013-7-15`: Testing against the Linux `rz`/`sz` commands. - The NuttX sz/rz commands have been modified so that they can be - built and executed under Linux. In this case, there are no - transfer problems at all in either direction and with large or - small files. This configuration could probably run at much higher - serial speeds and with much smaller buffers (although that has not - been verified as of this writing). + I have tested with the `boards/arm/lpc17xx_40xx/olimex-lpc1766stk` + configuration. I have been able to send large and small files with the target + `sz` command. I have been able to receive small files, but there are problems + receiving large files using the Linux `sz` command: The Linux `sz` does not + obey the buffering limits and continues to send data while `rz` is writing the + previously received data to the file and the serial driver's RX buffer is + overrun by a few bytes while the write is in progress. As a result, when it + reads the next buffer of data, a few bytes may be missing. The symptom of this + missing data is a CRC check failure. - 2018-5-27: - Updates to checksum calculations. Verified correct operation with - hardware flow control using the olimex-stm32-p407/zmodem - configuration. Only the host-to-target transfer was verified. + Either (1) we need a more courteous host application, or (2) we need to + greatly improve the target side buffering capability! - This was using the Linux sz utility. There appears to still be a - problem using the NuttX sz utility running on Linux. + My thought now is to implement the NuttX `sz` and `rz` commands as PC side + applications as well. Matching both sides and obeying the handshaking will + solve the issues. Another option might be to fix the serial driver hardware + flow control somehow. - 2018-5-27: - Verified correct operation with hardware flow control using the - olimex-stm32-p407/zmodem configuration with target-to-host - transfers was verified. Again, there are issues remaining if - I tried the NuttX rz utility running on Linux. +- `2013-7-16`. More Testing against the Linux `rz`/`sz` commands. - 2018-6-26: - with -w nnnn option, the host-to-target transfer can work reliably - without hardware flow control. + I have verified that with debug off and at lower serial BAUD (`2400`), the + transfers of large files succeed without errors. I do not consider this a + _solution_ to the problem. I also found that the LPC17xx hardware flow control + caused strange hangs; ZModem works better with hardware flow control disabled + on the LPC17xx. + + At this lower BAUD, RX buffer sizes could probably be reduced; Or perhaps the + BAUD could be increased. My thought, however, is that tuning in such an + unhealthy situation is not the approach: The best thing to do would be to use + the matching NuttX sz on the Linux host side. + +- `2013-7-16`. More Testing against the NuttX `rz`/`sz` on Both Ends. + + The NuttX `sz`/`rz` commands have been modified so that they can be built and + executed under Linux. In this case, there are no transfer problems at all in + either direction and with large or small files. This configuration could + probably run at much higher serial speeds and with much smaller buffers + (although that has not been verified as of this writing). + +- `2018-5-27` + + Updates to checksum calculations. Verified correct operation with hardware + flow control using the `olimex-stm32-p407/zmodem` configuration. Only the + host-to-target transfer was verified. + + This was using the Linux `sz` utility. There appears to still be a problem + using the NuttX `sz` utility running on Linux. + +- `2018-5-27` + + Verified correct operation with hardware flow control using the + `olimex-stm32-p407/zmodem` configuration with target-to-host transfers was + verified. Again, there are issues remaining if I tried the NuttX `rz` utility + running on Linux. + +- `2018-6-26` + + With `-w nnnn` option, the host-to-target transfer can work reliably without + hardware flow control. diff --git a/testing/README.md b/testing/README.md index 7aa442ef7..ae1eae6ed 100644 --- a/testing/README.md +++ b/testing/README.md @@ -1,171 +1,165 @@ -apps/testing README file -======================== +# Testing - The apps/testing directory is used to build NuttX-specific tests and to - include external testing frameworks. +The `apps/testing` directory is used to build NuttX-specific tests and to +include external testing frameworks. - There is overlap between what you will find in apps/examples and apps/testing - in the sense that there are also tests in apps/examples as well. Those - tests, however, can also be used to illustrate usage of a NuttX feature. - Most of the tests in apps/testing, on the other hand, are pure tests with - little value as usage examples. +There is overlap between what you will find in `apps/examples` and +`apps/testing` in the sense that there are also tests in `apps/examples` as +well. Those tests, however, can also be used to illustrate usage of a NuttX +feature. Most of the tests in `apps/testing`, on the other hand, are pure tests +with little value as usage examples. -testing/cxxtest -=============== +## `cxxtest` - This is a test of the C++ standard library. At present a port of the uClibc++ - C++ library is available. Due to licensing issues, the uClibc++ C++ library - is not included in the NuttX source tree by default, but must be installed - (see the README.txt file in the uClibc++ download package for installation). +This is a test of the C++ standard library. At present a port of the uClibc++ +C++ library is available. Due to licensing issues, the uClibc++ C++ library is +not included in the NuttX source tree by default, but must be installed (see the +`README.txt` file in the uClibc++ download package for installation). - The uClibc++ test includes simple test of: +The uClibc++ test includes simple test of: - - iostreams, - - STL, - - RTTI, and - - Exceptions +- iostreams, +- STL, +- RTTI, and +- Exceptions - Example Configuration Options - ----------------------------- - CONFIG_TESTING_CXXTEST=y - Eanbles the example +### Example Configuration Options - Other Required Configuration Settings - ------------------------------------- - Other NuttX setting that are required include: +- `CONFIG_TESTING_CXXTEST=y` – Eanbles the example - CONFIG_HAVE_CXX=y - CONFIG_HAVE_CXXINITIALIZE=y - CONFIG_UCLIBCXX=y or CONFIG_LIBCXX=y +### Other Required Configuration Settings - Additional uClibc++/libcxx settings may be required in your build environment. +Other NuttX setting that are required include: -testing/fstest -============== +- `CONFIG_HAVE_CXX=y` +- `CONFIG_HAVE_CXXINITIALIZE=y` +- `CONFIG_UCLIBCXX=y` or `CONFIG_LIBCXX=y` - This is a generic file system test that derives from testing/nxffs. It - was created to test the tmpfs file system, but should work with any file - system provided that all initialization has already been performed prior - to starting the test. +Additional uClibc++/libcxx settings may be required in your build environment. - This test a a general test for any file system, but includes some specific - hooks for the SPIFFS file system. +## `fstest` - * CONFIG_TESTING_FSTEST: Enable the file system example - * CONFIG_TESTING_FSTEST_MAXNAME: Determines the maximum size of names used - in the filesystem - * CONFIG_TESTING_FSTEST_MAXFILE: Determines the maximum size of a file - * CONFIG_TESTING_FSTEST_MAXIO: Max I/O, default 347. - * CONFIG_TESTING_FSTEST_MAXOPEN: Max open files. - * CONFIG_TESTING_FSTEST_MOUNTPT: Path where the file system is mounted. - * CONFIG_TESTING_FSTEST_NLOOPS: Number of test loops. default 100 - * CONFIG_TESTING_FSTEST_VERBOSE: Verbose output +This is a generic file system test that derives from `testing/nxffs`. It was +created to test the tmpfs file system, but should work with any file system +provided that all initialization has already been performed prior to starting +the test. -testing/mm -========== +This test a a general test for any file system, but includes some specific hooks +for the SPIFFS file system. - This is a simple test of the memory manager. +- `CONFIG_TESTING_FSTEST` – Enable the file system example. +- `CONFIG_TESTING_FSTEST_MAXNAME` – Determines the maximum size of names used in + the filesystem. +- `CONFIG_TESTING_FSTEST_MAXFILE` – Determines the maximum size of a file. +- `CONFIG_TESTING_FSTEST_MAXIO` – Max I/O, default `347`. +- `CONFIG_TESTING_FSTEST_MAXOPEN` – Max open files. +- `CONFIG_TESTING_FSTEST_MOUNTPT` – Path where the file system is mounted. +- `CONFIG_TESTING_FSTEST_NLOOPS` – Number of test loops. default `100`. +- `CONFIG_TESTING_FSTEST_VERBOSE` – Verbose output. -testing/nxffs -============= +## `mm` - This is a test of the NuttX NXFFS FLASH file system. This is an NXFFS - stress test and beats on the file system very hard. It should only - be used in a simulation environment! Putting this NXFFS test on real - hardware will most likely destroy your FLASH. You have been warned. +This is a simple test of the memory manager. -testing/ostest -============== +## `nxffs` - This is the NuttX 'qualification' suite. It attempts to exercise - a broad set of OS functionality. Its coverage is not very extensive - as of this writing, but it is used to qualify each NuttX release. +This is a test of the NuttX NXFFS FLASH file system. This is an NXFFS stress +test and beats on the file system very hard. It should only be used in a +simulation environment! Putting this NXFFS test on real hardware will most +likely destroy your FLASH. You have been warned. - The behavior of the ostest can be modified with the following - settings in the boards////configs//defconfig - file: +## `ostest` - * CONFIG_NSH_BUILTIN_APPS - Build the OS test example as an NSH built-in application. - * CONFIG_TESTING_OSTEST_LOOPS - Used to control the number of executions of the test. If - undefined, the test executes one time. If defined to be - zero, the test runs forever. - * CONFIG_TESTING_OSTEST_STACKSIZE - Used to create the ostest task. Default is 8192. - * CONFIG_TESTING_OSTEST_NBARRIER_THREADS - Specifies the number of threads to create in the barrier - test. The default is 8 but a smaller number may be needed on - systems without sufficient memory to start so many threads. - * CONFIG_TESTING_OSTEST_RR_RANGE - During round-robin scheduling test two threads are created. Each of the threads - searches for prime numbers in the configurable range, doing that configurable - number of times. - This value specifies the end of search range and together with number of runs - allows to configure the length of this test - it should last at least a few - tens of seconds. Allowed values [1; 32767], default 10000 - * CONFIG_TESTING_OSTEST_RR_RUNS - During round-robin scheduling test two threads are created. Each of the threads - searches for prime numbers in the configurable range, doing that configurable - number of times. +This is the NuttX _qualification_ suite. It attempts to exercise a broad set of +OS functionality. Its coverage is not very extensive as of this writing, but it +is used to qualify each NuttX release. -testing/smart -============= +The behavior of the `ostest` can be modified with the following settings in the +`boards////configs//defconfig` file: - This is a test of the SMART file system that derives from - testing/nxffs. +- `CONFIG_NSH_BUILTIN_APPS` – Build the OS test example as an NSH built-in + application. +- `CONFIG_TESTING_OSTEST_LOOPS` – Used to control the number of executions of + the test. If undefined, the test executes one time. If defined to be zero, + the test runs forever. - * CONFIG_TESTING_SMART: - Enable the SMART file system example - * CONFIG_TESTING_SMART_ARCHINIT: The default is to use the RAM MTD - device at drivers/mtd/rammtd.c. But an architecture-specific MTD - driver can be used instead by defining CONFIG_TESTING_SMART_ARCHINIT. In - this case, the initialization logic will call smart_archinitialize() - to obtain the MTD driver instance. - * CONFIG_TESTING_SMART_NEBLOCKS: When CONFIG_TESTING_SMART_ARCHINIT is not - defined, this test will use the RAM MTD device at drivers/mtd/rammtd.c - to simulate FLASH. In this case, this value must be provided to give - the number of erase blocks in MTD RAM device. The size of the allocated - RAM drive will be: CONFIG_RAMMTD_ERASESIZE * CONFIG_TESTING_SMART_NEBLOCKS - * CONFIG_TESTING_SMART_MAXNAME: Determines the maximum size of names used - in the filesystem - * CONFIG_TESTING_SMART_MAXFILE: Determines the maximum size of a file - * CONFIG_TESTING_SMART_MAXIO: Max I/O, default 347. - * CONFIG_TESTING_SMART_MAXOPEN: Max open files. - * CONFIG_TESTING_SMART_MOUNTPT: SMART mountpoint - * CONFIG_TESTING_SMART_NLOOPS: Number of test loops. default 100 - * CONFIG_TESTING_SMART_VERBOSE: Verbose output +- `CONFIG_TESTING_OSTEST_STACKSIZE` – Used to create the ostest task. Default is + `8192`. +- `CONFIG_TESTING_OSTEST_NBARRIER_THREADS` – Specifies the number of threads to + create in the barrier test. The default is 8 but a smaller number may be + needed on systems without sufficient memory to start so many threads. -testing/smart_test -================== +- `CONFIG_TESTING_OSTEST_RR_RANGE` – During round-robin scheduling test two + threads are created. Each of the threads searches for prime numbers in the + configurable range, doing that configurable number of times. This value + specifies the end of search range and together with number of runs allows to + configure the length of this test – it should last at least a few tens of + seconds. Allowed values `[1; 32767]`, default `10000`. - Performs a file-based test on a SMART (or any) filesystem. Validates - seek, append and seek-with-write operations. +- `CONFIG_TESTING_OSTEST_RR_RUNS` – During round-robin scheduling test two + threads are created. Each of the threads searches for prime numbers in the + configurable range, doing that configurable number of times. - * CONFIG_TESTING_SMART_TEST=y +## `smart` SMART File System - Source: NuttX - Author: Ken Pettit - Date: April 24, 2013 +This is a test of the SMART file system that derives from `testing/nxffs`. - Performs a file-based test on a SMART (or any) filesystem. Validates seek, - append and seek-with-write operations. +- `CONFIG_TESTING_SMART` – Enable the SMART file system example. - Usage: +- `CONFIG_TESTING_SMART_ARCHINIT` – The default is to use the RAM MTD device at + `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used + instead by defining `CONFIG_TESTING_SMART_ARCHINIT`. In this case, the + initialization logic will call `smart_archinitialize()` to obtain the MTD + driver instance. - flash_test mtdblock_device +- `CONFIG_TESTING_SMART_NEBLOCKS` – When `CONFIG_TESTING_SMART_ARCHINIT` is not + defined, this test will use the RAM MTD device at `drivers/mtd/rammtd.c` to + simulate FLASH. In this case, this value must be provided to give the number + of erase blocks in MTD RAM device. The size of the allocated RAM drive will + be: `CONFIG_RAMMTD_ERASESIZE * CONFIG_TESTING_SMART_NEBLOCKS`. - Additional options: +- `CONFIG_TESTING_SMART_MAXNAME` – Determines the maximum size of names used in + the filesystem. - --force to replace existing installation +- `CONFIG_TESTING_SMART_MAXFILE` – Determines the maximum size of a file. +- `CONFIG_TESTING_SMART_MAXIO` – Max I/O, default `347`. +- `CONFIG_TESTING_SMART_MAXOPEN` – Max open files. +- `CONFIG_TESTING_SMART_MOUNTPT` – SMART mountpoint. +- `CONFIG_TESTING_SMART_NLOOPS` – Number of test loops. default `100`. +- `CONFIG_TESTING_SMART_VERBOSE` – Verbose output. -testing/smp -=========== +## `smart_test` SMART File System - This is a simple test for SMP functionality. It is basically just the - pthread barrier test with some custom instrumentation. +Performs a file-based test on a SMART (or any) filesystem. Validates seek, +append and seek-with-write operations. -testing/unity -============= +* `CONFIG_TESTING_SMART_TEST=y` - Unity is a unit testing framework for C developed by ThrowTheSwitch.org: +``` +Author: Ken Pettit + Date: April 24, 2013 +``` - http://www.throwtheswitch.org/unity +Performs a file-based test on a SMART (or any) filesystem. Validates seek, +append and seek-with-write operations. + +``` +Usage: + + flash_test mtdblock_device + +Additional options: + + --force to replace existing installation +``` + +## `smp` + +This is a simple test for SMP functionality. It is basically just the pthread +barrier test with some custom instrumentation. + +## `unity` + +Unity is a unit testing framework for C developed by ThrowTheSwitch.org: + +http://www.throwtheswitch.org/unity diff --git a/testing/cxxtest/README.md b/testing/cxxtest/README.md index 11d8c8889..28072cf55 100644 --- a/testing/cxxtest/README.md +++ b/testing/cxxtest/README.md @@ -1,28 +1,27 @@ -README -====== +# Testing / `cxxtest` C++ STL - This is a test of the C++ standard library. At present a port of the uClibc++ - C++ library is available. Due to licensing issues, the uClibc++ C++ library - is not included in the NuttX source tree by default, but must be installed - (see the README.txt file in the uClibc++ download package for installation). +This is a test of the C++ standard library. At present a port of the uClibc++ +C++ library is available. Due to licensing issues, the uClibc++ C++ library is +not included in the NuttX source tree by default, but must be installed (see the +`README.txt` file in the uClibc++ download package for installation). - The uClibc++ test includes simple test of: +The uClibc++ test includes simple test of: - - iostreams, - - STL, - - RTTI, and - - Exceptions +- iostreams, +- STL, +- RTTI, and +- Exceptions - Example Configuration Options - ----------------------------- - CONFIG_TESTING_CXXTEST=y - Eanbles the example +## Example Configuration Options - Other Required Configuration Settings - ------------------------------------- - Other NuttX setting that are required include: +- `CONFIG_TESTING_CXXTEST=y` – Enables the example - CONFIG_HAVE_CXX=y - CONFIG_HAVE_CXXINITIALIZE=y - CONFIG_UCLIBCXX=y or CONFIG_LIBCXX=y +## Other Required Configuration Settings - Additional uClibc++/libcxx settings may be required in your build environment. +Other NuttX setting that are required include: + +- `CONFIG_HAVE_CXX=y` +- `CONFIG_HAVE_CXXINITIALIZE=y` +- `CONFIG_UCLIBCXX=y` or `CONFIG_LIBCXX=y` + +Additional `uClibc++/libcxx` settings may be required in your build environment. diff --git a/testing/fstest/README.md b/testing/fstest/README.md index 19a2762e9..458b150bd 100644 --- a/testing/fstest/README.md +++ b/testing/fstest/README.md @@ -1,20 +1,19 @@ -README -====== +# Testing / `fstest` Generic File System Test - This is a generic file system test that derives from testing/nxffs. It - was created to test the tmpfs file system, but should work with any file - system provided that all initialization has already been performed prior - to starting the test. +This is a generic file system test that derives from `testing/nxffs`. It was +created to test the tmpfs file system, but should work with any file system +provided that all initialization has already been performed prior to starting +the test. - This test a a general test for any file system, but includes some specific - hooks for the SPIFFS file system. +This test a a general test for any file system, but includes some specific hooks +for the SPIFFS file system. - * CONFIG_TESTING_FSTEST: Enable the file system example - * CONFIG_TESTING_FSTEST_MAXNAME: Determines the maximum size of names used - in the filesystem - * CONFIG_TESTING_FSTEST_MAXFILE: Determines the maximum size of a file - * CONFIG_TESTING_FSTEST_MAXIO: Max I/O, default 347. - * CONFIG_TESTING_FSTEST_MAXOPEN: Max open files. - * CONFIG_TESTING_FSTEST_MOUNTPT: Path where the file system is mounted. - * CONFIG_TESTING_FSTEST_NLOOPS: Number of test loops. default 100 - * CONFIG_TESTING_FSTEST_VERBOSE: Verbose output +- `CONFIG_TESTING_FSTEST` – Enable the file system example. +- `CONFIG_TESTING_FSTEST_MAXNAME` – Determines the maximum size of names used in + the filesystem. +- `CONFIG_TESTING_FSTEST_MAXFILE` – Determines the maximum size of a file. +- `CONFIG_TESTING_FSTEST_MAXIO` – Max I/O, default `347`. +- `CONFIG_TESTING_FSTEST_MAXOPEN` – Max open files. +- `CONFIG_TESTING_FSTEST_MOUNTPT` – Path where the file system is mounted. +- `CONFIG_TESTING_FSTEST_NLOOPS` – Number of test loops. default `100`. +- `CONFIG_TESTING_FSTEST_VERBOSE` – Verbose output. diff --git a/testing/nxffs/README.md b/testing/nxffs/README.md index eb755da35..cf333eaa5 100644 --- a/testing/nxffs/README.md +++ b/testing/nxffs/README.md @@ -1,7 +1,6 @@ -README -====== +# Testing / `nxffs` NuttX NXFFS FLASH File System - This is a test of the NuttX NXFFS FLASH file system. This is an NXFFS - stress test and beats on the file system very hard. It should only - be used in a simulation environment! Putting this NXFFS test on real - hardware will most likely destroy your FLASH. You have been warned. +This is a test of the NuttX NXFFS FLASH file system. This is an NXFFS stress +test and beats on the file system very hard. It should only be used in a +simulation environment! Putting this NXFFS test on real hardware will most +likely destroy your FLASH. You have been warned. diff --git a/testing/smart/README.md b/testing/smart/README.md index eba6736e3..febf64bb1 100644 --- a/testing/smart/README.md +++ b/testing/smart/README.md @@ -1,25 +1,23 @@ -README -====== +# Testing / `smart` SMART File System - This is a test of the SMART file system that derives from - testing/nxffs. +This is a test of the SMART file system that derives from `testing/nxffs`. - * CONFIG_TESTING_SMART: - Enable the SMART file system example - * CONFIG_TESTING_SMART_ARCHINIT: The default is to use the RAM MTD - device at drivers/mtd/rammtd.c. But an architecture-specific MTD - driver can be used instead by defining CONFIG_TESTING_SMART_ARCHINIT. In - this case, the initialization logic will call smart_archinitialize() - to obtain the MTD driver instance. - * CONFIG_TESTING_SMART_NEBLOCKS: When CONFIG_TESTING_SMART_ARCHINIT is not - defined, this test will use the RAM MTD device at drivers/mtd/rammtd.c - to simulate FLASH. In this case, this value must be provided to give - the number of erase blocks in MTD RAM device. The size of the allocated - RAM drive will be: CONFIG_RAMMTD_ERASESIZE * CONFIG_TESTING_SMART_NEBLOCKS - * CONFIG_TESTING_SMART_MAXNAME: Determines the maximum size of names used - in the filesystem - * CONFIG_TESTING_SMART_MAXFILE: Determines the maximum size of a file - * CONFIG_TESTING_SMART_MAXIO: Max I/O, default 347. - * CONFIG_TESTING_SMART_MAXOPEN: Max open files. - * CONFIG_TESTING_SMART_MOUNTPT: SMART mountpoint - * CONFIG_TESTING_SMART_NLOOPS: Number of test loops. default 100 - * CONFIG_TESTING_SMART_VERBOSE: Verbose output +- `CONFIG_TESTING_SMART` – Enable the SMART file system example. +- `CONFIG_TESTING_SMART_ARCHINIT` – The default is to use the RAM MTD device at + `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used + instead by defining `CONFIG_TESTING_SMART_ARCHINIT`. In this case, the + initialization logic will call `smart_archinitialize()` to obtain the MTD + driver instance. +- `CONFIG_TESTING_SMART_NEBLOCKS` – When `CONFIG_TESTING_SMART_ARCHINIT` is not + defined, this test will use the RAM MTD device at `drivers/mtd/rammtd.c` to + simulate FLASH. In this case, this value must be provided to give the number + of erase blocks in MTD RAM device. The size of the allocated RAM drive will + be: `CONFIG_RAMMTD_ERASESIZE * CONFIG_TESTING_SMART_NEBLOCKS`. +- `CONFIG_TESTING_SMART_MAXNAME` – Determines the maximum size of names used in + the filesystem. +- `CONFIG_TESTING_SMART_MAXFILE` – Determines the maximum size of a file. +- `CONFIG_TESTING_SMART_MAXIO` – Max I/O, default `347`. +- `CONFIG_TESTING_SMART_MAXOPEN` – Max open files. +- `CONFIG_TESTING_SMART_MOUNTPT` – SMART mountpoint. +- `CONFIG_TESTING_SMART_NLOOPS` – Number of test loops. default `100`. +- `CONFIG_TESTING_SMART_VERBOSE` – Verbose output. diff --git a/testing/smart_test/README.md b/testing/smart_test/README.md index 2675067e7..f0e6352f2 100644 --- a/testing/smart_test/README.md +++ b/testing/smart_test/README.md @@ -1,22 +1,26 @@ -README -====== +# Testing / `smart_test` SMART File System - Performs a file-based test on a SMART (or any) filesystem. Validates - seek, append and seek-with-write operations. +Performs a file-based test on a SMART (or any) filesystem. Validates seek, +append and seek-with-write operations. - * CONFIG_TESTING_SMART_TEST=y +```conf +CONFIG_TESTING_SMART_TEST=y +``` - Source: NuttX - Author: Ken Pettit - Date: April 24, 2013 +``` +Author: Ken Pettit + Date: April 24, 2013 +``` - Performs a file-based test on a SMART (or any) filesystem. Validates seek, - append and seek-with-write operations. +Performs a file-based test on a SMART (or any) filesystem. Validates seek, +append and seek-with-write operations. - Usage: +``` +Usage: flash_test mtdblock_device Additional options: --force to replace existing installation +``` diff --git a/tools/README.md b/tools/README.md index 44bfe2913..3c50b06b8 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,34 +1,30 @@ -NxWidgets/tools README File -=========================== +# Tools -bitmap_converter.py -------------------- +## NxWidgets `bitmap_converter.py` - This script converts from any image type supported by Python imaging library to - the RLE-encoded format used by NxWidgets. +This script converts from any image type supported by Python imaging library to +the RLE-encoded format used by NxWidgets. - RLE (Run Length Length) is a very simply encoding that compress quite well - with certain kinds of images: Images that that have many pixels of the - same color adjacent on a row (like simple graphics). It does not work well - with photographic images. +RLE (Run Length Length) is a very simply encoding that compress quite well with +certain kinds of images: Images that that have many pixels of the same color +adjacent on a row (like simple graphics). It does not work well with +photographic images. - But even simple graphics may not encode compactly if, for example, they have - been resized. Resizing an image can create hundreds of unique colors that - may differ by only a bit or two in the RGB representation. This "color - smear" is the result of pixel interpolation (and might be eliminated if - your graphics software supports resizing via pixel replication instead of - interpolation). +But even simple graphics may not encode compactly if, for example, they have +been resized. Resizing an image can create hundreds of unique colors that may +differ by only a bit or two in the RGB representation. This _color smear_ is the +result of pixel interpolation (and might be eliminated if your graphics software +supports resizing via pixel replication instead of interpolation). - When a simple graphics image does not encode well, the symptom is that - the resulting RLE data structures are quite large. The palette structure, - in particular, may have hundreds of colors in it. There is a way to fix - the graphic image in this case. Here is what I do (in fact, I do this - on all images prior to conversion just to be certain): +When a simple graphics image does not encode well, the symptom is that the +resulting RLE data structures are quite large. The palette structure, in +particular, may have hundreds of colors in it. There is a way to fix the graphic +image in this case. Here is what I do (in fact, I do this on all images prior to +conversion just to be certain): - - Open the original image in GIMP. - - Select the option to select the number of colors in the image. - - Pick the smallest number of colors that will represent the image - faithfully. For most simple graphic images this might be as few as 6 - or 8 colors. - - Save the image as PNG or other lossless format (NOT jpeg). - - Then generate the image. +- Open the original image in GIMP. +- Select the option to select the number of colors in the image. +- Pick the smallest number of colors that will represent the image faithfully. + For most simple graphic images this might be as few as 6 or 8 colors. +- Save the image as PNG or other lossless format (NOT jpeg). +- Then generate the image. diff --git a/wireless/bluetooth/btsak/README.md b/wireless/bluetooth/btsak/README.md index 49df05fdb..0a6b04108 100644 --- a/wireless/bluetooth/btsak/README.md +++ b/wireless/bluetooth/btsak/README.md @@ -1,104 +1,140 @@ -btsak -- Bluetooth Swiss Army Knife +# Wireless / Bluetooth / `btsak` Bluetooth Swiss Army Knife -Commands: +## Commands - Command: help - Description: Should overall command help - Usage: bt help +``` +Command: help +Description: Should overall command help +Usage: bt help +``` - Command: info - Description: Show Bluetooth driver information - Usage: bt info [-h] +``` +Command: info +Description: Show Bluetooth driver information +Usage: bt info [-h] +``` - Command: features - Description: Show Bluetooth driver information - Usage: bt features [-h] [le] - Where: le - Selects LE features vs BR/EDR features +``` +Command: features +Description: Show Bluetooth driver information +Usage: bt features [-h] [le] +Where: le - Selects LE features vs BR/EDR features +``` - Command: scan - Description: Bluetooth scan commands - Usage: bt scan [-h] - Where: start - Starts scanning. The -d option enables duplicate - filtering. - get - Shows new accumulated scan results - stop - Stops scanning +``` +Command: scan +Description: Bluetooth scan commands +Usage: bt scan [-h] +Where: start - Starts scanning. The -d option enables duplicate + filtering. + get - Shows new accumulated scan results + stop - Stops scanning +``` - Command: advertise - Description: Bluetooth advertise commands - Usage: bt advertise [-h] - Where: start - Starts advertising - stop - Stops advertising +``` +Command: advertise +Description: Bluetooth advertise commands +Usage: bt advertise [-h] +Where: start - Starts advertising + stop - Stops advertising +``` - Command: security - Description: Enable security (encryption) for a connection: - If device is paired, key encryption will be enabled. If - the link is already encrypted with sufficiently strong - key this command does nothing. +``` +Command: security +Description: Enable security (encryption) for a connection: + If device is paired, key encryption will be enabled. If + the link is already encrypted with sufficiently strong + key this command does nothing. - If the device is not paired pairing will be initiated. If - the device is paired and keys are too weak but input output - capabilities allow for strong enough keys pairing will be - initiated. + If the device is not paired pairing will be initiated. If + the device is paired and keys are too weak but input output + capabilities allow for strong enough keys pairing will be + initiated. - This command may return error if required level of security - is not possible to achieve due to local or remote device - limitation (eg input output capabilities). - Usage: bt security [-h] public|private - Where: - The 6-byte address of the connected peer - - Security level, on of: + This command may return error if required level of security + is not possible to achieve due to local or remote device + limitation (eg input output capabilities). +Usage: bt security [-h] public|private +Where: - The 6-byte address of the connected peer + - Security level, on of: - low - No encryption and no authentication - medium - Encryption and no authentication (no MITM) - high - Encryption and authentication (MITM) - fips - Authenticated LE secure connections and encryption + low - No encryption and no authentication + medium - Encryption and no authentication (no MITM) + high - Encryption and authentication (MITM) + fips - Authenticated LE secure connections and encryption +``` - Command: gatt - Description: Generic Attribute (GATT) commands - Usage: bt gatt [-h] [option [option [option...]]] - Where: See "GATT Commands" below +``` +Command: gatt +Description: Generic Attribute (GATT) commands +Usage: bt gatt [-h] [option [option [option...]]] +Where: See "GATT Commands" below +``` -GATT Commands +## GATT Commands - Command: exchange-mtu - Description: Set MTU to out maximum and negotiate MTU with peer - Usage: bt gatt exchange-mtu [-h] public|private +``` +Command: exchange-mtu +Description: Set MTU to out maximum and negotiate MTU with peer +Usage: bt gatt exchange-mtu [-h] public|private +``` - Command: mget - Description: Get the pass/fail result of the last GATT 'exchange-mtu' command - Usage: bt gatt mget [-h] +``` +Command: mget +Description: Get the pass/fail result of the last GATT 'exchange-mtu' command +Usage: bt gatt mget [-h] +``` - Command: discover - Description: Initiate discovery - Usage: bt gatt discover [-h] public|private [ []] +``` +Command: discover +Description: Initiate discovery +Usage: bt gatt discover [-h] public|private [ []] +``` - Command: characteristic - Description: Initiate characteristics discovery - Usage: bt gatt characteristic [-h] public|private [ []] +``` +Command: characteristic +Description: Initiate characteristics discovery +Usage: bt gatt characteristic [-h] public|private [ []] +``` - Command: descriptor - Description: Initiate characteristics discovery - Usage: bt gatt descriptor [-h] public|private [ []] +``` +Command: descriptor +Description: Initiate characteristics discovery +Usage: bt gatt descriptor [-h] public|private [ []] +``` - Command: dget - Description: Get the result of the last discovery action - Usage: bt gatt dget [-h] +``` +Command: dget +Description: Get the result of the last discovery action +Usage: bt gatt dget [-h] +``` - Command: read - Description: Initiate a GATT read operation. - Usage: bt gatt read [-h] public|private [] +``` +Command: read +Description: Initiate a GATT read operation. +Usage: bt gatt read [-h] public|private [] +``` - Command: read-multiple - Description: Initiate a GATT read-multiple operation. - Usage: bt gatt read-multiple [-h] public|private [ []..] +``` +Command: read-multiple +Description: Initiate a GATT read-multiple operation. +Usage: bt gatt read-multiple [-h] public|private [ []..] +``` - Command: rget - Description: Get the data resulting from the last read operation - Usage: bt gatt rget [-h] +``` +Command: rget +Description: Get the data resulting from the last read operation +Usage: bt gatt rget [-h] +``` - Command: write - Description: Initiate a GATT write operation. - Usage: bt gatt write [-h] public|private [ []..] +``` +Command: write +Description: Initiate a GATT write operation. +Usage: bt gatt write [-h] public|private [ []..] +``` - Command: wget - Description: Get the pass/fail result of the last GATT 'write' command - Usage: bt gatt wget [-h] +``` +Command: wget +Description: Get the pass/fail result of the last GATT 'write' command +Usage: bt gatt wget [-h] +``` diff --git a/wireless/ieee802154/i8sak/README.md b/wireless/ieee802154/i8sak/README.md index db025e1e4..1a0557b51 100644 --- a/wireless/ieee802154/i8sak/README.md +++ b/wireless/ieee802154/i8sak/README.md @@ -1,85 +1,95 @@ -IEEE 802.15.4 Swiss Army Knife (i8sak, or i8) -============================================================ +# Wireless / IEEE 802.15.4 / `i8sak` or `i8` IEEE 802.15.4 Swiss Army Knife + +## Description -Description -=========== The i8sak app is a useful CLI for testing various IEEE 802.15.4 functionality. -It also serves as a starting place for learning how to interface with the -NuttX IEEE 802.15.4 MAC layer. +It also serves as a starting place for learning how to interface with the NuttX +IEEE 802.15.4 MAC layer. The i8sak CLI can be used to manipulate multiple MAC layer networks at once. -Both a MAC character driver interface and a network interface using sockets -are supported. The MAC character driver is used in cases where networking is -not enabled and you want your application to use IEEE 802.15.4 directly. In -most cases however, you will probably be using 6LoWPAN networking support and +Both a MAC character driver interface and a network interface using sockets are +supported. The MAC character driver is used in cases where networking is not +enabled and you want your application to use IEEE 802.15.4 directly. In most +cases however, you will probably be using 6LoWPAN networking support and therefore, the MAC can be controlled directly from the socket interface rather than the MAC character driver. IEEE 802.15.4 MAC character drivers show up in -NuttX as /dev/ieeeN by default. +NuttX as `/dev/ieeeN` by default. -When you invoke the first call to i8sak with a specified interface name, it creates -an i8sak instance and launches a daemon to handle processing work. The instance -is considered sticky, so it is possible to run `i8 /dev/ieee0` or 'i8 wpan0' at -the beginning of a session and then can exclude the interface name from all -future calls. The number of i8sak instances supported is controllable through -menuconfig. +When you invoke the first call to i8sak with a specified interface name, it +creates an i8sak instance and launches a daemon to handle processing work. The +instance is considered sticky, so it is possible to run `i8 /dev/ieee0` or `i8 +wpan0` at the beginning of a session and then can exclude the interface name +from all future calls. The number of i8sak instances supported is controllable +through menuconfig. -The i8sak app has many settings that can be configured. Most options are "sticky", -meaning, if you set the endpoint short address once, any future operation using -the endpoint short address can default to the previously used address. This is -particularly useful to keep the command lengths down. +The `i8sak` app has many settings that can be configured. Most options are +_sticky_, meaning, if you set the endpoint short address once, any future +operation using the endpoint short address can default to the previously used +address. This is particularly useful to keep the command lengths down. -How To Use -========== -The i8sak app has a series of CLI functions that can be invoked. The default -i8sak command is 'i8' to make things quick and easy to type. +## How To Use -In my test setup I have 2 Clicker2-STM32 boards from MikroElektronika, with -the BEE-click (MRF24J40) radios. Choose one device to be the PAN Coordinator. -We'll refer to that as device A. +The i8sak app has a series of CLI functions that can be invoked. The default +i8sak command is `i8` to make things quick and easy to type. + +In my test setup I have 2 Clicker2-STM32 boards from MikroElektronika, with the +BEE-click (MRF24J40) radios. Choose one device to be the PAN Coordinator. We'll +refer to that as device A. On that device, run: -``` + +```shell i8 /dev/ieee0 startpan cd:ab ``` + This will tell the MAC layer that it should now act as a PAN coordinator using PAN ID CD:AB. For now, this function assumes that we are operating a non-beacon enabled PAN, since, as of this writing, beacon-enabled networks are unfinished. Next, on the same device, run: -``` + +```shell i8 acceptassoc ``` -Notice in the second command, we did not use the devname, again, that is "sticky" -so unless we are switching back and forth between character drivers, we can -just use it once. -The acceptassoc command, without any arguments, informs the i8sak instance to +Notice in the second command, we did not use the devname, again, that is +_sticky_ so unless we are switching back and forth between character drivers, we +can just use it once. + +The acceptassoc command, without any arguments, informs the `i8sak` instance to accept all association requests. The acceptassoc command also allows you to only -accept requests from a single device by specifying the extended address with option --e. +accept requests from a single device by specifying the extended address with +option `-e`. For instance: +```shell i8 acceptassoc -e DEADBEEF00FADE0B +``` But for this example, let's just use the command with no arguments. -Now, the second device will act as an endpoint device. The i8sak instance defaults -to being in endpoint mode. Let's refer to the second device as device B. +Now, the second device will act as an endpoint device. The i8sak instance +defaults to being in endpoint mode. Let's refer to the second device as device +`B`. On device B, run: +```shell i8 /dev/ieee0 assoc +``` -This command attempts to associate with the node at the configured endpoint address. -If everything is setup correctly, device A should have log information saying -that a device tried to associate and that it accepted the association. On device -B, the console should show that the association request was successful. With all -default settings, device B should have been allocated a short address of 0x000B. +This command attempts to associate with the node at the configured endpoint +address. If everything is setup correctly, device A should have log information +saying that a device tried to associate and that it accepted the association. On +device `B`, the console should show that the association request was successful. +With all default settings, device B should have been allocated a short address +of `0x000B`. If you are following along with a packet sniffer, you should see something similar to the following: +``` 1) Association Request Frame Type - CMD Sequence Number - 0 @@ -119,49 +129,61 @@ similar to the following: 3a) ACK Frame Type - ACK Sequence Number - 0 - +``` The default endpoint address can be configured via Kconfig or set dynamically -using the 'set' command. +using the `set` command. Here is how to set the endpoint short address +```shell i8 set ep_saddr 0a:00 +``` When setting the address, it's important to make sure the endpoint addressing -mode is configured the way you want: Use 's' for short addressing or 'e' for extended +mode is configured the way you want: Use `s` for short addressing or `e` for +extended +```shell i8 set ep_addrmode s +``` Device B has now successfully associated with device A. If you want to send data from device B to device A, run the following on device B: -``` + +```shell i8 tx ABCDEF ``` + This will immediately (not actually immediate, transaction is sent using CSMA) -send the frame to device A with frame payload 0xABCDEF +send the frame to device A with frame payload `0xABCDEF` Sending data from device A to device B is different. In IEEE 802.15.4, frames must be extracted from the coordinator. To prepare the frame, run the following command on device A -``` + +```shell i8 tx AB ``` -Because the devmode is PAN Coordinator, the i8sak app knows to send the data -as an indirect transaction. If you were running the i8sak app on a device -that is a coordinator, but not the PAN coordinator, you can force the i8sak app -to send the transaction directly, rather than to the parent coordinator, by using -the -d option. -NOTE: Currently, the indirect transaction timeout is disabled. This means frames -must be extracted or space may run out. This is only for the testing phase as it -is easier to debug when I am not fighting a timeout. Re-enabling the timeout may -effect the behavior of the indirect transaction features in the i8sak app. +Because the devmode is PAN Coordinator, the `i8sak` app knows to send the data +as an indirect transaction. If you were running the `i8sak` app on a device that +is a coordinator, but not the PAN coordinator, you can force the `i8sak` app to +send the transaction directly, rather than to the parent coordinator, by using +the `-d` option. -To extract the data, run the following command on device B: -``` +**Note**: Currently, the indirect transaction timeout is disabled. This means +frames must be extracted or space may run out. This is only for the testing +phase as it is easier to debug when I am not fighting a timeout. Re-enabling the +timeout may effect the behavior of the indirect transaction features in the +`i8sak` app. + +To extract the data, run the following command on device `B`: + +```shell i8 poll ``` + This command polls the endpoint (our device A PAN Coordinator in this case) to -see if there is any data. In the console of device B you should see a Poll request -status print out. +see if there is any data. In the console of device B you should see a Poll +request status print out. diff --git a/wireless/wapi/README.md b/wireless/wapi/README.md index 41cafb9c2..ab357fd3e 100644 --- a/wireless/wapi/README.md +++ b/wireless/wapi/README.md @@ -1,31 +1,32 @@ +# Wireless / `wapi` WAPI - `_`_`_`_____`_____`__` - |`|`|`|``_``|``_``|``| - |`|`|`|`````|```__|``| - |_____|__|__|__|``|__| +``` +`_`_`_`_____`_____`__` +|`|`|`|``_``|``_``|``| +|`|`|`|`````|```__|``| +|_____|__|__|__|``|__| +``` WAPI (Wireless API) provides an easy-to-use function set to configure wireless network interfaces on a GNU/Linux system. One can think WAPI as a lightweight C -API for iwconfig, wlanconfig, ifconfig, and route commands. (But it is not a -thin wrapper for these command line tools.) It is designed to be used in +API for `iwconfig`, `wlanconfig`, `ifconfig`, and `route` commands. (But it is +not a thin wrapper for these command line tools.) It is designed to be used in wireless heteregenous network research projects and supported by BWRC (Berkeley Wireless Research Center) and WISERLAB (Wireless Information Systems Engineering Research Laboratory at Özyeğin University). -For source codes, see http://github.com/vy/wapi. The most recent version of the +For source codes, see http://github.com/vy/wapi. The most recent version of the documentation is (hopefully) always available at http://vy.github.com/wapi. ---- L I C E N S E -------------------------------------------------------------- +## License -Copyright (c) 2010, Volkan YAZICI -All rights reserved. +Copyright (c) 2010, Volkan YAZICI All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.