Aksal/nuttx-apps
1
0
Fork 1
mirror of https://github.com/apache/nuttx-apps.git synced 2026-08-01 20:29:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Rewritten READMEs to Markdown

Browse source
This commit is contained in:
Maciej Wójcik 2020-07-23 15:19:35 +02:00 • committed by Brennan Ashton
parent 51e6645f71
commit 21049ece6e
56 changed files with 6803 additions and 6492 deletions
Download patch file Download diff file Expand all files Collapse all files

302
README.md
View file

@ -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=<path> or make CONFIG_APPS_DIR=<path>
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 <app-dir> <board-name>:<config-name>
like: `make APPDIR=<path>` or `make CONFIG_APPS_DIR=<path>`
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 <app-dir> <board-name>:<config-name>`
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.

3356
examples/README.md
View file

File diff suppressed because it is too large Load diff

1044
examples/bastest/README.md
View file

File diff suppressed because it is too large Load diff

67
examples/camera/README.md
View file

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

4
examples/camera/camera_main.c
View file

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

25
examples/flash_test/README.md
View file

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

22
examples/flowc/README.md
View file

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

301
examples/json/README.md
View file

@ -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;i<cJSON_GetArraySize(item);i++)
int i; for (i=0; i < cJSON_GetArraySize(item); i++)
{
cJSON *subitem=cJSON_GetArrayItem(item,i);
cJSON *subitem = cJSON_GetArrayItem(item, i);
// handle subitem.
}
}
```
Or, for PROPER manual mode:
```c
void parse_object(cJSON *item)
{
cJSON *subitem=item->child;
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_

26
examples/pdcurses/README.md
View file

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

57
examples/tcpblaster/README.md
View file

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

9
examples/telnetd/README.md
View file

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

59
fsutils/inifile/README.md
View file

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

16
gpsutils/README.md
View file

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

45
gpsutils/minmea/README.md
View file

@ -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 &lt;kosma@cloudyourcar.com&gt; at Cloud Your Car.
Minmea was written by Kosma Moczek &lt;kosma@cloudyourcar.com&gt; at Cloud Your
Car.

26
graphics/lvgl/README.md
View file

@ -1,21 +1,23 @@
# Usage
# Graphics / `lvgl` LVGL
## Usage
Import with `#include <lvgl/lvgl.h>` or `#include <lvgl.h>`.
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)

76
graphics/nxwidgets/Doxygen/README.md
View file

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

70
graphics/nxwidgets/README.md
View file

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

348
graphics/nxwidgets/UnitTests/README.md
View file

@ -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 <nuttx-directory-path>
make distclean
tools/configure.sh sim:nsh2
```bash
cd <nuttx-directory-path>
make distclean
tools/configure.sh sim:nsh2
```
Where:
Where:
<nuttx-directory-path> is the full, absolute path to the NuttX build directory
`<nuttx-directory-path>` 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 <nuttx-directory-path>
. ./setenv.sh
make
```bash
cd <nuttx-directory-path>
. ./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`.

76
graphics/nxwm/Doxygen/README.md
View file

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

47
graphics/nxwm/README.md
View file

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

53
graphics/pdcurs34/README.md
View file

@ -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 <wmcbrine@users.sf.net>

24
graphics/pdcurs34/pdcurses/README.md
View file

@ -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 <wht@n4hgf.mt-park.ga.us>

19
graphics/tiff/README.md
View file

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

641
graphics/twm4nx/README.md
View file

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

86
industry/abnt_codi/README.md
View file

@ -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: <br> `0001` – tip <br> `0010` – out of tip <br> `1000` – reserved
| | `4-5` | Type of charging indicator (flag): <br> `00` – Blue <br> `01` – Green <br> `10` – Irrigators <br> `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

33
interpreters/README.md
View file

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

104
interpreters/bas/README.md
View file

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

51
interpreters/ficl/README.md
View file

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

202
modbus/README.md
View file

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

226
netutils/README.md
View file

@ -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 <sean@sourcemud.org>,
Jack Kelly <endgame.dos@gmail.com>, and Katherine Flavel
<kate@elide.org>
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 <sean@sourcemud.org>, Jack Kelly
<endgame.dos@gmail.com> and Katherine Flavel <kate@elide.org>
- `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.

13
netutils/discover/README.md
View file

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

162
netutils/ftpc/README.md
View file

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

3
netutils/telnetd/README.md
View file

@ -1,4 +1,3 @@
README.txt
^^^^^^^^^^
# Network Utilities / `telnetd` Telnet Daemon
This directly contains a generic Telnet daemon.

3004
nshlib/README.md
View file

File diff suppressed because it is too large Load diff

60
system/cdcacm/README.md
View file

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

31
system/cfgdata/README.md
View file

@ -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 <cmd> [arguments]
**Usage**:
Where <cmd> 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 <cmd> [arguments]
```
Where `<cmd>` 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

105
system/composite/README.md
View file

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

21
system/flash_eraseall/README.md
View file

@ -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 <flash_block_device>
**Usage**:
```shell
flash_eraseall <flash_block_device>
```

528
system/i2c/README.md
View file

@ -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 <cmd> [arguments]
Where <cmd> is one of:
```
nsh> i2c help
Show help : ?
List buses : bus
List devices : dev [OPTIONS] <first> <last>
Read register : get [OPTIONS] [<repititions>]
Show help : help
Write register: set [OPTIONS] <value> [<repititions>]
Verify access : verf [OPTIONS] <value> [<repititions>]
Usage: i2c <cmd> [arguments]
Where <cmd> is one of:
Where common "sticky" OPTIONS include:
Show help : ?
List buses : bus
List devices : dev [OPTIONS] <first> <last>
Read register : get [OPTIONS] [<repititions>]
Show help : help
Write register: set [OPTIONS] <value> [<repititions>]
Verify access : verf [OPTIONS] <value> [<repititions>]
Where common _sticky_ OPTIONS include:
[-a addr] is the I2C device address (hex). Default: 03 Current: 03
[-b bus] is the I2C bus number (decimal). Default: 1 Current: 1
[-r regaddr] is the I2C device register address (hex). Default: 00 Current: 00
@ -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 <cmd> [arguments]
## Command Line Form
Where <cmd> is a "sub-command" and identifies one I2C operations supported
by the tool. [arguments] represents the list of arguments needed to perform
the I2C operation. Those arguments vary from command to command as
described below. However, there is also a core set of common OPTIONS
supported by all commands. So perhaps a better representation of the
general I2C command would be:
The I2C is started from NSH by invoking the `i2c` command from the NSH command
line. The general form of the `i2c` command is:
i2c <cmd> [OPTIONS] [arguments]
```shell
i2c <cmd> [arguments]
```
Where [OPTIONS] represents the common options and and arguments represent
the operation-specific arguments.
Where `<cmd>` is a _sub-command_ and identifies one I2C operations supported by
the tool. `[arguments]` represents the list of arguments needed to perform the
I2C operation. Those arguments vary from command to command as described below.
However, there is also a core set of common `OPTIONS` supported by all commands.
So perhaps a better representation of the general I2C command would be:
COMMON COMMAND OPTIONS
======================
```shell
i2c <cmd> [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] <first> <last>
------------------------------------------
### List devices: `dev [OPTIONS] <first> <last>`
The 'dev' command will attempt to identify all of the I2C devices on the
selected bus. The <first> and <last> arguments are 7-bit, hexadecimal
I2C addresses. This command will examine a range of addresses beginning
with <first> and continuing through <last>. It will request the value
of register address zero from each device.
The `dev` command will attempt to identify all of the I2C devices on the
selected bus. The `<first>` and `<last>` arguments are 7-bit, hexadecimal I2C
addresses. This command will examine a range of addresses beginning with
`<first>` and continuing through `<last>`. It will request the value of register
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 <repititions> argument can be supplied to repeat the
read operation an arbitrary number of times (up to 2 billion). If
auto-increment is select (-i), then the register address will be
temporarily incremented on each repitions. The increment is temporary
in the since that it will not alter the "sticky" value of the
register address.
An optional `<repititions>` argument can be supplied to repeat the read
operation an arbitrary number of times (up to 2 billion). If auto-increment is
select (`-i`), then the register address will be temporarily incremented on each
repitions. The increment is temporary in the since that it will not alter the
_sticky_ value of the register address.
On success, the output will look like the following (the data value
read will be shown as a 4-character hexadecimal number if the 16-bit
data width option is selected).
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] <value>
-------------------------------------
### Write register: `set [OPTIONS] <value>`
This command will write a value to an I2C register using the selected
I2C parameters in the common options. The value to write must be provided
as the final, hexadecimal value. This value may be an 8-bit value (in the
range 00-ff) or a 16-bit value (in the range 0000-ffff), depending upon
the selected data width.
This command will write 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 <repititions> argument can be supplied to repeat the
write operation an arbitrary number of times (up to 2 billion). If
auto-increment is select (-i), then the register address will be
temporarily incremented on each repitions. The increment is temporary
in the since that it will not alter the "sticky" value of the
register address.
An optional `<repititions>` argument can be supplied to repeat the write
operation an arbitrary number of times (up to 2 billion). If auto-increment is
select (`-i`), then the register address will be temporarily incremented on each
repitions. The increment is temporary in the since that it will not alter the
_sticky_ value of the register address.
On success, the output will look like the following (the data value
written will be shown as a 4-character hexadecimal number if the 16-bit
data width option is selected).
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] <value> [<repititions>]
------------------------------------------------------
### Verify access: `verf [OPTIONS] <value> [<repititions>]`
This command combines writing and reading from an I2C device register.
It will write a value to an will write a value to an I2C register using
the selected I2C parameters in the common options just as described for
tie 'set' command. Then this command will read the value back just
as described with the 'get' command. Finally, this command will compare
the value read and against the value written and emit an error message
if they do not match.
If no value is provided, then this command will use the register address
itself as the data, providing for a address-in-address test.
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 <repititions> argument can be supplied to repeat the
verify operation an arbitrary number of times (up to 2 billion). If
auto-increment is select (-i), then the register address will be
temporarily incremented on each repitions. The increment is temporary
in the since that it will not alter the "sticky" value of the
register address.
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 `<repititions>` argument can be supplied to repeat the verify
operation an arbitrary number of times (up to 2 billion). If auto-increment is
select (`-i`), then the register address will be temporarily incremented on each
repitions. The increment is temporary in the since that it will not alter the
`sticky` value of the register address.
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`).

71
system/nsh/README.md
View file

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

25
system/nxplayer/README.md
View file

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

78
system/psmq/README.md
View file

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

314
system/spi/README.md
View file

@ -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 <cmd> [arguments]
Where <cmd> is one of:
Show help : ?
List buses : bus
List buses : bus
SPI Exchange : exch [OPTIONS] [<hex senddata>]
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 <cmd> [arguments]
## Command Line Form
Where <cmd> 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 <cmd> [OPTIONS] [arguments]
```shell
spi <cmd> [arguments]
```
Where [OPTIONS] represents the common options and and arguments represent
the operation-specific arguments.
Where `<cmd>` 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 <cmd> [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] <Optional TX Data>
------------------------------------------------
### Exchange data: `exch [OPTIONS] <Optional TX Data>`
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`.

67
system/termcurses/README.md
View file

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

143
system/usbmsc/README.md
View file

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

423
system/zmodem/README.md
View file

@ -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 >/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 <filename>
```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 <filename>
```
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 <filename> [-l nnnn] [-w nnnn] </dev/ttyS0 >/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 <filename> 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 <filename> [-l nnnn] [-w nnnn] </dev/ttyS0 >/dev/ttyS0
```
- Change to the apps/systems/zmodem directory
- Make using the special makefile, Makefile.host
Where `<filename>` 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.

258
testing/README.md
View file

@ -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/<arch>/<chip>/<board>/configs/<config>/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/<arch>/<chip>/<board>/configs/<config>/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

41
testing/cxxtest/README.md
View file

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

33
testing/fstest/README.md
View file

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

11
testing/nxffs/README.md
View file

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

44
testing/smart/README.md
View file

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

26
testing/smart_test/README.md
View file

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

52
tools/README.md
View file

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

198
wireless/bluetooth/btsak/README.md
View file

@ -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 <ifname> help
```
Command: help
Description: Should overall command help
Usage: bt <ifname> help
```
Command: info
Description: Show Bluetooth driver information
Usage: bt <ifname> info [-h]
```
Command: info
Description: Show Bluetooth driver information
Usage: bt <ifname> info [-h]
```
Command: features
Description: Show Bluetooth driver information
Usage: bt <ifname> features [-h] [le]
Where: le - Selects LE features vs BR/EDR features
```
Command: features
Description: Show Bluetooth driver information
Usage: bt <ifname> features [-h] [le]
Where: le - Selects LE features vs BR/EDR features
```
Command: scan
Description: Bluetooth scan commands
Usage: bt <ifname> scan [-h] <start [-d]|get|stop>
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 <ifname> scan [-h] <start [-d]|get|stop>
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 <ifname> advertise [-h] <start|stop>
Where: start - Starts advertising
stop - Stops advertising
```
Command: advertise
Description: Bluetooth advertise commands
Usage: bt <ifname> advertise [-h] <start|stop>
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 <ifname> security [-h] <addr> public|private <level>
Where: <addr> - The 6-byte address of the connected peer
<level> - 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 <ifname> security [-h] <addr> public|private <level>
Where: <addr> - The 6-byte address of the connected peer
<level> - 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 <ifname> gatt [-h] <cmd> [option [option [option...]]]
Where: See "GATT Commands" below
```
Command: gatt
Description: Generic Attribute (GATT) commands
Usage: bt <ifname> gatt [-h] <cmd> [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 <ifname> gatt exchange-mtu [-h] <addr> public|private
```
Command: exchange-mtu
Description: Set MTU to out maximum and negotiate MTU with peer
Usage: bt <ifname> gatt exchange-mtu [-h] <addr> public|private
```
Command: mget
Description: Get the pass/fail result of the last GATT 'exchange-mtu' command
Usage: bt <ifname> gatt mget [-h]
```
Command: mget
Description: Get the pass/fail result of the last GATT 'exchange-mtu' command
Usage: bt <ifname> gatt mget [-h]
```
Command: discover
Description: Initiate discovery
Usage: bt <ifname> gatt discover [-h] <addr> public|private <uuid16> [<start> [<end>]]
```
Command: discover
Description: Initiate discovery
Usage: bt <ifname> gatt discover [-h] <addr> public|private <uuid16> [<start> [<end>]]
```
Command: characteristic
Description: Initiate characteristics discovery
Usage: bt <ifname> gatt characteristic [-h] <addr> public|private [<start> [<end>]]
```
Command: characteristic
Description: Initiate characteristics discovery
Usage: bt <ifname> gatt characteristic [-h] <addr> public|private [<start> [<end>]]
```
Command: descriptor
Description: Initiate characteristics discovery
Usage: bt <ifname> gatt descriptor [-h] <addr> public|private [<start> [<end>]]
```
Command: descriptor
Description: Initiate characteristics discovery
Usage: bt <ifname> gatt descriptor [-h] <addr> public|private [<start> [<end>]]
```
Command: dget
Description: Get the result of the last discovery action
Usage: bt <ifname> gatt dget [-h]
```
Command: dget
Description: Get the result of the last discovery action
Usage: bt <ifname> gatt dget [-h]
```
Command: read
Description: Initiate a GATT read operation.
Usage: bt <ifname> gatt read [-h] <addr> public|private <handle> [<offset>]
```
Command: read
Description: Initiate a GATT read operation.
Usage: bt <ifname> gatt read [-h] <addr> public|private <handle> [<offset>]
```
Command: read-multiple
Description: Initiate a GATT read-multiple operation.
Usage: bt <ifname> gatt read-multiple [-h] <addr> public|private <handle> [<handle> [<handle>]..]
```
Command: read-multiple
Description: Initiate a GATT read-multiple operation.
Usage: bt <ifname> gatt read-multiple [-h] <addr> public|private <handle> [<handle> [<handle>]..]
```
Command: rget
Description: Get the data resulting from the last read operation
Usage: bt <ifname> gatt rget [-h]
```
Command: rget
Description: Get the data resulting from the last read operation
Usage: bt <ifname> gatt rget [-h]
```
Command: write
Description: Initiate a GATT write operation.
Usage: bt <ifname> gatt write [-h] <addr> public|private <handle> <byte> [<byte> [<byte>]..]
```
Command: write
Description: Initiate a GATT write operation.
Usage: bt <ifname> gatt write [-h] <addr> public|private <handle> <byte> [<byte> [<byte>]..]
```
Command: wget
Description: Get the pass/fail result of the last GATT 'write' command
Usage: bt <ifname> gatt wget [-h]
```
Command: wget
Description: Get the pass/fail result of the last GATT 'write' command
Usage: bt <ifname> gatt wget [-h]
```

146
wireless/ieee802154/i8sak/README.md
View file

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

23
wireless/wapi/README.md
View file

@ -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 <volkan.yazici@gmail.com>
All rights reserved.
Copyright (c) 2010, Volkan YAZICI <volkan.yazici@gmail.com> 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.