You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by bt...@apache.org on 2020/07/25 08:02:00 UTC
[incubator-nuttx-apps] branch master updated (a01be75 -> 21049ec)
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx-apps.git.
from a01be75 Update boards matrix to add AVR builds.
new 51e6645 Rename README and README.txt to README.md
new 21049ec Rewritten READMEs to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
README.md | 239 +++
README.txt | 223 ---
examples/README.md | 2061 +++++++++++++++++++
examples/README.txt | 2113 --------------------
examples/bastest/{README.txt => README.md} | 1056 ++++++----
examples/camera/README.md | 42 +
examples/camera/README.txt | 39 -
examples/camera/camera_main.c | 4 +-
examples/flash_test/README.md | 23 +
examples/flash_test/README.txt | 18 -
examples/flowc/README.md | 17 +
examples/flowc/README.txt | 15 -
examples/json/README | 258 ---
examples/json/README.md | 297 +++
examples/pdcurses/README | 21 -
examples/pdcurses/README.md | 17 +
examples/tcpblaster/README.md | 43 +
examples/tcpblaster/README.txt | 40 -
examples/telnetd/README.md | 7 +
examples/telnetd/README.txt | 8 -
fsutils/inifile/{README.txt => README.md} | 59 +-
gpsutils/README.md | 10 +
gpsutils/README.txt | 12 -
gpsutils/minmea/README.md | 45 +-
graphics/lvgl/README.md | 26 +-
graphics/nxwidgets/Doxygen/README.md | 68 +
graphics/nxwidgets/Doxygen/README.txt | 64 -
graphics/nxwidgets/{README.txt => README.md} | 70 +-
graphics/nxwidgets/UnitTests/README.md | 259 +++
graphics/nxwidgets/UnitTests/README.txt | 241 ---
graphics/nxwm/Doxygen/README.md | 68 +
graphics/nxwm/Doxygen/README.txt | 64 -
graphics/nxwm/README.md | 27 +
graphics/nxwm/README.txt | 30 -
graphics/pdcurs34/README | 48 -
graphics/pdcurs34/README.md | 39 +
graphics/pdcurs34/pdcurses/{README => README.md} | 24 +-
graphics/tiff/README.md | 12 +
graphics/tiff/README.txt | 15 -
graphics/twm4nx/README.md | 386 ++++
graphics/twm4nx/README.txt | 385 ----
industry/abnt_codi/README.md | 27 +
industry/abnt_codi/README.txt | 67 -
interpreters/README.md | 21 +
interpreters/README.txt | 24 -
interpreters/bas/README.md | 59 +
interpreters/bas/README.txt | 63 -
interpreters/ficl/README.md | 39 +
interpreters/ficl/README.txt | 40 -
modbus/README.md | 121 ++
modbus/README.txt | 123 --
netutils/README.md | 138 ++
netutils/README.txt | 138 --
netutils/discover/README.md | 8 +
netutils/discover/README.txt | 9 -
netutils/ftpc/README.md | 81 +
netutils/ftpc/README.txt | 81 -
netutils/telnetd/{README.txt => README.md} | 3 +-
nshlib/README.md | 1990 ++++++++++++++++++
nshlib/README.txt | 1962 ------------------
system/cdcacm/README.md | 36 +
system/cdcacm/README.txt | 42 -
system/cfgdata/README.md | 22 +
system/cfgdata/README.txt | 17 -
system/composite/README.md | 69 +
system/composite/README.txt | 76 -
system/flash_eraseall/README.md | 15 +
system/flash_eraseall/README.txt | 12 -
system/i2c/README.md | 387 ++++
system/i2c/README.txt | 375 ----
system/nsh/README.md | 50 +
system/nsh/README.txt | 45 -
system/nxplayer/README.md | 18 +
system/nxplayer/README.txt | 17 -
system/psmq/README.md | 59 +
system/psmq/README.txt | 47 -
system/spi/README.md | 246 +++
system/spi/README.txt | 226 ---
system/termcurses/README.md | 50 +
system/termcurses/README.txt | 49 -
system/usbmsc/README.md | 85 +
system/usbmsc/README.txt | 82 -
system/zmodem/README.md | 280 +++
system/zmodem/README.txt | 271 ---
testing/README.md | 165 ++
testing/README.txt | 171 --
testing/cxxtest/README.md | 27 +
testing/cxxtest/README.txt | 28 -
testing/fstest/README.md | 19 +
testing/fstest/README.txt | 20 -
testing/nxffs/README.md | 6 +
testing/nxffs/README.txt | 7 -
testing/smart/README.md | 23 +
testing/smart/README.txt | 25 -
testing/smart_test/README.md | 26 +
testing/smart_test/README.txt | 22 -
tools/README.md | 30 +
tools/README.txt | 34 -
wireless/bluetooth/btsak/README.md | 140 ++
wireless/bluetooth/btsak/README.txt | 104 -
.../ieee802154/i8sak/{README.txt => README.md} | 150 +-
wireless/wapi/{README => README.md} | 23 +-
102 files changed, 8697 insertions(+), 8386 deletions(-)
create mode 100644 README.md
delete mode 100644 README.txt
create mode 100644 examples/README.md
delete mode 100644 examples/README.txt
rename examples/bastest/{README.txt => README.md} (69%)
create mode 100644 examples/camera/README.md
delete mode 100644 examples/camera/README.txt
create mode 100644 examples/flash_test/README.md
delete mode 100644 examples/flash_test/README.txt
create mode 100644 examples/flowc/README.md
delete mode 100644 examples/flowc/README.txt
delete mode 100644 examples/json/README
create mode 100644 examples/json/README.md
delete mode 100644 examples/pdcurses/README
create mode 100644 examples/pdcurses/README.md
create mode 100644 examples/tcpblaster/README.md
delete mode 100644 examples/tcpblaster/README.txt
create mode 100644 examples/telnetd/README.md
delete mode 100644 examples/telnetd/README.txt
rename fsutils/inifile/{README.txt => README.md} (72%)
create mode 100644 gpsutils/README.md
delete mode 100644 gpsutils/README.txt
create mode 100644 graphics/nxwidgets/Doxygen/README.md
delete mode 100644 graphics/nxwidgets/Doxygen/README.txt
rename graphics/nxwidgets/{README.txt => README.md} (50%)
create mode 100644 graphics/nxwidgets/UnitTests/README.md
delete mode 100644 graphics/nxwidgets/UnitTests/README.txt
create mode 100644 graphics/nxwm/Doxygen/README.md
delete mode 100644 graphics/nxwm/Doxygen/README.txt
create mode 100644 graphics/nxwm/README.md
delete mode 100644 graphics/nxwm/README.txt
delete mode 100644 graphics/pdcurs34/README
create mode 100644 graphics/pdcurs34/README.md
rename graphics/pdcurs34/pdcurses/{README => README.md} (51%)
create mode 100644 graphics/tiff/README.md
delete mode 100644 graphics/tiff/README.txt
create mode 100644 graphics/twm4nx/README.md
delete mode 100644 graphics/twm4nx/README.txt
create mode 100644 industry/abnt_codi/README.md
delete mode 100644 industry/abnt_codi/README.txt
create mode 100644 interpreters/README.md
delete mode 100644 interpreters/README.txt
create mode 100644 interpreters/bas/README.md
delete mode 100644 interpreters/bas/README.txt
create mode 100644 interpreters/ficl/README.md
delete mode 100644 interpreters/ficl/README.txt
create mode 100644 modbus/README.md
delete mode 100644 modbus/README.txt
create mode 100644 netutils/README.md
delete mode 100644 netutils/README.txt
create mode 100644 netutils/discover/README.md
delete mode 100644 netutils/discover/README.txt
create mode 100644 netutils/ftpc/README.md
delete mode 100644 netutils/ftpc/README.txt
rename netutils/telnetd/{README.txt => README.md} (51%)
create mode 100644 nshlib/README.md
delete mode 100644 nshlib/README.txt
create mode 100644 system/cdcacm/README.md
delete mode 100644 system/cdcacm/README.txt
create mode 100644 system/cfgdata/README.md
delete mode 100644 system/cfgdata/README.txt
create mode 100644 system/composite/README.md
delete mode 100644 system/composite/README.txt
create mode 100644 system/flash_eraseall/README.md
delete mode 100644 system/flash_eraseall/README.txt
create mode 100644 system/i2c/README.md
delete mode 100644 system/i2c/README.txt
create mode 100644 system/nsh/README.md
delete mode 100644 system/nsh/README.txt
create mode 100644 system/nxplayer/README.md
delete mode 100644 system/nxplayer/README.txt
create mode 100644 system/psmq/README.md
delete mode 100644 system/psmq/README.txt
create mode 100644 system/spi/README.md
delete mode 100644 system/spi/README.txt
create mode 100644 system/termcurses/README.md
delete mode 100644 system/termcurses/README.txt
create mode 100644 system/usbmsc/README.md
delete mode 100644 system/usbmsc/README.txt
create mode 100644 system/zmodem/README.md
delete mode 100644 system/zmodem/README.txt
create mode 100644 testing/README.md
delete mode 100644 testing/README.txt
create mode 100644 testing/cxxtest/README.md
delete mode 100644 testing/cxxtest/README.txt
create mode 100644 testing/fstest/README.md
delete mode 100644 testing/fstest/README.txt
create mode 100644 testing/nxffs/README.md
delete mode 100644 testing/nxffs/README.txt
create mode 100644 testing/smart/README.md
delete mode 100644 testing/smart/README.txt
create mode 100644 testing/smart_test/README.md
delete mode 100644 testing/smart_test/README.txt
create mode 100644 tools/README.md
delete mode 100644 tools/README.txt
create mode 100644 wireless/bluetooth/btsak/README.md
delete mode 100644 wireless/bluetooth/btsak/README.txt
rename wireless/ieee802154/i8sak/{README.txt => README.md} (53%)
rename wireless/wapi/{README => README.md} (73%)
[incubator-nuttx-apps] 01/02: Rename README and README.txt to
README.md
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx-apps.git
commit 51e6645f7112f0be0889e2a03132f56787f3829e
Author: Maciej Wójcik <w8...@gmail.com>
AuthorDate: Thu Jul 23 15:16:21 2020 +0200
Rename README and README.txt to README.md
---
README.txt => README.md | 0
examples/{README.txt => README.md} | 0
examples/bastest/{README.txt => README.md} | 0
examples/camera/{README.txt => README.md} | 0
examples/flash_test/{README.txt => README.md} | 0
examples/flowc/{README.txt => README.md} | 0
examples/json/{README => README.md} | 0
examples/pdcurses/{README => README.md} | 0
examples/tcpblaster/{README.txt => README.md} | 0
examples/telnetd/{README.txt => README.md} | 0
fsutils/inifile/{README.txt => README.md} | 0
gpsutils/{README.txt => README.md} | 0
graphics/{nxwm/Doxygen/README.txt => nxwidgets/Doxygen/README.md} | 0
graphics/nxwidgets/{README.txt => README.md} | 0
graphics/nxwidgets/UnitTests/{README.txt => README.md} | 0
graphics/{nxwidgets/Doxygen/README.txt => nxwm/Doxygen/README.md} | 0
graphics/nxwm/{README.txt => README.md} | 0
graphics/pdcurs34/{README => README.md} | 0
graphics/pdcurs34/pdcurses/{README => README.md} | 0
graphics/tiff/{README.txt => README.md} | 0
graphics/twm4nx/{README.txt => README.md} | 0
industry/abnt_codi/{README.txt => README.md} | 0
interpreters/{README.txt => README.md} | 0
interpreters/bas/{README.txt => README.md} | 0
interpreters/ficl/{README.txt => README.md} | 0
modbus/{README.txt => README.md} | 0
netutils/{README.txt => README.md} | 0
netutils/discover/{README.txt => README.md} | 0
netutils/ftpc/{README.txt => README.md} | 0
netutils/telnetd/{README.txt => README.md} | 0
nshlib/{README.txt => README.md} | 0
system/cdcacm/{README.txt => README.md} | 0
system/cfgdata/{README.txt => README.md} | 0
system/composite/{README.txt => README.md} | 0
system/flash_eraseall/{README.txt => README.md} | 0
system/i2c/{README.txt => README.md} | 0
system/nsh/{README.txt => README.md} | 0
system/nxplayer/{README.txt => README.md} | 0
system/psmq/{README.txt => README.md} | 0
system/spi/{README.txt => README.md} | 0
system/termcurses/{README.txt => README.md} | 0
system/usbmsc/{README.txt => README.md} | 0
system/zmodem/{README.txt => README.md} | 0
testing/{README.txt => README.md} | 0
testing/cxxtest/{README.txt => README.md} | 0
testing/fstest/{README.txt => README.md} | 0
testing/nxffs/{README.txt => README.md} | 0
testing/smart/{README.txt => README.md} | 0
testing/smart_test/{README.txt => README.md} | 0
tools/{README.txt => README.md} | 0
wireless/bluetooth/btsak/{README.txt => README.md} | 0
wireless/ieee802154/i8sak/{README.txt => README.md} | 0
wireless/wapi/{README => README.md} | 0
53 files changed, 0 insertions(+), 0 deletions(-)
diff --git a/README.txt b/README.md
similarity index 100%
rename from README.txt
rename to README.md
diff --git a/examples/README.txt b/examples/README.md
similarity index 100%
rename from examples/README.txt
rename to examples/README.md
diff --git a/examples/bastest/README.txt b/examples/bastest/README.md
similarity index 100%
rename from examples/bastest/README.txt
rename to examples/bastest/README.md
diff --git a/examples/camera/README.txt b/examples/camera/README.md
similarity index 100%
rename from examples/camera/README.txt
rename to examples/camera/README.md
diff --git a/examples/flash_test/README.txt b/examples/flash_test/README.md
similarity index 100%
rename from examples/flash_test/README.txt
rename to examples/flash_test/README.md
diff --git a/examples/flowc/README.txt b/examples/flowc/README.md
similarity index 100%
rename from examples/flowc/README.txt
rename to examples/flowc/README.md
diff --git a/examples/json/README b/examples/json/README.md
similarity index 100%
rename from examples/json/README
rename to examples/json/README.md
diff --git a/examples/pdcurses/README b/examples/pdcurses/README.md
similarity index 100%
rename from examples/pdcurses/README
rename to examples/pdcurses/README.md
diff --git a/examples/tcpblaster/README.txt b/examples/tcpblaster/README.md
similarity index 100%
rename from examples/tcpblaster/README.txt
rename to examples/tcpblaster/README.md
diff --git a/examples/telnetd/README.txt b/examples/telnetd/README.md
similarity index 100%
rename from examples/telnetd/README.txt
rename to examples/telnetd/README.md
diff --git a/fsutils/inifile/README.txt b/fsutils/inifile/README.md
similarity index 100%
rename from fsutils/inifile/README.txt
rename to fsutils/inifile/README.md
diff --git a/gpsutils/README.txt b/gpsutils/README.md
similarity index 100%
rename from gpsutils/README.txt
rename to gpsutils/README.md
diff --git a/graphics/nxwm/Doxygen/README.txt b/graphics/nxwidgets/Doxygen/README.md
similarity index 100%
rename from graphics/nxwm/Doxygen/README.txt
rename to graphics/nxwidgets/Doxygen/README.md
diff --git a/graphics/nxwidgets/README.txt b/graphics/nxwidgets/README.md
similarity index 100%
rename from graphics/nxwidgets/README.txt
rename to graphics/nxwidgets/README.md
diff --git a/graphics/nxwidgets/UnitTests/README.txt b/graphics/nxwidgets/UnitTests/README.md
similarity index 100%
rename from graphics/nxwidgets/UnitTests/README.txt
rename to graphics/nxwidgets/UnitTests/README.md
diff --git a/graphics/nxwidgets/Doxygen/README.txt b/graphics/nxwm/Doxygen/README.md
similarity index 100%
rename from graphics/nxwidgets/Doxygen/README.txt
rename to graphics/nxwm/Doxygen/README.md
diff --git a/graphics/nxwm/README.txt b/graphics/nxwm/README.md
similarity index 100%
rename from graphics/nxwm/README.txt
rename to graphics/nxwm/README.md
diff --git a/graphics/pdcurs34/README b/graphics/pdcurs34/README.md
similarity index 100%
rename from graphics/pdcurs34/README
rename to graphics/pdcurs34/README.md
diff --git a/graphics/pdcurs34/pdcurses/README b/graphics/pdcurs34/pdcurses/README.md
similarity index 100%
rename from graphics/pdcurs34/pdcurses/README
rename to graphics/pdcurs34/pdcurses/README.md
diff --git a/graphics/tiff/README.txt b/graphics/tiff/README.md
similarity index 100%
rename from graphics/tiff/README.txt
rename to graphics/tiff/README.md
diff --git a/graphics/twm4nx/README.txt b/graphics/twm4nx/README.md
similarity index 100%
rename from graphics/twm4nx/README.txt
rename to graphics/twm4nx/README.md
diff --git a/industry/abnt_codi/README.txt b/industry/abnt_codi/README.md
similarity index 100%
rename from industry/abnt_codi/README.txt
rename to industry/abnt_codi/README.md
diff --git a/interpreters/README.txt b/interpreters/README.md
similarity index 100%
rename from interpreters/README.txt
rename to interpreters/README.md
diff --git a/interpreters/bas/README.txt b/interpreters/bas/README.md
similarity index 100%
rename from interpreters/bas/README.txt
rename to interpreters/bas/README.md
diff --git a/interpreters/ficl/README.txt b/interpreters/ficl/README.md
similarity index 100%
rename from interpreters/ficl/README.txt
rename to interpreters/ficl/README.md
diff --git a/modbus/README.txt b/modbus/README.md
similarity index 100%
rename from modbus/README.txt
rename to modbus/README.md
diff --git a/netutils/README.txt b/netutils/README.md
similarity index 100%
rename from netutils/README.txt
rename to netutils/README.md
diff --git a/netutils/discover/README.txt b/netutils/discover/README.md
similarity index 100%
rename from netutils/discover/README.txt
rename to netutils/discover/README.md
diff --git a/netutils/ftpc/README.txt b/netutils/ftpc/README.md
similarity index 100%
rename from netutils/ftpc/README.txt
rename to netutils/ftpc/README.md
diff --git a/netutils/telnetd/README.txt b/netutils/telnetd/README.md
similarity index 100%
rename from netutils/telnetd/README.txt
rename to netutils/telnetd/README.md
diff --git a/nshlib/README.txt b/nshlib/README.md
similarity index 100%
rename from nshlib/README.txt
rename to nshlib/README.md
diff --git a/system/cdcacm/README.txt b/system/cdcacm/README.md
similarity index 100%
rename from system/cdcacm/README.txt
rename to system/cdcacm/README.md
diff --git a/system/cfgdata/README.txt b/system/cfgdata/README.md
similarity index 100%
rename from system/cfgdata/README.txt
rename to system/cfgdata/README.md
diff --git a/system/composite/README.txt b/system/composite/README.md
similarity index 100%
rename from system/composite/README.txt
rename to system/composite/README.md
diff --git a/system/flash_eraseall/README.txt b/system/flash_eraseall/README.md
similarity index 100%
rename from system/flash_eraseall/README.txt
rename to system/flash_eraseall/README.md
diff --git a/system/i2c/README.txt b/system/i2c/README.md
similarity index 100%
rename from system/i2c/README.txt
rename to system/i2c/README.md
diff --git a/system/nsh/README.txt b/system/nsh/README.md
similarity index 100%
rename from system/nsh/README.txt
rename to system/nsh/README.md
diff --git a/system/nxplayer/README.txt b/system/nxplayer/README.md
similarity index 100%
rename from system/nxplayer/README.txt
rename to system/nxplayer/README.md
diff --git a/system/psmq/README.txt b/system/psmq/README.md
similarity index 100%
rename from system/psmq/README.txt
rename to system/psmq/README.md
diff --git a/system/spi/README.txt b/system/spi/README.md
similarity index 100%
rename from system/spi/README.txt
rename to system/spi/README.md
diff --git a/system/termcurses/README.txt b/system/termcurses/README.md
similarity index 100%
rename from system/termcurses/README.txt
rename to system/termcurses/README.md
diff --git a/system/usbmsc/README.txt b/system/usbmsc/README.md
similarity index 100%
rename from system/usbmsc/README.txt
rename to system/usbmsc/README.md
diff --git a/system/zmodem/README.txt b/system/zmodem/README.md
similarity index 100%
rename from system/zmodem/README.txt
rename to system/zmodem/README.md
diff --git a/testing/README.txt b/testing/README.md
similarity index 100%
rename from testing/README.txt
rename to testing/README.md
diff --git a/testing/cxxtest/README.txt b/testing/cxxtest/README.md
similarity index 100%
rename from testing/cxxtest/README.txt
rename to testing/cxxtest/README.md
diff --git a/testing/fstest/README.txt b/testing/fstest/README.md
similarity index 100%
rename from testing/fstest/README.txt
rename to testing/fstest/README.md
diff --git a/testing/nxffs/README.txt b/testing/nxffs/README.md
similarity index 100%
rename from testing/nxffs/README.txt
rename to testing/nxffs/README.md
diff --git a/testing/smart/README.txt b/testing/smart/README.md
similarity index 100%
rename from testing/smart/README.txt
rename to testing/smart/README.md
diff --git a/testing/smart_test/README.txt b/testing/smart_test/README.md
similarity index 100%
rename from testing/smart_test/README.txt
rename to testing/smart_test/README.md
diff --git a/tools/README.txt b/tools/README.md
similarity index 100%
rename from tools/README.txt
rename to tools/README.md
diff --git a/wireless/bluetooth/btsak/README.txt b/wireless/bluetooth/btsak/README.md
similarity index 100%
rename from wireless/bluetooth/btsak/README.txt
rename to wireless/bluetooth/btsak/README.md
diff --git a/wireless/ieee802154/i8sak/README.txt b/wireless/ieee802154/i8sak/README.md
similarity index 100%
rename from wireless/ieee802154/i8sak/README.txt
rename to wireless/ieee802154/i8sak/README.md
diff --git a/wireless/wapi/README b/wireless/wapi/README.md
similarity index 100%
rename from wireless/wapi/README
rename to wireless/wapi/README.md
[incubator-nuttx-apps] 02/02: Rewritten READMEs to Markdown
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx-apps.git
commit 21049ece6e4a0e5d40900414a97c2730d5cc5d33
Author: Maciej Wójcik <w8...@gmail.com>
AuthorDate: Thu Jul 23 15:19:35 2020 +0200
Rewritten READMEs to Markdown
---
README.md | 332 ++--
examples/README.md | 3356 ++++++++++++++++----------------
examples/bastest/README.md | 1056 ++++++----
examples/camera/README.md | 67 +-
examples/camera/camera_main.c | 4 +-
examples/flash_test/README.md | 25 +-
examples/flowc/README.md | 22 +-
examples/json/README.md | 311 +--
examples/pdcurses/README.md | 26 +-
examples/tcpblaster/README.md | 61 +-
examples/telnetd/README.md | 9 +-
fsutils/inifile/README.md | 59 +-
gpsutils/README.md | 16 +-
gpsutils/minmea/README.md | 45 +-
graphics/lvgl/README.md | 26 +-
graphics/nxwidgets/Doxygen/README.md | 76 +-
graphics/nxwidgets/README.md | 70 +-
graphics/nxwidgets/UnitTests/README.md | 358 ++--
graphics/nxwm/Doxygen/README.md | 76 +-
graphics/nxwm/README.md | 47 +-
graphics/pdcurs34/README.md | 53 +-
graphics/pdcurs34/pdcurses/README.md | 24 +-
graphics/tiff/README.md | 19 +-
graphics/twm4nx/README.md | 763 ++++----
industry/abnt_codi/README.md | 86 +-
interpreters/README.md | 33 +-
interpreters/bas/README.md | 122 +-
interpreters/ficl/README.md | 51 +-
modbus/README.md | 218 +--
netutils/README.md | 258 +--
netutils/discover/README.md | 13 +-
netutils/ftpc/README.md | 162 +-
netutils/telnetd/README.md | 3 +-
nshlib/README.md | 3130 ++++++++++++++---------------
system/cdcacm/README.md | 78 +-
system/cfgdata/README.md | 31 +-
system/composite/README.md | 105 +-
system/flash_eraseall/README.md | 21 +-
system/i2c/README.md | 574 +++---
system/nsh/README.md | 71 +-
system/nxplayer/README.md | 25 +-
system/psmq/README.md | 78 +-
system/spi/README.md | 360 ++--
system/termcurses/README.md | 67 +-
system/usbmsc/README.md | 167 +-
system/zmodem/README.md | 469 ++---
testing/README.md | 336 ++--
testing/cxxtest/README.md | 41 +-
testing/fstest/README.md | 33 +-
testing/nxffs/README.md | 11 +-
testing/smart/README.md | 44 +-
testing/smart_test/README.md | 26 +-
tools/README.md | 52 +-
wireless/bluetooth/btsak/README.md | 244 ++-
wireless/ieee802154/i8sak/README.md | 150 +-
wireless/wapi/README.md | 23 +-
56 files changed, 7147 insertions(+), 6836 deletions(-)
diff --git a/README.md b/README.md
index 3af3771..a9c33ce 100644
--- a/README.md
+++ b/README.md
@@ -1,223 +1,239 @@
-Application Folder
-==================
-
-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
--------
-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
-------------------
+# Application Folder
+
+## 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
+
+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
+
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>
-
-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
+ 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
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:
+
+```conf
+CONFIG_NSH_BUILTIN_APPS=y
+```
- 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
-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:
+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.
-
- 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:
-
- 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.
-
- 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.
-
- 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:
-
- 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.
+ 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.
+
+ 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:
+
+ ```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
+ `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.
+
+ 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:
+
+ a) Copy `MyBoard` directory to `boards/MyBoard`.
+ b) Add a symbolic link to `MyApplication` at `apps/external`.
+ c) Configure NuttX, usually by:
+
+ ```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.
diff --git a/examples/README.md b/examples/README.md
index fa6ba3e..f1fb179 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,2113 +1,2061 @@
-examples
-^^^^^^^^
+# Examples
- Selecting examples:
+### Selecting Examples
- The examples directory contains several sample applications that
- can be linked with NuttX. The specific example is selected in the
- boards/<arch-name>/<chip-name>/<board-name>/configs/<config>/defconfig
- file via the CONFIG_EXAMPLES_xyz setting where xyz is the name of the
- example. For example,
+The examples directory contains several sample applications that can be linked
+with NuttX. The specific example is selected in the
+`boards/<arch-name>/<chip-name>/<board-name>/configs/<config>/defconfig` file
+via the `CONFIG_EXAMPLES_xyz` setting where `xyz` is the name of the example.
+For example:
- CONFIG_EXAMPLES_HELLO=y
+```conf
+CONFIG_EXAMPLES_HELLO=y
+```
- Selects the examples/hello "Hello, World!" example.
+Selects the `examples/hello` _Hello, World!_ example.
- Built-In functions
+### Built-In Functions
- Some of the examples may be built as "built-in" functions that
- can be executed at run time (rather than as NuttX "main" programs).
- These "built-in" examples can be also be executed from the NuttShell
- (NSH) command line. In order to configure these built-in NSH
- functions, you have to set up the following:
+Some of the examples may be built as _built-in_ functions that can be executed
+at run time (rather than as NuttX _main_ programs). These _built-in_ examples
+can be also be executed from the NuttShell (NSH) command line. In order to
+configure these built-in NSH functions, you have to set up the following:
- - CONFIG_NSH_BUILTIN_APPS - Enable support for external registered,
- "named" applications that can be executed from the NSH
- command line (see apps/README.txt for more information).
+- `CONFIG_NSH_BUILTIN_APPS` – Enable support for external registered, _named_
+ applications that can be executed from the NSH command line (see
+ `apps/README.md` for more information).
-examples/adc
-^^^^^^^^^^^^
+## `adc` Read from ADC
- A mindlessly simple test of an ADC devices. It simply reads from the
- ADC device and dumps the data to the console forever.
+A mindlessly simple test of an ADC devices. It simply reads from the ADC device
+and dumps the data to the console forever.
- This test depends on these specific ADC/NSH configurations settings (your
- specific ADC settings might require additional settings).
+This test depends on these specific ADC/NSH configurations settings (your
+specific ADC settings might require additional settings).
- CONFIG_ADC - Enabled ADC support
- CONFIG_NSH_BUILTIN_APPS - Build the ADC test as an NSH built-in function.
- Default: Built as a standalone program
+- `CONFIG_ADC` – Enabled ADC support.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the ADC test as an NSH built-in function.
+ Default: Built as a standalone program.
- Specific configuration options for this example include:
+Specific configuration options for this example include:
- CONFIG_EXAMPLES_ADC_DEVPATH - The default path to the ADC device. Default: /dev/adc0
- CONFIG_EXAMPLES_ADC_NSAMPLES - This number of samples is
- collected and the program terminates. Default: Samples are collected
- indefinitely.
- CONFIG_EXAMPLES_ADC_GROUPSIZE - The number of samples to read at once.
- Default: 4
-
-examples/ajoystick
-^^^^^^^^^^^^^^^^^^
-
- This is a simple test of the analog joystick driver. See details about
- this driver in nuttx/include/nuttx/input/ajoystick.h.
+- `CONFIG_EXAMPLES_ADC_DEVPATH` – The default path to the ADC device. Default:
+ `/dev/adc0`.
+- `CONFIG_EXAMPLES_ADC_NSAMPLES` – This number of samples is collected and the
+ program terminates. Default: Samples are collected indefinitely.
+- `CONFIG_EXAMPLES_ADC_GROUPSIZE` – The number of samples to read at once.
+ Default: `4`.
- Configuration Pre-requisites:
+## `ajoystick` Analog Joystick
- CONFIG_AJOYSTICK - The analog joystick driver
+This is a simple test of the analog joystick driver. See details about this
+driver in `nuttx/include/nuttx/input/ajoystick.h`.
- Example Configuration:
- CONFIG_EXAMPLES_AJOYSTICK - Enabled the analog joystick example
- CONFIG_EXAMPLES_AJOYSTICK_DEVNAME - Joystick device name. Default
- "/dev/adjoy0"
- CONFIG_EXAMPLES_AJOYSTICK_SIGNO - Signal used to signal the test
- application. Default 13.
+Configuration Pre-requisites:
-examples/alarm
-^^^^^^^^^^^^^^
- A simple example that tests the alarm IOCTLs of the RTC driver.
-
- Dependencies:
-
- CONFIG_RTC_DRIVER - RTC driver must be initialized to allow user space
- access to the RTC.
- CONFIG_RTC_ALARM - Support for RTC alarms must be enabled.
-
- Configuration:
+- `CONFIG_AJOYSTICK` – The analog joystick driver.
- CONFIG_EXAMPLES_ALARM - Enable the RTC driver alarm test
- CONFIG_EXAMPLES_ALARM_PROGNAME - this isthe name of the
- program that will be used when the NSH ELF program is
- installed.
- CONFIG_EXAMPLES_ALARM_PRIORITY - Alarm daemon priority
- CONFIG_EXAMPLES_ALARM_STACKSIZE - Alarm daemon stack size
- CONFIG_EXAMPLES_ALARM_DEVPATH - RTC device path (/dev/rtc0)
- ONFIG_EXAMPLES_ALARM_SIGNO - Alarm signal
+Example Configuration:
+- `CONFIG_EXAMPLES_AJOYSTICK` – Enabled the analog joystick example.
+- `CONFIG_EXAMPLES_AJOYSTICK_DEVNAME` – Joystick device name. Default
+ `/dev/adjoy0`.
+- `CONFIG_EXAMPLES_AJOYSTICK_SIGNO` – Signal used to signal the test
+ application. Default `13`.
-examples/apa102
-^^^^^^^^^^^^^^^
+## `alarm` RTC Alarm
- Rainbow example for APA102 LED Strip.
+A simple example that tests the alarm IOCTLs of the RTC driver.
-examples/bastest
-^^^^^^^^^^^^^^^^
- This directory contains a small program that will mount a ROMFS file system
- containing the BASIC test files extracted from the BAS 2.4 release. See
- examples/bastest/README.txt for licensing and usage information.
+Dependencies:
- CONFIG_EXAMPLES_BASTEST_DEVMINOR - The minor device number of the ROMFS block
- driver. For example, the N in /dev/ramN. Used for registering the RAM
- block driver that will hold the ROMFS file system containing the BASIC
- files to be tested. Default: 0
+- `CONFIG_RTC_DRIVER` – RTC driver must be initialized to allow user space
+ access to the RTC.
+- `CONFIG_RTC_ALARM` – Support for RTC alarms must be enabled.
- CONFIG_EXAMPLES_BASTEST_DEVPATH - The path to the ROMFS block driver device. This
- must match EXAMPLES_BASTEST_DEVMINOR. Used for registering the RAM block driver
- that will hold the ROMFS file system containing the BASIC files to be
- tested. Default: "/dev/ram0"
+Configuration:
-examples/bridge
-^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_ALARM` – Enable the RTC driver alarm test.
+- `CONFIG_EXAMPLES_ALARM_PROGNAME` – This is the name of the program that will
+ be used when the NSH ELF program is installed.
+- `CONFIG_EXAMPLES_ALARM_PRIORITY` – Alarm daemon priority.
+- `CONFIG_EXAMPLES_ALARM_STACKSIZE` – Alarm daemon stack size.
+- `CONFIG_EXAMPLES_ALARM_DEVPATH` – RTC device path (`/dev/rtc0`).
+- `CONFIG_EXAMPLES_ALARM_SIGNO` – Alarm signal.
- A simple test of a system with multiple networks. It simply echoes all UDP
- packets received on network 1 and network 2 to network 2 and network 1,
- respectively. Interface 1 and interface may or may not lie on the same
- network.
-
- CONFIG_EXAMPLES_BRIDGE - Enables the simple UDP bridge test
-
- There identical configurations for each of the two networks, NETn where n
- refers to the network being configured n={1,2}. Let 'm' refer to the
- other network.
+## `apa102` Rainbow on `APA102` LED Strip
- CONFIG_EXAMPLES_BRIDGE_NETn_IFNAME - The register name of the network n
- device. Must match the previously registered driver name and must
- not be the same as other network device name,
- CONFIG_EXAMPLES_BRIDGE_NETm_IFNAME
- CONFIG_EXAMPLES_BRIDGE_NETn_RECVPORT - Network n listen port number
- CONFIG_EXAMPLES_BRIDGE_NETn_SNDPORT - Network 2 send port number
- CONFIG_EXAMPLES_BRIDGE_NETn_IOBUFIZE - Size of the network n UDP
- send/receive I/O buffer
- CONFIG_EXAMPLES_BRIDGE_NETn_STACKSIZE - Network n daemon stacksize
- CONFIG_EXAMPLES_BRIDGE_NETn_PRIORITY - Network n daemon task priority
+Rainbow example for `APA102` LED Strip.
- If used as a NSH add-on, then it is assumed that initialization of both
- networks was performed externally prior to the time that this test was
- started. Otherwise, the following options are available:
+## `bastest` Bas BASIC Interpreter
- CONFIG_EXAMPLES_BRIDGE_NETn_NOMAC - Select of the network n hardware
- does not have a built-in MAC address. If selected, the MAC address
- provided by CONFIG_EXAMPLES_BRIDGE_NETn_MACADDR will be used to assign
- the MAC address to the network n device.
- CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC - Use DHCP Client to get the network n
- IP address.
- CONFIG_EXAMPLES_BRIDGE_NETn_IPADDR -- If CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC
- is not selected, then this is the fixed IP address for network n.
- CONFIG_EXAMPLES_BRIDGE_NETn_DRIPADDR - Netweork n default router IP
- address (Gateway)
- CONFIG_EXAMPLES_BRIDGE_NETn_NETMASK - Network n mask.
+This directory contains a small program that will mount a ROMFS file system
+containing the BASIC test files extracted from the Bas `2.4` release. See
+`examples/bastest/README.md` for licensing and usage information.
-examples/buttons
-^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_BASTEST_DEVMINOR` – The minor device number of the ROMFS
+ block driver. For example, the `N` in `/dev/ramN`. Used for registering the
+ RAM block driver that will hold the ROMFS file system containing the BASIC
+ files to be tested. Default: `0`.
- To be provided
+- `CONFIG_EXAMPLES_BASTEST_DEVPATH` – The path to the ROMFS block driver device.
+ This must match `EXAMPLES_BASTEST_DEVMINOR`. Used for registering the RAM
+ block driver that will hold the ROMFS file system containing the BASIC files
+ to be tested. Default: `/dev/ram0`.
-examples/can
-^^^^^^^^^^^^
+## `bridge` Network Bridge
- If the CAN device is configured in loopback mode, then this example can
- be used to test the CAN device in loop back mode. It simple sinces a
- sequence of CAN messages and verifies that those messages are returned
- exactly as sent.
+A simple test of a system with multiple networks. It simply echoes all UDP
+packets received on network `1` and network `2` to network `2` and network `1`,
+respectively. Interface `1` and interface may or may not lie on the same
+network.
- This test depends on these specific CAN/NSH configurations settings (your
- specific CAN settings might require additional settings).
+- `CONFIG_EXAMPLES_BRIDGE` – Enables the simple UDP bridge test.
- CONFIG_CAN - Enables CAN support.
- CONFIG_CAN_LOOPBACK - A CAN driver may or may not support a loopback
- mode for testing. The STM32 CAN driver does support loopback mode.
- CONFIG_NSH_BUILTIN_APPS - Build the CAN test as an NSH built-in function.
- Default: Built as a standalone program
+There identical configurations for each of the two networks, `NETn` where `n`
+refers to the network being configured `n={1,2}`. Let `m` refer to the other
+network.
- Specific configuration options for this example include:
+- `CONFIG_EXAMPLES_BRIDGE_NETn_IFNAME` – The register name of the network `n`
+ device. Must match the previously registered driver name and must not be the
+ same as other network device name, `CONFIG_EXAMPLES_BRIDGE_NETm_IFNAME`.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_RECVPORT` – Network `n` listen port number.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_SNDPORT` – Network `2` send port number.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_IOBUFIZE` – Size of the network `n` UDP
+ send/receive I/O buffer.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_STACKSIZE` – Network `n` daemon stacksize.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_PRIORITY` – Network `n` daemon task priority.
- CONFIG_EXAMPLES_CAN_DEVPATH - The path to the CAN device. Default: /dev/can0
- CONFIG_EXAMPLES_CAN_NMSGS - This number of CAN message is collected
- and the program terminates. Default: messages are sent and received
- indefinitely.
+If used as a NSH add-on, then it is assumed that initialization of both networks
+was performed externally prior to the time that this test was started.
+Otherwise, the following options are available:
- The default behavior assumes loopback mode. Messages are sent, then read
- and verified. The behavior can be altered for other kinds of testing where
- the test only sends or received (but does not verify) can messages.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_NOMAC` – Select of the network `n` hardware does
+ not have a built-in MAC address. If selected, the MAC address. provided by
+ `CONFIG_EXAMPLES_BRIDGE_NETn_MACADDR` will be used to assign the MAC address
+ to the network n device.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC` – Use DHCP Client to get the network n IP
+ address.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_IPADDR` – If `CONFIG_EXAMPLES_BRIDGE_NETn_DHCPC`
+ is not selected, then this is the fixed IP address for network `n`.
+- `CONFIG_EXAMPLES_BRIDGE_NETn_DRIPADDR` – Network `n` default router IP address
+ (Gateway).
+- `CONFIG_EXAMPLES_BRIDGE_NETn_NETMASK` – Network `n` mask.
- CONFIG_EXAMPLES_CAN_READONLY - Only receive messages
- CONFIG_EXAMPLES_CAN_WRITEONLY - Only send messages
+## `buttons` Read GPIO Buttons
-examples/canard
-^^^^^^^^^^^^^^^
+To be provided.
- Example application for canutils/libcarnard.
+## `can` CAN Device Test
-examples/cctype
-^^^^^^^^^^^^^^^
+If the CAN device is configured in loopback mode, then this example can be used
+to test the CAN device in loop back mode. It simple sinces a sequence of CAN
+messages and verifies that those messages are returned exactly as sent.
- Verifies all possible inputs for all functions defined in the header file
- cctype.
+This test depends on these specific CAN/NSH configurations settings (your
+specific CAN settings might require additional settings).
-examples/chat
-^^^^^^^^^^^^^
+- `CONFIG_CAN` – Enables CAN support.
+- `CONFIG_CAN_LOOPBACK` – A CAN driver may or may not support a loopback mode
+ for testing. The STM32 CAN driver does support loopback mode.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the CAN test as an NSH built-in function.
+ Default: Built as a standalone program.
- Demonstrates AT chat functionality over a TTY device. This is useful with AT
- modems, for example, to establish a pppd connection (see the related pppd
- example). Moreover, some AT modems - such as ones made by u-blox - have an
- internal TCP/IP stack, often with an implementation of TLS/SSL. In such cases
- the chat utility can be used to configure the internal TCP/IP stack, establish
- socket connections, set up security (e.g., download base64-encoded
- certificates to the modem), and perform data exchange through sockets over the
- TTY device.
+Specific configuration options for this example include:
- Useful configuration parameters:
- CONFIG_EXAMPLES_CHAT_PRESET[0..3] - preset chat scripts
- CONFIG_EXAMPLES_CHAT_TTY_DEVNODE - TTY device node name
- CONFIG_EXAMPLES_CHAT_TIMEOUT_SECONDS - default receive timeout
+- `CONFIG_EXAMPLES_CAN_DEVPATH` – The path to the CAN device. Default:
+ `/dev/can0`.
+- `CONFIG_EXAMPLES_CAN_NMSGS` – This number of CAN message is collected and the
+ program terminates. Default: messages are sent and received indefinitely.
-examples/configdata
-^^^^^^^^^^^^^^^^^^^
+The default behavior assumes loopback mode. Messages are sent, then read and
+verified. The behavior can be altered for other kinds of testing where the test
+only sends or received (but does not verify) can messages.
- This is a Unit Test for the MTD configuration data driver
+- `CONFIG_EXAMPLES_CAN_READONLY` – Only receive messages.
+- `CONFIG_EXAMPLES_CAN_WRITEONLY` – Only send messages.
-examples/cpuhog
-^^^^^^^^^^^^^^^
+## `canard`
- Attempts to keep the system busy by passing data through a pipe in loop
- back mode. This may be useful if you are trying run down other problems
- that you think might only occur when the system is very busy.
+Example application for `canutils/libcarnard`.
-examples/dac
-^^^^^^^^^^^^
+## `cctype`
- This is a tool for writing values to DAC device.
+Verifies all possible inputs for all functions defined in the header file
+`cctype`.
-examples/dhcpd
-^^^^^^^^^^^^^^
+## `chat` AT over TTY
- This examples builds a tiny DHCP server for the target system.
+Demonstrates AT chat functionality over a TTY device. This is useful with AT
+modems, for example, to establish a `pppd` connection (see the related `pppd`
+example). Moreover, some AT modems – such as ones made by u-blox – have an
+internal TCP/IP stack, often with an implementation of TLS/SSL. In such cases
+the chat utility can be used to configure the internal TCP/IP stack, establish
+socket connections, set up security (e.g., download base64-encoded certificates
+to the modem), and perform data exchange through sockets over the TTY device.
- NOTE: For test purposes, this example can be built as a
- host-based DHCPD server. This can be built as follows:
+Useful configuration parameters:
- cd examples/dhcpd
- make -f Makefile.host TOPDIR=<nuttx-directory>
+- `CONFIG_EXAMPLES_CHAT_PRESET[0..3]` – preset chat scripts.
+- `CONFIG_EXAMPLES_CHAT_TTY_DEVNODE` – TTY device node name.
+- `CONFIG_EXAMPLES_CHAT_TIMEOUT_SECONDS` – default receive timeout.
- NuttX configuration settings:
+## `configdata`
- CONFIG_NET=y - Of course
- CONFIG_NET_UDP=y - UDP support is required for DHCP
- (as well as various other UDP-related
- configuration settings)
- CONFIG_NET_BROADCAST=y - UDP broadcast support is needed.
- CONFIG_NETUTILS_NETLIB=y - The networking library is needed
+This is a Unit Test for the MTD configuration data driver.
- CONFIG_EXAMPLES_DHCPD_NOMAC - (May be defined to use software assigned MAC)
+## `cpuhog` Keep CPU Busy
- See also CONFIG_NETUTILS_DHCPD_* settings described elsewhere
- and used in netutils/dhcpd/dhcpd.c. These settings are required
- to described the behavior of the daemon.
+Attempts to keep the system busy by passing data through a pipe in loop back
+mode. This may be useful if you are trying run down other problems that you
+think might only occur when the system is very busy.
-examples/discover
-^^^^^^^^^^^^^^^^^
+## `dac` Write to DAC
- This example exercises netutils/discover utility. This example initializes
- and starts the UDP discover daemon. This daemon is useful for discovering
- devices in local networks, especially with DHCP configured devices. It
- listens for UDP broadcasts which also can include a device class so that
- groups of devices can be discovered. It is also possible to address all
- classes with a kind of broadcast discover.
+This is a tool for writing values to DAC device.
- This example will automatically be built as an NSH built-in if
- CONFIG_NSH_BUILTIN_APPS is selected. Otherwise, it will be a standalone
- program with entry point "discover_main".
+## `dhcpd` DHCP Server
- NuttX configuration settings:
+This examples builds a tiny DHCP server for the target system.
- CONFIG_EXAMPLES_DISCOVER_DHCPC - DHCP Client
- CONFIG_EXAMPLES_DISCOVER_NOMAC - Use canned MAC address
- CONFIG_EXAMPLES_DISCOVER_IPADDR - Target IP address
- CONFIG_EXAMPLES_DISCOVER_DRIPADDR - Router IP address
- CONFIG_EXAMPLES_DISCOVER_NETMASK - Network Mask
+**Note**: For test purposes, this example can be built as a host-based DHCPD
+server. This can be built as follows:
-examples/djoystick
-^^^^^^^^^^^^^^^^^^
+```bash
+cd examples/dhcpd
+make -f Makefile.host TOPDIR=<nuttx-directory>
+```
- This is a simple test of the discrete joystick driver. See details about
- this driver in nuttx/include/nuttx/input/djoystick.h.
+NuttX configuration settings:
- Configuration Pre-requisites:
+- `CONFIG_NET=y` – of course.
+- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various
+ other UDP-related configuration settings).
+- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed.
+- `CONFIG_NETUTILS_NETLIB=y` – The networking library is needed.
+- `CONFIG_EXAMPLES_DHCPD_NOMAC` – (May be defined to use software assigned MAC)
- CONFIG_DJOYSTICK - The discrete joystick driver
+See also `CONFIG_NETUTILS_DHCPD_*` settings described elsewhere and used in
+`netutils/dhcpd/dhcpd.c`. These settings are required to described the behavior
+of the daemon.
- Example Configuration:
- CONFIG_EXAMPLES_DJOYSTICK - Enabled the discrete joystick example
- CONFIG_EXAMPLES_DJOYSTICK_DEVNAME - Joystick device name. Default
- "/dev/djoy0"
- CONFIG_EXAMPLES_DJOYSTICK_SIGNO - Signal used to signal the test
- application. Default 13.
+## `discover` UDP Discover Daemon
+This example exercises `netutils/discover` utility. This example initializes and
+starts the UDP discover daemon. This daemon is useful for discovering devices in
+local networks, especially with DHCP configured devices. It listens for UDP
+broadcasts which also can include a device class so that groups of devices can
+be discovered. It is also possible to address all classes with a kind of
+broadcast discover.
-examples/dsptest
-^^^^^^^^^^^^^^^^^^
+This example will automatically be built as an NSH built-in if
+`CONFIG_NSH_BUILTIN_APPS` is selected. Otherwise, it will be a standalone
+program with entry point `discover_main`.
- This is a Unit Test for the Nuttx DSP library. It use Unity testing framework.
+NuttX configuration settings:
- Dependencies:
+- `CONFIG_EXAMPLES_DISCOVER_DHCPC` – DHCP Client.
+- `CONFIG_EXAMPLES_DISCOVER_NOMAC` – Use canned MAC address.
+- `CONFIG_EXAMPLES_DISCOVER_IPADDR` – Target IP address.
+- `CONFIG_EXAMPLES_DISCOVER_DRIPADDR` – Router IP address.
+- `CONFIG_EXAMPLES_DISCOVER_NETMASK` – Network Mask.
- CONFIG_LIBDSP=y
- CONFIG_LIBDSP_DEBUG=y
- CONFIG_TESTING_UNITY=y
+## `djoystick` Discrete Joystick
- Optional configuration:
+This is a simple test of the discrete joystick driver. See details about this
+driver in `nuttx/include/nuttx/input/djoystick.h`.
- CONFIG_TESTING_UNITY_OUTPUT_COLOR - enable colored output
+Configuration Pre-requisites:
-examples/elf
-^^^^^^^^^^^^
+- `CONFIG_DJOYSTICK` – The discrete joystick driver.
- This example builds a small ELF loader test case. This includes several
- test programs under examples/elf tests. These tests are build using
- the relocatable ELF format and installed in a ROMFS file system. At run time,
- each program in the ROMFS file system is executed. Requires CONFIG_ELF.
- Other configuration options:
+Example Configuration:
- CONFIG_EXAMPLES_ELF_DEVMINOR - The minor device number of the ROMFS block
- driver. For example, the N in /dev/ramN. Used for registering the RAM
- block driver that will hold the ROMFS file system containing the ELF
- executables to be tested. Default: 0
+- `CONFIG_EXAMPLES_DJOYSTICK` – Enabled the discrete joystick example.
+- `CONFIG_EXAMPLES_DJOYSTICK_DEVNAME` – Joystick device name. Default
+ `/dev/djoy0`.
+- `CONFIG_EXAMPLES_DJOYSTICK_SIGNO` – Signal used to signal the test
+ application. Default `13`.
- CONFIG_EXAMPLES_ELF_DEVPATH - The path to the ROMFS block driver device. This
- must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver
- that will hold the ROMFS file system containing the ELF executables to be
- tested. Default: "/dev/ram0"
- NOTES:
+## `dsptest` DSP
- 1. CFLAGS should be provided in CELFFLAGS. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be:
+This is a Unit Test for the Nuttx DSP library. It use Unity testing framework.
- CELFFLAGS = $(CFLAGS) -mlong-calls
+Dependencies:
- Similarly for C++ flags which must be provided in CXXELFFLAGS.
+```conf
+CONFIG_LIBDSP=y
+CONFIG_LIBDSP_DEBUG=y
+CONFIG_TESTING_UNITY=y
+```
- 2. Your top-level nuttx/Make.defs file must also include an appropriate definition,
- LDELFFLAGS, to generate a relocatable ELF object. With GNU LD, this should
- include '-r' and '-e main' (or _main on some platforms).
+Optional configuration:
- LDELFFLAGS = -r -e main
+- `CONFIG_TESTING_UNITY_OUTPUT_COLOR` – enable colored output.
- If you use GCC to link, you make also need to include '-nostdlib' or
- '-nostartfiles' and '-nodefaultlibs'.
+## `elf` ELF loader
- 3. This example also requires genromfs. genromfs can be build as part of the
- nuttx toolchain. Or can built from the genromfs sources that can be found
- in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the
- PATH variable must include the path to the genromfs executable.
+This example builds a small ELF loader test case. This includes several test
+programs under `examples/elf` tests. These tests are build using the relocatable
+ELF format and installed in a ROMFS file system. At run time, each program in
+the ROMFS file system is executed. Requires `CONFIG_ELF`. Other configuration
+options:
- 4. ELF size: The ELF files in this example are, be default, quite large
- because they include a lot of "build garbage". You can greatly reduce the
- size of the ELF binaries are using the 'objcopy --strip-unneeded' command to
- remove un-necessary information from the ELF files.
+- `CONFIG_EXAMPLES_ELF_DEVMINOR` – The minor device number of the ROMFS block
+ driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM
+ block driver that will hold the ROMFS file system containing the ELF
+ executables to be tested. Default: `0`.
- 5. Simulator. You cannot use this example with the NuttX simulator on
- Cygwin. That is because the Cygwin GCC does not generate ELF file but
- rather some Windows-native binary format.
+- `CONFIG_EXAMPLES_ELF_DEVPATH` – The path to the ROMFS block driver device.
+ This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block
+ driver that will hold the ROMFS file system containing the ELF executables to
+ be tested. Default: `/dev/ram0`.
- If you really want to do this, you can create a NuttX x86 buildroot toolchain
- and use that be build the ELF executables for the ROMFS file system.
+**Notes**:
- 6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at nuttx/binfmt/libelf/gnu-elf.ld.
- That example might have to be tuned for your particular linker output to
- position additional sections correctly. The GNU LD LDELFFLAGS then might
- be:
+1. `CFLAGS` should be provided in `CELFFLAGS`. RAM and FLASH memory regions may
+ require long allcs. For ARM, this might be:
- LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld
+ ```makefile
+ CELFFLAGS = $(CFLAGS) -mlong-calls
+ ```
-examples/fb
-^^^^^^^^^^^
+ Similarly for C++ flags which must be provided in `CXXELFFLAGS`.
- A simple test of the framebuffer character driver.
+2. Your top-level `nuttx/Make.defs` file must also include an appropriate
+ definition, `LDELFFLAGS`, to generate a relocatable ELF object. With GNU LD,
+ this should include `-r` and `-e main` (or `_main` on some platforms).
-examples/flash_test
-^^^^^^^^^^^^^^^^^^^
+ ```makefile
+ LDELFFLAGS = -r -e main
+ ```
- This example performs a SMART flash block device test. This test performs
- a sector allocate, read, write, free and garbage collection test on a SMART
- MTD block device.
+ If you use GCC to link, you make also need to include `-nostdlib` or
+ `-nostartfiles` and `-nodefaultlibs`.
- * CONFIG_EXAMPLES_FLASH_TEST=y - Enables the FLASH Test
+3. This example also requires `genromfs`. `genromfs` can be build as part of the
+ nuttx toolchain. Or can built from the `genromfs` sources that can be found
+ in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the
+ `PATH` variable must include the path to the genromfs executable.
- Dependencies:
+4. ELF size: The ELF files in this example are, be default, quite large because
+ they include a lot of _build garbage_. You can greatly reduce the size of the
+ ELF binaries are using the `objcopy --strip-unneeded` command to remove
+ un-necessary information from the ELF files.
- * CONFIG_MTD_SMART=y - SMART block driver support
- * CONFIG_BUILD_PROTECTED=n and CONFIG_BUILD_KERNEL=n - This test uses
- internal OS interfaces and so is not available in the NUTTX kernel
- builds
+5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+ That is because the Cygwin GCC does not generate ELF file but rather some
+ Windows-native binary format.
-examples/flowc
-^^^^^^^^^^^^^^
+ If you really want to do this, you can create a NuttX x86 buildroot toolchain
+ and use that be build the ELF executables for the ROMFS file system.
- A simple test of serial hardware flow control.
+6. Linker scripts. You might also want to use a linker scripts to combine
+ sections better. An example linker script is at
+ `nuttx/binfmt/libelf/gnu-elf.ld`. That example might have to be tuned for
+ your particular linker output to position additional sections correctly. The
+ GNU LD `LDELFFLAGS` then might be:
-examples/ft80x
-^^^^^^^^^^^^^^
+ ```makefile
+ LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld
+ ```
- This examples has ports of several FTDI demos for the FTDI/BridgeTek FT80x
- GUI chip. As an example configuration, see
- nuttx/boards/arm/stm32/viewtool-stm32f107/configs/ft80x/defconfig.
+## `fb` Framebuffer
-examples/ftpc
-^^^^^^^^^^^^^
+A simple test of the framebuffer character driver.
- This is a simple FTP client shell used to exercise the capabilities
- of the FTPC library (apps/netutils/ftpc).
+## `flash_test` SMART Flash
- From NSH, the startup command sequence is as follows. This is only
- an example, your configuration could have different mass storage devices,
- mount paths, and FTP directories:
+This example performs a SMART flash block device test. This test performs a
+sector allocate, read, write, free and garbage collection test on a SMART MTD
+block device.
- nsh> mount -t vfat /dev/mmcsd0 /tmp # Mount the SD card at /tmp
- nsh> cd /tmp # cd into the /tmp directory
- nsh> ftpc xx.xx.xx.xx[:pp] # Start the FTP client
- nfc> login <name> <password> # Log into the FTP server
- nfc> help # See a list of FTP commands
+- `CONFIG_EXAMPLES_FLASH_TEST=y` – Enables the FLASH Test.
- where xx.xx.xx.xx is the IP address of the FTP server and pp is an
- optional port number.
+Dependencies:
- NOTE: By default, FTPC uses readline to get data from stdin. So your
- defconfig file must have the following build path:
+- `CONFIG_MTD_SMART=y` – SMART block driver support.
+- `CONFIG_BUILD_PROTECTED=n` and `CONFIG_BUILD_KERNEL=n` – This test uses
+ internal OS interfaces and so is not available in the NUTTX kernel builds.
- CONFIG_SYSTEM_READLINE=y
+## `flowc` Serial Hardware Flow Control
- NOTE: If you use the ftpc task over a telnet NSH connection, then you
- should set the following configuration item:
+A simple test of serial hardware flow control.
- CONFIG_EXAMPLES_FTPC_FGETS=y
+## `ft80x` FT80x GUI Chip
- By default, the FTPC client will use readline() to get characters from
- the console. Readline includes and command-line editor and echos
- characters received in stdin back through stdout. Neither of these
- behaviors are desire-able if Telnet is used.
+This examples has ports of several FTDI demos for the FTDI/BridgeTek FT80x GUI
+chip. As an example configuration, see
+`nuttx/boards/arm/stm32/viewtool-stm32f107/configs/ft80x/defconfig`.
- You may also want to define the following in your configuration file.
- Otherwise, you will have not feedback about what is going on:
+## `ftpc` FTP Client
- CONFIG_DEBUG_FEATURES=y
- CONFIG_DEBUG_INFO=y
- CONFIG_DEBUG_FTPC=y
+This is a simple FTP client shell used to exercise the capabilities of the FTPC
+library (`apps/netutils/ftpc`).
-examples/ftpd
-^^^^^^^^^^^^^^
+From NSH, the startup command sequence is as follows. This is only an example,
+your configuration could have different mass storage devices, mount paths, and
+FTP directories:
- This example exercises the FTPD daemon at apps/netuils/ftpd. Below are
- configurations specific to the FTPD example (the FTPD daemon itself may
- require other configuration options as well).
+```
+nsh> mount -t vfat /dev/mmcsd0 /tmp # Mount the SD card at /tmp
+nsh> cd /tmp # cd into the /tmp directory
+nsh> ftpc xx.xx.xx.xx[:pp] # Start the FTP client
+nfc> login <name> <password> # Log into the FTP server
+nfc> help # See a list of FTP commands
+```
- CONFIG_EXAMPLES_FTPD - Enable the FTPD example.
- CONFIG_EXAMPLES_FTPD_PRIO - Priority of the FTP daemon.
- Default: SCHED_PRIORITY_DEFAULT
- CONFIG_EXAMPLES_FTPD_STACKSIZE - Stack size allocated for the
- FTP daemon. Default: 2048
- CONFIG_EXAMPLES_FTPD_NONETINIT - Define to suppress configuration of the
- network by apps/examples/ftpd. You would need to suppress network
- configuration if the network is configuration prior to running the
- example.
+where `xx.xx.xx.xx` is the IP address of the FTP server and `pp` is an optional
+port number.
- NSH always initializes the network so if CONFIG_NSH_NETINIT is
- defined, so is CONFIG_EXAMPLES_FTPD_NONETINIT (se it does not explicitly
- need to be defined in that case):
+**Note**: By default, FTPC uses `readline` to get data from `stdin`. So your
+defconfig file must have the following build path:
- CONFIG_NSH_BUILTIN_APPS - Build the FTPD daemon example test as an
- NSH built-in function. By default the FTPD daemon will be built
- as a standalone application.
+```conf
+CONFIG_SYSTEM_READLINE=y
+```
- If CONFIG_EXAMPLES_FTPD_NONETINIT is not defined, then the following may
- be specified to customized the network configuration:
+**Note**: If you use the ftpc task over a telnet NSH connection, then you should
+set the following configuration item:
- CONFIG_EXAMPLES_FTPD_NOMAC - If the hardware has no MAC address of its
- own, define this =y to provide a bogus address for testing.
- CONFIG_EXAMPLES_FTPD_IPADDR - The target IP address. Default 10.0.0.2
- CONFIG_EXAMPLES_FTPD_DRIPADDR - The default router address. Default
- 10.0.0.1
- CONFIG_EXAMPLES_FTPD_NETMASK - The network mask. Default: 255.255.255.0
+```conf
+CONFIG_EXAMPLES_FTPC_FGETS=y
+```
- Other required configuration settings: Of course TCP networking support
- is required. But here are a couple that are less obvious:
+By default, the FTPC client will use `readline()` to get characters from the
+console. Readline includes and command-line editor and echos characters received
+in stdin back through `stdout`. Neither of these behaviors are desire-able if
+Telnet is used.
- CONFIG_DISABLE_PTHREAD - pthread support is required
+You may also want to define the following in your configuration file. Otherwise,
+you will have not feedback about what is going on:
- Other FTPD configuration options they may be of interest:
+```conf
+CONFIG_DEBUG_FEATURES=y
+CONFIG_DEBUG_INFO=y
+CONFIG_DEBUG_FTPC=y
+```
- CONFIG_FTPD_VENDORID - The vendor name to use in FTP communications.
- Default: "NuttX"
- CONFIG_FTPD_SERVERID - The server name to use in FTP communications.
- Default: "NuttX FTP Server"
- CONFIG_FTPD_CMDBUFFERSIZE - The maximum size of one command. Default:
- 512 bytes.
- CONFIG_FTPD_DATABUFFERSIZE - The size of the I/O buffer for data
- transfers. Default: 2048 bytes.
- CONFIG_FTPD_WORKERSTACKSIZE - The stacksize to allocate for each
- FTP daemon worker thread. Default: 2048 bytes.
+## `ftpd` FTP daemon
- The following netutils libraries should be enabled in your defconfig
- file:
+This example exercises the FTPD daemon at `apps/netuils/ftpd`. Below are
+configurations specific to the FTPD example (the FTPD daemon itself may require
+other configuration options as well).
- CONFIG_NETUTILS_NETLIB=y
- CONFIG_NETUTILS_TELNED=y
+- `CONFIG_EXAMPLES_FTPD` – Enable the FTPD example.
+- `CONFIG_EXAMPLES_FTPD_PRIO` – Priority of the FTP daemon. Default:
+ `SCHED_PRIORITY_DEFAULT`.
+- `CONFIG_EXAMPLES_FTPD_STACKSIZE` – Stack size allocated for the FTP daemon.
+ Default: `2048`.
+- `CONFIG_EXAMPLES_FTPD_NONETINIT` – Define to suppress configuration of the
+ network by `apps/examples/ftpd`. You would need to suppress network
+ configuration if the network is configuration prior to running the example.
-examples/gpio
-^^^^^^^^^^^^
+NSH always initializes the network so if `CONFIG_NSH_NETINIT` is defined, so is
+`CONFIG_EXAMPLES_FTPD_NONETINIT` (se it does not explicitly need to be defined
+in that case):
- A simple test/example of the NuttX GPIO driver.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the FTPD daemon example test as an NSH
+ built-in function. By default the FTPD daemon will be built as a standalone
+ application.
-examples/hello
-^^^^^^^^^^^^^^
+If `CONFIG_EXAMPLES_FTPD_NONETINIT` is not defined, then the following may be
+specified to customized the network configuration:
- This is the mandatory, "Hello, World!!" example. It is little more
- than examples/null with a single printf statement. Really useful only
- for bringing up new NuttX architectures.
+- `CONFIG_EXAMPLES_FTPD_NOMAC` – If the hardware has no MAC address of its own,
+ define this `=y` to provide a bogus address for testing.
+- `CONFIG_EXAMPLES_FTPD_IPADDR` – The target IP address. Default `10.0.0.2`.
+- `CONFIG_EXAMPLES_FTPD_DRIPADDR` – The default router address. Default:
+ `10.0.0.1`.
+- `CONFIG_EXAMPLES_FTPD_NETMASK` – The network mask. Default: `255.255.255.0`.
- * CONFIG_NSH_BUILTIN_APPS
- Build the "Hello, World" example as an NSH built-in application.
+Other required configuration settings: Of course TCP networking support is
+required. But here are a couple that are less obvious:
-examples/helloxx
-^^^^^^^^^^^^^^^^
+- `CONFIG_DISABLE_PTHREAD` – `pthread` support is required.
- This is C++ version of the "Hello, World!!" example. It is intended
- only to verify that the C++ compiler is functional, that basic C++
- library suupport is available, and that class are instantiated
- correctly.
-
- NuttX configuration prerequisites:
-
- CONFIG_HAVE_CXX -- Enable C++ Support
-
- Optional NuttX configuration settings:
-
- CONFIG_HAVE_CXXINITIALIZE -- Enable support for static constructors
- (may not be available on all platforms).
-
- NuttX configuration settings specific to this examp;le:
-
- CONFIG_NSH_BUILTIN_APPS -- Build the helloxx example as a
- "built-in" that can be executed from the NSH command line.
-
- Also needed:
-
- CONFIG_HAVE_CXX=y
-
- And you may have to tinker with the following to get libxx to compile
- properly:
-
- CCONFIG_ARCH_SIZET_LONG=y or =n
-
- The argument of the 'new' operators should take a type of size_t. But size_t
- has an unknown underlying. In the nuttx sys/types.h header file, size_t
- is typed as uint32_t (which is determined by architecture-specific logic).
- But the C++ compiler may believe that size_t is of a different type resulting
- in compilation errors in the operator. Using the underlying integer type
- Instead of size_t seems to resolve the compilation issues.
-
-examples/hidkbd
-^^^^^^^^^^^^^^^^
-
- This is a simple test to debug/verify the USB host HID keyboard class
- driver.
-
- CONFIG_EXAMPLES_HIDKBD_DEFPRIO - Priority of "waiter" thread. Default:
- 50
- CONFIG_EXAMPLES_HIDKBD_STACKSIZE - Stacksize of "waiter" thread. Default
- 1024
- CONFIG_EXAMPLES_HIDKBD_DEVNAME - Name of keyboard device to be used.
- Default: "/dev/kbda"
- CONFIG_EXAMPLES_HIDKBD_ENCODED - Decode special key press events in the
- user buffer. In this case, the example coded will use the interfaces
- defined in include/nuttx/input/kbd_codec.h to decode the returned
- keyboard data. These special keys include such things as up/down
- arrows, home and end keys, etc. If this not defined, only 7-bit print-
- able and control ASCII characters will be provided to the user.
- Requires CONFIG_HIDKBD_ENCODED && CONFIG_LIB_KBDCODEC
-
-examples/igmp
-^^^^^^^^^^^^^
-
- This is a trivial test of the NuttX IGMP capability. It present it
- does not do much of value -- Much more is needed in order to verify
- the IGMP features!
-
- * CONFIG_EXAMPLES_IGMP_NOMAC
- Set if the hardware has no MAC address; one will be assigned
- * CONFIG_EXAMPLES_IGMP_IPADDR
- Target board IP address
- * CONFIG_EXAMPLES_IGMP_DRIPADDR
- Default router address
- * CONFIG_EXAMPLES_IGMP_NETMASK
- Network mask
- * CONFIG_EXAMPLES_IGMP_GRPADDR
- Multicast group address
- * CONFIG_EXAMPLES_NETLIB
- The networking library is needed
+Other FTPD configuration options they may be of interest:
-examples/i2cchar
-^^^^^^^^^^^^^^^^
+- `CONFIG_FTPD_VENDORID` – The vendor name to use in FTP communications.
+ Default: `NuttX`.
+- `CONFIG_FTPD_SERVERID` – The server name to use in FTP communications.
+ Default: `NuttX FTP Server`.
+- `CONFIG_FTPD_CMDBUFFERSIZE` – The maximum size of one command. Default: `512`
+ bytes.
+- `CONFIG_FTPD_DATABUFFERSIZE` – The size of the I/O buffer for data transfers.
+ Default: `2048` bytes.
+- `CONFIG_FTPD_WORKERSTACKSIZE` – The stacksize to allocate for each FTP daemon
+ worker thread. Default: `2048` bytes.
- A mindlessly simple test of an I2C driver. It reads an write garbage data to the
- I2C transmitter and/or received as fast possible.
+The following netutils libraries should be enabled in your `defconfig` file:
- This test depends on these specific I2S/AUDIO/NSH configurations settings (your
- specific I2S settings might require additional settings).
+```conf
+CONFIG_NETUTILS_NETLIB=y
+CONFIG_NETUTILS_TELNED=y
+```
- CONFIG_I2S - Enabled I2S support
- CONFIG_AUDIO - Enabled audio support
- CONFIG_DRIVERS_AUDIO - Enable audio device support
- CONFIG_AUDIO_I2SCHAR = Enabled support for the I2S character device
- CONFIG_NSH_BUILTIN_APPS - Build the I2S test as an NSH built-in function.
- Default: Built as a standalone program
-
- Specific configuration options for this example include:
-
- CONFIG_EXAMPLES_I2SCHAR - Enables the I2C test
- CONFIG_EXAMPLES_I2SCHAR_DEVPATH - The default path to the ADC device.
- Default: /dev/i2schar0
- CONFIG_EXAMPLES_I2SCHAR_TX - This should be set if the I2S device supports
- a transmitter.
- CONFIG_EXAMPLES_I2SCHAR_TXBUFFERS - This is the default number of audio
- buffers to send before the TX transfers terminate. When both TX and
- RX transfers terminate, the task exits (and, if an NSH builtin, the
- i2schar command returns). This number can be changed from the NSH
- command line.
- CONFIG_EXAMPLES_I2SCHAR_TXSTACKSIZE - This is the stack size to use when
- starting the transmitter thread. Default 1536.
- CONFIG_EXAMPLES_I2SCHAR_RX - This should be set if the I2S device supports
- a transmitter.
- CONFIG_EXAMPLES_I2SCHAR_RXBUFFERS - This is the default number of audio
- buffers to receive before the RX transfers terminate. When both TX and
- RX transfers terminate, the task exits (and, if an NSH builtin, the
- i2schar command returns). This number can be changed from the NSH
- command line.
- CONFIG_EXAMPLES_I2SCHAR_RXSTACKSIZE - This is the stack size to use when
- starting the receiver thread. Default 1536.
- CONFIG_EXAMPLES_I2SCHAR_BUFSIZE - The size of the data payload in one
- audio buffer. Applies to both TX and RX audio buffers.
- CONFIG_EXAMPLES_I2SCHAR_DEVINIT - Define if architecture-specific I2S
- device initialize is available. If defined, the platform specific
- code must provide a function i2schar_devinit() that will be called
- each time that this test executes. Not available in the kernel build
- mode.
-
-examples/ina219
-^^^^^^^^^^^^^^^
-
- This is a simple infinite loop that polls the INA219 sensor and displays
- the measurements.
-
-examples/ipforward
-^^^^^^^^^^^^^^^^^^
-
- A simple test of IP forwarding using TUN devices. This can be used on any
- platform, but was intended for use on the simulation platform because it
- performs a test of IP forwarding without the use of hardware.
-
-examples/json
-^^^^^^^^^^^^^
-
- This example exercises the cJSON implementation at apps/netutils/json.
- This example contains logic taken from the cJSON project:
-
- http://sourceforge.net/projects/cjson/
-
- The example corresponds to SVN revision r42 (with lots of changes for
- NuttX coding standards). As of r42, the SVN repository was last updated
- on 2011-10-10 so I presume that the code is stable and there is no risk
- of maintaining duplicate logic in the NuttX repository.
-
-examples/leds
-^^^^^^^^^^^^
-
- This is a simple test of the board LED driver at nuttx/drivers/leds/userled_*.c.
-
-examples/lis2csh_reader
-^^^^^^^^^^^^^^^^^^^^^^^
-
- A simple reader example for the LIS3DSH acceleration sensor as found on
- STM32F4Discovery rev. C
-
-examples/hts221_reader
-^^^^^^^^^^^^^^^^^^^^^^^
-
- A simple reader example for the HTS221 humidity sensor.
-
-examples/lsm303_reader
-^^^^^^^^^^^^^^^^^^^^^^^
+## `gpio` GPIO Read and Write
- A simple reader example for the LSM303 acc-mag sensor.
+A simple `test/example` of the NuttX GPIO driver.
-examples/lsm6dsl_reader
-^^^^^^^^^^^^^^^^^^^^^^^
+## `hello` Hello World
- A simple reader example for the LSM6DSL acc-gyro sensor.
+This is the mandatory, _Hello, World!!_ example. It is little more than
+`examples/null` with a single `printf` statement. Really useful only for
+bringing up new NuttX architectures.
-examples/media
-^^^^^^^^^^^^^^
+- `CONFIG_NSH_BUILTIN_APPS` – Build the _Hello, World_ example as an NSH
+ built-in application.
- The media test simply writes values onto the media hidden behind a
- character driver and verifies that the media can be successfully written
- and read. This low level test is useful in the early phases of the
- bringup of a new block or mtd driver because it avoids the complexity of
- a file system.
+## `helloxx` Hello World in C++
- This test uses a character driver and cannot directly access block or mtd
- drivers. This test is suitable for use EEPROM character drivers (see
- nuttx/drivers/eeprom), or with block drivers wrapped as character drivers
- (see nuttx/drivers/bch)
+This is C++ version of the _Hello, World!!_ example. It is intended only to
+verify that the C++ compiler is functional, that basic C++ library support is
+available, and that class are instantiated correctly.
- int ret = bchdev_register(<path-to-block-dirver>,
- <path-to-character-driver>, false);
+NuttX configuration prerequisites:
- MTD drivers need an additional wrapper layer, the FTL wrapper must first
- be used to convert the MTD driver to a block device:
+- `CONFIG_HAVE_CXX` – Enable C++ Support.
- int ret = ftl_initialize(<N>, mtd);
- ret = bchdev_register(/dev/mtdblock<N>, <path-to-character-driver>,
- false);
+Optional NuttX configuration settings:
-examples/module
-^^^^^^^^^^^^^^
+- `CONFIG_HAVE_CXXINITIALIZE` – Enable support for static constructors (may not
+ be available on all platforms).
- This example builds a small loadable module test case. This includes a
- character driver under examples/module/drivers. This driver is built using
- the relocatable ELF format and installed in a ROMFS file system. At run time,
- the driver module is loaded and exercised. Requires CONFIG_MODULE.
- Other configuration options:
+NuttX configuration settings specific to this example:
- CONFIG_EXAMPLES_ELF_DEVMINOR - The minor device number of the ROMFS block
- driver. For example, the N in /dev/ramN. Used for registering the RAM
- block driver that will hold the ROMFS file system containing the ELF
- executables to be tested. Default: 0
+- `CONFIG_NSH_BUILTIN_APPS` – Build the helloxx example as a _built-in_ that can
+ be executed from the NSH command line.
- CONFIG_EXAMPLES_ELF_DEVPATH - The path to the ROMFS block driver device. This
- must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver
- that will hold the ROMFS file system containing the ELF executables to be
- tested. Default: "/dev/ram0"
+Also needed:
- NOTES:
+- `CONFIG_HAVE_CXX=y`
- 1. CFLAGS should be provided in CMODULEFLAGS. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be:
+And you may have to tinker with the following to get libxx to compile properly:
- CMODULEFLAGS = $(CFLAGS) -mlong-calls
+- `CCONFIG_ARCH_SIZET_LONG=y` or `=n`.
- Similarly for C++ flags which must be provided in CXXMODULEFLAGS.
+The argument of the `new` operators should take a type of `size_t`. But `size_t`
+has an unknown underlying. In the nuttx `sys/types.h` header file, `size_t` is
+typed as `uint32_t` (which is determined by architecture-specific logic). But
+the C++ compiler may believe that `size_t` is of a different type resulting in
+compilation errors in the operator. Using the underlying integer type Instead of
+`size_t` seems to resolve the compilation issues.
- 2. Your top-level nuttx/Make.defs file must also include an appropriate definition,
- LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, this should
- include '-r' and '-e <entry point>'.
+## `hidkbd` USB Host HID keyboard
- LDMODULEFLAGS = -r -e module_initialize
+This is a simple test to `debug/verify` the USB host HID keyboard class driver.
- If you use GCC to link, you make also need to include '-nostdlib' or
- '-nostartfiles' and '-nodefaultlibs'.
+- `CONFIG_EXAMPLES_HIDKBD_DEFPRIO` – Priority of _waiter_ thread. Default: `50`.
+- `CONFIG_EXAMPLES_HIDKBD_STACKSIZE` – Stacksize of _waiter_ thread. Default
+ `1024`.
+- `CONFIG_EXAMPLES_HIDKBD_DEVNAME` – Name of keyboard device to be used.
+ Default: `/dev/kbda`.
+- `CONFIG_EXAMPLES_HIDKBD_ENCODED` – Decode special key press events in the
+ user buffer. In this case, the example coded will use the interfaces defined
+ in `include/nuttx/input/kbd_codec.h` to decode the returned keyboard data.
+ These special keys include such things as up/down arrows, home and end keys,
+ etc. If this not defined, only 7-bit printable and control ASCII characters
+ will be provided to the user. Requires `CONFIG_HIDKBD_ENCODED` and
+ `CONFIG_LIB_KBDCODEC`.
- 3. This example also requires genromfs. genromfs can be build as part of the
- nuttx toolchain. Or can built from the genromfs sources that can be found
- in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the
- PATH variable must include the path to the genromfs executable.
+## `igmp` Trivial IGMP
- 4. ELF size: The ELF files in this example are, be default, quite large
- because they include a lot of "build garbage". You can greatly reduce the
- size of the ELF binaries are using the 'objcopy --strip-unneeded' command to
- remove un-necessary information from the ELF files.
+This is a trivial test of the NuttX IGMP capability. It present it does not do
+much of value – Much more is needed in order to verify the IGMP features!
- 5. Simulator. You cannot use this example with the NuttX simulator on
- Cygwin. That is because the Cygwin GCC does not generate ELF file but
- rather some Windows-native binary format.
+- `CONFIG_EXAMPLES_IGMP_NOMAC` – Set if the hardware has no MAC address; one
+ will be assigned.
+- `CONFIG_EXAMPLES_IGMP_IPADDR` – Target board IP address.
+- `CONFIG_EXAMPLES_IGMP_DRIPADDR` – Default router address.
+- `CONFIG_EXAMPLES_IGMP_NETMASK` – Network mask.
+- `CONFIG_EXAMPLES_IGMP_GRPADDR` – Multicast group address.
+- `CONFIG_EXAMPLES_NETLIB` – The networking library is needed.
- If you really want to do this, you can create a NuttX x86 buildroot toolchain
- and use that be build the ELF executables for the ROMFS file system.
+## `i2cchar` Transfer Through I2C
- 6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at nuttx/libc/modlib/gnu-elf.ld.
- That example might have to be tuned for your particular linker output to
- position additional sections correctly. The GNU LD LDMODULEFLAGS then might
- be:
+A mindlessly simple test of an I2C driver. It reads an write garbage data to the
+I2C transmitter and/or received as fast possible.
- LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld
+This test depends on these specific I2S/AUDIO/NSH configurations settings (your
+specific I2S settings might require additional settings).
-examples/modbus
-^^^^^^^^^^^^^^^
+- `CONFIG_I2S` – Enabled I2S support.
+- `CONFIG_AUDIO` – Enabled audio support.
+- `CONFIG_DRIVERS_AUDIO` – Enable audio device support.
+- `CONFIG_AUDIO_I2SCHAR` – Enabled support for the I2S character device.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the I2S test as an NSH built-in function.
+ Default: Built as a standalone program.
- This is a port of the FreeModbus Linux demo. It derives from the
- demos/LINUX directory of the FreeModBus version 1.5.0 (June 6, 2010)
- that can be downloaded in its entirety from http://developer.berlios.de/project/showfiles.php?group_id=6120.
+Specific configuration options for this example include:
- CONFIG_EXAMPLES_MODBUS_PORT, Default 0 (for /dev/ttyS0)
- CONFIG_EXAMPLES_MODBUS_BAUD, Default B38400
- CONFIG_EXAMPLES_MODBUS_PARITY, Default MB_PAR_EVEN
+- `CONFIG_EXAMPLES_I2SCHAR` – Enables the I2C test.
- CONFIG_EXAMPLES_MODBUS_REG_INPUT_START, Default 1000
- CONFIG_EXAMPLES_MODBUS_REG_INPUT_NREGS, Default 4
- CONFIG_EXAMPLES_MODBUS_REG_HOLDING_START, Default 2000
- CONFIG_EXAMPLES_MODBUS_REG_HOLDING_NREGS, Default 130
+- `CONFIG_EXAMPLES_I2SCHAR_DEVPATH` – The default path to the ADC device.
+ Default: `/dev/i2schar0`.
- The FreeModBus library resides at apps/modbus. See apps/modbus/README.txt
- for additional configuration information.
+- `CONFIG_EXAMPLES_I2SCHAR_TX` – This should be set if the I2S device supports a
+ transmitter.
-examples/mount
-^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_I2SCHAR_TXBUFFERS` – This is the default number of audio
+ buffers to send before the TX transfers terminate. When both TX and RX
+ transfers terminate, the task exits (and, if an NSH builtin, the `i2schar`
+ command returns). This number can be changed from the NSH command line.
- This contains a simple test of filesystem mountpoints.
+- `CONFIG_EXAMPLES_I2SCHAR_TXSTACKSIZE` – This is the stack size to use when
+ starting the transmitter thread. Default `1536`.
- * CONFIG_EXAMPLES_MOUNT_DEVNAME
- The name of the user-provided block device to mount.
- If CONFIG_EXAMPLES_MOUNT_DEVNAME is not provided, then
- a RAM disk will be configured.
+- `CONFIG_EXAMPLES_I2SCHAR_RX` – This should be set if the I2S device supports a
+ transmitter.
- * CONFIG_EXAMPLES_MOUNT_NSECTORS
- The number of "sectors" in the RAM disk used when
- CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined.
+- `CONFIG_EXAMPLES_I2SCHAR_RXBUFFERS` – This is the default number of audio
+ buffers to receive before the RX transfers terminate. When both TX and RX
+ transfers terminate, the task exits (and, if an NSH builtin, the `i2schar`
+ command returns). This number can be changed from the NSH command line.
- * CONFIG_EXAMPLES_MOUNT_SECTORSIZE
- The size of each sectors in the RAM disk used when
- CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined.
+- `CONFIG_EXAMPLES_I2SCHAR_RXSTACKSIZE` – This is the stack size to use when
+ starting the receiver thread. Default `1536`.
- * CONFIG_EXAMPLES_MOUNT_RAMDEVNO
- The RAM device minor number used to mount the RAM disk used
- when CONFIG_EXAMPLES_MOUNT_DEVNAME is not defined. The
- default is zero (meaning that "/dev/ram0" will be used).
+- `CONFIG_EXAMPLES_I2SCHAR_BUFSIZE` – The size of the data payload in one audio
+ buffer. Applies to both TX and RX audio buffers.
-examples/mtdpart
-^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_I2SCHAR_DEVINIT` – Define if architecture-specific I2S device
+ initialize is available. If defined, the platform specific code must provide a
+ function `i2schar_devinit()` that will be called each time that this test
+ executes. Not available in the kernel build mode.
- This examples provides a simple test of MTD partition logic.
+## `ina219` Current/Power Monitor `INA219`
- * CONFIG_EXAMPLES_MTDPART - Enables the MTD partition test example
- * CONFIG_EXAMPLES_MTDPART_ARCHINIT - The default is to use the RAM MTD
- device at drivers/mtd/rammtd.c. But an architecture-specific MTD driver
- can be used instead by defining CONFIG_EXAMPLES_MTDPART_ARCHINIT. In
- this case, the initialization logic will call mtdpart_archinitialize()
- to obtain the MTD driver instance.
- * CONFIG_EXAMPLES_MTDPART_NPARTITIONS - This setting provides the number
- of partitions to test. The test will divide the reported size of the
- MTD device into equal-sized sub-regions for each test partition. Default:
- 3
+This is a simple infinite loop that polls the `INA219` sensor and displays the
+measurements.
- When CONFIG_EXAMPLES_MTDPART_ARCHINIT is not defined, this test will use
- the RAM MTD device at drivers/mtd/rammtd.c to simulate FLASH. The size of
- the allocated RAM drive will be: CONFIG_EXMPLES_RAMMTD_ERASESIZE *
- CONFIG_EXAMPLES_MTDPART_NEBLOCKS
+## `ipforward` IP Forwarding Using TUN
- * CONFIG_EXAMPLES_MTDPART_ERASESIZE - This value gives the size of one
- erase block in the MTD RAM device. This must exactly match the default
- configuration in drivers/mtd/rammtd.c!
- * CONFIG_EXAMPLES_MTDPART_NEBLOCKS - This value gives the number of erase
- blocks in MTD RAM device.
+A simple test of IP forwarding using TUN devices. This can be used on any
+platform, but was intended for use on the simulation platform because it
+performs a test of IP forwarding without the use of hardware.
-examples/mtdrwb
-^^^^^^^^^^^^^^^^
-
- This examples provides a simple test of MTD Read-Ahead/Write buffering
- logic.
-
- * CONFIG_EXAMPLES_MTDRWB - Enables the MTD R/W buffering test example
- * CONFIG_EXAMPLES_MTDRWB_ARCHINIT - The default is to use the RAM MTD
- device at drivers/mtd/rammtd.c. But an architecture-specific MTD driver
- can be used instead by defining CONFIG_EXAMPLES_MTDRWB_ARCHINIT. In
- this case, the initialization logic will call mtdrwb_archinitialize()
- to obtain the MTD driver instance.
-
- When CONFIG_EXAMPLES_MTDRWB_ARCHINIT is not defined, this test will use
- the RAM MTD device at drivers/mtd/rammtd.c to simulate FLASH. The size of
- the allocated RAM drive will be: CONFIG_EXMPLES_RAMMTD_ERASESIZE *
- CONFIG_EXAMPLES_MTDRWB_NEBLOCKS
-
- * CONFIG_EXAMPLES_MTDRWB_ERASESIZE - This value gives the size of one
- erase block in the MTD RAM device. This must exactly match the default
- configuration in drivers/mtd/rammtd.c!
- * CONFIG_EXAMPLES_MTDRWB_NEBLOCKS - This value gives the number of erase
- blocks in MTD RAM device.
-
-examples/netpkt
-^^^^^^^^^^^^^^^
-
- A test of AF_PACKET, "raw" sockets. Contributed by Lazlo Sitzer.
-
-examples/netloop
-^^^^^^^^^^^^^^^^
-
- This is a simple test of the netwok loopback device. examples/nettest can
- also be configured to provide (better) test of local loopback transfers.
- This version derives from examples/poll and is focused on testing poll()
- with loopback devices.
-
- CONFIG_EXAMPLES_NETLOOP=y - Enables the nettest example
-
- Dependencies:
-
- CONFIG_NET_LOOPBACK - Requires local loopback support
- CONFIG_NET_TCP - Requires TCP support with the following:
- CONFIG_NET_TCPBACKLOG
- CONFIG_NET_TCP_WRITE_BUFFERS
- CONFIG_NET_IPv4 - Currently supports only IPv4
-
-examples/nettest
-^^^^^^^^^^^^^^^^
-
- This is a simple network test for verifying client- and server-
- functionality in a TCP/IP connection.
-
- CONFIG_EXAMPLES_NETTEST=y - Enables the nettest example
- CONFIG_EXAMPLES_NETLIB=y - The networking library in needed.
-
- Configurations:
-
- - Server on target hardware; client on host
- - Client on target hardware; Server on host
- - Server and Client on different targets.
- - Loopback configuration with both client and server on the same target.
-
- See also examples/tcpecho
-
-examples/nrf24l01_term
-^^^^^^^^^^^^^^^^^^^^^^
-
- These is a simple test of NRF24L01-based wireless connectivity. Enabled\
- with:
-
- CONFIG_EXAMPLES_NRF24L01TERM
-
- Options:
-
- CONFIG_NSH_BUILTIN_APPS - Built as an NSH built-in applications.
-
-examples/nx
-^^^^^^^^^^^
-
- This directory contains a simple test of a subset of the NX APIs
- defined in include/nuttx/nx/nx.h. The following configuration options
- can be selected:
-
- CONFIG_NSH_BUILTIN_APPS -- Build the NX example as a "built-in"
- that can be executed from the NSH command line
- CONFIG_EXAMPLES_NX_BGCOLOR -- The color of the background. Default depends on
- CONFIG_EXAMPLES_NX_BPP.
- CONFIG_EXAMPLES_NX_COLOR1 -- The color of window 1. Default depends on
- CONFIG_EXAMPLES_NX_BPP.
- CONFIG_EXAMPLES_NX_COLOR2 -- The color of window 2. Default depends on
- CONFIG_EXAMPLES_NX_BPP.
- CONFIG_EXAMPLES_NX_TBCOLOR -- The color of the toolbar. Default depends on
- CONFIG_EXAMPLES_NX_BPP.
- CONFIG_EXAMPLES_NX_FONTID - Selects the font (see font ID numbers in
- include/nuttx/nx/nxfonts.h)
- CONFIG_EXAMPLES_NX_FONTCOLOR -- The color of the fonts. Default depends on
- CONFIG_EXAMPLES_NX_BPP.
- CONFIG_EXAMPLES_NX_BPP -- Pixels per pixel to use. Valid options
- include 2, 4, 8, 16, 24, and 32. Default is 32.
- CONFIG_EXAMPLES_NX_RAWWINDOWS -- Use raw windows; Default is to
- use pretty, framed NXTK windows with toolbars.
- CONFIG_EXAMPLES_NX_STACKSIZE -- The stacksize to use when creating
- the NX server. Default 2048
- CONFIG_EXAMPLES_NX_CLIENTPRIO -- The client priority. Default: 100
- CONFIG_EXAMPLES_NX_SERVERPRIO -- The server priority. Default: 120
- CONFIG_EXAMPLES_NX_LISTENERPRIO -- The priority of the event listener
- thread. Default 80.
- CONFIG_EXAMPLES_NX_NOTIFYSIGNO -- The signal number to use with
- nx_eventnotify(). Default: 4
-
- The example also has the following settings and will generate an error
- if they are not as expected:
-
- CONFIG_DISABLE_MQUEUE=n
- CONFIG_DISABLE_PTHREAD=n
- CONFIG_NX_BLOCKING=y
- CONFIG_LIB_BOARDCTL=y
-
-examples/nxterm
-^^^^^^^^^^^^^^^^^^
-
- This directory contains yet another version of the NuttShell (NSH). This
- version uses the NX console device defined in include/nuttx/nx/nxterm.h
- for output. the result is that the NSH input still come from the standard
- console input (probably a serial console). But the text output will go to
- an NX winbdow. Prerequisite configuration settings for this test include:
-
- CONFIG_NX=y -- NX graphics must be enabled
- CONFIG_NXTERM=y -- The NX console driver must be built
- CONFIG_DISABLE_MQUEUE=n -- Message queue support must be available.
- CONFIG_DISABLE_PTHREAD=n -- pthreads are needed
- CONFIG_NX_BLOCKING=y -- pthread APIs must be blocking
- CONFIG_NSH_CONSOLE=y -- NSH must be configured to use a console.
-
- The following configuration options can be selected to customize the
- test:
-
- CONFIG_EXAMPLES_NXTERM_BGCOLOR -- The color of the background. Default
- Default is a darker royal blue.
- CONFIG_EXAMPLES_NXTERM_WCOLOR -- The color of the window. Default is a light
- slate blue.
- CONFIG_EXAMPLES_NXTERM_FONTID -- Selects the font (see font ID numbers in
- include/nuttx/nx/nxfonts.h)
- CONFIG_EXAMPLES_NXTERM_FONTCOLOR -- The color of the fonts. Default is
- black.
- CONFIG_EXAMPLES_NXTERM_BPP -- Pixels per pixel to use. Valid options
- include 2, 4, 8, 16, 24, and 32. Default is 32.
- CONFIG_EXAMPLES_NXTERM_TOOLBAR_HEIGHT -- The height of the toolbar.
- Default: 16
- CONFIG_EXAMPLES_NXTERM_TBCOLOR -- The color of the toolbar. Default is
- a medium grey.
- CONFIG_EXAMPLES_NXTERM_MINOR -- The NX console device minor number.
- Default is 0 corresponding to /dev/nxterm0
- CONFIG_EXAMPLES_NXTERM_DEVNAME -- The quoted, full path to the
- NX console device corresponding to CONFIG_EXAMPLES_NXTERM_MINOR.
- Default: "/dev/nxterm0"
- CONFIG_EXAMPLES_NXTERM_PRIO - Priority of the NxTerm task.
- Default: SCHED_PRIORITY_DEFAULT
- CONFIG_EXAMPLES_NXTERM_STACKSIZE - Stack size allocated for the
- NxTerm task. Default: 2048
- CONFIG_EXAMPLES_NXTERM_STACKSIZE -- The stacksize to use when creating
- the NX server. Default 2048
- CONFIG_EXAMPLES_NXTERM_CLIENTPRIO -- The client priority. Default: 100
- CONFIG_EXAMPLES_NXTERM_SERVERPRIO -- The server priority. Default: 120
- CONFIG_EXAMPLES_NXTERM_LISTENERPRIO -- The priority of the event listener
- thread. Default 80.
- CONFIG_EXAMPLES_NXTERM_NOTIFYSIGNO -- The signal number to use with
- nx_eventnotify(). Default: 4
-
-examples/nxflat
-^^^^^^^^^^^^^^^
-
- This example builds a small NXFLAT test case. This includes several
- test programs under examples/nxflat tests. These tests are build using
- the NXFLAT format and installed in a ROMFS file system. At run time,
- each program in the ROMFS file system is executed. Requires CONFIG_NXFLAT.
-
-examplex/nxhello
-^^^^^^^^^^^^^^^^
-
- A very simple graphics example that just says "Hello, World!" in the
- center of the display.
-
- The following configuration options can be selected:
-
- CONFIG_NSH_BUILTIN_APPS -- Build the NXHELLO example as a "built-in"
- that can be executed from the NSH command line
- CONFIG_EXAMPLES_NXHELLO_VPLANE -- The plane to select from the frame-
- buffer driver for use in the test. Default: 0
- CONFIG_EXAMPLES_NXHELLO_DEVNO - The LCD device to select from the LCD
- driver for use in the test: Default: 0
- CONFIG_EXAMPLES_NXHELLO_BGCOLOR -- The color of the background. Default
- depends on CONFIG_EXAMPLES_NXHELLO_BPP.
- CONFIG_EXAMPLES_NXHELLO_FONTID - Selects the font (see font ID numbers in
- include/nuttx/nx/nxfonts.h)
- CONFIG_EXAMPLES_NXHELLO_FONTCOLOR -- The color of the fonts used in the
- background window. Default depends on CONFIG_EXAMPLES_NXHELLO_BPP.
- CONFIG_EXAMPLES_NXHELLO_BPP -- Pixels per pixel to use. Valid options
- include 2, 4, 8, 16, 24, and 32. Default is 32.
-
-examples/nximage
-^^^^^^^^^^^^^^^^
-
- This is a simple example that just puts the NuttX logo image in the center
- of the display. This only works for RGB23 (888), RGB16 (656), RGB8 (332),
- and 8-bit greyscale for now.
-
- CONFIG_NSH_BUILTIN_APPS -- Build the NXIMAGE example as a "built-in"
- that can be executed from the NSH command line
- CONFIG_EXAMPLES_NXIMAGE_VPLANE -- The plane to select from the frame-
- buffer driver for use in the test. Default: 0
- CONFIG_EXAMPLES_NXIMAGE_DEVNO - The LCD device to select from the LCD
- driver for use in the test: Default: 0
- CONFIG_EXAMPLES_NXIMAGE_BPP -- Pixels per pixel to use. Valid options
- include 8, 16, and 24. Default is 16.
- CONFIG_EXAMPLES_NXIMAGE_XSCALEp5, CONFIG_EXAMPLES_NXIMAGE_XSCALE1p5,
- CONFIG_EXAMPLES_NXIMAGE_XSCALE2p0 -- The logo image width is 160 columns.
- One of these may be defined to rescale the image horizontally by .5, 1.5,
- or 2.0.
- CONFIG_EXAMPLES_NXIMAGE_YSCALEp5, CONFIG_EXAMPLES_NXIMAGE_YSCALE1p5,
- CONFIG_EXAMPLES_NXIMAGE_YSCALE2p0 -- The logo image height is 160 rows.
- One of these may be defined to rescale the image vertically by .5, 1.5,
- or 2.0.
- CONFIG_EXAMPLES_NXIMAGE_GREYSCALE -- Grey scale image. Default: RGB.
-
- How was that run-length encoded image produced?
-
- a. I used GIMP output the image as a .c file.
- b. I added some C logic to palette-ize the RGB image in the GIMP .c file
- c. Then I add some simple run-length encoding to palette-ized image.
-
- But now there is a tool that can be found in the NxWidgets package at
- NxWidgets/tools/bitmap_converter.py that can be used to convert any
- graphics format to the NuttX RLE format.
-
- NOTE: As of this writing, most of the pixel depth, scaling options, and
- combinations thereof have not been tested.
-
-examplex/nxlines
-^^^^^^^^^^^^^^^^
-
- A very simple graphics example that just exercised the NX line drawing
- logic.
-
- The following configuration options can be selected:
-
- CONFIG_EXAMPLES_NXLINES_VPLANE -- The plane to select from the frame-
- buffer driver for use in the test. Default: 0
- CONFIG_EXAMPLES_NXLINES_DEVNO - The LCD device to select from the LCD
- driver for use in the test: Default: 0
- CONFIG_EXAMPLES_NXLINES_BGCOLOR -- The color of the background. Default
- depends on CONFIG_EXAMPLES_NXLINES_BPP.
- CONFIG_EXAMPLES_NXLINES_LINEWIDTH - Selects the width of the lines in
- pixels (default: 16)
- CONFIG_EXAMPLES_NXLINES_LINECOLOR -- The color of the central lines drawn
- in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
- (there really is no meaningful default).
- CONFIG_EXAMPLES_NXLINES_BORDERWIDTH -- The width of the circular border
- drawn in the background window. (default: 16).
- CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the circular border
- drawn in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
- (there really is no meaningful default).
- CONFIG_EXAMPLES_NXLINES_CIRCLECOLOR -- The color of the circular region
- filled in the background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP
- (there really is no meaningful default).
- CONFIG_EXAMPLES_NXLINES_BORDERCOLOR -- The color of the lines drawn in the
- background window. Default depends on CONFIG_EXAMPLES_NXLINES_BPP (there
- really is no meaningful default).
-
- CONFIG_EXAMPLES_NXLINES_BPP -- Pixels per pixel to use. Valid options
- include 2, 4, 8, 16, 24, and 32. Default is 16.
- CONFIG_NSH_BUILTIN_APPS - Build the NX lines examples as an NSH built-in
- function.
-
-examples/nxtext
-^^^^^^^^^^^^^^^
-
- This directory contains another simple test of a subset of the NX APIs
- defined in include/nuttx/nx/nx.h. This text focuses on text displays on
- the display background combined with pop-up displays over the text.
- The text display will continue to update while the pop-up is visible.
-
- NOTE: This example will *only* work with FB drivers and with LCD
- drivers that support reading the contents of the internal LCD memory
- *unless* you define CONFIG_EXAMPLES_NXTEXT_NOGETRUN. If you notice
- garbage on the display or a failure at the point where the display
- should scroll, it is probably because you have an LCD driver that is
- write-only.
-
- The following configuration options can be selected:
-
- CONFIG_NSH_BUILTIN_APPS -- Build the NXTEXT example as a "built-in"
- that can be executed from the NSH command line
- CONFIG_EXAMPLES_NXTEXT_BGCOLOR -- The color of the background. Default
- depends on CONFIG_EXAMPLES_NXTEXT_BPP.
- CONFIG_EXAMPLES_NXTEXT_BGFONTID - Selects the font to use in the
- background text (see font ID numbers in include/nuttx/nx/nxfonts.h)
- CONFIG_EXAMPLES_NXTEXT_BGFONTCOLOR -- The color of the fonts used in the
- background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP.
- CONFIG_EXAMPLES_NXTEXT_PUCOLOR -- The color of the pop-up window. Default
- depends on CONFIG_EXAMPLES_NXTEXT_BPP.
- CONFIG_EXAMPLES_NXTEXT_PUFONTID - Selects the font to use in the pop-up
- windows (see font ID numbers in include/nuttx/nx/nxfonts.h)
- CONFIG_EXAMPLES_NXTEXT_PUFONTCOLOR -- The color of the fonts used in the
- background window. Default depends on CONFIG_EXAMPLES_NXTEXT_BPP.
- CONFIG_EXAMPLES_NXTEXT_BPP -- Pixels per pixel to use. Valid options
- include 2, 4, 8, 16, 24, and 32. Default is 32.
- CONFIG_EXAMPLES_NXTEXT_NOGETRUN -- If your display is read-only OR if
- reading is not reliable, then select this configuration to avoid
- reading from the display.
- CONFIG_EXAMPLES_NXTEXT_BMCACHE - The maximum number of characters that
- can be put in the background window. Default is 128.
- CONFIG_EXAMPLES_NXTEXT_GLCACHE - The maximum number of pre-rendered
- fonts that can be retained for the background window.
- CONFIG_EXAMPLES_NXTEXT_STACKSIZE -- The stacksize to use when creating
- the NX server. Default 2048
- CONFIG_EXAMPLES_NXTEXT_CLIENTPRIO -- The client priority. Default: 100
- CONFIG_EXAMPLES_NXTEXT_SERVERPRIO -- The server priority. Default: 120
- CONFIG_EXAMPLES_NXTEXT_LISTENERPRIO -- The priority of the event listener
- thread. Default 80.
- CONFIG_EXAMPLES_NXTEXT_NOTIFYSIGNO -- The signal number to use with
- nx_eventnotify(). Default: 4
-
- The example also expects the following settings and will generate an
- error if they are not as expected:
-
- CONFIG_DISABLE_MQUEUE=n
- CONFIG_DISABLE_PTHREAD=n
- CONFIG_NX_BLOCKING=y
-
-examples/null
-^^^^^^^^^^^^^
-
- This is the do nothing application. It is only used for bringing
- up new NuttX architectures in the most minimal of environments.
-
-examples/obd2
-^^^^^^^^^^^^^
-
- A simple test of apps/canutils/libobd2.
-
-examples/oneshot
-^^^^^^^^^^^^^^^^
-
- Simple test of a oneshot driver.
-
-examples/pca9635
-^^^^^^^^^^^^^^^^
-
- A simple test of the PCA9635PW LED driver.
-
-examples/pdcurses
-^^^^^^^^^^^^^^^^^
-
- This directory contains the demo/test programs that accompany the public
- domain cursors package (pdcurses) that can be found at apps/graphics/pdcurs34.
-
-examples/pipe
-^^^^^^^^^^^^^
-
- A test of the mkfifo() and pipe() APIs. Requires CONFIG_PIPES
-
- * CONFIG_EXAMPLES_PIPE_STACKSIZE
- Sets the size of the stack to use when creating the child tasks.
- The default size is 1024.
+## `json` cJSON
-examples/poll
-^^^^^^^^^^^^^
+This example exercises the cJSON implementation at `apps/netutils/json`. This
+example contains logic taken from the cJSON project:
- A test of the poll() and select() APIs using FIFOs and, if available,
- stdin, and a TCP/IP socket. In order to use the TCP/IP select
- test, you must have the following things selected in your NuttX
- configuration file:
+http://sourceforge.net/projects/cjson/
- CONFIG_NET - Defined for general network support
- CONFIG_NET_TCP - Defined for TCP/IP support
- CONFIG_NET_NTCP_READAHEAD_BUFFERS - Defined to be greater than zero
+The example corresponds to SVN revision `r42` (with lots of changes for NuttX
+coding standards). As of `r42`, the SVN repository was last updated on
+`2011-10-10` so I presume that the code is stable and there is no risk of
+maintaining duplicate logic in the NuttX repository.
- CONFIG_EXAMPLES_POLL_NOMAC - (May be defined to use software assigned MAC)
- CONFIG_EXAMPLES_POLL_IPADDR - Target IP address
- CONFIG_EXAMPLES_POLL_DRIPADDR - Default router IP address
- CONFIG_EXAMPLES_POLL_NETMASK - Network mask
+## `leds` Toggle LEDs
- In order to for select to work with incoming connections, you
- must also select:
+This is a simple test of the board LED driver at
+`nuttx/drivers/leds/userled_*.c`.
- CONFIG_NET_TCPBACKLOG - Incoming connections pend in a backlog until accept() is called.
+## `lis2csh_reader` `LIS3DSH` Accelerometer
- In additional to the target device-side example, there is also
- a host-side application in this directory. It can be compiled under
- Linux or Cygwin as follows:
+A simple reader example for the `LIS3DSH` acceleration sensor as found on
+STM32F4Discovery rev. C.
- cd examples/usbserial
- make -f Makefile.host TOPDIR=<nuttx-directory> TARGETIP=<target-ip>
+## `hts221_reader` `HTS221` Humidity Sensor
- Where <target-ip> is the IP address of your target board.
+A simple reader example for the `HTS221` humidity sensor.
- This will generate a small program called 'host'. Usage:
+## `lsm303_reader` `LSM303` Accelerometer/Magnetometer
- 1. Build the examples/poll target program with TCP/IP poll support
- and start the target.
+A simple reader example for the `LSM303` acc-mag sensor.
- 3. Then start the host application:
+## `lsm6dsl_reader` `LSM6DSL` Accelerometer/Gyroscope
- ./host
+A simple reader example for the `LSM6DSL` acc-gyro sensor.
- The host and target will exchange are variety of small messages. Each
- message sent from the host should cause the select to return in target.
- The target example should read the small message and send it back to
- the host. The host should then receive the echo'ed message.
+## `media`
- If networking is enabled, applications using this example will need to
- provide the following definition in the defconfig file to enable the
- networking library:
+The media test simply writes values onto the media hidden behind a character
+driver and verifies that the media can be successfully written and read. This
+low level test is useful in the early phases of the bringup of a new block or
+mtd driver because it avoids the complexity of a file system.
- CONFIG_NETUTILS_NETLIB=y
+This test uses a character driver and cannot directly access block or mtd
+drivers. This test is suitable for use EEPROM character drivers (see
+`nuttx/drivers/eeprom`), or with block drivers wrapped as character drivers (see
+`nuttx/drivers/bch`)
-examples/posix_spawn
-^^^^^^^^^^^^^^^^^^^^
+```c
+int ret = bchdev_register(<path-to-block-dirver>,
+ <path-to-character-driver>, false);
+```
- This is a simple test of the posix_spawn() API. The example derives from
- examples/elf. As a result, these tests are built using the relocatable
- ELF format installed in a ROMFS file system. At run time, the test program
- in the ROMFS file system is spawned using posix_spawn().
+MTD drivers need an additional wrapper layer, the FTL wrapper must first be used
+to convert the MTD driver to a block device:
- Requires:
+```c
+int ret = ftl_initialize(<N>, mtd);
+ret = bchdev_register(/dev/mtdblock<N>, <path-to-character-driver>,
+ false);
+```
- CONFIG_BINFMT_DISABLE=n - Don't disable the binary loader
- CONFIG_ELF=y - Enable ELF binary loader
- CONFIG_LIBC_EXECFUNCS=y - Enable support for posix_spawn
- CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_spawn_exports"
- - The name of the symbol table
- created by the test.
- CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_spawn_nexports"
- - Name of variable holding the
- number of symbols
- CONFIG_POSIX_SPAWN_STACKSIZE=768 - This default setting.
+## `module` Loadable Module
- Test-specific configuration options:
+This example builds a small loadable module test case. This includes a character
+driver under `examples/module/drivers`. This driver is built using the
+relocatable ELF format and installed in a ROMFS file system. At run time, the
+driver module is loaded and exercised. Requires `CONFIG_MODULE`. Other
+configuration options:
- CONFIG_EXAMPLES_POSIXSPAWN_DEVMINOR - The minor device number of the ROMFS
- block. driver. For example, the N in /dev/ramN. Used for registering the
- RAM block driver that will hold the ROMFS file system containing the ELF
- executables to be tested. Default: 0
+- `CONFIG_EXAMPLES_ELF_DEVMINOR` – The minor device number of the ROMFS block
+ driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM
+ block driver that will hold the ROMFS file system containing the ELF
+ executables to be tested. Default: `0`.
- CONFIG_EXAMPLES_POSIXSPAWN_DEVPATH - The path to the ROMFS block driver
- device. This must match EXAMPLES_POSIXSPAWN_DEVMINOR. Used for
- registering the RAM block driver that will hold the ROMFS file system
- containing the ELF executables to be tested. Default: "/dev/ram0"
+- `CONFIG_EXAMPLES_ELF_DEVPATH` – The path to the ROMFS block driver device.
+ This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block
+ driver that will hold the ROMFS file system containing the ELF executables to
+ be tested. Default: `/dev/ram0`.
- NOTES:
+**Notes**:
- 1. CFLAGS should be provided in CELFFLAGS. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be:
+1. `CFLAGS` should be provided in `CMODULEFLAGS`. RAM and FLASH memory regions
+ may require long allcs. For ARM, this might be:
- CELFFLAGS = $(CFLAGS) -mlong-calls
+ ```makefile
+ CMODULEFLAGS = $(CFLAGS) -mlong-calls
+ ```
- Similarly for C++ flags which must be provided in CXXELFFLAGS.
+ Similarly for C++ flags which must be provided in `CXXMODULEFLAGS`.
- 2. Your top-level nuttx/Make.defs file must also include an appropriate
- definition, LDELFFLAGS, to generate a relocatable ELF object. With GNU
- LD, this should include '-r' and '-e main' (or _main on some platforms).
+2. Your top-level `nuttx/Make.defs` file must also include an appropriate
+ definition, LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD,
+ this should include `-r` and `-e <entry point>`.
- LDELFFLAGS = -r -e main
+ ```makefile
+ LDMODULEFLAGS = -r -e module_initialize
+ ```
- If you use GCC to link, you make also need to include '-nostdlib' or
- '-nostartfiles' and '-nodefaultlibs'.
+ If you use GCC to link, you make also need to include `-nostdlib` or
+ `-nostartfiles` and `-nodefaultlibs`.
- 3. This example also requires genromfs. genromfs can be build as part of the
- nuttx toolchain. Or can built from the genromfs sources that can be found
- in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the
- PATH variable must include the path to the genromfs executable.
+3. This example also requires `genromfs`. `genromfs` can be build as part of the
+ nuttx toolchain. Or can built from the `genromfs` sources that can be found
+ in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the
+ PATH variable must include the path to the `genromfs` executable.
- 4. ELF size: The ELF files in this example are, be default, quite large
- because they include a lot of "build garbage". You can greatly reduce the
- size of the ELF binaries are using the 'objcopy --strip-unneeded' command to
- remove un-necessary information from the ELF files.
+4. ELF size: The ELF files in this example are, be default, quite large because
+ they include a lot of _build garbage_. You can greatly reduce the size of the
+ ELF binaries are using the `objcopy --strip-unneeded` command to remove
+ un-necessary information from the ELF files.
- 5. Simulator. You cannot use this example with the NuttX simulator on
- Cygwin. That is because the Cygwin GCC does not generate ELF file but
- rather some Windows-native binary format.
+5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+ That is because the Cygwin GCC does not generate ELF file but rather some
+ Windows-native binary format.
- If you really want to do this, you can create a NuttX x86 buildroot toolchain
- and use that be build the ELF executables for the ROMFS file system.
+ If you really want to do this, you can create a NuttX x86 `buildroot`
+ toolchain and use that be build the ELF executables for the ROMFS file
+ system.
- 6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at nuttx/binfmt/libelf/gnu-elf.ld.
- That example might have to be tuned for your particular linker output to
- position additional sections correctly. The GNU LD LDELFFLAGS then might
- be:
+6. Linker scripts. You might also want to use a linker scripts to combine
+ sections better. An example linker script is at
+ `nuttx/libc/modlib/gnu-elf.ld`. That example might have to be tuned for your
+ particular linker output to position additional sections correctly. The GNU
+ LD `LDMODULEFLAGS` then might be:
- LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld
+ ```makefile
+ LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld
+ ```
-examples/powerled
-^^^^^^^^^^^^^^^^^
+## `modbus` FreeModbus
- This is a powerled driver example application. This application support three
- operation modes which can be selected from NSH command line:
+This is a port of the FreeModbus Linux demo. It derives from the demos/LINUX
+directory of the FreeModBus version `1.5.0` (June 6, 2010) that can be
+downloaded in its entirety from
+http://developer.berlios.de/project/showfiles.php?group_id=6120.
- 1. Demo mode
+- `CONFIG_EXAMPLES_MODBUS_PORT`, Default `0` (for `/dev/ttyS0`).
+- `CONFIG_EXAMPLES_MODBUS_BAUD`, Default B`38400`.
+- `CONFIG_EXAMPLES_MODBUS_PARITY`, Default `MB_PAR_EVEN`.
+- `CONFIG_EXAMPLES_MODBUS_REG_INPUT_START`, Default `1000`.
+- `CONFIG_EXAMPLES_MODBUS_REG_INPUT_NREGS`, Default `4`.
+- `CONFIG_EXAMPLES_MODBUS_REG_HOLDING_START`, Default `2000`.
+- `CONFIG_EXAMPLES_MODBUS_REG_HOLDING_NREGS`, Default `130`.
- 2. Continuous mode
+The FreeModBus library resides at `apps/modbus`. See `apps/modbus/README.txt`
+for additional configuration information.
- 3. Flash mode
+## `mount` Mount Filesystem
-examples/pty_test
-^^^^^^^^^^^^^^^^^
+This contains a simple test of filesystem mountpoints.
- A test of NuttX pseudo-terminals. Provided by Alan Carvalho de Assis.
+- `CONFIG_EXAMPLES_MOUNT_DEVNAME` – The name of the user-provided block device
+ to mount. If `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not provided, then a RAM disk
+ will be configured.
-examples/pwfb
-^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_MOUNT_NSECTORS` – The number of _sectors_ in the RAM disk
+ used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined.
- A graphics example using pre-window frame buffers. The example shows
- three windows containing text moving around, crossing each other from
- "above" and from "below". The example application is NOT updating the
- windows any anyway! The application is only changing the window
- position. The windows are being updated from the per-winidow
- framebuffers automatically.
+- `CONFIG_EXAMPLES_MOUNT_SECTORSIZE` – The size of each sectors in the RAM disk
+ used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined.
- This example is reminiscent of Pong: Each window travels in straight
- line until it hits an edge, then it bounces off. The window is also
- raised when it hits the edge (gets "focus"). This tests all
- combinations of overap.
+- `CONFIG_EXAMPLES_MOUNT_RAMDEVNO` – The RAM device minor number used to mount
+ the RAM disk used when `CONFIG_EXAMPLES_MOUNT_DEVNAME` is not defined. The
+ default is zero (meaning that `/dev/ram0` will be used).
- NOTE: A significant amount of RAM, usually external SDRAM, is required
- to run this demo. At 16bpp and a 480x272 display, each window requires
- about 70Kb of RAM for its framebuffer.
+## `mtdpart` MTD Partition Test
-examples/pwm
-^^^^^^^^^^^^
+This examples provides a simple test of MTD partition logic.
- A test of a PWM device driver. It simply enables a pulsed output for
- a specified frequency and duty for a specified period of time. This
- example can ONLY be built as an NSH built-in function.
+- `CONFIG_EXAMPLES_MTDPART` – Enables the MTD partition test example.
- This test depends on these specific PWM/NSH configurations settings (your
- specific PWM settings might require additional settings).
+- `CONFIG_EXAMPLES_MTDPART_ARCHINIT` – The default is to use the RAM MTD device
+ at `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used
+ instead by defining `CONFIG_EXAMPLES_MTDPART_ARCHINIT`. In this case, the
+ initialization logic will call `mtdpart_archinitialize()` to obtain the MTD
+ driver instance.
- CONFIG_PWM - Enables PWM support.
- CONFIG_PWM_PULSECOUNT - Enables PWM pulse count support (if the hardware
- supports it).
- CONFIG_NSH_BUILTIN_APPS - Build the PWM test as an NSH built-in function.
+- `CONFIG_EXAMPLES_MTDPART_NPARTITIONS` – This setting provides the number of
+ partitions to test. The test will divide the reported size of the MTD device
+ into equal-sized sub-regions for each test partition. Default: `3`.
- Specific configuration options for this example include:
+When `CONFIG_EXAMPLES_MTDPART_ARCHINIT` is not defined, this test will use the
+RAM MTD device at `drivers/mtd/rammtd.c` to simulate FLASH. The size of the
+allocated RAM drive will be: `CONFIG_EXMPLES_RAMMTD_ERASESIZE *
+CONFIG_EXAMPLES_MTDPART_NEBLOCKS`.
- CONFIG_EXAMPLES_PWM_DEVPATH - The path to the default PWM device. Default: /dev/pwm0
- CONFIG_EXAMPLES_PWM_FREQUENCY - The initial PWM frequency. Default: 100 Hz
- CONFIG_EXAMPLES_PWM_DUTYPCT - The initial PWM duty as a percentage. Default: 50%
- CONFIG_EXAMPLES_PWM_DURATION - The initial PWM pulse train duration in seconds.
- Used only if the current pulse count is zero (pulse count is only supported
- if CONFIG_PWM_PULSECOUNT is defined). Default: 5 seconds
- CONFIG_EXAMPLES_PWM_PULSECOUNT - The initial PWM pulse count. This option is
- only available if CONFIG_PWM_PULSECOUNT is non-zero. Default: 0 (i.e., use
- the duration, not the count).
+* `CONFIG_EXAMPLES_MTDPART_ERASESIZE` – This value gives the size of one erase
+ block in the MTD RAM device. This must exactly match the default configuration
+ in `drivers/mtd/rammtd.c`!
-examples/qencoder
-^^^^^^^^^^^^^^^^^
+* `CONFIG_EXAMPLES_MTDPART_NEBLOCKS` – This value gives the number of erase
+ blocks in MTD RAM device.
- This example is a simple test of a Quadrature Encoder driver. It simply reads
- positional data from the encoder and prints it.,
+## `mtdrwb` MTD Read-ahead and Write Buffering
- This test depends on these specific QE/NSH configurations settings (your
- specific PWM settings might require additional settings).
+This examples provides a simple test of MTD Read-Ahead/Write buffering logic.
- CONFIG_SENSORS_QENCODER - Enables quadrature encoder support (upper-half driver).
- CONFIG_NSH_BUILTIN_APPS - Build the QE test as an NSH built-in function.
- Default: Built as a standalone progrem.
+- `CONFIG_EXAMPLES_MTDRWB` – Enables the MTD R/W buffering test example.
- Additional configuration options will mostly likely be required for the board-
- specific lower-half driver. See the README.txt file in your board configuration
- directory.
+- `CONFIG_EXAMPLES_MTDRWB_ARCHINIT` – The default is to use the RAM MTD device
+ at `drivers/mtd/rammtd.c`. But an architecture-specific MTD driver can be used
+ instead by defining `CONFIG_EXAMPLES_MTDRWB_ARCHINIT`. In this case, the
+ initialization logic will call `mtdrwb_archinitialize()` to obtain the MTD
+ driver instance.
- Specific configuration options for this example include:
+When `CONFIG_EXAMPLES_MTDRWB_ARCHINIT` is not defined, this test will use the
+RAM MTD device at `drivers/mtd/rammtd.c` to simulate FLASH. The size of the
+allocated RAM drive will be: `CONFIG_EXMPLES_RAMMTD_ERASESIZE *
+CONFIG_EXAMPLES_MTDRWB_NEBLOCKS`
- CONFIG_EXAMPLES_QENCODER_DEVPATH - The path to the QE device. Default:
- /dev/qe0
- CONFIG_EXAMPLES_QENCODER_NSAMPLES - This number of samples is
- collected and the program terminates. Default: Samples are collected
- indefinitely.
- CONFIG_EXAMPLES_QENCODER_DELAY - This value provides the delay (in
- milliseconds) between each sample. Default: 100 milliseconds
+- `CONFIG_EXAMPLES_MTDRWB_ERASESIZE` – This value gives the size of one erase
+ block in the MTD RAM device. This must exactly match the default configuration
+ in `drivers/mtd/rammtd.c`!
-examples/random
-^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_MTDRWB_NEBLOCKS` – This value gives the number of erase
+ blocks in MTD RAM device.
- This is a very simply test of /dev/random. It simple collects random
- numbers and displays them on the console.
+## `netpkt` `AF_PACKET` _Raw_ Sockets
- Prerequistes:
+A test of `AF_PACKET`, _raw_ sockets. Contributed by Lazlo Sitzer.
- CONFIG_DEV_RANDOM - Support for /dev/random must be enabled in order
- to select this example.
+## `netloop` Network loopback device
- Configuration:
+This is a simple test of the netwok loopback device. `examples/nettest` can also
+be configured to provide (better) test of local loopback transfers. This version
+derives from `examples/poll` and is focused on testing `poll()` with loopback
+devices.
- CONFIG_EXAMPLES_RANDOM - Enables the /dev/random test
- CONFIG_EXAMPLES_MAXSAMPLES - This is the size of the /dev/random I/O
- buffer in units of 32-bit samples. Careful! This buffer is allocated
- on the stack as needed! Default 64.
- CONFIG_EXAMPLES_NSAMPLES; - When you execute the rand command, a number
- of samples ranging from 1 to EXAMPLES_MAXSAMPLES may be specified. If
- no argument is specified, this is the default number of samples that\
- will be collected and displayed. Default 8
+- `CONFIG_EXAMPLES_NETLOOP=y` – Enables the nettest example.
-examples/relays
-^^^^^^^^^^^^^^^
+Dependencies:
- Requires CONFIG_ARCH_RELAYS.
- Contributed by Darcy Gong.
+- `CONFIG_NET_LOOPBACK` – Requires local loopback support.
+- `CONFIG_NET_TCP` – Requires TCP support with the following:
+ - `CONFIG_NET_TCPBACKLOG`
+ - `CONFIG_NET_TCP_WRITE_BUFFERS`
+- `CONFIG_NET_IPv4` – Currently supports only IPv4.
- NOTE: This test exercises internal relay driver interfaces. As such, it
- relies on internal OS interfaces that are not normally available to a
- user-space program. As a result, this example cannot be used if a
- NuttX is built as a protected, supervisor kernel (CONFIG_BUILD_PROTECTED
- or CONFIG_BUILD_KERNEL).
+## `nettest` Client/Server Over TCP
-examples/rfid_readuid
-^^^^^^^^^^^^^^^^^^^^^
+This is a simple network test for verifying client- and server- functionality in
+a TCP/IP connection.
- RFID READUID example
+- `CONFIG_EXAMPLES_NETTEST=y` – Enables the nettest example.
+- `CONFIG_EXAMPLES_NETLIB=y` – The networking library in needed.
+
+Configurations:
+
+- Server on target hardware; client on host.
+- Client on target hardware; server on host.
+- Server and Client on different targets.
+- Loopback configuration with both client and server on the same target.
+
+See also `examples/tcpecho`.
+
+## `nrf24l01_term` NRF24L01 Wireless Connection
+
+These is a simple test of NRF24L01-based wireless connectivity. Enabled with:
+
+- `CONFIG_EXAMPLES_NRF24L01TERM`
+
+Options:
+
+- `CONFIG_NSH_BUILTIN_APPS` – Built as an NSH built-in applications.
+
+## `nx`
+
+This directory contains a simple test of a subset of the NX APIs defined in
+`include/nuttx/nx/nx.h`. The following configuration options can be selected:
+
+- `CONFIG_NSH_BUILTIN_APPS` – Build the NX example as a _built-in_ that can be
+ executed from the NSH command line
+- `CONFIG_EXAMPLES_NX_BGCOLOR` – The color of the background. Default depends on
+ `CONFIG_EXAMPLES_NX_BPP`.
+- `CONFIG_EXAMPLES_NX_COLOR1` – The color of window 1. Default depends on
+ `CONFIG_EXAMPLES_NX_BPP`.
+- `CONFIG_EXAMPLES_NX_COLOR2` – The color of window 2. Default depends on
+ `CONFIG_EXAMPLES_NX_BPP`.
+- `CONFIG_EXAMPLES_NX_TBCOLOR` – The color of the toolbar. Default depends on
+ `CONFIG_EXAMPLES_NX_BPP`.
+- `CONFIG_EXAMPLES_NX_FONTID` – Selects the font (see font ID numbers in
+ `include/nuttx/nx/nxfonts.h`).
+- `CONFIG_EXAMPLES_NX_FONTCOLOR` – The color of the fonts. Default depends on
+ `CONFIG_EXAMPLES_NX_BPP`.
+- `CONFIG_EXAMPLES_NX_BPP` – Pixels per pixel to use. Valid options include `2`,
+ `4`, `8`, `16`, `24` and `32`. Default is `32`.
+- `CONFIG_EXAMPLES_NX_RAWWINDOWS` – Use raw windows; Default is to use pretty,
+ framed NXTK windows with toolbars.
+- `CONFIG_EXAMPLES_NX_STACKSIZE` – The stacksize to use when creating the NX
+ server. Default `2048`.
+- `CONFIG_EXAMPLES_NX_CLIENTPRIO` – The client priority. Default: `100`
+- `CONFIG_EXAMPLES_NX_SERVERPRIO` – The server priority. Default: `120`
+- `CONFIG_EXAMPLES_NX_LISTENERPRIO` – The priority of the event listener thread.
+ Default `80`.
+- `CONFIG_EXAMPLES_NX_NOTIFYSIGNO` – The signal number to use with
+ `nx_eventnotify()`. Default: `4`.
+
+The example also has the following settings and will generate an error if they
+are not as expected:
+
+```conf
+CONFIG_DISABLE_MQUEUE=n
+CONFIG_DISABLE_PTHREAD=n
+CONFIG_NX_BLOCKING=y
+CONFIG_LIB_BOARDCTL=y
+```
+
+## `nxterm` Display NuttShell (NSH) as NX Console
+
+This directory contains yet another version of the NuttShell (NSH). This version
+uses the NX console device defined in `include/nuttx/nx/nxterm.h` for output.
+the result is that the NSH input still come from the standard console input
+(probably a serial console). But the text output will go to an NX winbdow.
+Prerequisite configuration settings for this test include:
+
+- `CONFIG_NX=y` – NX graphics must be enabled
+- `CONFIG_NXTERM=y` – The NX console driver must be built
+- `CONFIG_DISABLE_MQUEUE=n` – Message queue support must be available.
+- `CONFIG_DISABLE_PTHREAD=n` – pthreads are needed
+- `CONFIG_NX_BLOCKING=y` – pthread APIs must be blocking
+- `CONFIG_NSH_CONSOLE=y` – NSH must be configured to use a console.
+
+The following configuration options can be selected to customize the test:
+
+- `CONFIG_EXAMPLES_NXTERM_BGCOLOR` – The color of the background. Default
+ Default is a darker royal blue.
+- `CONFIG_EXAMPLES_NXTERM_WCOLOR` – The color of the window. Default is a light
+ slate blue.
+- `CONFIG_EXAMPLES_NXTERM_FONTID` – Selects the font (see font ID numbers in
+ `include/nuttx/nx/nxfonts.h`).
+- `CONFIG_EXAMPLES_NXTERM_FONTCOLOR` – The color of the fonts. Default is black.
+- `CONFIG_EXAMPLES_NXTERM_BPP` – Pixels per pixel to use. Valid options include
+ `2`, `4`, `8`, `16`, `24` and `32`. Default is `32`.
+- `CONFIG_EXAMPLES_NXTERM_TOOLBAR_HEIGHT` – The height of the toolbar. Default:
+ `16`.
+- `CONFIG_EXAMPLES_NXTERM_TBCOLOR` – The color of the toolbar. Default is a
+ medium grey.
+- `CONFIG_EXAMPLES_NXTERM_MINOR` – The NX console device minor number. Default
+ is `0` corresponding to `/dev/nxterm0`.
+- `CONFIG_EXAMPLES_NXTERM_DEVNAME` – The quoted, full path to the NX console
+ device corresponding to `CONFIG_EXAMPLES_NXTERM_MINOR`. Default:
+ `/dev/nxterm0`.
+- `CONFIG_EXAMPLES_NXTERM_PRIO` – Priority of the NxTerm task. Default:
+ `SCHED_PRIORITY_DEFAULT`.
+- `CONFIG_EXAMPLES_NXTERM_STACKSIZE` – Stack size allocated for the NxTerm task.
+ Default: `2048`.
+- `CONFIG_EXAMPLES_NXTERM_STACKSIZE` – The stacksize to use when creating the NX
+ server. Default: `2048`.
+- `CONFIG_EXAMPLES_NXTERM_CLIENTPRIO` – The client priority. Default: `100`.
+- `CONFIG_EXAMPLES_NXTERM_SERVERPRIO` – The server priority. Default: `120`.
+- `CONFIG_EXAMPLES_NXTERM_LISTENERPRIO` – The priority of the event listener
+ thread. Default: `80`.
+- `CONFIG_EXAMPLES_NXTERM_NOTIFYSIGNO` – The signal number to use with
+ `nx_eventnotify()`. Default: `4`.
+
+## `nxflat` NXFLAT Binary
+
+This example builds a small NXFLAT test case. This includes several test
+programs under `examples/nxflat` tests. These tests are build using the NXFLAT
+format and installed in a ROMFS file system. At run time, each program in the
+ROMFS file system is executed. Requires `CONFIG_NXFLAT`.
+
+## `nxhello`
+
+A very simple graphics example that just says _Hello, World!_ in the center of
+the display.
+
+The following configuration options can be selected:
+
+- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXHELLO` example as a _built-in_ that
+ can be executed from the NSH command line
+- `CONFIG_EXAMPLES_NXHELLO_VPLANE` – The plane to select from the frame- buffer
+ driver for use in the test. Default: `0`.
+- `CONFIG_EXAMPLES_NXHELLO_DEVNO` – The LCD device to select from the LCD driver
+ for use in the test. Default: `0`.
+- `CONFIG_EXAMPLES_NXHELLO_BGCOLOR` – The color of the background. Default
+ depends on `CONFIG_EXAMPLES_NXHELLO_BPP`.
+- `CONFIG_EXAMPLES_NXHELLO_FONTID` – Selects the font (see font ID numbers in
+ include/nuttx/nx/nxfonts.h).
+- `CONFIG_EXAMPLES_NXHELLO_FONTCOLOR` – The color of the fonts used in the
+ background window. Default depends on `CONFIG_EXAMPLES_NXHELLO_BPP`.
+- `CONFIG_EXAMPLES_NXHELLO_BPP` – Pixels per pixel to use. Valid options include
+ `2`, `4`, `8`, `16`, `24` and `32`. Default: `32`.
+
+## `nximage` Display NuttX Logo
+
+This is a simple example that just puts the NuttX logo image in the center of
+the display. This only works for `RGB23` (`888`), `RGB16` (`656`), `RGB8`
+(`332`), and 8-bit greyscale for now.
+
+- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXIMAGE` example as a _built-in_ that
+ can be executed from the NSH command line.
+- `CONFIG_EXAMPLES_NXIMAGE_VPLANE` – The plane to select from the frame- buffer
+ driver for use in the test. Default: `0`.
+- `CONFIG_EXAMPLES_NXIMAGE_DEVNO` – The LCD device to select from the LCD driver
+ for use in the test: Default: `0`.
+- `CONFIG_EXAMPLES_NXIMAGE_BPP` – Pixels per pixel to use. Valid options include
+ `8`, `16` and `24`. Default is `16`.
+- `CONFIG_EXAMPLES_NXIMAGE_XSCALEp5`, `CONFIG_EXAMPLES_NXIMAGE_XSCALE1p5` or
+ `CONFIG_EXAMPLES_NXIMAGE_XSCALE2p0` – The logo image width is 160 columns. One
+ of these may be defined to rescale the image horizontally by .5, 1.5 or 2.0.
+- `CONFIG_EXAMPLES_NXIMAGE_YSCALEp5`, `CONFIG_EXAMPLES_NXIMAGE_YSCALE1p5` or
+ `CONFIG_EXAMPLES_NXIMAGE_YSCALE2p0` – The logo image height is 160 rows. One
+ of these may be defined to rescale the image vertically by .5, 1.5 or 2.0.
+- `CONFIG_EXAMPLES_NXIMAGE_GREYSCALE` – Grey scale image. Default: `RGB`.
+
+How was that run-length encoded image produced?
+
+1. I used GIMP output the image as a `.c` file.
+2. I added some C logic to palette-ize the RGB image in the GIMP `.c` file.
+3. Then I add some simple run-length encoding to palette-ized image.
+
+But now there is a tool that can be found in the NxWidgets package at
+`NxWidgets/tools/bitmap_converter.py` that can be used to convert any graphics
+format to the NuttX RLE format.
+
+**Note**: As of this writing, most of the pixel depth, scaling options, and
+combinations thereof have not been tested.
+
+## `nxlines` NX Line Drawing
+
+A very simple graphics example that just exercised the NX line drawing logic.
+
+The following configuration options can be selected:
+
+- `CONFIG_EXAMPLES_NXLINES_VPLANE` – The plane to select from the frame- buffer
+ driver for use in the test. Default: `0`.
+- `CONFIG_EXAMPLES_NXLINES_DEVNO` – The LCD device to select from the LCD driver
+ for use in the test: Default: `0`.
+- `CONFIG_EXAMPLES_NXLINES_BGCOLOR` – The color of the background. Default
+ depends on `CONFIG_EXAMPLES_NXLINES_BPP`.
+- `CONFIG_EXAMPLES_NXLINES_LINEWIDTH` – Selects the width of the lines in pixels
+ (default: `16`).
+- `CONFIG_EXAMPLES_NXLINES_LINECOLOR` – The color of the central lines drawn in
+ the background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP` (there
+ really is no meaningful default).
+- `CONFIG_EXAMPLES_NXLINES_BORDERWIDTH` – The width of the circular border drawn
+ in the background window. (default: `16`).
+- `CONFIG_EXAMPLES_NXLINES_BORDERCOLOR` – The color of the circular border drawn
+ in the background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP`
+ (there really is no meaningful default).
+- `CONFIG_EXAMPLES_NXLINES_CIRCLECOLOR` – The color of the circular region
+ filled in the background window. Default depends on
+ `CONFIG_EXAMPLES_NXLINES_BPP` (there really is no meaningful default).
+- `CONFIG_EXAMPLES_NXLINES_BORDERCOLOR` – The color of the lines drawn in the
+ background window. Default depends on `CONFIG_EXAMPLES_NXLINES_BPP` (there
+ really is no meaningful default).
+- `CONFIG_EXAMPLES_NXLINES_BPP` – Pixels per pixel to use. Valid options include
+ `2`, `4`, `8`, `16`, `24`, and `32`. Default is `16`.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the NX lines examples as an NSH built-in
+ function.
+
+## `nxtext` Display NX Text
+
+This directory contains another simple test of a subset of the NX APIs defined
+in `include/nuttx/nx/nx.h`. This text focuses on text displays on the display
+background combined with pop-up displays over the text. The text display will
+continue to update while the pop-up is visible.
+
+**Note**: This example will **only** work with FB drivers and with LCD drivers
+that support reading the contents of the internal LCD memory **unless** you
+define `CONFIG_EXAMPLES_NXTEXT_NOGETRUN`. If you notice garbage on the display
+or a failure at the point where the display should scroll, it is probably
+because you have an LCD driver that is write-only.
+
+The following configuration options can be selected:
+
+- `CONFIG_NSH_BUILTIN_APPS` – Build the `NXTEXT` example as a _built-in_ that
+ can be executed from the NSH command line.
+- `CONFIG_EXAMPLES_NXTEXT_BGCOLOR` – The color of the background. Default
+ depends on `CONFIG_EXAMPLES_NXTEXT_BPP`.
+- `CONFIG_EXAMPLES_NXTEXT_BGFONTID` – Selects the font to use in the background
+ text (see font ID numbers in `include/nuttx/nx/nxfonts.h`).
+- `CONFIG_EXAMPLES_NXTEXT_BGFONTCOLOR` – The color of the fonts used in the
+ background window. Default depends on `CONFIG_EXAMPLES_NXTEXT_BPP`.
+- `CONFIG_EXAMPLES_NXTEXT_PUCOLOR` – The color of the pop-up window. Default
+ depends on `CONFIG_EXAMPLES_NXTEXT_BPP`.
+- `CONFIG_EXAMPLES_NXTEXT_PUFONTID` – Selects the font to use in the pop-up
+ windows (see font ID numbers in `include/nuttx/nx/nxfonts.h`).
+- `CONFIG_EXAMPLES_NXTEXT_PUFONTCOLOR` – The color of the fonts used in the
+ background window. Default depends on `CONFIG_EXAMPLES_NXTEXT_BPP`.
+- `CONFIG_EXAMPLES_NXTEXT_BPP` – Pixels per pixel to use. Valid options include
+ `2`, `4`, `8`, `16`, `24` and `32`. Default is `32`.
+- `CONFIG_EXAMPLES_NXTEXT_NOGETRUN` – If your display is read-only OR if reading
+ is not reliable, then select this configuration to avoid reading from the
+ display.
+- `CONFIG_EXAMPLES_NXTEXT_BMCACHE` – The maximum number of characters that can
+ be put in the background window. Default is `128`.
+- `CONFIG_EXAMPLES_NXTEXT_GLCACHE` – The maximum number of pre-rendered fonts
+ that can be retained for the background window.
+- `CONFIG_EXAMPLES_NXTEXT_STACKSIZE` – The stacksize to use when creating the NX
+ server. Default `2048`.
+- `CONFIG_EXAMPLES_NXTEXT_CLIENTPRIO` – The client priority. Default: `100`.
+- `CONFIG_EXAMPLES_NXTEXT_SERVERPRIO` – The server priority. Default: `120`.
+- `CONFIG_EXAMPLES_NXTEXT_LISTENERPRIO` – The priority of the event listener
+ thread. Default: `80`.
+- `CONFIG_EXAMPLES_NXTEXT_NOTIFYSIGNO` – The signal number to use with
+ `nx_eventnotify()`. Default: `4`.
+
+The example also expects the following settings and will generate an error if
+they are not as expected:
+
+```conf
+CONFIG_DISABLE_MQUEUE=n
+CONFIG_DISABLE_PTHREAD=n
+CONFIG_NX_BLOCKING=y
+```
+
+## `null`
+
+This is the do nothing application. It is only used for bringing up new NuttX
+architectures in the most minimal of environments.
+
+## `obd2`
+
+A simple test of `apps/canutils/libobd2`.
+
+## `oneshot` Oneshot Timer
+
+Simple test of a oneshot driver.
+
+## `pca9635` `PCA9635PW` LED
+
+A simple test of the `PCA9635PW` LED driver.
+
+## `pdcurses`
+
+This directory contains the `demo/test` programs that accompany the public
+domain cursors package (`pdcurses`) that can be found at
+`apps/graphics/pdcurs34`.
+
+## `pipe`
+
+A test of the `mkfifo()` and `pipe()` APIs. Requires `CONFIG_PIPES`
+
+- `CONFIG_EXAMPLES_PIPE_STACKSIZE` – Sets the size of the stack to use when
+ creating the child tasks. The default size is `1024`.
+
+## `poll`
+
+A test of the `poll()` and `select()` APIs using FIFOs and, if available,
+`stdin`, and a TCP/IP socket. In order to use the TCP/IP select test, you must
+have the following things selected in your NuttX configuration file:
-examples/rgbled
-^^^^^^^^^^^^^^^
+- `CONFIG_NET` – Defined for general network support.
+- `CONFIG_NET_TCP` – Defined for TCP/IP support.
+- `CONFIG_NET_NTCP_READAHEAD_BUFFERS` – Defined to be greater than zero.
+- `CONFIG_EXAMPLES_POLL_NOMAC` – (May be defined to use software assigned
+ MAC)
+- `CONFIG_EXAMPLES_POLL_IPADDR` – Target IP address.
+- `CONFIG_EXAMPLES_POLL_DRIPADDR` – Default router IP address.
+- `CONFIG_EXAMPLES_POLL_NETMASK` – Network mask.
- This example demonstrates the use of the RGB led driver to drive an RGB LED
- with PWM outputs so that all color characteristcs of RGB LED can be controlled.
+In order to for select to work with incoming connections, you must also select:
-examples/romfs
-^^^^^^^^^^^^^^
+- `CONFIG_NET_TCPBACKLOG` – Incoming connections pend in a backlog until
+ `accept()` is called.
- This example exercises the romfs filesystem. Configuration options
- include:
+In additional to the target device-side example, there is also a host-side
+application in this directory. It can be compiled under Linux or Cygwin as
+follows:
- * CONFIG_EXAMPLES_ROMFS_RAMDEVNO
- The minor device number to use for the ROM disk. The default is
- 1 (meaning /dev/ram1)
+```makefile
+cd examples/usbserial
+make -f Makefile.host TOPDIR=<nuttx-directory> TARGETIP=<target-ip>
+```
- * CONFIG_EXAMPLES_ROMFS_SECTORSIZE
- The ROM disk sector size to use. Default is 64.
+Where `<target-ip>` is the IP address of your target board.
- * CONFIG_EXAMPLES_ROMFS_MOUNTPOINT
- The location to mount the ROM disk. Default: "/usr/local/share"
+This will generate a small program called 'host'. Usage:
-examples/sendmail
-^^^^^^^^^^^^^^^^^
+1. Build the `examples/poll` target program with TCP/IP poll support and start
+ the target.
- This examples exercises the uIP SMTP logic by sending a test message
- to a selected recipient. This test can also be built to execute on
- the Cygwin/Linux host environment:
+2. Then start the host application:
- cd examples/sendmail
- make -f Makefile.host TOPDIR=<nuttx-directory>
+ ```bash
+ ./host
+ ```
- Settings unique to this example include:
+The host and target will exchange are variety of small messages. Each message
+sent from the host should cause the select to return in target. The target
+example should read the small message and send it back to the host. The host
+should then receive the echo'ed message.
- CONFIG_EXAMPLES_SENDMAIL_NOMAC - May be defined to use software assigned MAC (optional)
- CONFIG_EXAMPLES_SENDMAIL_IPADDR - Target IP address (required)
- CONFIG_EXAMPLES_SENDMAIL_DRIPADDR - Default router IP address (required)
- CONFIG_EXAMPLES_SENDMAILT_NETMASK - Network mask (required)
- CONFIG_EXAMPLES_SENDMAIL_RECIPIENT - The recipient of the email (required)
- CONFIG_EXAMPLES_SENDMAIL_SENDER - Optional. Default: "nuttx-testing@example.com"
- CONFIG_EXAMPLES_SENDMAIL_SUBJECT - Optional. Default: "Testing SMTP from NuttX"
- CONFIG_EXAMPLES_SENDMAIL_BODY - Optional. Default: "Test message sent by NuttX"
+If networking is enabled, applications using this example will need to provide
+the following definition in the `defconfig` file to enable the networking
+library:
- NOTE: This test has not been verified on the NuttX target environment.
- As of this writing, unit-tested in the Cygwin/Linux host environment.
+- `CONFIG_NETUTILS_NETLIB=y`
- NOTE 2: This sendmail example only works for the simplest of
- environments. Virus protection software on your host may have
- to be disabled to allow you to send messages. Only very open,
- unprotected recipients can be used. Most will protect themselves
- from this test email because it looks like SPAM.
+## `posix_spawn`
- Applications using this example will need to enable the following
- netutils libraries in their defconfig file:
+This is a simple test of the `posix_spawn()` API. The example derives from
+`examples/elf`. As a result, these tests are built using the relocatable ELF
+format installed in a ROMFS file system. At run time, the test program in the
+ROMFS file system is spawned using `posix_spawn()`.
- CONFIG_NETUTILS_NETLIB=y
- CONFIG_NETUTILS_SMTP=y
+Requires:
-examples/serialblaster
-^^^^^^^^^^^^^^^^^^^^^^
+- `CONFIG_BINFMT_DISABLE=n` – Don't disable the binary loader.
+- `CONFIG_ELF=y` – Enable ELF binary loader.
+- `CONFIG_LIBC_EXECFUNCS=y` – Enable support for posix_spawn.
+- `CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_spawn_exports"` – The name of the symbol
+ table created by the test.
+- `CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_spawn_nexports"` – Name of variable holding
+ the number of symbols.
+- `CONFIG_POSIX_SPAWN_STACKSIZE=768` – This default setting.
- Sends a repeating pattern (the alphabet) out a serial port continuously.
- This may be useful if you are trying run down other problems that you
- think might only occur when the serial port usage is high.
+Test-specific configuration options:
-examples/serialrx
-^^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_POSIXSPAWN_DEVMINOR` – The minor device number of the ROMFS
+ block. driver. For example, the `N` in `/dev/ramN`. Used for registering the
+ RAM block driver that will hold the ROMFS file system containing the ELF
+ executables to be tested. Default: `0`.
- Constant receives serial data. This is the complement to serialblaster.
- This may be useful if you are trying run down other problems that you
- think might only occur when the serial port usage is high.
+- `CONFIG_EXAMPLES_POSIXSPAWN_DEVPATH` – The path to the ROMFS block driver
+ device. This must match `EXAMPLES_POSIXSPAWN_DEVMINOR`. Used for registering
+ the RAM block driver that will hold the ROMFS file system containing the ELF
+ executables to be tested. Default: `/dev/ram0`.
-examples/serloop
-^^^^^^^^^^^^^^^^
+**Notes**:
- This is a mindlessly simple loopback test on the console. Useful
- for testing new serial drivers. Configuration options include:
+1. `CFLAGS` should be provided in `CELFFLAGS`. RAM and FLASH memory regions may
+ require long allcs. For ARM, this might be:
- * CONFIG_EXAMPLES_SERLOOP_BUFIO
- Use C buffered I/O (getchar/putchar) vs. raw console I/O
- (read/read).
+ ```makefile
+ CELFFLAGS = $(CFLAGS) -mlong-calls
+ ```
-examples/slcd
-^^^^^^^^^^^^^
- A simple test of alphanumeric, segment LCDs (SLCDs).
+ Similarly for C++ flags which must be provided in `CXXELFFLAGS`.
- * CONFIG_EXAMPLES_SLCD - Enable the SLCD test
+2. Your top-level `nuttx/Make.defs` file must also include an appropriate
+ definition, `LDELFFLAGS`, to generate a relocatable ELF object. With GNU LD,
+ this should include `-r` and `-e main` (or `_main` on some platforms).
+ ```makefile
+ LDELFFLAGS = -r -e main
+ ```
-examples/smps
-^^^^^^^^^^^^^
+ If you use GCC to link, you make also need to include `-nostdlib` or
+ `-nostartfiles` and `-nodefaultlibs`.
- This is a SMPS (Switched-mode power supply) driver example application.
+3. This example also requires `genromfs`. `genromfs` can be build as part of the
+ nuttx toolchain. Or can built from the `genromfs` sources that can be found
+ in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the
+ `PATH` variable must include the path to the `genromfs` executable.
-examples/sotest
-^^^^^^^^^^^^^^^
+4. ELF size: The ELF files in this example are, be default, quite large because
+ they include a lot of _build garbage_. You can greatly reduce the size of the
+ ELF binaries are using the `objcopy --strip-unneeded` command to remove
+ un-necessary information from the ELF files.
- This example builds a small shared library module test case. The test
- shared library is built using the relocatable ELF format and installed
- in a ROMFS file system. At run time, the shared library is installed
- and exercised. Requires CONFIG_LIBC_DLFCN. Other configuration options:
+5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+ That is because the Cygwin GCC does not generate ELF file but rather some
+ Windows-native binary format.
- CONFIG_EXAMPLES_SOTEST_DEVMINOR - The minor device number of the ROMFS block
- driver. For example, the N in /dev/ramN. Used for registering the RAM
- block driver that will hold the ROMFS file system containing the ELF
- executables to be tested. Default: 0
+ If you really want to do this, you can create a NuttX x86 buildroot toolchain
+ and use that be build the ELF executables for the ROMFS file system.
- CONFIG_EXAMPLES_SOTEST_DEVPATH - The path to the ROMFS block driver device. This
- must match EXAMPLES_ELF_DEVMINOR. Used for registering the RAM block driver
- that will hold the ROMFS file system containing the ELF executables to be
- tested. Default: "/dev/ram0"
+6. Linker scripts. You might also want to use a linker scripts to combine
+ sections better. An example linker script is at
+ `nuttx/binfmt/libelf/gnu-elf.ld`. That example might have to be tuned for
+ your particular linker output to position additional sections correctly. The
+ GNU LD `LDELFFLAGS` then might be:
- NOTES:
+ ```makefile
+ LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/libelf/gnu-elf.ld
+ ```
- 1. CFLAGS should be provided in CMODULEFLAGS. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be:
+## `powerled`
- CMODULEFLAGS = $(CFLAGS) -mlong-calls
+This is a powerled driver example application. This application support three
+operation modes which can be selected from NSH command line:
- Similarly for C++ flags which must be provided in CXXMODULEFLAGS.
+1. Demo mode.
+2. Continuous mode.
+3. Flash mode.
- 2. Your top-level nuttx/Make.defs file must also include an appropriate definition,
- LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, this should
- include '-r' and '-e <entry point>'.
+## `pty_test` Pseudo-Terminals
- LDMODULEFLAGS = -r -e module_initialize
+A test of NuttX pseudo-terminals. Provided by Alan Carvalho de Assis.
- If you use GCC to link, you make also need to include '-nostdlib' or
- '-nostartfiles' and '-nodefaultlibs'.
+## `pwfb`
- 3. This example also requires genromfs. genromfs can be build as part of the
- nuttx toolchain. Or can built from the genromfs sources that can be found
- in the NuttX tools repository (genromfs-0.5.2.tar.gz). In any event, the
- PATH variable must include the path to the genromfs executable.
+A graphics example using pre-window frame buffers. The example shows three
+windows containing text moving around, crossing each other from _above_ and from
+_below_. The example application is NOT updating the windows any anyway! The
+application is only changing the window position. The windows are being updated
+from the per-winidow framebuffers automatically.
- 4. ELF size: The ELF files in this example are, be default, quite large
- because they include a lot of "build garbage". You can greatly reduce the
- size of the ELF binaries are using the 'objcopy --strip-unneeded' command to
- remove un-necessary information from the ELF files.
+This example is reminiscent of Pong: Each window travels in straight line until
+it hits an edge, then it bounces off. The window is also raised when it hits the
+edge (gets _focus_). This tests all combinations of overap.
- 5. Simulator. You cannot use this example with the NuttX simulator on
- Cygwin. That is because the Cygwin GCC does not generate ELF file but
- rather some Windows-native binary format.
+**Note**: A significant amount of RAM, usually external SDRAM, is required to
+run this demo. At 16bpp and a 480x272 display, each window requires about 70Kb
+of RAM for its framebuffer.
- If you really want to do this, you can create a NuttX x86 buildroot toolchain
- and use that be build the ELF executables for the ROMFS file system.
+## `pwm` General PWM
- 6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at nuttx/libc/modlib/gnu-elf.ld.
- That example might have to be tuned for your particular linker output to
- position additional sections correctly. The GNU LD LDMODULEFLAGS then might
- be:
+A test of a PWM device driver. It simply enables a pulsed output for a specified
+frequency and duty for a specified period of time. This example can ONLY be
+built as an NSH built-in function.
- LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld
+This test depends on these specific PWM/NSH configurations settings (your
+specific PWM settings might require additional settings).
-examples/stat
-^^^^^^^^^^^^^
+- `CONFIG_PWM` – Enables PWM support.
+- `CONFIG_PWM_PULSECOUNT` – Enables PWM pulse count support (if the hardware
+ supports it).
+- `CONFIG_NSH_BUILTIN_APPS` – Build the PWM test as an NSH built-in function.
- A simple test of stat(), fstat(), and statfs(). This is useful primarily for
- bringing up a new file system and verifying the correctness of these operations.
+Specific configuration options for this example include:
-examples/sx127x_demo
-^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_PWM_DEVPATH` – The path to the default PWM device. Default:
+ `/dev/pwm0`.
+- `CONFIG_EXAMPLES_PWM_FREQUENCY` – The initial PWM frequency. Default: `100` Hz
+- `CONFIG_EXAMPLES_PWM_DUTYPCT` – The initial PWM duty as a percentage. Default:
+ `50`%.
+- `CONFIG_EXAMPLES_PWM_DURATION` – The initial PWM pulse train duration in
+ seconds. Used only if the current pulse count is zero (pulse count is only
+ supported if `CONFIG_PWM_PULSECOUNT` is defined). Default: `5` seconds.
+- `CONFIG_EXAMPLES_PWM_PULSECOUNT` – The initial PWM pulse count. This option is
+ only available if `CONFIG_PWM_PULSECOUNT` is non-zero. Default: `0` (i.e., use
+ the duration, not the count).
- This example demonstrates the use of the SX127X radio/
+## `qencoder` Quadrature Encoder
-examples/system
-^^^^^^^^^^^^^^^
+This example is a simple test of a Quadrature Encoder driver. It simply reads
+positional data from the encoder and prints it.,
- This is a simple test of the system() command. The test simply executes this
- system command:
+This test depends on these specific QE/NSH configurations settings (your
+specific PWM settings might require additional settings).
- ret = system("ls -Rl /");
+- `CONFIG_SENSORS_QENCODER` – Enables quadrature encoder support (upper-half
+ driver).
+- `CONFIG_NSH_BUILTIN_APPS` – Build the QE test as an NSH built-in function.
+ Default: Built as a standalone program.
-examples/tcpblaster
-^^^^^^^^^^^^^^^^^^
+Additional configuration options will mostly likely be required for the board-
+specific lower-half driver. See the `README.txt` file in your board
+configuration directory.
- The tcpblaster example derives from the nettest example and basically duplicatesi
- that example when the nettest PERFORMANCE option is selected. tcpblaster has a
- little better reporting of performance stats, however.
+Specific configuration options for this example include:
-examples/tcpecho
-^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_QENCODER_DEVPATH` – The path to the QE device. Default:
+ `/dev/qe0`.
+- `CONFIG_EXAMPLES_QENCODER_NSAMPLES` – This number of samples is collected and
+ the program terminates. Default: Samples are collected indefinitely.
+- `CONFIG_EXAMPLES_QENCODER_DELAY` – This value provides the delay (in
+ milliseconds) between each sample. Default: `100` milliseconds.
- Simple single threaded, poll based TCP echo server. This example implements
- the TCP Echo Server from W. Richard Stevens UNIX Network Programming Book.
- Contributed by Max Holtberg.
+## `random` Random Numbers
- See also examples/nettest
+This is a very simply test of `/dev/random`. It simple collects random numbers
+and displays them on the console.
- * CONFIG_EXAMPLES_TCPECHO =y: Enables the TCP echo server.
- * CONFIG_XAMPLES_TCPECHO_PORT: Server Port, default 80
- * CONFIG_EXAMPLES_TCPECHO_BACKLOG: Listen Backlog, default 8
- * CONFIG_EXAMPLES_TCPECHO_NCONN: Number of Connections, default 8
- * CONFIG_EXAMPLES_TCPECHO_DHCPC: DHCP Client, default n
- * CONFIG_EXAMPLES_TCPECHO_NOMAC: Use Canned MAC Address, default n
- * CONFIG_EXAMPLES_TCPECHO_IPADDR: Target IP address, default 0x0a000002
- * CONFIG_EXAMPLES_TCPECHO_DRIPADDR: Default Router IP address (Gateway), default 0x0a000001
- * CONFIG_EXAMPLES_TCPECHO_NETMASK: Network Mask, default 0xffffff00
+Prerequistes:
-examples/telnetd
-^^^^^^^^^^^^^^^^
+- `CONFIG_DEV_RANDOM` – Support for `/dev/random` must be enabled in order to
+ select this example.
- This directory contains a functional port of the tiny uIP shell. In
- the NuttX environment, the NuttShell (at apps/nshlib) supersedes this
- tiny shell and also supports telnetd.
+Configuration:
- CONFIG_EXAMPLES_TELNETD - Enable the Telnetd example
- CONFIG_NETUTILS_NETLIB, CONFIG_NETUTILS_TELNED - Enable netutils
- libraries needed by the Telnetd example.
- CONFIG_EXAMPLES_TELNETD_DAEMONPRIO - Priority of the Telnet daemon.
- Default: SCHED_PRIORITY_DEFAULT
- CONFIG_EXAMPLES_TELNETD_DAEMONSTACKSIZE - Stack size allocated for the
- Telnet daemon. Default: 2048
- CONFIG_EXAMPLES_TELNETD_CLIENTPRIO- Priority of the Telnet client.
- Default: SCHED_PRIORITY_DEFAULT
- CONFIG_EXAMPLES_TELNETD_CLIENTSTACKSIZE - Stack size allocated for the
- Telnet client. Default: 2048
- CONFIG_EXAMPLES_TELNETD_NOMAC - If the hardware has no MAC address of its
- own, define this =y to provide a bogus address for testing.
- CONFIG_EXAMPLES_TELNETD_IPADDR - The target IP address. Default 10.0.0.2
- CONFIG_EXAMPLES_TELNETD_DRIPADDR - The default router address. Default
- 10.0.0.1
- CONFIG_EXAMPLES_TELNETD_NETMASK - The network mask. Default: 255.255.255.0
+- `CONFIG_EXAMPLES_RANDOM` – Enables the `/dev/random` test.
+- `CONFIG_EXAMPLES_MAXSAMPLES` – This is the size of the `/dev/random` I/O
+ buffer in units of 32-bit samples. Careful! This buffer is allocated on the
+ stack as needed! Default `64`.
+- `CONFIG_EXAMPLES_NSAMPLES` – When you execute the `rand` command, a number of
+ samples ranging from `1` to `EXAMPLES_MAXSAMPLES` may be specified. If no
+ argument is specified, this is the default number of samples that will be
+ collected and displayed. Default `8`.
- Also, make sure that you have the following set in the NuttX configuration
- file or else the performance will be very bad (because there will be only
- one character per TCP transfer):
-
- CONFIG_STDIO_BUFFER_SIZE - Some value >= 64
- CONFIG_STDIO_LINEBUFFER=y
-
-examples/thttpd
-^^^^^^^^^^^^^^^
+## `relays` Relays
- An example that builds netutils/thttpd with some simple NXFLAT
- CGI programs. see boards/README.txt for most THTTPD settings.
- In addition to those, this example accepts:
+Requires `CONFIG_ARCH_RELAYS`. Contributed by Darcy Gong.
- CONFIG_EXAMPLES_THTTPD_NOMAC - (May be defined to use software assigned MAC)
- CONFIG_EXAMPLES_THTTPD_DRIPADDR - Default router IP address
- CONFIG_EXAMPLES_THTTPD_NETMASK - Network mask
+**Note**: This test exercises internal relay driver interfaces. As such, it
+relies on internal OS interfaces that are not normally available to a user-space
+program. As a result, this example cannot be used if a NuttX is built as a
+protected, supervisor kernel (`CONFIG_BUILD_PROTECTED` or
+`CONFIG_BUILD_KERNEL`).
- Applications using this example will need to enable the following
- netutils libraries in the defconfig file:
+## `rfid_readuid` RFID
- CONFIG_NETUTILS_NETLIB=y
- CONFIG_NETUTILS_THTTPD=y
+RFID `READUID` example.
-examples/tiff
-^^^^^^^^^^^^^
+## `rgbled` RGB LED Using PWM
- This is a simple unit test for the TIFF creation library at apps/graphic/tiff.
- It is configured to work in the Linux user-mode simulation and has not been
- tested in any other environment.
+This example demonstrates the use of the RGB led driver to drive an RGB LED with
+PWM outputs so that all color characteristcs of RGB LED can be controlled.
- At a minimum, to run in an embedded environment, you will probably have to
- change the configured paths to the TIFF files defined in the example.
+## `romfs` File System
- CONFIG_EXAMPLES_TIFF_OUTFILE - Name of the resulting TIFF file. Default is
- "/tmp/result.tif"
- CONFIG_EXAMPLES_TIFF_TMPFILE1/2 - Names of two temporaries files that
- will be used in the file creation. Defaults are "/tmp/tmpfile1.dat" and
- "/tmp/tmpfile2.dat"
+This example exercises the romfs filesystem. Configuration options include:
- The following must also be defined in your apps/ configuration file:
+- `CONFIG_EXAMPLES_ROMFS_RAMDEVNO` – The minor device number to use for the ROM
+ disk. The default is `1` (meaning `/dev/ram1`).
+- `CONFIG_EXAMPLES_ROMFS_SECTORSIZE` – The ROM disk sector size to use. Default
+ is `64`.
+- `CONFIG_EXAMPLES_ROMFS_MOUNTPOINT` – The location to mount the ROM disk.
+ Default: `/usr/local/share`.
- CONFIG_EXAMPLES_TIFF=y
- CONFIG_GRAPHICS_TIFF=y
+## `sendmail` SMTP Client
-examples/timer
-^^^^^^^^^^^^^^
+This examples exercises the uIP SMTP logic by sending a test message to a
+selected recipient. This test can also be built to execute on the Cygwin/Linux
+host environment:
- This is a simple test of the timer driver (see include/nuttx/timers/timer.h).
-
- Dependencies:
- CONFIG_TIMER - The timer driver must be selected
-
- Example configuration:
-
- CONFIG_EXAMPLES_TIMER_DEVNAME - This is the name of the timer device that
- will be tested. Default: "/dev/timer0"
- CONFIG_EXAMPLES_TIMER_INTERVAL - This is the timer interval in
- microseconds. Default: 1000000
- CONFIG_EXAMPLES_TIMER_DELAY - This is the delay between timer samples in
- microseconds. Default: 10000
- CONFIG_EXAMPLES_TIMER_STACKSIZE - This is the stack size allocated when
- the timer task runs. Default: 2048
- CONFIG_EXAMPLES_TIMER_PRIORITY - This is the priority of the timer task:
- Default: 100
- CONFIG_EXAMPLES_TIMER_PROGNAME - This is the name of the program that
- will be used when the NSH ELF program is installed. Default: "timer"
-
-examples/touchscreen
-^^^^^^^^^^^^^^^^^^^^
-
- This configuration implements a simple touchscreen test at
- apps/examples/touchscreen. This test will create an empty X11 window
- and will print the touchscreen output as it is received from the
- simulated touchscreen driver.
-
- CONFIG_NSH_BUILTIN_APPS - Build the touchscreen test as
- an NSH built-in function. Default: Built as a standalone program
- CONFIG_EXAMPLES_TOUCHSCREEN_MINOR - The minor device number. Minor=N
- corresponds to touchscreen device /dev/inputN. Note this value must
- with CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH. Default 0.
- CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH - The path to the touchscreen
- device. This must be consistent with CONFIG_EXAMPLES_TOUCHSCREEN_MINOR.
- Default: "/dev/input0"
- CONFIG_EXAMPLES_TOUCHSCREEN_NSAMPLES - This number of samples is
- collected and the program terminates. Default: Samples are collected
- indefinitely.
- CONFIG_EXAMPLES_TOUCHSCREEN_MOUSE - The touchscreen test can also be
- configured to work with a mouse driver by setting this option.
-
- The following additional configurations must be set in the NuttX
- configuration file:
+```bash
+cd examples/sendmail
+make -f Makefile.host TOPDIR=<nuttx-directory>
+```
- CONFIG_INPUT=y
- (Plus any touchscreen-specific settings).
+Settings unique to this example include:
- The following must also be defined in your apps configuration file:
+- `CONFIG_EXAMPLES_SENDMAIL_NOMAC` – May be defined to use software assigned
+ MAC (optional)
+- `CONFIG_EXAMPLES_SENDMAIL_IPADDR` – Target IP address (required)
+- `CONFIG_EXAMPLES_SENDMAIL_DRIPADDR` – Default router IP address (required)
+- `CONFIG_EXAMPLES_SENDMAILT_NETMASK` – Network mask (required)
+- `CONFIG_EXAMPLES_SENDMAIL_RECIPIENT` – The recipient of the email (required)
+- `CONFIG_EXAMPLES_SENDMAIL_SENDER` – Optional. Default:
+ `nuttx-testing@example.com`
+- `CONFIG_EXAMPLES_SENDMAIL_SUBJECT` – Optional. Default: `Testing SMTP from
+ NuttX`
+- `CONFIG_EXAMPLES_SENDMAIL_BODY` – Optional. Default: `Test message sent
+ by NuttX`
- CONFIG_EXAMPLES_TOUCHSREEN=y
+**Note 1**: This test has not been verified on the NuttX target environment. As
+of this writing, unit-tested in the Cygwin/Linux host environment.
- This example code will call boardctl() to setup the touchscreen driver
- for texting. The implementation of boardctl() will require that board-
- specific logic provide the following interfaces that will be called by
- the boardctl() in order to initialize the touchscreen hardware:
+**Note 2**: This sendmail example only works for the simplest of environments.
+Virus protection software on your host may have to be disabled to allow you to
+send messages. Only very open, unprotected recipients can be used. Most will
+protect themselves from this test email because it looks like SPAM.
- int board_tsc_setup(int minor);
+Applications using this example will need to enable the following netutils
+libraries in their defconfig file:
-examples/udp
-^^^^^^^^^^^^
+```conf
+CONFIG_NETUTILS_NETLIB=y
+CONFIG_NETUTILS_SMTP=y
+```
- This is a simple network test for verifying client- and server-
- functionality over UDP.
+## `serialblaster`
- Applications using this example will need to enabled the following
- netutils libraries in the defconfig file:
+Sends a repeating pattern (the alphabet) out a serial port continuously. This
+may be useful if you are trying run down other problems that you think might
+only occur when the serial port usage is high.
- CONFIG_NETUTILS_NETLIB=y
+## `serialrx`
- Possible configurations:
+Constant receives serial data. This is the complement to `serialblaster`. This
+may be useful if you are trying run down other problems that you think might
+only occur when the serial port usage is high.
- - Server on target hardware; client on host
- - Client on target hardware; Server on host
- - Server and Client on different targets.
+## `serloop` Serial Loopback
-examples/udpblaster
-^^^^^^^^^^^^^^^^^^^
+This is a mindlessly simple loopback test on the console. Useful for testing new
+serial drivers. Configuration options include:
- This is a simple network test for stressing UDP transfers. It simply
- sends UDP packets from both the host and the target and the highest ratei
- possible.
+- `CONFIG_EXAMPLES_SERLOOP_BUFIO` – Use C buffered I/O (`getchar`/`putchar`) vs.
+ raw console I/O (read/read).
+## `slcd` Alphanumeric Segment LCD
-examples/unionfs
-^^^^^^^^^^^^^^^^
+A simple test of alphanumeric, segment LCDs (SLCDs).
- This is at trivial test of the Union File System. See
- nuttx/fs/unionfs/README.txt. Dependencies:
+- `CONFIG_EXAMPLES_SLCD` – Enable the SLCD test
- CONFIG_DISABLE_MOUNTPOINT - Mountpoint support must not be disabled
- CONFIG_NFILE_DESCRIPTORS > 4 - Some file descriptors must be allocated
- CONFIG_FS_ROMFS - ROMFS support is required
- CONFIG_FS_UNIONFS - Union File System support is required
+## `smps` Switched-Mode Power Supply
- Configuration options. Use the defaults if you are unsure of what you are doing:
+This is a SMPS (Switched-mode power supply) driver example application.
- CONFIG_EXAMPLES_UNIONFS - Enables the example
- CONFIG_EXAMPLES_UNIONFS_MOUNTPT - Mountpoint path for the Union File System
- CONFIG_EXAMPLES_UNIONFS_TMPA - Temporary mount point for file system 1
- CONFIG_EXAMPLES_UNIONFS_TMPB - Temporary mount point for file system 2
- CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_A - ROMFS file system 1 RAM disk device number
- CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_B - ROMFS file system 2 RAM disk device number
- CONFIG_EXAMPLES_UNIONFS_SECTORSIZE - ROM disk sector size.
+## `sotest` Shared Library Module Test
- See the README.txt file at nuttx/boards/sim/sim/sim/README.txt for a walk-through of
- the output of this text.
+This example builds a small shared library module test case. The test shared
+library is built using the relocatable ELF format and installed in a ROMFS file
+system. At run time, the shared library is installed and exercised. Requires
+`CONFIG_LIBC_DLFCN`. Other configuration options:
-examples/usbserial
-^^^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_SOTEST_DEVMINOR` – The minor device number of the ROMFS block
+ driver. For example, the `N` in `/dev/ramN`. Used for registering the RAM
+ block driver that will hold the ROMFS file system containing the ELF
+ executables to be tested. Default: `0`.
- TARGET CONFIGURATION:
+- `CONFIG_EXAMPLES_SOTEST_DEVPATH` – The path to the ROMFS block driver device.
+ This must match `EXAMPLES_ELF_DEVMINOR`. Used for registering the RAM block
+ driver that will hold the ROMFS file system containing the ELF executables to
+ be tested. Default: `/dev/ram0`.
- This is another implementation of "Hello, World" but this one uses
- a USB serial driver. Configuration options can be used to simply
- the test. These options include:
+**Notes**:
- CONFIG_EXAMPLES_USBSERIAL_INONLY
- Only verify IN (device-to-host) data transfers. Default: both
- CONFIG_EXAMPLES_USBSERIAL_OUTONLY
- Only verify OUT (host-to-device) data transfers. Default: both
- CONFIG_EXAMPLES_USBSERIAL_ONLYSMALL
- Send only small, single packet messages. Default: Send large and small.
- CONFIG_EXAMPLES_USBSERIAL_ONLYBIG
- Send only large, multi-packet messages. Default: Send large and small.
+1. `CFLAGS` should be provided in `CMODULEFLAGS`. RAM and FLASH memory regions
+ may require long allcs. For ARM, this might be:
- If CONFIG_USBDEV_TRACE is enabled (or CONFIG_DEBUG_FEATURES and CONFIG_DEBUG_USB), then
- the example code will also manage the USB trace output. The amount of trace output
- can be controlled using:
+ ```makefile
+ CMODULEFLAGS = $(CFLAGS) -mlong-calls
+ ```
- CONFIG_EXAMPLES_USBSERIAL_TRACEINIT
- Show initialization events
- CONFIG_EXAMPLES_USBSERIAL_TRACECLASS
- Show class driver events
- CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS
- Show data transfer events
- CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER
- Show controller events
- CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS
- Show interrupt-related events.
+ Similarly for C++ flags which must be provided in `CXXMODULEFLAGS`.
- Error results are always shown in the trace output
+2. Your top-level `nuttx/Make.defs` file must also include an appropriate
+ definition, `LDMODULEFLAGS`, to generate a relocatable ELF object. With GNU
+ LD, this should include `-r` and `-e <entry point>`.
- HOST-SIDE TEST PROGRAM
+ ```makefile
+ LDMODULEFLAGS = -r -e module_initialize
+ ```
- In additional to the target device-side example, there is also a
- host-side application in this directory. This host side application
- must be executed on a Linux host in order to perform the USBSERIAL
- test. The host application can be compiled under Linux (or Cygwin?)
- as follows:
+ If you use GCC to link, you make also need to include `-nostdlib` or
+ `-nostartfiles` and `-nodefaultlibs`.
- cd examples/usbserial
- make -f Makefile.host TOPDIR=<nuttx-directory>
+3. This example also requires `genromfs`. `genromfs` can be build as part of the
+ nuttx toolchain. Or can built from the `genromfs` sources that can be found
+ in the NuttX tools repository (`genromfs-0.5.2.tar.gz`). In any event, the
+ `PATH` variable must include the path to the `genromfs` executable.
- RUNNING THE TEST
+4. ELF size: The ELF files in this example are, be default, quite large because
+ they include a lot of _build garbage_. You can greatly reduce the size of the
+ ELF binaries are using the `objcopy --strip-unneeded` command to remove
+ un-necessary information from the ELF files.
- This will generate a small program called 'host'. Usage:
+5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+ That is because the Cygwin GCC does not generate ELF file but rather some
+ Windows-native binary format.
- 1. Build the examples/usbserial target program and start the target.
+ If you really want to do this, you can create a NuttX x86 buildroot toolchain
+ and use that be build the ELF executables for the ROMFS file system.
- 2. Wait a bit, then do enter:
+6. Linker scripts. You might also want to use a linker scripts to combine
+ sections better. An example linker script is at
+ `nuttx/libc/modlib/gnu-elf.ld`. That example might have to be tuned for your
+ particular linker output to position additional sections correctly. The GNU
+ LD `LDMODULEFLAGS` then might be:
- dmesg
+```makefile
+LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/modlib/gnu-elf.ld
+```
- At the end of the dmesg output, you should see the serial
- device was successfully idenfied and assigned to a tty device,
- probably /dev/ttyUSB0 or /dev/ttyACM0 (depending on the configured
- USB serial driver).
+## `stat`
- 3. Then start the host application:
+A simple test of `stat()`, `fstat()`, and `statfs()`. This is useful primarily
+for bringing up a new file system and verifying the correctness of these
+operations.
- ./host [<tty-dev>]
+## `sx127x_demo` `SX127X` Radio
- Where:
+This example demonstrates the use of the `SX127X` radio.
- <tty-dev> is the USB TTY device to use. The default is
- "/dev/ttyUSB0" (for the PL2303 emulation) or "/dev/ttyACM0" (for
- the CDC/ACM serial device).
+## `system`
- The host and target will exchange are variety of very small and very large
- serial messages.
+This is a simple test of the `system()` command. The test simply executes this
+`system` command:
-examples/userfs
-^^^^^^^^^^^^^^^
+```c
+ret = system("ls -Rl /");
+```
- A simple test of the UserFS file system.
+## `tcpblaster` TCP Performance Test
-examples/ustream
-^^^^^^^^^^^^^^^^
+The `tcpblaster` example derives from the `nettest` example and basically
+duplicates that example when the `nettest` PERFORMANCE option is selected.
+`tcpblaster` has a little better reporting of performance stats, however.
- This is the same test as examples/udp and similar to examples/ustream,
- but using Unix domain datagram sockets.
+## `tcpecho` TCP Echo Server
- Dependencies:
- CONFIG_NET_LOCAL - Depends on support for Unix domain sockets
+Simple single threaded, poll based TCP echo server. This example implements the
+TCP Echo Server from W. Richard Stevens _UNIX Network Programming_ Book.
+Contributed by Max Holtberg.
- Configuration:
- CONFIG_EXAMPLES_UDGRAM - Enables the Unix domain socket example.
- CONFIG_EXAMPLES_UDGRAM_ADDR - Specifics the Unix domain address.
- Default "/dev/fifo".
+See also `examples/nettest`
-examples/ustream
-^^^^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_TCPECHO=y` – Enables the TCP echo server.
+- `CONFIG_XAMPLES_TCPECHO_PORT` – Server Port, default `80`.
+- `CONFIG_EXAMPLES_TCPECHO_BACKLOG` – Listen Backlog, default `8`.
+- `CONFIG_EXAMPLES_TCPECHO_NCONN` – Number of Connections, default `8`.
+- `CONFIG_EXAMPLES_TCPECHO_DHCPC` – DHCP Client, default `n`.
+- `CONFIG_EXAMPLES_TCPECHO_NOMAC` – Use Canned MAC Address, default `n`.
+- `CONFIG_EXAMPLES_TCPECHO_IPADDR` – Target IP address, default `0x0a000002`.
+- `CONFIG_EXAMPLES_TCPECHO_DRIPADDR` – Default Router IP address (Gateway),
+ default `0x0a000001`.
+- `CONFIG_EXAMPLES_TCPECHO_NETMASK` – Network Mask, default `0xffffff00`.
- This is the same test as examples/udp and similar to examples/udgram,
- but using Unix domain stream sockets.
+## `telnetd` Simple Telnet Shell
- Dependencies:
- CONFIG_NET_LOCAL - Depends on support for Unix domain sockets
+This directory contains a functional port of the tiny uIP shell. In the NuttX
+environment, the NuttShell (at `apps/nshlib`) supersedes this tiny shell and
+also supports `telnetd`.
- Configuration:
- CONFIG_EXAMPLES_USTREAM - Enables the Unix domain socket example.
- CONFIG_EXAMPLES_USTREAM_ADDR - Specifics the Unix domain address.
- Default "/dev/fifo".
+- `CONFIG_EXAMPLES_TELNETD` – Enable the Telnetd example.
+- `CONFIG_NETUTILS_NETLIB`, `CONFIG_NETUTILS_TELNED` – Enable netutils libraries
+ needed by the Telnetd example.
+- `CONFIG_EXAMPLES_TELNETD_DAEMONPRIO` – Priority of the Telnet daemon. Default:
+ `SCHED_PRIORITY_DEFAULT`.
+- `CONFIG_EXAMPLES_TELNETD_DAEMONSTACKSIZE` – Stack size allocated for the
+ Telnet daemon. Default: `2048`.
+- `CONFIG_EXAMPLES_TELNETD_CLIENTPRIO` – Priority of the Telnet client. Default:
+ `SCHED_PRIORITY_DEFAULT`.
+- `CONFIG_EXAMPLES_TELNETD_CLIENTSTACKSIZE` – Stack size allocated for the
+ Telnet client. Default: `2048`.
+- `CONFIG_EXAMPLES_TELNETD_NOMAC` – If the hardware has no MAC address of its
+ own, define this `=y` to provide a bogus address for testing.
+- `CONFIG_EXAMPLES_TELNETD_IPADDR` – The target IP address. Default `10.0.0.2`.
+- `CONFIG_EXAMPLES_TELNETD_DRIPADDR` – The default router address. Default
+ `10.0.0.1`.
+- `CONFIG_EXAMPLES_TELNETD_NETMASK` – The network mask. Default:
+ `255.255.255.0`.
-examples/watchdog
-^^^^^^^^^^^^^^^^^
+Also, make sure that you have the following set in the NuttX configuration file
+or else the performance will be very bad (because there will be only one
+character per TCP transfer):
+
+- `CONFIG_STDIO_BUFFER_SIZE` – Some value `>= 64`
+- `CONFIG_STDIO_LINEBUFFER=y`
+
+## `thttpd` THTTPD server
- A simple test of a watchdog timer driver. Initializes starts the watchdog
- timer. It pings the watchdog timer for a period of time then lets the
- watchdog timer expire... resetting the CPU is successful. This
- example can ONLY be built as an NSH built-in function.
+An example that builds `netutils/thttpd` with some simple NXFLAT CGI programs.
+See `boards/README.txt` for most THTTPD settings. In addition to those, this
+example accepts:
- This test depends on these specific Watchdog/NSH configurations settings (your
- specific watchdog hardware settings might require additional settings).
+- `CONFIG_EXAMPLES_THTTPD_NOMAC` – (May be defined to use software assigned
+ MAC)
+- `CONFIG_EXAMPLES_THTTPD_DRIPADDR` – Default router IP address.
+- `CONFIG_EXAMPLES_THTTPD_NETMASK` – Network mask.
- CONFIG_WATCHDOG- Enables watchdog timer support support.
- CONFIG_NSH_BUILTIN_APPS - Build the watchdog time test as an NSH
- built-in function.
+Applications using this example will need to enable the following `netutils`
+libraries in the `defconfig` file:
- Specific configuration options for this example include:
+```conf
+CONFIG_NETUTILS_NETLIB=y
+CONFIG_NETUTILS_THTTPD=y
+```
- CONFIG_EXAMPLES_WATCHDOG_DEVPATH - The path to the Watchdog device.
- Default: /dev/watchdog0
- CONFIG_EXAMPLES_WATCHDOG_PINGTIME - Time in milliseconds that the example
- will ping the watchdog before letting the watchdog expire. Default: 5000
- milliseconds
- CONFIG_EXAMPLES_WATCHDOG_PINGDELAY - Time delay between pings in
- milliseconds. Default: 500 milliseconds.
- CONFIG_EXAMPLES_WATCHDOG_TIMEOUT - The watchdog timeout value in
- milliseconds before the watchdog timer expires. Default: 2000
- milliseconds.
+## `tiff`
-examples/webserver
-^^^^^^^^^^^^^^^^^^
+This is a simple unit test for the TIFF creation library at `apps/graphic/tiff`.
+It is configured to work in the Linux user-mode simulation and has not been
+tested in any other environment.
- This is a port of uIP tiny webserver example application. Settings
- specific to this example include:
+At a minimum, to run in an embedded environment, you will probably have to
+change the configured paths to the TIFF files defined in the example.
- CONFIG_EXAMPLES_WEBSERVER_NOMAC - (May be defined to use software assigned MAC)
- CONFIG_EXAMPLES_WEBSERVER_IPADDR - Target IP address
- CONFIG_EXAMPLES_WEBSERVER_DRIPADDR - Default router IP address
- CONFIG_EXAMPLES_WEBSERVER_NETMASK - Network mask
- CONFIG_EXAMPLES_WEBSERVER_DHCPC - Select to get IP address via DHCP
+- `CONFIG_EXAMPLES_TIFF_OUTFILE` – Name of the resulting TIFF file. Default is
+ `/tmp/result.tif`.
+- `CONFIG_EXAMPLES_TIFF_TMPFILE1/2` – Names of two temporaries files that will
+ be used in the file creation. Defaults are `/tmp/tmpfile1.dat` and
+ `/tmp/tmpfile2.dat`.
- If you use DHCPC, then some special configuration network options are
- required. These include:
+The following must also be defined in your `apps/` configuration file:
- CONFIG_NET=y - Of course
- CONFIG_NET_UDP=y - UDP support is required for DHCP
- (as well as various other UDP-related
- configuration settings).
- CONFIG_NET_BROADCAST=y - UDP broadcast support is needed.
- CONFIG_NET_ETH_PKTSIZE=650 - Per RFC2131 (p. 9), the DHCP client must be
- (or larger) prepared to receive DHCP messages of up to
- 576 bytes (excluding Ethernet, IP, or UDP
- headers and FCS).
- NOTE: Note that the actual MTU setting will
- depend upon the specific link protocol.
- Here Ethernet is indicated.
+```conf
+CONFIG_EXAMPLES_TIFF=y
+CONFIG_GRAPHICS_TIFF=y
+```
- Other configuration items apply also to the selected webserver net utility.
- Additional relevant settings for the uIP webserver net utility are:
+## `timer`
- CONFIG_NETUTILS_HTTPDSTACKSIZE
- CONFIG_NETUTILS_HTTPDFILESTATS
- CONFIG_NETUTILS_HTTPDNETSTATS
+This is a simple test of the timer driver (see `include/nuttx/timers/timer.h`).
+
+Dependencies:
+
+- `CONFIG_TIMER` – The timer driver must be selected
+
+Example configuration:
+
+- `CONFIG_EXAMPLES_TIMER_DEVNAME` – This is the name of the timer device that
+ will be tested. Default: `/dev/timer0`.
+- `CONFIG_EXAMPLES_TIMER_INTERVAL` – This is the timer interval in microseconds.
+ Default: `1000000`.
+- `CONFIG_EXAMPLES_TIMER_DELAY` – This is the delay between timer samples in
+ microseconds. Default: `10000`.
+- `CONFIG_EXAMPLES_TIMER_STACKSIZE` – This is the stack size allocated when the
+ timer task runs. Default: `2048`.
+- `CONFIG_EXAMPLES_TIMER_PRIORITY` – This is the priority of the timer task:
+ Default: `100`.
+- `CONFIG_EXAMPLES_TIMER_PROGNAME` – This is the name of the program that will
+ be used when the NSH ELF program is installed. Default: `timer`.
+
+## `touchscreen` Touchscreen Events
+
+This configuration implements a simple touchscreen test at
+`apps/examples/touchscreen`. This test will create an empty X11 window and will
+print the touchscreen output as it is received from the simulated touchscreen
+driver.
+
+- `CONFIG_NSH_BUILTIN_APPS` – Build the touchscreen test as an NSH built-in
+ function. Default: Built as a standalone program.
+- `CONFIG_EXAMPLES_TOUCHSCREEN_MINOR` – The minor device number. Minor `N`
+ corresponds to touchscreen device `/dev/inputN`. Note this value must with
+ `CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH`. Default `0`.
+- `CONFIG_EXAMPLES_TOUCHSCREEN_DEVPATH` – The path to the touchscreen device.
+ This must be consistent with `CONFIG_EXAMPLES_TOUCHSCREEN_MINOR`. Default:
+ `/dev/input0`.
+- `CONFIG_EXAMPLES_TOUCHSCREEN_NSAMPLES` – This number of samples is collected
+ and the program terminates. Default: Samples are collected indefinitely.
+- `CONFIG_EXAMPLES_TOUCHSCREEN_MOUSE` – The touchscreen test can also be
+ configured to work with a mouse driver by setting this option.
- Applications using this example will need to enable the following
- netutils libraries in their defconfig file:
+The following additional configurations must be set in the NuttX configuration
+file:
- CONFIG_NETUTILS_NETLIB=y
- CONFIG_NETUTILS_DHCPC=y
- CONFIG_NETDB_DNSCLIENT=y
- CONFIG_NETUTILS_WEBSERVER=y
+- `CONFIG_INPUT=y` (plus any touchscreen-specific settings)
- NOTE: This example does depend on the perl script at
- nuttx/tools/mkfsdata.pl. You must have perl installed on your
- development system at /usr/bin/perl.
+The following must also be defined in your apps configuration file:
-examples/wget
-^^^^^^^^^^^^^
+- `CONFIG_EXAMPLES_TOUCHSREEN=y`
- A simple web client example. It will obtain a file from a server using the HTTP
- protocol. Settings unique to this example include:
+This example code will call `boardctl()` to setup the touchscreen driver for
+texting. The implementation of `boardctl()` will require that board- specific
+logic provide the following interfaces that will be called by the `boardctl()`
+in order to initialize the touchscreen hardware:
- CONFIG_EXAMPLES_WGET_URL - The URL of the file to get
- CONFIG_EXAMPLES_WGET_NOMAC - (May be defined to use software assigned MAC)
- CONFIG_EXAMPLES_WGET_IPADDR - Target IP address
- CONFIG_EXAMPLES_WGET_DRIPADDR - Default router IP address
- CONFIG_EXAMPLES_WGET_NETMASK - Network mask
+```c
+int board_tsc_setup(int minor);
+```
- This example uses netutils/webclient. Additional configuration settings apply
- to that code as follows (but built-in defaults are probably OK):
-
- CONFIG_WEBCLIENT_GETMIMETYPE, CONFIG_WEBCLIENT_MAXHTTPLINE,
- CONFIG_WEBCLIENT_MAXMIMESIZE, CONFIG_WEBCLIENT_MAXHOSTNAME,
- CONFIG_WEBCLIENT_MAXFILENAME
-
- Of course, the example also requires other settings including CONFIG_NET and
- CONFIG_NET_TCP. The example also uses the uIP resolver which requires CONFIG_UDP.
-
- WARNNG: As of this writing, wget is untested on the target platform. At present
- it has been tested only in the host-based configuration described in the following
- note. The primary difference is that the target version will rely on the also
- untested uIP name resolver.
-
- NOTE: For test purposes, this example can be built as a host-based wget function.
- This can be built as follows:
-
- cd examples/wget
- make -f Makefile.host
+## `udp` Client/Server Over UDP
- Applications using this example will need to enable the following netutils
- libraries in the defconfig file:
+This is a simple network test for verifying client- and server- functionality
+over UDP.
- CONFIG_NETUTILS_NETLIB=y
- CONFIG_NETDB_DNSCLIENT=y
- CONFIG_NETUTILS_WEBCLIENT=y
+Applications using this example will need to enabled the following `netutils`
+libraries in the `defconfig` file:
-examples/wget
-^^^^^^^^^^^^^
-
- Uses wget to get a JSON encoded file, then decodes the file.
-
- CONFIG_EXAMPLES_WDGETJSON_MAXSIZE - Max. JSON Buffer Size
- CONFIG_EXAMPLES_EXAMPLES_WGETJSON_URL - wget URL
+- `CONFIG_NETUTILS_NETLIB=y`
-examples/xmlrpc
-^^^^^^^^^^^^^^^
+Possible configurations:
- This example exercises the "Embeddable Lightweight XML-RPC Server" which
- is discussed at:
+- Server on target hardware; client on host.
+- Client on target hardware; Server on host.
+- Server and Client on different targets.
- http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364
+## `udpblaster`
- Configuration options:
+This is a simple network test for stressing UDP transfers. It simply sends UDP
+packets from both the host and the target and the highest possible rate.
- CONFIG_EXAMPLES_XMLRPC_BUFFERSIZE - HTTP buffer size. Default 1024
- CONFIG_EXAMPLES_XMLRPC_DHCPC - Use DHCP Client. Default n. Ignored
- if CONFIG_NSH_NETINIT is selected.
- CONFIG_EXAMPLES_XMLRPC_NOMAC - Use Canned MAC Address. Default n. Ignored
- if CONFIG_NSH_NETINIT is selected.
- CONFIG_EXAMPLES_XMLRPC_IPADDR - Target IP address. Default 0x0a000002.
- Ignored if CONFIG_NSH_NETINIT is selected.
- CONFIG_EXAMPLES_XMLRPC_DRIPADDR - Default Router IP address (Gateway).
- Default 0x0a000001. Ignored if CONFIG_NSH_NETINIT is selected.
- CONFIG_EXAMPLES_XMLRPC_NETMASK - Network Mask. Default 0xffffff00
- Ignored if CONFIG_NSH_NETINIT is selected.
+## `unionfs` Union File System
-examples/zerocross
-^^^^^^^^^^^^^^^^^^
+This is at trivial test of the Union File System. See
+`nuttx/fs/unionfs/README.txt`. Dependencies:
- A simple test of the Zero Crossing device driver.
+- `CONFIG_DISABLE_MOUNTPOINT` – Mountpoint support must not be
+ disabled.
+- `CONFIG_NFILE_DESCRIPTORS > 4` – Some file descriptors must be
+ allocated.
+- `CONFIG_FS_ROMFS` – ROMFS support is required.
+- `CONFIG_FS_UNIONFS` – Union File System support is required.
+
+Configuration options. Use the defaults if you are unsure of what you are doing:
+
+- `CONFIG_EXAMPLES_UNIONFS` – Enables the example.
+- `CONFIG_EXAMPLES_UNIONFS_MOUNTPT` – Mountpoint path for the Union File
+ System.
+- `CONFIG_EXAMPLES_UNIONFS_TMPA` – Temporary mount point for file system
+ `1`.
+- `CONFIG_EXAMPLES_UNIONFS_TMPB` – Temporary mount point for file system
+ `2`.
+- `CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_A` – ROMFS file system `1` RAM disk device
+ number.
+- `CONFIG_EXAMPLES_UNIONFS_RAMDEVNO_B` – ROMFS file system `2` RAM disk device
+ number.
+- `CONFIG_EXAMPLES_UNIONFS_SECTORSIZE` – ROM disk sector size.
+
+See the `README.txt` file at `nuttx/boards/sim/sim/sim/README.txt` for a
+walk-through of the output of this text.
+
+## `usbserial` USB Serial Hello World
+
+### Target configuration
+
+This is another implementation of _Hello, World_ but this one uses a USB serial
+driver. Configuration options can be used to simply the test. These options
+include:
+
+- `CONFIG_EXAMPLES_USBSERIAL_INONLY` – Only verify IN (device-to-host) data
+ transfers. Default: both.
+- `CONFIG_EXAMPLES_USBSERIAL_OUTONLY` – Only verify OUT (host-to-device) data
+ transfers. Default: both.
+- `CONFIG_EXAMPLES_USBSERIAL_ONLYSMALL` – Send only small, single packet
+ messages. Default: Send large and small.
+- `CONFIG_EXAMPLES_USBSERIAL_ONLYBIG` – Send only large, multi-packet messages.
+ Default: Send large and small.
+
+If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and
+`CONFIG_DEBUG_USB`), then the example code will also manage the USB trace
+output. The amount of trace output can be controlled using:
+
+- `CONFIG_EXAMPLES_USBSERIAL_TRACEINIT` – Show initialization events.
+- `CONFIG_EXAMPLES_USBSERIAL_TRACECLASS` – Show class driver events.
+- `CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS` – Show data transfer events.
+- `CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER` – Show controller events.
+- `CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS` – Show interrupt-related events.
+
+Error results are always shown in the trace output.
+
+### Host-side test program
+
+In additional to the target device-side example, there is also a host-side
+application in this directory. This host side application must be executed on a
+Linux host in order to perform the `USBSERIAL` test. The host application can be
+compiled under Linux (or Cygwin?) as follows:
+
+```bash
+cd examples/usbserial
+make -f Makefile.host TOPDIR=<nuttx-directory>
+```
+
+### Running the test
+
+This will generate a small program called `host`. Usage:
+
+1. Build the `examples/usbserial` target program and start the target.
+
+2. Wait a bit, then do enter:
+
+ ```shell
+ dmesg
+ ```
+
+ At the end of the dmesg output, you should see the serial device was
+ successfully idenfied and assigned to a tty device, probably `/dev/ttyUSB0`
+ or `/dev/ttyACM0` (depending on the configured USB serial driver).
+
+3. Then start the host application:
+
+ ```bash
+ ./host [<tty-dev>]
+ ```
+
+ Where:
+
+ - `<tty-dev>` is the USB TTY device to use. The default is `/dev/ttyUSB0`
+ (for the PL2303 emulation) or `/dev/ttyACM0` (for the CDC/ACM serial
+ device).
+
+The host and target will exchange are variety of very small and very large
+serial messages.
+
+## `userfs` UserFS File System
+
+A simple test of the UserFS file system.
+
+## `ustream` Unix Datagram Sockets
+
+This is the same test as `examples/udp` and similar to `examples/ustream`, but
+using Unix domain datagram sockets.
+
+Dependencies:
+
+- `CONFIG_NET_LOCAL` – Depends on support for Unix domain sockets.
+
+Configuration:
+
+- `CONFIG_EXAMPLES_UDGRAM` – Enables the Unix domain socket example.
+- `CONFIG_EXAMPLES_UDGRAM_ADDR` – Specifics the Unix domain address. Default:
+ `/dev/fifo`.
+
+## `ustream` Unix Stream Sockets
+
+This is the same test as `examples/udp` and similar to `examples/udgram`, but
+using Unix domain stream sockets.
+
+Dependencies:
+
+- `CONFIG_NET_LOCAL` – Depends on support for Unix domain sockets.
+
+Configuration:
+
+- `CONFIG_EXAMPLES_USTREAM` – Enables the Unix domain socket example.
+- `CONFIG_EXAMPLES_USTREAM_ADDR` – Specifics the Unix domain address. Default:
+ `/dev/fifo`.
+
+## `watchdog` Watchdog Timer
+
+A simple test of a watchdog timer driver. Initializes starts the watchdog timer.
+It pings the watchdog timer for a period of time then lets the watchdog timer
+expire... resetting the CPU is successful. This example can ONLY be built as an
+NSH built-in function.
+
+This test depends on these specific Watchdog/NSH configurations settings (your
+specific watchdog hardware settings might require additional settings).
+
+- `CONFIG_WATCHDOG` – Enables watchdog timer support support.
+- `CONFIG_NSH_BUILTIN_APPS` – Build the watchdog time test as an NSH built-in
+ function.
+
+Specific configuration options for this example include:
+
+- `CONFIG_EXAMPLES_WATCHDOG_DEVPATH` – The path to the Watchdog device. Default:
+ `/dev/watchdog0`.
+- `CONFIG_EXAMPLES_WATCHDOG_PINGTIME` – Time in milliseconds that the example
+ will ping the watchdog before letting the watchdog expire. Default: `5000`
+ milliseconds.
+- `CONFIG_EXAMPLES_WATCHDOG_PINGDELAY` – Time delay between pings in
+ milliseconds. Default: `500` milliseconds.
+- `CONFIG_EXAMPLES_WATCHDOG_TIMEOUT` – The watchdog timeout value in
+ milliseconds before the watchdog timer expires. Default: `2000` milliseconds.
+
+## `webserver` Simple Webserver
+
+This is a port of uIP tiny webserver example application. Settings specific to
+this example include:
+
+- `CONFIG_EXAMPLES_WEBSERVER_NOMAC` (may be defined to use software assigned
+ MAC)
+- `CONFIG_EXAMPLES_WEBSERVER_IPADDR` – Target IP address.
+- `CONFIG_EXAMPLES_WEBSERVER_DRIPADDR` – Default router IP address.
+- `CONFIG_EXAMPLES_WEBSERVER_NETMASK` – Network mask.
+- `CONFIG_EXAMPLES_WEBSERVER_DHCPC` – Select to get IP address via DHCP.
+
+If you use DHCPC, then some special configuration network options are required.
+These include:
+
+- `CONFIG_NET=y` – of course.
+- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various
+ other UDP-related configuration settings).
+- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed.
+- `CONFIG_NET_ETH_PKTSIZE=650` or larger. Per RFC2131 (p. 9), the DHCP client
+ must be prepared to receive DHCP messages of up to `576` bytes (excluding
+ Ethernet, IP, or UDP headers and FCS). **Note** that the actual MTU setting
+ will depend upon the specific link protocol. Here Ethernet is indicated.
+
+Other configuration items apply also to the selected `webserver` net utility.
+Additional relevant settings for the uIP `webserver` net utility are:
+
+- `CONFIG_NETUTILS_HTTPDSTACKSIZE`
+- `CONFIG_NETUTILS_HTTPDFILESTATS`
+- `CONFIG_NETUTILS_HTTPDNETSTATS`
+
+Applications using this example will need to enable the following `netutils`
+libraries in their `defconfig` file:
+
+```conf
+CONFIG_NETUTILS_NETLIB=y
+CONFIG_NETUTILS_DHCPC=y
+CONFIG_NETDB_DNSCLIENT=y
+CONFIG_NETUTILS_WEBSERVER=y
+```
+
+**Note**: This example does depend on the `perl` script at
+`nuttx/tools/mkfsdata.pl`. You must have `perl` installed on your development
+system at `/usr/bin/perl`.
+
+## `wget` Web Client
+
+A simple web client example. It will obtain a file from a server using the HTTP
+protocol. Settings unique to this example include:
+
+- `CONFIG_EXAMPLES_WGET_URL` – The URL of the file to get
+- `CONFIG_EXAMPLES_WGET_NOMAC` – (May be defined to use software assigned MAC)
+- `CONFIG_EXAMPLES_WGET_IPADDR` – Target IP address
+- `CONFIG_EXAMPLES_WGET_DRIPADDR` – Default router IP address
+- `CONFIG_EXAMPLES_WGET_NETMASK` – Network mask
+
+This example uses `netutils/webclient`. Additional configuration settings apply
+to that code as follows (but built-in defaults are probably OK):
+
+- `CONFIG_WEBCLIENT_GETMIMETYPE`
+- `CONFIG_WEBCLIENT_MAXHTTPLINE`
+- `CONFIG_WEBCLIENT_MAXMIMESIZE`
+- `CONFIG_WEBCLIENT_MAXHOSTNAME`
+- `CONFIG_WEBCLIENT_MAXFILENAME`
+
+Of course, the example also requires other settings including `CONFIG_NET` and
+`CONFIG_NET_TCP`. The example also uses the uIP resolver which requires
+`CONFIG_UDP`.
+
+**Warning**: As of this writing, `wget` is untested on the target platform. At
+present it has been tested only in the host-based configuration described in the
+following note. The primary difference is that the target version will rely on
+the also untested uIP name resolver.
+
+**Note**: For test purposes, this example can be built as a host-based `wget`
+function. This can be built as follows:
+
+```bash
+cd examples/wget
+make -f Makefile.host
+```
+
+Applications using this example will need to enable the following `netutils`
+libraries in the `defconfig` file:
+
+```conf
+CONFIG_NETUTILS_NETLIB=y
+CONFIG_NETDB_DNSCLIENT=y
+CONFIG_NETUTILS_WEBCLIENT=y
+```
+
+## `wgetjson` GET JSON Using `wget`
+
+Uses `wget` to get a JSON encoded file, then decodes the file.
+
+- `CONFIG_EXAMPLES_WDGETJSON_MAXSIZE` – Max. JSON Buffer Size.
+- `CONFIG_EXAMPLES_EXAMPLES_WGETJSON_URL` – `wget` URL
+
+## `xmlrpc` XML-RPC Server
+
+This example exercises the _Embeddable Lightweight XML-RPC Server_ which is
+discussed at:
+
+http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364
+
+Configuration options:
+
+- `CONFIG_EXAMPLES_XMLRPC_BUFFERSIZE` – HTTP buffer size. Default `1024`
+- `CONFIG_EXAMPLES_XMLRPC_DHCPC` – Use DHCP Client. Default `n`. Ignored if
+ `CONFIG_NSH_NETINIT` is selected.
+- `CONFIG_EXAMPLES_XMLRPC_NOMAC` – Use Canned MAC Address. Default `n`. Ignored
+ if `CONFIG_NSH_NETINIT` is selected.
+- `CONFIG_EXAMPLES_XMLRPC_IPADDR` – Target IP address. Default `0x0a000002`.
+ Ignored if `CONFIG_NSH_NETINIT` is selected.
+- `CONFIG_EXAMPLES_XMLRPC_DRIPADDR` – Default Router IP address (Gateway).
+ Default `0x0a000001`. Ignored if `CONFIG_NSH_NETINIT` is selected.
+- `CONFIG_EXAMPLES_XMLRPC_NETMASK` – Network Mask. Default `0xffffff00`. Ignored
+ if `CONFIG_NSH_NETINIT` is selected.
+
+## `zerocross` Zero Crossing Device
+
+A simple test of the Zero Crossing device driver.
diff --git a/examples/bastest/README.md b/examples/bastest/README.md
index 40c3cb1..b4c0baf 100644
--- a/examples/bastest/README.md
+++ b/examples/bastest/README.md
@@ -1,61 +1,58 @@
-README
-======
-
- This directory contains a small program that will mount a ROMFS file system
- containing the BASIC test files extracted from the BAS 2.4 release.
-
-Background
-==========
- Bas is an interpreter for the classic dialect of the programming language
- BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s,
- unlike some other UNIX BASIC interpreters, that implement a different
- syntax, breaking compatibility to existing programs. Bas offers many ANSI
- BASIC statements for structured programming, such as procedures, local
- variables and various loop types. Further there are matrix operations,
- automatic LIST indentation and many statements and functions found in
- specific classic dialects. Line numbers are not required.
-
- 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.
-
-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
-
- Copyright (c) 1999-2014 Michael Haardt
-
- 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 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- THE SOFTWARE.
-
-TEST OVERVIEW
-=============
-
-test01.bas
-==========
+# Examples / `bastest` Bas BASIC Tests
+
+This directory contains a small program that will mount a ROMFS file system
+containing the BASIC test files extracted from the BAS `2.4` release.
+
+## Background
+
+Bas is an interpreter for the classic dialect of the programming language BASIC.
+It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some
+other UNIX BASIC interpreters, that implement a different syntax, breaking
+compatibility to existing programs. Bas offers many ANSI BASIC statements for
+structured programming, such as procedures, local variables and various loop
+types. Further there are matrix operations, automatic LIST indentation and many
+statements and functions found in specific classic dialects. Line numbers are
+not required.
+
+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.
+
+## 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
+
+Copyright (c) 1999-2014 Michael Haardt
+
+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 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# Test Overview
+
+## `test01.bas`
+
Scalar variable assignment
-Test File
----------
+### Test File
+
+```basic
10 a=1
20 print a
30 a$="hello"
@@ -66,27 +63,31 @@ Test File
80 print a
90 a=.2e-6
100 print a
+```
-Expected Result
----------------
+### Expected Result
+
+```
1
hello
0.0002
0.000
0.0000020
0.0000002
+```
+
+### Notes
+
+Output would differ on other platforms NttX does not use scientific notation in
+floating point output.
-Notes
------
- Output would differ on other platforms NttX does not use scientific
- notation in floating point output.
+## `test02.bas`
-test02.bas
-==========
Array variable assignment
-Test File
----------
+### Test File
+
+```basic
10 dim a(1)
20 a(0)=10
30 a(1)=11
@@ -94,19 +95,23 @@ Test File
50 print a(0)
60 print a(1)
70 print a
+```
+
+### Expected Result
-Expected Result
----------------
+```
10
11
12
+```
+
+## `test03.bas`
-test03.bas
-==========
-FOR loops
+`FOR` loops
-Test File
----------
+### Test File
+
+```basic
10 for i=0 to 10
20 print i
30 if i=5 then exit for
@@ -123,9 +128,11 @@ Test File
140 for i$="" to "aaaaaaaaaa" step "a"
150 print i$
160 next
+```
+
+### Expected Result
-Expected Result
----------------
+```
0
1
2
@@ -146,21 +153,25 @@ aaaaaaa
aaaaaaaa
aaaaaaaaa
aaaaaaaaaa
+```
-test04.bas
-==========
-REPEAT UNTIL loop
+## `test04.bas`
-Test File
----------
+`REPEAT` `UNTIL` loop
+
+### Test File
+
+```basic
10 a=1
20 repeat
30 print a
40 a=a+1
50 until a=10
+```
+
+### Expected Result
-Expected Result
----------------
+```
1
2
3
@@ -170,13 +181,15 @@ Expected Result
7
8
9
+```
-test05.bas
-==========
-GOSUB RETURN subroutines
+## `test05.bas`
-Test File
----------
+`GOSUB` `RETURN` subroutines
+
+### Test File
+
+```basic
10 gosub 100
20 gosub 100
30 end
@@ -184,20 +197,24 @@ Test File
110 gosub 200
120 return
200 print "hello, world":return
+```
+
+### Expected Result
-Expected Result
----------------
+```
hello, world
hello, world
hello, world
hello, world
+```
+
+## `test06.bas`
-test06.bas
-==========
Recursive function without arguments
-Test File
----------
+### Test File
+
+```basic
10 def fnloop
20 if n=0.0 then
30 r=0.0
@@ -209,9 +226,11 @@ Test File
90 =r
100 n=10
110 print fnloop
+```
+
+### Expected Result
-Expected Result
----------------
+```
10
9
8
@@ -223,28 +242,34 @@ Expected Result
2
1
0
+```
+
+## `test07.bas`
-test07.bas
-==========
Recursive function with arguments
-Test File
----------
+### Test File
+
+```basic
10 def fna(x)
20 if x=0 then r=1 else r=x*fna(x-1)
30 =r
40 print fna(7)
+```
-Expected Result
----------------
- 5040
+### Expected Result
-test08.bas
-==========
-DATA, READ and RESTORE
+```
+5040
+```
-Test File
----------
+## `test08.bas`
+
+`DATA`, `READ` and `RESTORE`
+
+### Test File
+
+```basic
10 data "a",b
20 data "c","d
40 read j$
@@ -254,21 +279,25 @@ Test File
80 read j$,k$
90 print "j=";j$;" k=";k$
100 next
+```
-Expected Result
----------------
+### Expected Result
+
+```
j=a
j=c k=d
Error: end of `data' in line 80 at:
80 read j$,k$
^
+```
+
+## `test09.bas`
+
+`LOCAL` variables
-test09.bas
-==========
-LOCAL variables
+### Test File
-Test File
----------
+```basic
10 def fna(a)
20 local b
30 b=a+1
@@ -277,19 +306,23 @@ Test File
70 print b
80 print fna(4)
90 print b
+```
-Expected Result
----------------
+### Expected Result
+
+```
3
5
3
+```
+
+## `test10.bas`
+
+`PRINT USING`
-test10.bas
-==========
-PRINT USING
+### Test File
-Test File
----------
+```basic
10 print using "!";"abcdef"
20 print using "\ \";"abcdef"
30 print using "###-";-1
@@ -320,9 +353,11 @@ Test File
280 print using "a!b";"S","T"
290 print using "a!b!c";"S"
300 print using "a!b!c";"S","T"
+```
-Expected Result
----------------
+### Expected Result
+
+```
a
abc
1-
@@ -353,33 +388,39 @@ aSb
aSbaTb
aSb
aSbTc
+```
+
+## `test11.bas`
-test11.bas
-==========
-OPEN and LINE INPUT
+`OPEN` and `LINE INPUT`
-Test File
----------
+### Test File
+
+```basic
10 open "i",1,"test.bas"
20 while not eof(1)
30 line input #1,a$
40 print a$
50 wend
+```
+
+### Expected Result
-Expected Result
----------------
+```basic
10 open "i",1,"test.bas"
20 while not eof(1)
30 line input #1,a$
40 print a$
50 wend
+```
+
+## `test12.bas`
-test12.bas
-==========
Exception handling
-Test File
----------
+### Test File
+
+```basic
10 on error print "global handler 1 caught error in line ";erl : resume 30
20 print mid$("",-1)
30 on error print "global handler 2 caught error in line ";erl : end
@@ -389,35 +430,43 @@ Test File
70 end proc
80 procx
90 print 1 mod 0
+```
+
+### Expected Result
-Expected Result
----------------
+```
global handler 1 caught error in line 20
local handler caught error in line 60
global handler 2 caught error in line 90
+```
+
+## `test13.bas`
-test01.bas
-==========
Unnumbered lines
-Test File
----------
+### Test File
+
+```basic
print "a"
goto 20
print "b"
20 print "c"
+```
+
+### Expected Result
-Expected Result
----------------
+```
a
c
+```
+
+## `test14.bas`
-test14.bas
-==========
-SELECT CASE
+`SELECT CASE`
-Test File
----------
+### Test File
+
+```basic
10 for i=0 to 9
20 for j=0 to 9
30 print i,j
@@ -439,9 +488,11 @@ Test File
190 end select
200 next
210 next
+```
+
+### Expected Result
-Expected Result
----------------
+```
0 0
i after case 0
0 1
@@ -643,13 +694,15 @@ i after case else
i after case else
9 9
i after case else
+```
-test15.bas
-==========
-FIELD, PUT and GET
+## `test15.bas`
-Test File
----------
+`FIELD`, `PUT` and `GET`
+
+### Test File
+
+```basic
a$="a"
open "r",1,"test.dat",128
print "before field a$=";a$
@@ -667,20 +720,24 @@ get #2
print "after get b$=";b$
close #2
kill "test.dat"
+```
+
+### Expected Result
-Expected Result
----------------
+```
before field a$=a
a$=hi ya
after close a$=
after get b$=hi ya
+```
-test16.bas
-==========
-SWAP
+## `test16.bas`
-Test File
----------
+`SWAP`
+
+### Test File
+
+```basic
a=1 : b=2
print "a=";a;"b=";b
swap a,b
@@ -690,20 +747,24 @@ a$(1,0)="a" : b$(0,1)="b"
print "a$(1,0)=";a$(1,0);"b$(0,1)=";b$(0,1)
swap a$(1,0),b$(0,1)
print "a$(1,0)=";a$(1,0);"b$(0,1)=";b$(0,1)
+```
+
+### Expected Result
-Expected Result
----------------
+```
a= 1 b= 2
a= 2 b= 1
a$(1,0)=ab$(0,1)=b
a$(1,0)=bb$(0,1)=a
+```
-test17.bas
-==========
-DO, EXIT DO, LOOP
+## `test17.bas`
-Test File
----------
+`DO`, `EXIT DO`, `LOOP`
+
+### Test File
+
+```basic
print "loop started"
i=1
do
@@ -712,9 +773,11 @@ do
if i>10 then exit do
loop
print "loop ended"
+```
+
+### Expected Result
-Expected Result
----------------
+```
loop started
i is 1
i is 2
@@ -727,13 +790,15 @@ i is 8
i is 9
i is 10
loop ended
+```
+
+## `test18.bas`
+
+`DO WHILE`, `LOOP`
-test18.bas
-==========
-DO WHILE, LOOP
+### Test File
-Test File
----------
+```basic
print "loop started"
x$=""
do while len(x$)<3
@@ -746,9 +811,11 @@ do while len(x$)<3
loop
loop
print "loop ended"
+```
-Expected Result
----------------
+### Expected Result
+
+```
loop started
x$ is
y$ is
@@ -760,13 +827,15 @@ x$ is aa
y$ is
y$ is b
loop ended
+```
+
+## `test19.bas`
+
+`ELSEIF`
-test19.bas
-==========
-ELSEIF
+### Test File
-Test File
----------
+```basic
for x=1 to 3
if x=1 then
print "1a"
@@ -786,22 +855,26 @@ for x=1 to 3
print "2b"
elseif x=3 then print "3b"
next
+```
-Expected Result
----------------
+### Expected Result
+
+```
1a
2a
3a
1b
2b
3b
+```
+
+## `test20.bas`
-test20.bas
-==========
Caller trace
-Test File
----------
+### Test File
+
+```basic
10 gosub 20
20 gosub 30
30 procb
@@ -812,9 +885,11 @@ Test File
80 def procb
90 proca
100 end proc
+```
-Expected Result
----------------
+### Expected Result
+
+```
hi
Break in line 60 at:
60 stop
@@ -831,13 +906,15 @@ Called in line 20 at:
Called in line 10 at:
10 gosub 20
^
+```
+
+## `test21.bas`
-test21.bas
-==========
Matrix assignment
-Test File
----------
+### Test File
+
+```basic
dim a(3,4)
for i=0 to 3
for j=0 to 4
@@ -853,9 +930,11 @@ for i=0 to 3
next
print
next
+```
-Expected Result
----------------
+### Expected Result
+
+```
0 1 2 3 4
10 11 12 13 14
20 21 22 23 24
@@ -864,13 +943,15 @@ Expected Result
0 11 12 13 14
0 21 22 23 24
0 31 32 33 34
+```
+
+## `test22.bas`
-test22.bas
-==========
-MAT PRINT
+`MAT PRINT`
-Test File
----------
+### Test File
+
+```basic
dim a(2,2)
for i=0 to 2
for j=0 to 2
@@ -884,9 +965,11 @@ for j=1 to 2
print
next
mat print using " ##.##";a,a
+```
+
+### Expected Result
-Expected Result
----------------
+```
11.00 21.00
12.00 22.00
11.00 12.00
@@ -894,13 +977,15 @@ Expected Result
11.00 12.00
21.00 22.00
+```
+
+## `test23.bas`
-test23.bas
-==========
Matrix addition and subtraction
-Test File
----------
+### Test File
+
+```basic
dim a(2,2)
a(2,2)=2.5
dim b%(2,2)
@@ -913,9 +998,11 @@ c$(2,1)="hi"
mat print c$
mat c$=c$+c$
mat print c$
+```
+
+### Expected Result
-Expected Result
----------------
+```
0 0
0 2.5
0 0
@@ -924,13 +1011,15 @@ Expected Result
hi
hihi
+```
+
+## `test24.bas`
-test24.bas
-==========
Matrix multiplication
-Test File
----------
+### Test File
+
+```basic
10 dim b(2,3),c(3,2)
20 for i=1 to 2 : for j=1 to 3 : read b(i,j) : next : next
30 for i=1 to 3 : for j=1 to 2 : read c(i,j) : next : next
@@ -938,9 +1027,11 @@ Test File
50 mat print b,c,a
60 data 1,2,3,3,2,1
70 data 1,2,2,1,3,3
+```
+
+### Expected Result
-Expected Result
----------------
+```
1 2 3
3 2 1
@@ -950,13 +1041,15 @@ Expected Result
14 13
10 11
+```
+
+## `test25.bas`
-test25.bas
-==========
Matrix scalar multiplication
-Test File
----------
+### Test File
+
+```basic
10 dim a(3,3)
20 for i=1 to 3 : for j=1 to 3 : read a(i,j) : next : next
30 mat print a
@@ -970,9 +1063,11 @@ Test File
110 mat print inch_array
120 mat cm_array=(2.54)*inch_array
130 mat print cm_array
+```
+
+### Expected Result
-Expected Result
----------------
+```
1 2 3
4 5 6
7 8 9
@@ -990,29 +1085,35 @@ Expected Result
91.44
254
99.9998
+```
+
+## `test26.bas`
-test26.bas
-==========
MAT READ
-Test File
----------
+### Test File
+
+```basic
dim a(3,3)
data 5,5,5,8,8,8,3,3
mat read a(2,3)
mat print a
+```
+
+### Expected Result
-Expected Result
----------------
+```
5 5 5
8 8 8
+```
+
+## `test27.bas`
-test27.bas
-==========
Matrix inversion
-Test File
----------
+### Test File
+
+```basic
data 1,2,3,4
mat read a(2,2)
mat print a
@@ -1020,81 +1121,99 @@ mat b=inv(a)
mat print b
mat c=a*b
mat print c
+```
+
+### Expected Result
-Expected Result
----------------
+```
1 2
3 4
-2 1
1.5 -0.5
1 0
0 1
+```
-test28.bas
-==========
-TDL BASIC FNRETURN/FNEND
+## `test28.bas`
-Test File
----------
+TDL BASIC `FNRETURN`/`FNEND`
+
+### Test File
+
+```basic
def fnfac(n)
if n=1 then fnreturn 1
fnend n*fnfac(n-1)
print fnfac(10)
+```
+
+### Expected Result
-Expected Result
----------------
+```
3628800
+```
+
+## `test29.bas`
-test29.bas
-==========
TDL INSTR
-Test File
----------
+### Test File
+
+```basic
print instr("123456789","456");" = 4?"
print INSTR("123456789","654");" = 0?"
print INSTR("1234512345","34");" = 3?"
print INSTR("1234512345","34",6);" = 8?"
print INSTR("1234512345","34",6,2);" = 0?"
print INSTR("1234512345","34",6,4);" = 8?"
+```
-Expected Result
----------------
+### Expected Result
+
+```
4 = 4?
0 = 0?
3 = 3?
8 = 8?
0 = 0?
8 = 8?
+```
+
+## `test30.bas`
-test30.bas
-==========
Type mismatch check
-Test File
----------
+### Test File
+
+```basic
print 1+"a"
+```
-Expected Result
----------------
+### Expected Result
+
+```
Error: Invalid binary operand at: end of program
+```
+
+## `test31.bas`
-test31.bas
-==========
PRINT default format
-Test File
----------
+### Test File
+
+```basic
10 for i=-8 to 8
20 x=1+1/3 : y=1 : j=i
30 for j=i to -1 : x=x/10 : y=y/10 : next
40 for j=i to 1 step -1 : x=x*10 : y=y*10 : next
50 print x,y
60 next
+```
-Expected Result
----------------
+### Expected Result
+
+```
0.0000000 0.0000000
0.0000001 0.0000001
0.0000013 0.0000010
@@ -1112,18 +1231,20 @@ Expected Result
1333333 1000000
13333333.3333333 10000000.0000000
133333333.3333333 100000000.0000000
+```
+
+### Notes
+
+Output would differ on other platforms NttX does not use scientific notation in
+floating point output.
-Notes
------
- Output would differ on other platforms NttX does not use scientific
- notation in floating point output.
+## `test32.bas`
-test032.bas
-==========
-SUB routines
+`SUB` routines
-Test File
----------
+### Test File
+
+```basic
PUTS("abc")
END
@@ -1131,17 +1252,21 @@ SUB PUTS(s$)
FOR i=1 to LEN(s$) : print mid$(s$,i,1); : NEXT
PRINT
END SUB
+```
+
+### Expected Result
-Expected Result
----------------
+```
abc
+```
-test33.bas
-==========
-OPEN FOR BINARY
+## `test33.bas`
-Test File
----------
+`OPEN FOR BINARY`
+
+### Test File
+
+```basic
open "/tmp/test.out" for binary as 1
put 1,1,"xy"
put 1,3,"z!"
@@ -1158,25 +1283,28 @@ print s$
print x
print n%
kill "/tmp/test.out"
+```
+
+### Expected Result
-Expected Result
----------------
+```
xyz!
0.333333
9999
+```
-Notes
------
- The logic in this test will fail if there is no writable file system
- mount at /tmp.
+### Notes
+The logic in this test will fail if there is no writable file system mount at
+`/tmp`.
-test34.bas
-==========
-OPTION BASE
+## `test34.bas`
-Test File
----------
+`OPTION BASE`
+
+### Test File
+
+```basic
option base 3
dim a(3,5)
a(3,3)=1
@@ -1194,22 +1322,26 @@ print a(3,3)
print a(3,5)
print b(-2,-2)
print b(-1,2)
+```
+
+### Expected Result
-Expected Result
----------------
+```
1
2
1
2
10
20
+```
+
+## `test35.bas`
-test35.bas
-==========
Real to integer conversion
-Test File
----------
+### Test File
+
+```basic
a%=1.2
print a%
a%=1.7
@@ -1218,20 +1350,24 @@ a%=-0.2
print a%
a%=-0.7
print a%
+```
+
+### Expected Result
-Expected Result
----------------
+```
1
2
0
-1
+```
+
+## `test36.bas`
+
+`OPEN` file locking
-test36.bas
-==========
-OPEN file locking
+### Test File
-Test File
----------
+```basic
on error goto 10
print "opening file"
open "/tmp/test.out" for output lock write as #1
@@ -1239,52 +1375,64 @@ print "open succeeded"
if command$<>"enough" then shell "sh ./test/runbas test.bas enough"
end
10 print "open failed"
+```
-Expected Result
----------------
+### Expected Result
+
+```
opening file
open succeeded
opening file
open failed
+```
+
+### Notes
-Notes
------
1. The logic in this test will fail opening the test.out file if there is no
- writable file system mount at /tmp.
+ writable file system mount at `/tmp`.
2. This test will still currently fail when try to fork the shell because
- support for that feature is not implemented. The following error message
+ support for that feature is not implemented. The following error message
should be received:
-Error: Forking child process failed (Unknown error) in line 5 at:
-if command$<>"enough" then shell "sh ./test/runbas test.bas enough"
- ^
+ ```
+ Error: Forking child process failed (Unknown error) in line 5 at:
+ if command$<>"enough" then shell "sh ./test/runbas test.bas enough"
+ ^
+ ```
-test37.bas
-==========
-LINE INPUT reaching EOF
+## `test37.bas`
-Test File
----------
+`LINE INPUT` reaching `EOF`
+
+### Test File
+
+```basic
10 open "i",1,"/mnt/romfs/test37.dat"
20 while not eof(1)
30 line input #1,a$
40 if a$="abc" then print a$; else print "def"
50 wend
+```
+
+## Data file (`/mnt/romfs/test37.dat`)
-Data file (/mnt/romfs/test37.dat)
--------------------------------
+```
abc
+```
-Result
-------
+## Result
+
+```
abc
+```
+
+## `test38.bas`
+
+`MAT REDIM`
-test38.bas
-==========
-MAT REDIM
+### Test File
-Test File
----------
+```basic
dim x(10)
mat read x
mat print x
@@ -1293,9 +1441,11 @@ mat print x
mat redim x(12)
mat print x
data 1,2,3,4,5,6,7,8,9,10
+```
-Expected Result
----------------
+### Expected Result
+
+```
1
2
3
@@ -1325,13 +1475,15 @@ Expected Result
0
0
0
+```
+
+## `test39.bas`
-test39.bas
-==========
Nested function and procedure calls
-Test File
----------
+### Test File
+
+```basic
def proc_a(x)
print fn_b(1,x)
end proc
@@ -1343,33 +1495,41 @@ def fn_c(b)
= b+3
proc_a(2)
+```
+
+### Expected Result
-Expected Result
----------------
+```
6
+```
+
+## `test40.bas`
-test40.bas
-==========
-IMAGE
+`IMAGE`
-Test File
----------
+### Test File
+
+```basic
d=3.1
print using "#.#";d
print using 10;d
10 image #.##
+```
+
+### Expected Result
-Expected Result
----------------
+```
3.1
3.10
+```
+
+## `test41.bas`
-test41.bas
-==========
-EXIT FUNCTION
+`EXIT FUNCTION`
-Test File
----------
+### Test File
+
+```basic
function f(c)
print "f running"
if (c) then f=42 : exit function
@@ -1378,20 +1538,24 @@ end function
print f(0)
print f(1)
+```
+
+### Expected Result
-Expected Result
----------------
+```
f running
43
f running
42
+```
+
+## `test42.bas`
-test42.bas
-==========
Arithmetic
-Test File
----------
+### Test File
+
+```basic
10 print 4.7\3
20 print -2.3\1
30 print int(-2.3)
@@ -1400,9 +1564,11 @@ Test File
60 print fix(2.3)
70 print fp(-2.3)
80 print fp(2.3)
+```
+
+### Expected Result
-Expected Result
----------------
+```
1
-2
-3
@@ -1411,13 +1577,15 @@ Expected Result
2
-0.3
0.3
+```
+
+## `test43.bas`
-test43.bas
-==========
Matrix multiplication size checks
-Test File
----------
+### Test File
+
+```basic
DIM a(3,3),b(3,1),c(3,3)
MAT READ a
MAT READ b
@@ -1433,22 +1601,26 @@ MAT READ a
MAT READ b
MAT c=a*b
MAT PRINT c
+```
+
+### Expected Result
-Expected Result
----------------
+```
17
47
77
Error: Dimension mismatch in line 14 at:
mat c=a*b
^
+```
-test44.bas
-==========
-DELETE
+## `test44.bas`
-Test File
----------
+`DELETE`
+
+### Test File
+
+```basic
10 print 10
20 print 20
30 print 30
@@ -1456,27 +1628,33 @@ Test File
50 print 50
60 print 60
70 print 70
+```
+
+## Usage
-Usage
------
+```basic
load "test.bas"
delete -20
delete 60-
delete 30-40
delete 15
list
+```
-Expected Result
----------------
+### Expected Result
+
+```
Error: No such line at: 15
50 print 50
+```
+
+## `test45.bas`
+
+`MID$` on left side
-test45.bas
-==========
-MID$ on left side
+### Test File
-Test File
----------
+```basic
10 mid$(a$,6,4) = "ABCD"
20 print a$
30 a$="0123456789"
@@ -1485,31 +1663,39 @@ Test File
60 a$="0123456789"
70 let mid$(a$,6,4) = "ABCD"
80 print a$
+```
-Expected Result
----------------
+### Expected Result
+
+```
01234ABCD9
01234ABCD9
+```
+
+## `test46.bas`
-test46.bas
-==========
-END used without program
+`END` used without program
-Test File
----------
+### Test File
+
+```basic
for i=1 to 10:print i;:next i:end
+```
+
+### Expected Result
-Expected Result
----------------
+```
1 2 3 4 5 6 7 8 9 10
+```
+
+## `test47.bas`
-test47.bas
-==========
-MAT WRITE
+`MAT WRITE`
-Test File
----------
+### Test File
+
+```basic
dim a(3,4)
for i=0 to 3
for j=0 to 4
@@ -1519,9 +1705,11 @@ for i=0 to 3
print
next
mat write a
+```
+
+### Expected Result
-Expected Result
----------------
+```
0 1 2 3 4
10 11 12 13 14
20 21 22 23 24
@@ -1529,13 +1717,15 @@ Expected Result
11,12,13,14
21,22,23,24
31,32,33,34
+```
+
+## `test48.bas`
-test48.bas
-==========
Multi assignment
-Test File
----------
+### Test File
+
+```basic
a,b = 10
print a,b
dim c(10)
@@ -1543,19 +1733,23 @@ a,c(a) = 2
print a,c(2),c(10)
a$,b$="test"
print a$,b$
+```
+
+### Expected Result
-Expected Result
----------------
+```
10 10
2 0 2
test test
+```
+
+## `test49.bas`
-test49.bas
-==========
Matrix determinant
-Test File
----------
+### Test File
+
+```basic
width 120
dim a(7,7),b(7,7)
mat read a
@@ -1571,9 +1765,11 @@ data 66,72,71,38,40,27,69
mat b=inv(a)
mat print b
print det
+```
+
+### Expected Result
-Expected Result
----------------
+```
58 71 67 36 35 19 60
50 71 71 56 45 20 52
64 40 84 50 51 43 69
@@ -1593,19 +1789,20 @@ Expected Result
-9.636079e+07 -320208 537452 -2323663 1.135493e+07 -3.019649e+07
9.650995e+07
1
+```
-Notes
------
- Output will differ because NuttX does not use scientific notation in
- output. Some minor rounding differences may also be expected.
+### Notes
+Output will differ because NuttX does not use scientific notation in output.
+Some minor rounding differences may also be expected.
-test50.bas
-==========
-Min and max function
+## `test50.bas`
-Test File
----------
+`min` and `max` function
+
+### Test File
+
+```basic
print min(1,2)
print min(2,1)
print min(-0.3,0.3)
@@ -1614,9 +1811,11 @@ print max(1,2)
print max(2,1)
print max(-0.3,0.3)
print max(-0.3,4)
+```
+
+### Expected Result
-Expected Result
----------------
+```
1
1
-0.3
@@ -1625,42 +1824,53 @@ Expected Result
2
0.3
4
+```
+
+## `test51.bas`
-test51.bas
-==========
Print items
-Test File
----------
+### Test File
+
+```basic
PRINT "Line 1";TAB(78);1.23456789
+```
-Expected Result
----------------
+### Expected Result
+
+```
Line 1 1.234568
+```
+
+## `test52.bas`
+
+`MAT INPUT`
-test52.bas
-==========
-MAT INPUT
+### Test File
-Test File
----------
+```basic
dim a(2,2)
mat input a
mat print a
mat input a
mat print a
+```
-Test File
----------
+### Test File
+
+```basic
1,2,3,4,5
1
3,4
+```
+
+### Expected Result
-Expected Result
----------------
+```
?
1 2
3 4
? ?
1 0
3 4
+```
diff --git a/examples/camera/README.md b/examples/camera/README.md
index a2d1235..42909da 100644
--- a/examples/camera/README.md
+++ b/examples/camera/README.md
@@ -1,39 +1,42 @@
-examples/camera
-^^^^^^^^^^^^^^^
+# Examples / `camera` Camera Snapshot
- This sample is implemented as 'camera' command on NuttX Shell.
- The synopsys of the command is as below.
+This sample is implemented as `camera` command on NuttX Shell. The synopsys of
+the command is as below.
- nsh> camera ([-jpg]) ([capture num])
+```
+nsh> camera ([-jpg]) ([capture num])
- -jpg : this option is set for storing JPEG file into a strage.
- : If this option isn't set capturing raw YUV422 data in a file.
- : raw YUV422 is default.
+ -jpg : this option is set for storing JPEG file into a strage.
+ : If this option isn't set capturing raw YUV422 data in a file.
+ : raw YUV422 is default.
- capture num : this option instructs number of taking pictures.
- : 10 is default.
- Storage will be selected automatically based on the available storage option.
+ capture num : this option instructs number of taking pictures.
+ : 10 is default.
+```
- Execution example:
+Storage will be selected automatically based on the available storage option.
- nsh> camera
- nximage_listener: Connected
- nximage_initialize: Screen resolution (320,240)
- Take 10 pictures as YUV file in /mnt/sd0 after 5000 mili-seconds.
- After finishing taking pictures, this app will be finished after 10000 mili-seconds.
- Expier time is pasted.
- Start captureing...
- FILENAME:/mnt/sd0/VIDEO001.YUV
- FILENAME:/mnt/sd0/VIDEO002.YUV
- FILENAME:/mnt/sd0/VIDEO003.YUV
- FILENAME:/mnt/sd0/VIDEO004.YUV
- FILENAME:/mnt/sd0/VIDEO005.YUV
- FILENAME:/mnt/sd0/VIDEO006.YUV
- FILENAME:/mnt/sd0/VIDEO007.YUV
- FILENAME:/mnt/sd0/VIDEO008.YUV
- FILENAME:/mnt/sd0/VIDEO009.YUV
- FILENAME:/mnt/sd0/VIDEO010.YUV
- Finished captureing...
- Expier time is pasted.
- nximage_listener: Lost server connection: 117
+Execution example:
+```
+nsh> camera
+nximage_listener: Connected
+nximage_initialize: Screen resolution (320,240)
+Take 10 pictures as YUV file in /mnt/sd0 after 5000 mili-seconds.
+After finishing taking pictures, this app will be finished after 10000 mili-seconds.
+Expier time is pasted.
+Start capturing...
+FILENAME:/mnt/sd0/VIDEO001.YUV
+FILENAME:/mnt/sd0/VIDEO002.YUV
+FILENAME:/mnt/sd0/VIDEO003.YUV
+FILENAME:/mnt/sd0/VIDEO004.YUV
+FILENAME:/mnt/sd0/VIDEO005.YUV
+FILENAME:/mnt/sd0/VIDEO006.YUV
+FILENAME:/mnt/sd0/VIDEO007.YUV
+FILENAME:/mnt/sd0/VIDEO008.YUV
+FILENAME:/mnt/sd0/VIDEO009.YUV
+FILENAME:/mnt/sd0/VIDEO010.YUV
+Finished capturing...
+Expier time is pasted.
+nximage_listener: Lost server connection: 117
+```
diff --git a/examples/camera/camera_main.c b/examples/camera/camera_main.c
index caa6622..0da36de 100644
--- a/examples/camera/camera_main.c
+++ b/examples/camera/camera_main.c
@@ -552,7 +552,7 @@ int main(int argc, FAR char *argv[])
while (1)
{
- printf("Start captureing...\n");
+ printf("Start capturing...\n");
ret = start_stillcapture(v_fd, capture_type);
if (ret != OK)
{
@@ -587,7 +587,7 @@ int main(int argc, FAR char *argv[])
}
RESET_INITIAL_TIME(then);
- printf("Finished captureing...\n");
+ printf("Finished capturing...\n");
}
exit_this_app:
diff --git a/examples/flash_test/README.md b/examples/flash_test/README.md
index 6679037..9fb2fdf 100644
--- a/examples/flash_test/README.md
+++ b/examples/flash_test/README.md
@@ -1,18 +1,23 @@
+# Examples / `flash_test` SMART Flash Device Test
-Install Program
-===============
+```
+Author: Ken Pettit
+ Date: April 24, 2013
+```
- Source: NuttX
- Author: Ken Pettit
- Date: April 24, 2013
+This application performs a SMART flash block device test. This test performs a
+sector allocate, read, write, free and garbage collection test on a SMART MTD
+block device. This test can be built only as an NSH command
-This application performs a SMART flash block device test. This test performs a sector allocate, read, write, free and garbage collection test on a SMART MTD block device. This test can be built only as an NSH command
-
-NOTE: This test uses internal OS interfaces and so is not available in the NUTTX kernel build
+**Note**: This test uses internal OS interfaces and so is not available in the
+NUTTX kernel build
+```
Usage:
- flash_test mtdblock_device
+
+ flash_test mtdblock_device
Additional options:
- --force to replace existing installation
+ --force to replace existing installation
+```
diff --git a/examples/flowc/README.md b/examples/flowc/README.md
index 051bf3c..6f3d232 100644
--- a/examples/flowc/README.md
+++ b/examples/flowc/README.md
@@ -1,15 +1,17 @@
-General Usage Instructions:
+# Examples / `flowc`
-1. The receiver side enter, start the receiver program. The receiver
- is now waiting to receive data on the configured serial port
+General Usage Instructions:
-2. On the sender side start the sender program. This will send data to
- the receiver which will verify that no data is lost.
+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.
- On Linux, you can alternatively do:
+On Linux, you can alternatively do:
- $ stty -F /dev/ttyACM0 crtscts
- $ cat testdata.dat >/dev/ttyACM0
+```bash
+$ stty -F /dev/ttyACM0 crtscts
+$ cat testdata.dat >/dev/ttyACM0
+```
- where you need to replace /dev/ttyACM0 with your selected serial
- device.
+where you need to replace `/dev/ttyACM0` with your selected serial device.
diff --git a/examples/json/README.md b/examples/json/README.md
index 45682e0..9e430c7 100644
--- a/examples/json/README.md
+++ b/examples/json/README.md
@@ -1,132 +1,155 @@
-apps/examples/json/README.txt
-=============================
+# Examples / `json` cJSON JSON Parser
This directory contains logic taken from the cJSON project:
http://sourceforge.net/projects/cjson/
-This corresponds to SVN revision r42 (with lots of changes for NuttX coding
-standards). As of r42, the SVN repository was last updated on 2011-10-10
-so I presume that the code is stable and there is no risk of maintaining
-duplicate logic in the NuttX repository.
+This corresponds to SVN revision `r42` (with lots of changes for NuttX coding
+standards). As of `r42`, the SVN repository was last updated on `2011-10-10` so
+I presume that the code is stable and there is no risk of maintaining duplicate
+logic in the NuttX repository.
-Contents
-========
+# Contents
- o License
- o Welcome to cJSON
+- License
+- Welcome to cJSON
-License
-=======
+# License
- Copyright (c) 2009 Dave Gamble
+Copyright (c) 2009 Dave Gamble
- Permission is hereby granted, free of charge, to any person obtaining a copy
- of this software and associated documentation files (the "Software"), to deal
- in the Software without restriction, including without limitation the rights
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- copies of the Software, and to permit persons to whom the Software is
- furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
- The above copyright notice and this permission notice shall be included in
- all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-Welcome to cJSON
-================
+# Welcome to cJSON
-cJSON aims to be the dumbest possible parser that you can get your job done with.
-It's a single file of C, and a single header file.
+cJSON aims to be the dumbest possible parser that you can get your job done
+with. It's a single file of C, and a single header file.
-JSON is described best here: http://www.json.org/
-It's like XML, but fat-free. You use it to move data around, store things, or just
-generally represent your program's state.
+JSON is described best here: http://www.json.org/ It's like XML, but fat-free.
+You use it to move data around, store things, or just generally represent your
+program's state.
-First up, how do I build?
-Add cJSON.c to your project, and put cJSON.h somewhere in the header search path.
-For example, to build the test app:
+First up, how do I build? Add `cJSON.c` to your project, and put `cJSON.h`
+somewhere in the header search path. For example, to build the test app:
+```bash
gcc cJSON.c test.c -o test -lm
./test
+```
-As a library, cJSON exists to take away as much legwork as it can, but not get in your way.
-As a point of pragmatism (i.e. ignoring the truth), I'm going to say that you can use it
-in one of two modes: Auto and Manual. Let's have a quick run-through.
+As a library, cJSON exists to take away as much legwork as it can, but not get
+in your way. As a point of pragmatism (i.e. ignoring the truth), I'm going to
+say that you can use it in one of two modes: Auto and Manual. Let's have a quick
+run-through.
-I lifted some JSON from this page: http://www.json.org/fatfree.html
-That page inspired me to write cJSON, which is a parser that tries to share the same
+I lifted some JSON from this page: http://www.json.org/fatfree.html That page
+inspired me to write cJSON, which is a parser that tries to share the same
philosophy as JSON itself. Simple, dumb, out of the way.
Some JSON:
+
+```json
{
- "name": "Jack (\"Bee\") Nimble",
- "format": {
- "type": "rect",
- "width": 1920,
- "height": 1080,
- "interlace": false,
- "frame rate": 24
- }
+ "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.
-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);
-
-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.
+
+```c
+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?
+
+```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
-
-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.
-
-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)
+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`.
+
+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):
+
+```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_
diff --git a/examples/pdcurses/README.md b/examples/pdcurses/README.md
index b7dd0e4..2bce03f 100644
--- a/examples/pdcurses/README.md
+++ b/examples/pdcurses/README.md
@@ -1,21 +1,17 @@
-PDCurses Demos
-==============
+# Examples / `pdcurses` PDCurses Demos
-This directory contains demonstration programs to show and test the
-capabilities of pdcurses libraries. Some of them predate PDCurses,
-PCcurses or even pcurses/ncurses. Although some PDCurses-specific code
-has been added, all programs remain portable to other implementations
-(at a minimum, to ncurses).
+This directory contains demonstration programs to show and test the capabilities
+of `pdcurses` libraries. Some of them predate PDCurses, PCcurses or even
+`pcurses`/`ncurses`. Although some PDCurses-specific code has been added, all
+programs remain portable to other implementations (at a minimum, to `ncurses`).
-Building
---------
+## Building
The demos are built by the platform-specific makefiles, in the platform
-directories. There are no dependencies besides curses and the standard
-C library, and no configuration is needed.
+directories. There are no dependencies besides curses and the standard C
+library, and no configuration is needed.
-Distribution Status
--------------------
+## Distribution Status
-Public Domain, except for rain_main.c and worm_main.c, which are under
-the ncurses license (MIT-like).
+Public Domain, except for `rain_main.c` and `worm_main.c`, which are under the
+ncurses license (MIT-like).
diff --git a/examples/tcpblaster/README.md b/examples/tcpblaster/README.md
index 86ff00a..4b699a7 100644
--- a/examples/tcpblaster/README.md
+++ b/examples/tcpblaster/README.md
@@ -1,40 +1,43 @@
-tcpblaster Performance Test Example
-===================================
+# Examples / `tcpblaster` TCP Performance Test
-To set up, do `make menuconfig` and select the Apps > Examples > tcpblaster. By default, nuttx will the be the client
-which sends data; and the host computer (Linux, macOS, or Windows) will be the server.
+To set up, do `make menuconfig` and select the _Apps_ → _Examples_ →
+_tcpblaster_. By default, nuttx will the be the client which sends data; and the
+host computer (Linux, macOS, or Windows) will be the server.
-Set up networking so the nuttx computer can ping the host, and the host can ping nuttx. Now you are ready to run the
-test.
+Set up networking so the nuttx computer can ping the host, and the host can ping
+nuttx. Now you are ready to run the test.
On host:
- $ ./tcpserver
- Binding to IPv4 Address: 00000000
- server: Accepting connections on port 5471
+```
+$ ./tcpserver
+Binding to IPv4 Address: 00000000
+server: Accepting connections on port 5471
+```
On nuttx:
- nsh> tcpclient
- Connecting to IPv4 Address: 0100000a
- client: Connected
- [2014-07-31 00:16:15.000] 0: Sent 200 4096-byte buffers: 800.0 KB (avg 4.0 KB) in 0.18 seconds ( 4444.4 KB/second)
+```
+nsh> tcpclient
+Connecting to IPv4 Address: 0100000a
+client: Connected
+[2014-07-31 00:16:15.000] 0: Sent 200 4096-byte buffers: 800.0 KB (avg 4.0 KB) in 0.18 seconds ( 4444.4 KB/second)
+```
Now on the host you should see something like:
- $ ./tcpserver
- Binding to IPv4 Address: 00000000
- server: Accepting connections on port 5471
- server: Connection accepted -- receiving
- [2020-02-22 16:17:07.000] 0: Received 200 buffers: 502.9 KB (buffer average size: 2.5 KB) in 0.12 seconds ( 4194.8 KB/second)
- [2020-02-22 16:17:07.000] 1: Received 200 buffers: 393.1 KB (buffer average size: 2.0 KB) in 0.09 seconds ( 4299.4 KB/second)
-
-
-This will tell you the link speed in KB/sec – kilobytes per second. If you want kilobits, multiply by 8.
-
-You can use the `make menuconfig` to reverse the setup, and have nuttx be the server, and the host be the client. If you
-do that, start the server first (nuttx), then start the client (host).
-
-
-
-
+```
+$ ./tcpserver
+Binding to IPv4 Address: 00000000
+server: Accepting connections on port 5471
+server: Connection accepted -- receiving
+[2020-02-22 16:17:07.000] 0: Received 200 buffers: 502.9 KB (buffer average size: 2.5 KB) in 0.12 seconds ( 4194.8 KB/second)
+[2020-02-22 16:17:07.000] 1: Received 200 buffers: 393.1 KB (buffer average size: 2.0 KB) in 0.09 seconds ( 4299.4 KB/second)
+```
+
+This will tell you the link speed in KB/sec – kilobytes per second. If you want
+kilobits, multiply by `8`.
+
+You can use the `make menuconfig` to reverse the setup, and have nuttx be the
+server, and the host be the client. If you do that, start the server first
+(nuttx), then start the client (host).
diff --git a/examples/telnetd/README.md b/examples/telnetd/README.md
index bdba71d..28cd2e1 100644
--- a/examples/telnetd/README.md
+++ b/examples/telnetd/README.md
@@ -1,8 +1,7 @@
-README.txt
-^^^^^^^^^^
+# Examples / `telnetd` Telnet Daemon
-This directory contains a functional port of the tiny uIP shell. In the
-NuttX environment, the NuttShell (at apps/nshlib) supersedes this tiny
-shell and also supports telnetd.
+This directory contains a functional port of the tiny uIP shell. In the NuttX
+environment, the NuttShell (at `apps/nshlib`) supersedes this tiny shell and
+also supports telnetd.
This example is retained here for reference purposes only.
diff --git a/fsutils/inifile/README.md b/fsutils/inifile/README.md
index e015ea2..86590cb 100644
--- a/fsutils/inifile/README.md
+++ b/fsutils/inifile/README.md
@@ -1,46 +1,42 @@
-README.txt
-==========
+# File System Utilities / `inifile` INI File
-Syntax
-======
+## Syntax
- This directory contains a very simple INI file parser. An INI file consists
- of a sequence of lines up to the end of file. A line may be one of the
- following:
+This directory contains a very simple INI file parser. An INI file consists of a
+sequence of lines up to the end of file. A line may be one of the following:
- 1) A blank line.
+1. A blank line.
- 2) A comment line. Any line beginning with ';'
+2. A comment line. Any line beginning with `;`
- 3) A section header. Definitions are divided into sections. Each
- section begins with a line containing the section name enclosed in
- square brackets. For example, "[section1]". The left bracket must
- be the first character on the line. Section names are case
- insensitive, i.e., "SECTION1" and "Section1" refer to the same
- section.
+3. A section header. Definitions are divided into sections. Each section begins
+ with a line containing the section name enclosed in square brackets. For
+ example, `[section1]`. The left bracket must be the first character on the
+ line. Section names are case insensitive, i.e., `SECTION1` and `Section1`
+ refer to the same section.
- 4) Variable assignments. A variable assignment is a variable name
- followed by the '=' sign and then the value of the variable. For
- example, "A=B": "A" is the variable name; "B" is the variable value.
- All variables following the section header belong in the section.
+4. Variable assignments. A variable assignment is a variable name followed by
+ the `=` sign and then the value of the variable. For example, `A=B`: `A` is
+ the variable name; `B` is the variable value. All variables following the
+ section header belong in the section.
- Variable names may be preceded with white space. Whitespace is not
- permitted before the '=' sign. Variable names are case insensitive,
- i.e., "A" and "a" refer to the same variable name.
+ Variable names may be preceded with white space. Whitespace is not permitted
+ before the `=` sign. Variable names are case insensitive, i.e., `A` and `a`
+ refer to the same variable name.
- Variable values may be numeric (any base) or a string. The case of
- string arguments is preserved.
+ Variable values may be numeric (any base) or a string. The case of string
+ arguments is preserved.
-Programming Interfaces
-======================
+## Programming Interfaces
- See apps/include/fsutils/inifile.h for interfaces supported by the INI file parser.
+See `apps/include/fsutils/inifile.h` for interfaces supported by the INI file
+parser.
-Test Program
-============
+## Test Program
- Below is a simple test program:
+Below is a simple test program:
+```c
int main(int argc, char *argv[])
{
INIHANDLE handle;
@@ -123,9 +119,11 @@ int main(int argc, char *argv[])
inifile_uninitialize(handle);
return 0;
}
+```
Test program output:
+```
Section: section2 Variable: VAR5 String: 5
Section: section1 Variable: VAR2 String: 2
Section: section3 Variable: VAR3 String: OOPS
@@ -143,3 +141,4 @@ Section: section2 Variable: VAR6 Value: 6
Section: section1 Variable: VAR42 String: 0
Section: section1 Variable: VAR2 Value: 2
Section: section2 Variable: VAR4 Value: 4
+```
diff --git a/gpsutils/README.md b/gpsutils/README.md
index 548f838..e05d9a1 100644
--- a/gpsutils/README.md
+++ b/gpsutils/README.md
@@ -1,12 +1,10 @@
-External Libraries
-^^^^^^^^^^^^^^^^^^
+# `gpsutils` GPS Utilities
- The apps/gpsutils directory is used to include libraries from external
- projects that are not part of NuttX Applications, but are useful for NuttX
- developers and users.
+The `gpsutils` directory is used to include libraries from external projects
+that are not part of NuttX Applications, but are useful for NuttX developers and
+users.
-gpsutils/minmea
-^^^^^^^^^^^^^^^^^^
+## `minmea` GPS NMEA 0183 parser
- MINMEA is a NMEA parser developed by Kosma Moczek. Kosma is also a NuttX
- contributor.
+MINMEA is a NMEA parser developed by Kosma Moczek. Kosma is also a NuttX
+contributor.
diff --git a/gpsutils/minmea/README.md b/gpsutils/minmea/README.md
index f6e35ba..c8ac5b5 100644
--- a/gpsutils/minmea/README.md
+++ b/gpsutils/minmea/README.md
@@ -1,4 +1,6 @@
-# minmea, a lightweight GPS NMEA 0183 parser library
+# GPS Utilities / `minmea` GPS NMEA 0183 parser
+
+A lightweight GPS NMEA 0183 parser library
[](https://travis-ci.org/cloudyourcar/minmea)
@@ -29,32 +31,35 @@ Adding support for more sentences is trivial; see ``minmea.c`` source.
## Fractional number format
-Internally, minmea stores fractional numbers as pairs of two integers: ``{value, scale}``.
-For example, a value of ``"-123.456"`` would be parsed as ``{-123456, 1000}``. As this
-format is quite unwieldy, minmea provides the following convenience functions for converting
-to either fixed-point or floating-point format:
+Internally, minmea stores fractional numbers as pairs of two integers: ``{value,
+scale}``. For example, a value of ``"-123.456"`` would be parsed as ``{-123456,
+1000}``. As this format is quite unwieldy, minmea provides the following
+convenience functions for converting to either fixed-point or floating-point
+format:
* ``minmea_rescale({-123456, 1000}, 10) => -1235``
* ``minmea_float({-123456, 1000}) => -123.456``
-The compound type ``struct minmea_float`` uses ``int_least32_t`` internally. Therefore,
-the coordinate precision is guaranteed to be at least ``[+-]DDDMM.MMMMM`` (five decimal digits)
-or ±20cm LSB at the equator.
+The compound type ``struct minmea_float`` uses ``int_least32_t`` internally.
+Therefore, the coordinate precision is guaranteed to be at least
+``[+-]DDDMM.MMMMM`` (five decimal digits) or ±20cm LSB at the equator.
## Coordinate format
-NMEA uses the clunky ``DDMM.MMMM`` format which, honestly, is not good in the internet era.
-Internally, minmea stores it as a fractional number (see above); for practical uses,
-the value should be probably converted to the DD.DDDDD floating point format using the
-following function:
+NMEA uses the clunky ``DDMM.MMMM`` format which, honestly, is not good in the
+internet era. Internally, minmea stores it as a fractional number (see above);
+for practical uses, the value should be probably converted to the DD.DDDDD
+floating point format using the following function:
* ``minmea_tocoord({-375165, 100}) => -37.860832``
-The library doesn't perform this conversion automatically for the following reasons:
+The library doesn't perform this conversion automatically for the following
+reasons:
* The conversion is not reversible.
* It requires floating point hardware.
-* The user might want to perform this conversion later on or retain the original values.
+* The user might want to perform this conversion later on or retain the original
+ values.
## Example
@@ -122,9 +127,9 @@ typing ``make``.
## Limitations
* Only a handful of frames is supported right now.
-* There's no support for omitting parts of the library from building. As
- a workaround, use the ``-ffunction-sections -Wl,--gc-sections`` linker flags
- (or equivalent) to remove the unused functions (parsers) from the final image.
+* There's no support for omitting parts of the library from building. As a
+ workaround, use the ``-ffunction-sections -Wl,--gc-sections`` linker flags (or
+ equivalent) to remove the unused functions (parsers) from the final image.
* Some systems lack ``timegm``. On these systems, the recommended course of
action is to build with ``-Dtimegm=mktime`` which will work correctly as long
the system runs in the default ``UTC`` timezone. Native Windows builds should
@@ -138,8 +143,10 @@ Please write unit tests for any new functions you add - it's fun!
## Licensing
Minmea is open source software; see ``COPYING`` for amusement. Email me if the
-license bothers you and I'll happily re-license under anything else under the sun.
+license bothers you and I'll happily re-license under anything else under the
+sun.
## Author
-Minmea was written by Kosma Moczek <kosma@cloudyourcar.com> at Cloud Your Car.
+Minmea was written by Kosma Moczek <kosma@cloudyourcar.com> at Cloud Your
+Car.
diff --git a/graphics/lvgl/README.md b/graphics/lvgl/README.md
index d2fc977..a3c846a 100644
--- a/graphics/lvgl/README.md
+++ b/graphics/lvgl/README.md
@@ -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)
diff --git a/graphics/nxwidgets/Doxygen/README.md b/graphics/nxwidgets/Doxygen/README.md
index 26d76ce..dc38ed5 100644
--- a/graphics/nxwidgets/Doxygen/README.md
+++ b/graphics/nxwidgets/Doxygen/README.md
@@ -1,64 +1,68 @@
-README
-======
+# Graphics / `nxwidgets` NXWidgets / Doxygen
This directory contains the documentation automatically generated by Doxygen.
-Contents
-========
+## Contents
- o Installing the necessary packages in Ubuntu
- o Generating documentation
- o References
+- Installing the necessary packages in Ubuntu
+- Generating documentation
+- References
-Installing the necessary packages in Ubuntu
-===========================================
+## Installing the Necessary Packages in Ubuntu
1. Install the following packages.
- $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz
+ ```bash
+ $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz
+ ```
2. (Optional) Install Doxygen from the latest sourcode.
- The Ubuntu package is outdated. The newer the version of Doxygen, the better
- the documentation looks.
+ The Ubuntu package is outdated. The newer the version of Doxygen, the better
+ the documentation looks.
- Place yourself in some temporary folder where you can download the source,
- and run [1]:
+ Place yourself in some temporary folder where you can download the source,
+ and run [1]:
- $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
- $ cd doxygen-svn
- $ ./configure
- $ make
- $ make install
+ ```bash
+ $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
+ $ cd doxygen-svn
+ $ ./configure
+ $ make
+ $ make install
+ ```
-Generating documentation
-========================
+## Generating Documentation
Two ways described here:
-1. Use the provided gendoc.sh script.
+1. Use the provided `gendoc.sh` script.
- trunk/NXWidgets/Doxygen/gendoc.sh
+ ```bash
+ trunk/NXWidgets/Doxygen/gendoc.sh
+ ```
- The script only needs the argument to the absolute path where to place the
- generated documentation. I.e.:
+ The script only needs the argument to the absolute path where to place the
+ generated documentation. I.e.:
- $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
- $ mkdir doc
- $ ./gendoc.sh $PWD/doc
+ ```bash
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ mkdir doc
+ $ ./gendoc.sh $PWD/doc
+ ```
+2. Using the `Doxyfile` directly:
-2. Using the Doxyfile directly:
-
- The file "Doxyfile" contains the configuration of the Doxygen settings
- for the run, edit only if necessary.
+ The file `Doxyfile` contains the configuration of the Doxygen settings for
+ the run, edit only if necessary.
To generate the documentation type:
- $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
- $ doxygen Doxyfile
+ ```bash
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ doxygen Doxyfile
+ ```
-References
-==========
+## References
[1] http://www.stack.nl/~dimitri/doxygen/download.html
diff --git a/graphics/nxwidgets/README.md b/graphics/nxwidgets/README.md
index a146b60..5fc93f3 100644
--- a/graphics/nxwidgets/README.md
+++ b/graphics/nxwidgets/README.md
@@ -1,70 +1,68 @@
-NXWidgets
-=========
+# Graphics / `nxwidgets` NXWidgets
In order to better support NuttX based platforms, a special graphical user
-interface has been created called NXWidgets. NXWidgets is written in C++
-and integrates seamlessly with the NuttX NX graphics subsystem in order
-to provide graphic objects, or "widgets," in the NX Graphics Subsystem
+interface has been created called NXWidgets. NXWidgets is written in C++ and
+integrates seamlessly with the NuttX NX graphics subsystem in order to provide
+graphic objects, or _widgets_, in the NX Graphics Subsystem
Some of the features of NXWidgets include:
-o Conservative C++
+- Conservative C++
- NXWidgets is written entirely in C++ but using only selected �embedded
- friendly� C++ constructs that are fully supported under NuttX. No
- additional C++ support libraries are required.
+ NXWidgets is written entirely in C++ but using only selected _embedded
+ friendly_ C++ constructs that are fully supported under NuttX. No additional
+ C++ support libraries are required.
-o NX Integration
+- NX Integration
- NXWidgets integrate seamlessly with the NX graphics system. Think of the
- X server under Linux � the NX graphics system is like a tiny X server
- that provides windowing under NuttX. By adding NXWidgets, you can support
- graphics objects like buttons and text boxes in the NX windows and toolbars.
+ NXWidgets integrate seamlessly with the NX graphics system. Think of the X
+ server under Linux – the NX graphics system is like a tiny X server that
+ provides windowing under NuttX. By adding NXWidgets, you can support graphics
+ objects like buttons and text boxes in the NX windows and toolbars.
-o Small Footprint
+- Small Footprint
NXWidgets is tailored for use MCUs in embedded applications. It is ideally
- suited for mid- and upper-range of most MCU families. A complete NXWidgets
- is possible in as little as 40Kb of FLASH and maybe 4Kb of SRAM.
+ suited for mid- and upper-range of most MCU families. A complete NXWidgets is
+ possible in as little as 40Kb of FLASH and maybe 4Kb of SRAM.
-o Output Devices
+- Output Devices
NXWidgets will work on the high-end frame buffer devices as well as on LCDs
connected via serial or parallel ports to a small MCU.
-o Input Devices
+- Input Devices
NXWidgets will accept position and selection inputs from a mouse or a
touchscreen. It will also support character input from a keyboard such as a
- USB keyboard. NXWidgets supports on very special widget called CKeypad that
- will provide keyboard input via an on-screen keypad that can be operated
- via mouse or touchscreen inputs.
+ USB keyboard. NXWidgets supports on very special widget called `CKeypad` that
+ will provide keyboard input via an on-screen keypad that can be operated via
+ mouse or touchscreen inputs.
-o Many Graphic Objects
+- Many Graphic Objects
Some of the graphic objects supported by NXWidgets include labels, buttons,
text boxes, button arrays, check boxes, cycle buttons, images, sliders,
scrollable list boxes, progress bars, and more.
-Note: Many of the fundamental classed in NxWidgets derive from the Antony
-Dzeryn's "Woopsi" project: http://woopsi.org/ which also has a BSD style
-license. See the COPYING file for details.
+**Note**: Many of the fundamental classed in NxWidgets derive from the Antony
+Dzeryn's _Woopsi_ project: http://woopsi.org/ which also has a BSD style
+license. See the `COPYING` file for details.
-Directory Structure
-===================
+## Directory Structure
-Kconfig
+- `Kconfig`
- This is a Kconfig file that should be provided at apps/NxWidgets/Kconfig.
+ This is a `Kconfig` file that should be provided at `apps/NxWidgets/Kconfig`.
When copied to that location, it will be used by the NuttX configuration
systems to configure settings for NxWidgets and NxWM
-nxwidgets
+- `nxwidgets`
- The source code, header files, and build environment for NxWidgets is
- provided in this directory.
+ The source code, header files, and build environment for NxWidgets is provided
+ in this directory.
-UnitTests
+- `UnitTests`
- Provides a collection of unit-level tests for many of the individual
- widgets provided by nxwidgets.
+ Provides a collection of unit-level tests for many of the individual widgets
+ provided by `nxwidgets`.
diff --git a/graphics/nxwidgets/UnitTests/README.md b/graphics/nxwidgets/UnitTests/README.md
index a93bc30..d376801 100644
--- a/graphics/nxwidgets/UnitTests/README.md
+++ b/graphics/nxwidgets/UnitTests/README.md
@@ -1,241 +1,259 @@
-README
-======
+# Graphics / NXWidgets / Unit Tests
This directory contains a collection of Unit Tests that can be used to verify
NXWidgets.:
-Contents
-========
- o Building the Unit Tests
- 1. Setup NuttX
- a) Configure NuttX
- b) Enable C++ Support
- c) Enable Debug Options
- d) NxWM
- e) Other Possible .config file changes
- f) Other Possible .config file changes
- 2. Configure in the Selected Unit Test
- o Work-Arounds
- 1. Build Issues
- 2. Stack Size Issues with the X11 Simulation
- o Unit Test Directories
-
-Installing and Building the Unit Tests
-======================================
+## Contents
+
+**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**
- a) Configure NuttX
+1. Build Issues
- 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).
+**Unit Test Directories**
+
+## Installing and Building the Unit Tests
+
+1. Setup NuttX
- 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. Configure NuttX
- 1) sim/nxwmm, or the simulated platform (no touchscreen), and
- 2) stm3240g-evel, for the STM3240G-EVAL board (with the STMPE11 touchscreen)
+ 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).
- We will assume the sim/nsh2 configuration in this discussion. The
- sim/nsh2 configuration is installed as follows:
+ **Note**: There are some other special configurationsrecommended for
+ unit-leveling testing of NxWM because the configuration is more complex in
+ that case. These are:
- cd <nuttx-directory-path>
- make distclean
- tools/configure.sh sim:nsh2
+ 1) `sim/nxwmm`, or the simulated platform (no touchscreen), and
+ 2) `stm3240g-evel`, for the `STM3240G-EVAL` board (with the STMPE11
+ touchscreen)
- Where:
+ We will assume the `sim/nsh2` configuration in this discussion. The
+ `sim/nsh2` configuration is installed as follows:
- <nuttx-directory-path> is the full, absolute path to the NuttX build directory
+ ```bash
+ cd <nuttx-directory-path>
+ make distclean
+ tools/configure.sh sim:nsh2
+ ```
- If you are using the sim/nsh2 or stm3210e-eval configurations, then skip
- to step 2 (Hmmm.. better check 1d) too).
+ Where:
- 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"
+ `<nuttx-directory-path>` is the full, absolute path to the NuttX build
+ directory
- b) Enable C++ Support
+ If you are using the `sim/nsh2` or `stm3210e-eval` configurations, then
+ skip to step 2 (Hmmm.. better check 1d) too).
- 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:
+ 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_
- CONFIG_HAVE_CXX=y
+ 2. Enable C++ Support
- 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).
+ 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:
- c) Enable Debug Options
+ ```conf
+ CONFIG_HAVE_CXX=y
+ ```
- If you are running on a simulated target, then you might also want to
- enable debug symbols:
+ 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).
- CONFIG_DEBUG_SYMBOLS=y
+ 3. Enable Debug Options
- Then you can run the simulation using GDB or DDD which is a very powerful
- debugging environment!
+ If you are running on a simulated target, then you might also want to
+ enable debug symbols:
- d) Special configuration requirements for the nxwm unit test:
+ ```conf
+ CONFIG_DEBUG_SYMBOLS=y
+ ```
- CONFIG_NXTERM=y
+ Then you can run the simulation using GDB or DDD which is a very powerful
+ debugging environment!
- e) Other .config file changes -- NSH configurations only.
+ 4. Special configuration requirements for the nxwm unit test.
- 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):
+ ```conf
+ CONFIG_NXTERM=y
+ ```
- CONFIG_NSH_BUILTIN_APPS=y
+ 5. Other `.config` file changes – NSH configurations only.
- 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.
+ 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):
- f) Other .config file changes -- NON-NSH configurations only.
+ ```conf
+ CONFIG_NSH_BUILTIN_APPS=y
+ ```
- 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:
+ `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.
- CONFIG_USER_ENTRYPOINT="nsh_main"
+ 6. Other `.config` file changes – NON-NSH configurations only.
- 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:
+ 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="cbutton_main"
+ ```conf
+ CONFIG_USER_ENTRYPOINT="nsh_main"
+ ```
- And the correct entry point for UnitTests/nxwm 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="nxwm_main"
+ ```conf
+ CONFIG_USER_ENTRYPOINT="cbutton_main"
+ ```
- etc.
+ And the correct entry point for `UnitTests/nxwm` would be:
- 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):
+ ```conf
+ CONFIG_USER_ENTRYPOINT="nxwm_main"
+ ```
- CONFIG_EXAMPLES_TOUSCHCREEN=y ## REMOVE (provided "tc_main")
+ 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`):
+
+ ```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:
-
- 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
-=========
-
-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
+ size of the add-on program is controlled in another way. Here are the steps
+ for increasing the stack size in that case:
+
+ ```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
+ ```
+
+## 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.
+
+- `CButton`
+ - Exercises the `CButton` widget.
+ - Depends on `CLabel`.
+- `CButtonArray`
+ - Exercises the `CButtonArray` widget.
+- `CCheckBox`
+ - Exercises the `CCheckBox` widget.
+ - Depends on `CLabel` and `CButton`.
+- `CGlyphButton`
+ - Exercises the `CGlyphButton` widget.
+ - Depends on `CLabel` and `CButton`.
+- `CImage`
+ - Exercises the `CImage` widget.
+- `CLabel`
+ - Exercises the `CLabel` widget.
+- `CProgressBar`
+ - Exercises the `CProgressBar` widget.
+- `CRadioButton`
+ - Exercises the `CRadioButton` and `CRadioButtonGroup` widgets.
+ - Depends on `CLabel` and `CButton`.
+- `CScrollBarHorizontal`
+ - Exercises the `ScrollbarHorizontal`.
+ - Depends on `CSliderHorizontal` and `CGlyphButton`.
+- `CScrollBarVertical`
+ - Exercises the `ScrollbarHorizontal`.
+ - Depends on `CSliderVertical` and `CGlyphButton`.
+- `CSliderHorizontal`
+ - Exercises the `CSliderHorizontal`.
+ - Depends on `CSliderHorizontalGrip`.
+- `CSliderVertical`
+ - Exercises the `CSliderVertical`.
+ - Depends on `CSliderVerticalGrip`.
+- `CTextBox`
+ - Exercises the `CTextBox` widget.
+ - Depends on `CLabel`.
diff --git a/graphics/nxwm/Doxygen/README.md b/graphics/nxwm/Doxygen/README.md
index 26d76ce..cf44363 100644
--- a/graphics/nxwm/Doxygen/README.md
+++ b/graphics/nxwm/Doxygen/README.md
@@ -1,64 +1,68 @@
-README
-======
+# Graphics / `nxwm` NxWM / Doxygen
This directory contains the documentation automatically generated by Doxygen.
-Contents
-========
+## Contents
- o Installing the necessary packages in Ubuntu
- o Generating documentation
- o References
+- Installing the necessary packages in Ubuntu
+- Generating documentation
+- References
-Installing the necessary packages in Ubuntu
-===========================================
+## Installing the necessary packages in Ubuntu
1. Install the following packages.
- $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz
+ ```bash
+ $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz
+ ```
2. (Optional) Install Doxygen from the latest sourcode.
- The Ubuntu package is outdated. The newer the version of Doxygen, the better
- the documentation looks.
+ The Ubuntu package is outdated. The newer the version of Doxygen, the better
+ the documentation looks.
- Place yourself in some temporary folder where you can download the source,
- and run [1]:
+ Place yourself in some temporary folder where you can download the source,
+ and run [1]:
- $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
- $ cd doxygen-svn
- $ ./configure
- $ make
- $ make install
+ ```bash
+ $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
+ $ cd doxygen-svn
+ $ ./configure
+ $ make
+ $ make install
+ ```
-Generating documentation
-========================
+## Generating documentation
Two ways described here:
-1. Use the provided gendoc.sh script.
+1. Use the provided `gendoc.sh` script.
- trunk/NXWidgets/Doxygen/gendoc.sh
+ ```bash
+ trunk/NXWidgets/Doxygen/gendoc.sh
+ ```
- The script only needs the argument to the absolute path where to place the
- generated documentation. I.e.:
+ The script only needs the argument to the absolute path where to place the
+ generated documentation. I.e.:
- $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
- $ mkdir doc
- $ ./gendoc.sh $PWD/doc
+ ```bash
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ mkdir doc
+ $ ./gendoc.sh $PWD/doc
+ ```
+2. Using the `Doxyfile` directly:
-2. Using the Doxyfile directly:
-
- The file "Doxyfile" contains the configuration of the Doxygen settings
- for the run, edit only if necessary.
+ The file `Doxyfile` contains the configuration of the Doxygen settings for
+ the run, edit only if necessary.
To generate the documentation type:
- $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
- $ doxygen Doxyfile
+ ```bash
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ doxygen Doxyfile
+ ```
-References
-==========
+## References
[1] http://www.stack.nl/~dimitri/doxygen/download.html
diff --git a/graphics/nxwm/README.md b/graphics/nxwm/README.md
index 497b012..2578a46 100644
--- a/graphics/nxwm/README.md
+++ b/graphics/nxwm/README.md
@@ -1,30 +1,27 @@
-nxwm
-====
+# Graphics / `nxwm` NxWM
- This directory holds a tiny desktop for small embedded devices with a
- touchscreen,. NxWM. NxWM is true multiple window manager but only one
- window is displayed at a time. This simplification helps performance on
- LCD based products (in the same way that a tiled window manager helps)
- and also makes the best use of small displays. It is awkward from a
- human factors point-of-view trying to manage multiple windows on a
- small display.
+This directory holds a tiny desktop for small embedded devices with a
+touchscreen,. NxWM. NxWM is true multiple window manager but only one window is
+displayed at a time. This simplification helps performance on LCD based products
+(in the same way that a tiled window manager helps) and also makes the best use
+of small displays. It is awkward from a human factors point-of-view trying to
+manage multiple windows on a small display.
- The window manager consists of a task bar with icons representing the
- running tasks. If you touch the task's icon, it comes to the top. Each
- window has a toolbar with (1) a title, (2) a minimize button, and (3) a
- stop application button using the standard icons for these things.
+The window manager consists of a task bar with icons representing the running
+tasks. If you touch the task's icon, it comes to the top. Each window has a
+toolbar with (1) a title, (2) a minimize button, and (3) a stop application
+button using the standard icons for these things.
- There is always a start window that is available in the task bar. When
- you touch the start window icon, it brings up the start window containing
- icons representing all of the available applications. If you touch an
- icon in the start window, it will be started and added to the task bar.
+There is always a start window that is available in the task bar. When you touch
+the start window icon, it brings up the start window containing icons
+representing all of the available applications. If you touch an icon in the
+start window, it will be started and added to the task bar.
- There is a base class that defines an add-on application and an
- interface that supports incorporation of new application. The only
- application that is provided is NxTerm. This is an NSH session
- running in a window. You should be able to select the NX icon in the start
- menu and create as many NSH sessions in windows as you want. (keybard input
- still comes through serial).
+There is a base class that defines an add-on application and an interface that
+supports incorporation of new application. The only application that is provided
+is NxTerm. This is an NSH session running in a window. You should be able to
+select the NX icon in the start menu and create as many NSH sessions in windows
+as you want. (keybard input still comes through serial).
- Note 1: NwWM requires NuttX-7.19 or above to work with the current
- NxWidgets-1.18 release.
+Note 1: NwWM requires `NuttX-7.19` or above to work with the current
+`NxWidgets-1.18` release.
diff --git a/graphics/pdcurs34/README.md b/graphics/pdcurs34/README.md
index ae03c09..85451a8 100644
--- a/graphics/pdcurs34/README.md
+++ b/graphics/pdcurs34/README.md
@@ -1,48 +1,39 @@
-Welcome to PDCurses!
-====================
+# Graphics / `pdcurs34` PDCurses
-Public Domain Curses, aka PDCurses, is an implementation of X/Open
-curses for multiple platforms. The latest version can be found at:
+**Welcome to PDCurses!**
- http://pdcurses.sourceforge.net/
+Public Domain Curses, aka PDCurses, is an implementation of X/Open curses for
+multiple platforms. The latest version can be found at:
-For changes, see the HISTORY file.
+[pdcurses.sourceforge.net](http://pdcurses.sourceforge.net)
+For changes, see the `HISTORY` file.
-Legal Stuff
------------
+## Legal Stuff
-The core package is in the public domain, but small portions of PDCurses
-are subject to copyright under various licenses. Each directory
-contains a README file, with a section titled "Distribution Status"
-which describes the status of the files in that directory.
+The core package is in the public domain, but small portions of PDCurses are
+subject to copyright under various licenses. Each directory contains a `README`
+file, with a section titled _Distribution Status_ which describes the status of
+the files in that directory.
-If you use PDCurses in an application, an acknowledgement would be
-appreciated, but is not mandatory. If you make corrections or
-enhancements to PDCurses, please forward them to the current maintainer
-for the benefit of other users.
+If you use PDCurses in an application, an acknowledgement would be appreciated,
+but is not mandatory. If you make corrections or enhancements to PDCurses,
+please forward them to the current maintainer for the benefit of other users.
This software is provided AS IS with NO WARRANTY whatsoever.
-
-Ports
------
+## Ports
PDCurses has been ported to DOS, OS/2, Win32, X11 and SDL. A directory
-containing the port-specific source files exists for each of these
-platforms. Build instructions are in the README file for each platform.
-
-
-Distribution Status
--------------------
+containing the port-specific source files exists for each of these platforms.
+Build instructions are in the `README` file for each platform.
-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.
+## 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.
-Maintainer
-----------
+## Maintainer
William McBrine <wm...@users.sf.net>
diff --git a/graphics/pdcurs34/pdcurses/README.md b/graphics/pdcurs34/pdcurses/README.md
index a6a7ee8..2e21711 100644
--- a/graphics/pdcurs34/pdcurses/README.md
+++ b/graphics/pdcurs34/pdcurses/README.md
@@ -1,25 +1,17 @@
-PDCurses Portable Core
-======================
+# Graphics / `pdcurs34` PDCurses / `pdcurses` Portable Core
-This directory contains core PDCurses source code files common to all
-platforms.
+This directory contains core PDCurses source code files common to all platforms.
+## Building
-Building
---------
+These modules are built by the platform-specific makefiles, in the platform
+directories.
-These modules are built by the platform-specific makefiles, in the
-platform directories.
-
-
-Distribution Status
--------------------
+## Distribution Status
The files in this directory are released to the Public Domain.
+## Acknowledgements
-Acknowledgements
-----------------
-
-The panel library was originally provided by
+The panel library was originally provided by
Warren Tucker <wh...@n4hgf.mt-park.ga.us>
diff --git a/graphics/tiff/README.md b/graphics/tiff/README.md
index b414107..dd46207 100644
--- a/graphics/tiff/README.md
+++ b/graphics/tiff/README.md
@@ -1,15 +1,12 @@
-README for the TIFF Creation Library
-=====================================
+# Graphics / `tiff` TIFF Creation Library
-This directory contains a library that can be used to create TIFF image
-files. This file was created for the purpose of supporting screen dumps
-from an LCD. Howeve, the logic is general and could be used for most
-any purpose.
+This directory contains a library that can be used to create TIFF image files.
+This file was created for the purpose of supporting screen dumps from an LCD.
+Howeve, the logic is general and could be used for most any purpose.
-The only usage documentation is in the (rather extensive) comments in
-the file apps/include/tiff.h
+The only usage documentation is in the (rather extensive) comments in the file
+`apps/include/tiff.h`.
-Unit Test
-=========
+## Unit Test
-See apps/examples/tiff
+See `apps/examples/tiff`.
diff --git a/graphics/twm4nx/README.md b/graphics/twm4nx/README.md
index a1de5ff..5c594b9 100644
--- a/graphics/twm4nx/README.md
+++ b/graphics/twm4nx/README.md
@@ -1,385 +1,386 @@
-README
-======
+# Graphics / `twm4nx` Tab Window Manager (TWM)
-Twm4Nx is a port of twm, Tab Window Manager (or Tom's Window Manager)
-version 1.0.10 to NuttX NX windows server. No, a port is not the right
-word. It is a re-design of TWM from the inside out to work with the NuttX
-NX server. The name Twm4Nx reflects this legacy. But Twm4Nx is more a
-homage to TWM than a port of TWM.
+Twm4Nx is a port of twm, Tab Window Manager (or Tom's Window Manager) version
+`1.0.10` to NuttX NX windows server. No, a port is not the right word. It is a
+re-design of TWM from the inside out to work with the NuttX NX server. The name
+Twm4Nx reflects this legacy. But Twm4Nx is more a homage to TWM than a port of
+TWM.
-The original TWM was based on X11 which provides a rich set of features.
-TWM provided titlebars, shaped windows, several forms of icon management,
-user-defined macro functions, click-to-type and pointer-driven keyboard
-focus, graphic contexts, and user-specified key and pointer button bindings,
-etc.
+The original TWM was based on X11 which provides a rich set of features. TWM
+provided titlebars, shaped windows, several forms of icon management,
+user-defined macro functions, click-to-type and pointer-driven keyboard focus,
+graphic contexts, and user-specified key and pointer button bindings, etc.
Twm4Nx, on the other hand is based on the NuttX NX server which provides
-comparatively minimal support. Additional drawing support comes from
-the NuttX NxWidgets library (which necessitated the change to C++).
-
-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.
-
-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:
-
- 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.
-
-How To:
-
- 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.
-
- 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.
-
- 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:
-
- 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.
-
- - All windows close after the terminal menu option is selected.
-
- 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:
-
- 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.
-
- Moving a Window:
- - Grab the title in the toolbar and move the window to the desired
- position.
-
- 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:
-
- 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.
-
- - NOTE: While resizing, non-critical events from all other windows
- are ignored.
-
- 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.
-
-Issues:
-
- 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.
-
- Here are all known issues and features that are missing:
-
- 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.
-
- There are no near-term plans to address these compatibility issues.
-
- 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:
-
- 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.
-
-Adding Twm4Nx Applications
-==========================
-
- 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.
-
- 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.
-
- These example applications can be found at: apps/graphics/twm4nx/apps and
- apps/include/graphics/twm4nx/apps
-
- 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:
-
- bool initialize(FAR CTwm4Nx *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.
-
- In practice, the application factory implementation class inherits from
- the following base classes:
-
- 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.
-
- 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:
-
- CNxTermFactory nxtermFactory;
- success = nxtermFactory.initialize(twm4nx);
-
- 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:
-
- FAR CMainMenu *cmain = twm4nx->getMainMenu();
- return cmain->addApplication(this);
-
- The argument to the CMainMenu::addApplication() method is of type
- IApplication *. Remember, however, that our application implementation
- class inherited from IApplication.
-
- 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:
-
- 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.
-
- The Twm4Nx application is then started when the application factory's
- CTwm4NxEvent::event() method is called with the specified event.
-
- 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:
-
- 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.
-
- To create an application window, the application must call the
- CWindowFactory::createWindow() method. For the NxTerm example, this looks
- like:
-
- NXWidgets::CNxString name("NuttShell");
-
- uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN);
-
- 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:
-
- 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
-
- Once the CWindow is instantiated, events needed by the application can
- be configured as is done in the NxTerm application:
-
- 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:
-
- 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.
+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).
+
+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
+
+### 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:
+
+ 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.
+
+## How To
+
+### 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.
+
+ 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.
+
+### 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:
+ - 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.
+
+### 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:
+ - 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.
+
+### Moving a Window:
+
+- Grab the title in the toolbar and move the window to the desired position.
+
+### 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:
+ - 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.
+
+### Themes
+
+- 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.
+
+## Issues:
+
+`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.
+
+Here are all known issues and features that are missing:
+
+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.
+
+There are no near-term plans to address these compatibility issues.
+
+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:
+
+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.
+
+## Adding Twm4Nx Applications
+
+### 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.
+
+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.
+
+These example applications can be found at: `apps/graphics/twm4nx/apps` and
+`apps/include/graphics/twm4nx/apps`
+
+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:
+
+```cpp
+bool initialize(FAR CTwm4Nx *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.
+
+In practice, the application factory implementation class inherits from the
+following base classes:
+
+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.
+
+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:
+
+```cpp
+CNxTermFactory nxtermFactory;
+success = nxtermFactory.initialize(twm4nx);
+```
+
+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`:
+
+```cpp
+FAR CMainMenu *cmain = twm4nx->getMainMenu();
+return cmain->addApplication(this);
+```
+
+The argument to the `CMainMenu::addApplication()` method is of type
+`IApplication *`. Remember, however, that our application implementation `class`
+inherited from `IApplication`.
+
+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:
+
+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`.
+
+The Twm4Nx application is then started when the application factory's
+`CTwm4NxEvent::event()` method is called with the specified event.
+
+### 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:
+
+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.
+
+To create an application window, the application must call the
+`CWindowFactory::createWindow()` method. For the NxTerm example, this looks
+like:
+
+```cpp
+NXWidgets::CNxString name("NuttShell");
+
+uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN);
+
+FAR CWindowFactory *factory = m_twm4nx->getWindowFactory();
+m_nxtermWindow = factory->createWindow(name, &CONFIG_TWM4NX_NXTERM_ICON,
+ (FAR CIconMgr *)0, wflags);
+```
+
+The window factory is another factory that creates and manages window instance.
+The `createWindow()` method requires four parameters:
+
+1. The name of the window. This is the name that is show in the window toolbar
+ and may be the same name as was used in the Main Menu entry.
+2. A reference to the the Icon image associated with the window. This is the
+ image that is show on the desktop when the window is iconified. It is of
+ type `NXWidgets::SRlePaletteBitmap`.
+3. A pointer to the Icon Manager instance that this window belongs with. This
+ can be NULL to use the default Twm4Nx Icon Manager.
+4. A set of flags that describe properties of the windows.
+
+ The flag values are defined byte `WFLAGS_*` definitions provided in
+ `apps/include/graphics/twm4nx/cwindow.hxx`:
+
+ - `WFLAGS_NO_MENU_BUTTON` – Omit the menu button from the toolbar.
+ - `WFLAGS_NO_DELETE_BUTTON` – Omit the delete button from the toolbar.
+ - `WFLAGS_NO_RESIZE_BUTTON` – Omit the resize button from the toolbar.
+ - `WFLAGS_NO_MINIMIZE_BUTTON` – Omit the minimize button from the toolbar.
+ - `WFLAGS_NO_TOOLBAR` – Omit the toolbar altogether.
+ - `WFLAGS_ICONMGR` – This window is an icon manager.
+ - `WFLAGS_MENU` – This window is a menu window.
+ - `WFLAGS_HIDDEN` – Start with the window hidden.
+
+Once the `CWindow` is instantiated, events needed by the application can be
+configured as is done in the NxTerm application:
+
+```cpp
+struct SAppEvents events;
+events.eventObj = (FAR void *)this;
+events.redrawEvent = EVENT_NXTERM_REDRAW;
+events.resizeEvent = EVENT_NXTERM_RESIZE;
+events.mouseEvent = EVENT_NXTERM_XYINPUT;
+events.kbdEvent = EVENT_NXTERM_KBDINPUT;
+events.closeEvent = EVENT_NXTERM_CLOSE;
+events.deleteEvent = EVENT_NXTERM_DELETE;
+
+bool success = m_nxtermWindow->configureEvents(events);
+```
+
+Again, recall that the application inherits from `CTwm4NxEvent`. So passing
+`this` as the event object above assures that the specific events are routed to
+the application instance.
+
+Drawing in the application window can be performed using that facilities of
+NXWidgets using the `NXWidgets::CGraphicsPort` associated with the window. The
+NxTerm application does not perform any drawing, however; that drawing is
+performed by the NxTerm driver.
+
+The `NXWidgets::CGraphicsPort` can be obtained from a `CWindow` instance, say
+`m_window`, like:
+
+```cpp
+FAR NXWidgets::CWidgetControl *control = m_window->getWidgetControl();
+NXWidgets::CGraphicsPort *port = control->getGraphicsPort();
+```
+
+That `CGraphicsPort` is then passed to the widget constructor, binding the
+widget to that window and forcing all widget drawing to occur within the window.
+
+Obviously, a lot more could be written about drawing, much more than can be
+addressed in this README file.
diff --git a/industry/abnt_codi/README.md b/industry/abnt_codi/README.md
index e1f008f..849e2dc 100644
--- a/industry/abnt_codi/README.md
+++ b/industry/abnt_codi/README.md
@@ -1,67 +1,27 @@
+# Industry / `abnt_codi` ABNT CODI
+
The ABNT CODI is an old energy meter standard used in Brazil.
This code interprets the end user serial output existent in the energy meter.
That output externalizes its data blinking an LED as a serial protocol at the
-baudrate of 110 BPS and uses 8 octects:
- _____________________________________________________________________________
-| | | |
-| OCTET | bits | Description |
-|________|______|_____________________________________________________________|
-| | | |
-| 001 | 0-7 | Number of seconds to the end of current active demand (LSB) |
-|________|______|_____________________________________________________________|
-| | | |
-| 002 | 0-3 | Number of seconds to the end of current active demand (MSB) |
-|________|______|_____________________________________________________________|
-| | | |
-| | 4 | Bill indicator. It is inverted at each demand replenishment |
-|________|______|_____________________________________________________________|
-| | | |
-| | 5 | Reactive Interval Indicator. Inverted at end react interval |
-|________|______|_____________________________________________________________|
-| | | |
-| | 6 | If 1 means the reactive-capacitive is used to calculate UFER|
-|________|______|_____________________________________________________________|
-| | | |
-| | 7 | If 1 means the reactive-inductive is used to calculate UFER |
-|________|______|_____________________________________________________________|
-| | | |
-| 003 | 0-3 | Current seasonal segment: |
-| | | 0001 - tip |
-| | | 0010 - out of tip |
-| | | 1000 - reserved |
-|________|______|_____________________________________________________________|
-| | | |
-| | 4-5 | Type of charging indicator (flag): |
-| | | 00 - Blue |
-| | | 01 - Green |
-| | | 10 - Irrigators |
-| | | 11 - Other |
-|________|______|_____________________________________________________________|
-| | | |
-| | 6 | Not used |
-|________|______|_____________________________________________________________|
-| | | |
-| | 7 | If equal 1 means reactive rate is enabled |
-|________|______|_____________________________________________________________|
-| | | |
-| 004 | 0-7 | Number of pulses for active energy of cur dem interv (LSB) |
-|________|______|_____________________________________________________________|
-| | | |
-| 005 | 0-6 | Number of pulses for active energy of cur dem interv (MSB) |
-|________|______|_____________________________________________________________|
-| | | |
-| | 7 | Not used |
-|________|______|_____________________________________________________________|
-| | | |
-| 006 | 0-7 | Number of pulses for reactive energy of cur dem interv (LSB)|
-|________|______|_____________________________________________________________|
-| | | |
-| 007 | 0-6 | Number of pulses for reactive energy of cur dem interv (MSB)|
-|________|______|_____________________________________________________________|
-| | | |
-| | 7 | Not used |
-|________|______|_____________________________________________________________|
-| | | |
-| 008 | 0-7 | Inverted bits of "xor" from previous octects |
-|________|______|_____________________________________________________________|
+baudrate of `110 BPS` and uses `8` octects:
+
+| Octet | Bits | Description
+|:-----:|------:|-------------
+| `001` | `0-7` | Number of seconds to the end of current active demand (`LSB`)
+| `002` | `0-3` | Number of seconds to the end of current active demand (`MSB`)
+| | `4` | Bill indicator. It is inverted at each demand replenishment
+| | `5` | Reactive Interval Indicator. Inverted at end react interval
+| | `6` | If `1` means the reactive-capacitive is used to calculate `UFER`
+| | `7` | If `1` means the reactive-inductive is used to calculate `UFER`
+| `003` | `0-3` | Current seasonal segment: <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
diff --git a/interpreters/README.md b/interpreters/README.md
index 8d40078..0379e1e 100644
--- a/interpreters/README.md
+++ b/interpreters/README.md
@@ -1,24 +1,21 @@
-apps/interpreters README file
-=============================
+# Interpreters
-This apps/ directory is set aside to hold interpreters that may be
+This `apps/` directory is set aside to hold interpreters that may be
incorporated into NuttX.
-ficl
-----
+## Ficl
- This is DIY port of Ficl (the "Forth Inspired Command Language"). See
- http://ficl.sourceforge.net/. It is a "DIY" port because the Ficl source
- is not in that directory, only an environment and instructions that will
- let you build Ficl under NuttX. The rest is up to you.
+This is DIY port of Ficl (the _Forth Inspired Command Language_). See
+http://ficl.sourceforge.net/. It is a _DIY_ port because the Ficl source is not
+in that directory, only an environment and instructions that will let you build
+Ficl under NuttX. The rest is up to you.
-minibasic
----------
+## Mini Basic
- The Mini Basic implementation at apps/interpreters derives from version 1.0
- by Malcolm McLean, Leeds University, and was released under the Creative
- Commons Attibution license. I am not legal expert, but this license
- appears to be compatible with the NuttX BSD license see:
- https://creativecommons.org/licenses/ . I, however, cannot take
- responsibility for any actions that you might take based on my
- understanding. Please use your own legal judgement.
+The Mini Basic implementation at `apps/interpreters` derives from version `1.0`
+by Malcolm McLean, Leeds University, and was released under the Creative Commons
+Attibution license. I am not legal expert, but this license appears to be
+compatible with the NuttX BSD license see:
+https://creativecommons.org/licenses/. I, however, cannot take responsibility
+for any actions that you might take based on my understanding. Please use your
+own legal judgement.
diff --git a/interpreters/bas/README.md b/interpreters/bas/README.md
index d843593..be3f431 100644
--- a/interpreters/bas/README.md
+++ b/interpreters/bas/README.md
@@ -1,63 +1,59 @@
-README
-======
-
-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.
-
- 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.
-
-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
-
- Copyright (c) 1999-2014 Michael Haardt
-
- 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 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
-
- 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
+# 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.
+
+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.
+
+## 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
+
+Copyright (c) 1999-2014 Michael Haardt
+
+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 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Bas 2.4 Release Notes
+
+Changes compared to version `2.3`
+
+- Matrix inversion on integer arrays with option base 1 fixed.
+- `PRINT USING` behaviour for `!` fixed.
+- `PRINT`, separator should advance to the next zone, even if the current
+ position is at the start of a zone.
+- Added `ip()`, `frac()`, `fp()`, `log10()`, `log2()`, `min()` and `max()`.
+- Fixed `NEXT` checking the variable case sensitive.
+- Use `terminfo` capability cr to make use of its padding.
+- `LET` segmentation fault fixed.
+- `PRINT` now uses print items.
+- `-r` for restricted operation.
+- `MAT INPUT` does not drop excess arguments, but uses them for the next row.
+- License changed to MIT.
diff --git a/interpreters/ficl/README.md b/interpreters/ficl/README.md
index 73ed900..743a1ee 100644
--- a/interpreters/ficl/README.md
+++ b/interpreters/ficl/README.md
@@ -1,40 +1,39 @@
-apps/interpreter/README.txt
-===========================
+# Interpreters / `ficl` Ficl
-Ficl is a programming language interpreter designed to be embedded into
-other systems as a command, macro, and development prototyping language.
-Ficl is an acronym for "Forth Inspired Command Language". See
-http://ficl.sourceforge.net/
+Ficl is a programming language interpreter designed to be embedded into other
+systems as a command, macro, and development prototyping language. Ficl is an
+acronym for _Forth Inspired Command Language_. See http://ficl.sourceforge.net/
-Build Instructions
-------------------
+## Build Instructions
-Disclaimer: This installation steps have only been exercised using Ficl
-4.1.0. With new versions you will likely have to make some adjustments
-to this instructtions or to the files within this directory. Think of this
-information as "recommendations" -- not necessarily proven instructions.
+Disclaimer: This installation steps have only been exercised using Ficl 4.1.0.
+With new versions you will likely have to make some adjustments to this
+instructtions or to the files within this directory. Think of this information
+as _recommendations_ - not necessarily proven instructions.
-1. CD to apps/interpreters/ficl
+1. `cd` to `interpreters/ficl`
2. Download Ficl: http://sourceforge.net/projects/ficl/files/
3. Uznip the Ficl compressed file.
- For example, 'unzip ficl-4.1.0.zip' will leave the file
- apps/interpreters/ficl/ficl-4.1.0
+ For example, `unzip ficl-4.1.0.zip` will leave the file
+ `interpreters/ficl/ficl-4.1.0`.
-4. Configure to build Ficl in the apps/interpreters/ficl directory using
- the configure.sh script.
+4. Configure to build Ficl in the `interpreters/ficl` directory using the
+ `configure.sh` script.
- For example, './configure.sh ficl-4.1.0' will leave the Makefile
- fragment 'Make.srcs' in the ficl build directory.
+ For example, `./configure.sh ficl-4.1.0` will leave the Makefile fragment
+ `Make.srcs` in the ficl build directory.
-5. Create your NuttX configuration. Using the 'make menuconfig', you
- should select:
+5. Create your NuttX configuration. Using the `make menuconfig`, you should
+ select:
- CONFIG_INTERPRETERS_FICL=y
+ ```conf
+ CONFIG_INTERPRETERS_FICL=y
+ ```
-6. Configure and build NuttX. On successful completion, the Ficl objects
- will be available in apps/libapps.a and that NuttX binary will be
- linked against that file. Of course, Ficl will do nothing unless
- you have written some application code that uses it!
+6. Configure and build NuttX. On successful completion, the Ficl objects will be
+ available in `apps/libapps.a` and that NuttX binary will be linked against
+ that file. Of course, Ficl will do nothing unless you have written some
+ application code that uses it!
diff --git a/modbus/README.md b/modbus/README.md
index 1d3e9c7..9fe4cc9 100644
--- a/modbus/README.md
+++ b/modbus/README.md
@@ -1,123 +1,121 @@
-apps/modbus README
-==================
+# Modbus
-This directory contains a port of last open source version of FreeModBus
-(BSD license). The code in this directory is a subset of FreeModBus version
-1.5.0 (June 6, 2010) that can be downloaded in its entirety from http://developer.berlios.de/project/showfiles.php?group_id=6120.
+This directory contains a port of last open source version of FreeModBus (BSD
+license). The code in this directory is a subset of FreeModBus version 1.5.0
+(June 6, 2010) that can be downloaded in its entirety from
+http://developer.berlios.de/project/showfiles.php?group_id=6120.
Includes extensions to support RTU master mode by Armink(383016632@qq.com):
-https://github.com/armink/FreeModbus_Slave-Master-RTT-STM32. Ported to
-NuttX by Darcy Gong.
-
-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:
-
- --------------------------- ----------------------------------------------
- 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.
-
-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.
-
-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.
+https://github.com/armink/FreeModbus_Slave-Master-RTT-STM32. Ported to NuttX by
+Darcy Gong.
+
+## 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:
+
+```
+--------------------------- ----------------------------------------------
+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`.
+
+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.
+
+## 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.
The NuttX-named configuration options that are available include:
- CONFIG_MODBUS - General ModBus support
- CONFIG_MB_ASCII_ENABLED - Modbus ASCII support
- CONFIG_MB_ASCII_MASTER - Modbus ASCII master support
- CONFIG_MB_RTU_ENABLED - Modbus RTU support
- CONFIG_MB_RTU_MASTER - Modbus RTU master support
- CONFIG_MB_TCP_ENABLED - Modbus TCP support
- CONFIG_MB_ASCII_TIMEOUT_SEC - Character timeout value for Modbus ASCII. The
- character timeout value is not fixed for Modbus ASCII and is therefore
- a configuration option. It should be set to the maximum expected delay
- time of the network. Default 1
- CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS - Timeout to wait in ASCII prior
- to enabling transmitter. If defined the function calls
- vMBPortSerialDelay with the argument CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS
- to allow for a delay before the serial transmitter is enabled. This is
- required because some targets are so fast that there is no time between
- receiving and transmitting the frame. If the master is too slow with
- enabling its receiver then it will not receive the response correctly.
- CONFIG_MB_FUNC_HANDLERS_MAX - Maximum number of Modbus functions codes the
- protocol stack should support. The maximum number of supported Modbus
- functions must be greater than the sum of all enabled functions in this
- file and custom function handlers. If set too small, adding more
- functions will fail.
- CONFIG_MB_FUNC_OTHER_REP_SLAVEID_BUF - Number of bytes which should be
- allocated for the Report Slave ID command. This number limits the
- maximum size of the additional segment in the report slave id function.
- See eMBSetSlaveID() for more information on how to set this value. It
- is only used if CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED is set to 1.
- CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED - If the Report Slave ID
- function should be enabled.
- CONFIG_MB_FUNC_READ_INPUT_ENABLED - If the Read Input Registers function
- should be enabled.
- CONFIG_MB_FUNC_READ_HOLDING_ENABLED - If the Read Holding Registers
- function should be enabled.
- CONFIG_MB_FUNC_WRITE_HOLDING_ENABLED - If the Write Single Register
- function should be enabled.
- CONFIG_MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED - If the Write Multiple
- registers function should be enabled.
- CONFIG_MB_FUNC_READ_COILS_ENABLED - If the Read Coils function should
- be enabled.
- CONFIG_MB_FUNC_WRITE_COIL_ENABLED - If the Write Coils function should
- be enabled.
- CONFIG_MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED - If the Write Multiple Coils
- function should be enabled.
- CONFIG_MB_FUNC_READ_DISCRETE_INPUTS_ENABLED - If the Read Discrete Inputs
- function should be enabled.
- CONFIG_MB_FUNC_READWRITE_HOLDING_ENABLED - If the Read/Write Multiple
- Registers function should be enabled.
+- `CONFIG_MODBUS` – General ModBus support.
+- `CONFIG_MB_ASCII_ENABLED` – Modbus ASCII support.
+- `CONFIG_MB_ASCII_MASTER` – Modbus ASCII master support.
+- `CONFIG_MB_RTU_ENABLED` – Modbus RTU support.
+- `CONFIG_MB_RTU_MASTER` – Modbus RTU master support.
+- `CONFIG_MB_TCP_ENABLED` – Modbus TCP support.
+- `CONFIG_MB_ASCII_TIMEOUT_SEC` – Character timeout value for Modbus ASCII. The
+ character timeout value is not fixed for Modbus ASCII and is therefore a
+ configuration option. It should be set to the maximum expected delay time of
+ the network. Default: `1`.
+- `CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS` – Timeout to wait in ASCII prior
+ to enabling transmitter. If defined the function calls `vMBPortSerialDelay`
+ with the argument `CONFIG_MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS` to allow for a
+ delay before the serial transmitter is enabled. This is required because some
+ targets are so fast that there is no time between receiving and transmitting
+ the frame. If the master is too slow with enabling its receiver then it will
+ not receive the response correctly.
+- `CONFIG_MB_FUNC_HANDLERS_MAX` – Maximum number of Modbus functions codes the
+ protocol stack should support. The maximum number of supported Modbus
+ functions must be greater than the sum of all enabled functions in this file
+ and custom function handlers. If set too small, adding more functions will
+ fail.
+- `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_BUF` – Number of bytes which should be
+ allocated for the Report Slave ID command. This number limits the maximum size
+ of the additional segment in the report slave id function. See
+ `eMBSetSlaveID()` for more information on how to set this value. It is only
+ used if `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED` is set to `1`.
+- `CONFIG_MB_FUNC_OTHER_REP_SLAVEID_ENABLED` – If the Report Slave ID function
+ should be enabled.
+- `CONFIG_MB_FUNC_READ_INPUT_ENABLED` – If the Read Input Registers function
+ should be enabled.
+- `CONFIG_MB_FUNC_READ_HOLDING_ENABLED` – If the Read Holding Registers function
+ should be enabled.
+- `CONFIG_MB_FUNC_WRITE_HOLDING_ENABLED` – If the Write Single Register function
+ should be enabled.
+- `CONFIG_MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED` – If the Write Multiple
+ registers function should be enabled.
+- `CONFIG_MB_FUNC_READ_COILS_ENABLED` – If the Read Coils function should be
+ enabled.
+- `CONFIG_MB_FUNC_WRITE_COIL_ENABLED` – If the Write Coils function should be
+ enabled.
+- `CONFIG_MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED` – If the Write Multiple Coils
+ function should be enabled.
+- `CONFIG_MB_FUNC_READ_DISCRETE_INPUTS_ENABLED` – If the Read Discrete Inputs
+ function should be enabled.
+- `CONFIG_MB_FUNC_READWRITE_HOLDING_ENABLED` – If the Read/Write Multiple
+ Registers function should be enabled.
See also other serial settings, in particular:
- CONFIG_SERIAL_TERMIOS - Serial driver supports termios.h interfaces (tcsetattr,
- tcflush, etc.). If this is not defined, then the terminal settings (baud,
- parity, etc.) are not configurable at runtime; serial streams will not be
- flushed when closed.
+- `CONFIG_SERIAL_TERMIOS` – Serial driver supports `termios.h` interfaces
+ (`tcsetattr`, `tcflush`, etc.). If this is not defined, then the terminal
+ settings (baud, parity, etc.) are not configurable at runtime; serial streams
+ will not be flushed when closed.
-Note
-====
+## Note
The developer of FreeModBus, Christian Walter, is still developing Modbus
-libraries, although they are now commercial. See
+libraries, although they are now commercial. See
http://www.embedded-solutions.at/ for further information.
diff --git a/netutils/README.md b/netutils/README.md
index c6fef25..3ddf9a9 100644
--- a/netutils/README.md
+++ b/netutils/README.md
@@ -1,138 +1,138 @@
-netutils README.txt
-^^^^^^^^^^^^^^^^^^^
-
-Contents
---------
-
- - uIP Applications
- - Other Network Applications
- - Tips for Using Telnetd
- - Tips for Using DHCPC
-
-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:
-
- 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.
-
-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.
-
-Other Network Applications
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Additional applications that were not part of uIP (but which are
-highly influenced by uIP) include:
-
- 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 <se...@sourcemud.org>,
- Jack Kelly <en...@gmail.com>, and Katherine Flavel
- <ka...@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:
-
- 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.
+# Network Utilities
+
+## Contents
+
+- uIP Applications
+- Other Network Applications
+- Tips for Using Telnetd
+- Tips for Using DHCPC
+
+## uIP Applications
+
+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.
+
+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.
+
+## Other Network Applications
+
+Additional applications that were not part of uIP (but which are highly
+influenced by uIP) include:
+
+- `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.
-To enable and link the Telnetd daemon, you need to include the following in
-in your defconfig file:
+ 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 <se...@sourcemud.org>, Jack Kelly
+ <en...@gmail.com> and Katherine Flavel <ka...@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_TELNETD=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:
+
+```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:
-
- 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.
+required. These include:
+
+- `CONFIG_NET=y`
+- `CONFIG_NET_UDP=y` – UDP support is required for DHCP (as well as various
+ other UDP-related configuration settings).
+- `CONFIG_NET_BROADCAST=y` – UDP broadcast support is needed.
+- `CONFIG_NET_ETH_PKTSIZE=650` or larger. The client must be prepared to receive
+ DHCP messages of up to `576` bytes (excluding Ethernet, IP or UDP headers and
+ FCS). **Note**: Note that the actual MTU setting will depend upon the specific
+ link protocol. Here Ethernet is indicated.
diff --git a/netutils/discover/README.md b/netutils/discover/README.md
index 11aab8b..f5516a7 100644
--- a/netutils/discover/README.md
+++ b/netutils/discover/README.md
@@ -1,9 +1,8 @@
-apps/netutils/discover README.txt
-=================================
+# Network Utilities / `discover`
-This daemon is useful for discovering devices in local networks, especially
-with DHCP configured devices. It listens for UDP broadcasts which also can
-include a device class so that groups of devices can be discovered. It is
-also possible to address all classes with a kind of broadcast discover.
+This daemon is useful for discovering devices in local networks, especially with
+DHCP configured devices. It listens for UDP broadcasts which also can include a
+device class so that groups of devices can be discovered. It is also possible to
+address all classes with a kind of broadcast discover.
-See nuttx/tools/discover.py for a client example.
+See `nuttx/tools/discover.py` for a client example.
diff --git a/netutils/ftpc/README.md b/netutils/ftpc/README.md
index d995227..b849807 100644
--- a/netutils/ftpc/README.md
+++ b/netutils/ftpc/README.md
@@ -1,81 +1,81 @@
-/* FTP Commands *************************************************************/
-/* Command summary:
- *
- * ABOR - abort a file transfer
- * ACCT - send account information
- * APPE - append to a remote file
- * CDUP - CWD to the parent of the current directory
- * CWD - change working directory
- * DELE - delete a remote file
- * HELP - return help on using the server
- * LIST - list remote files
- * MDTM - return the modification time of a file
- * MKD - make a remote directory
- * MLSD - Standardized directory listing (instead of LIST)
- * MLST - Standardized object listing (instead of LIST)
- * MODE - set transfer mode
- * NLST - name list of remote directory
- * NOOP - do nothing
- * PASS - send password
- * PASV - enter passive mode
- * PORT - open a data port
- * PWD - print working directory
- * QUIT - terminate the connection
- * REIN - reinitialize the connection
- * RETR - retrieve a remote file
- * REST - Sets the point at which a file transfer should start
- * RMD - remove a remote directory
- * RNFR - rename from
- * RNTO - rename to
- * SITE - site-specific commands
- * SIZE - return the size of a file
- * STOR - store a file on the remote host
- * STOU - store a file uniquely
- * STRU - set file transfer structure
- * STAT - return server status
- * SYST - return system type
- * TYPE - set transfer type
- * USER - send username
- *
-/* FTP Replies **************************************************************/
- *
- * 110 - Restart marker reply.
- * 120 - Service ready in nnn minutes.
- * 125 - Data connection already open; transfer starting.
- * 150 - File status okay; about to open data connection.
- * 200 - Command okay.
- * 202 - Command not implemented, superfluous at this site.
- * 211 - System status, or system help reply.
- * 212 - Directory status.
- * 213 - File status.
- * 214 - Help message.
- * 215 - NAME system type.
- * 220 - Service ready for new user.
- * 221 - Service closing control connection.
- * 225 - Data connection open; no transfer in progress.
- * 226 - Closing data connection.
- * 227 - Entering Passive Mode (h1,h2,h3,h4,p1,p2).
- * 230 - User logged in, proceed.
- * 250 - Requested file action okay, completed.
- * 257 - "PATHNAME" created.
- * 331 - User name okay, need password.
- * 332 - Need account for login.
- * 350 - Requested file action pending further information.
- * 421 - Service not available, closing control connection.
- * 425 - Can't open data connection.
- * 426 - Connection closed; transfer aborted.
- * 450 - Requested file action not taken.
- * 451 - Requested action aborted: local error in processing.
- * 452 - Requested action not taken.
- * 500 - Syntax error, command unrecognized.
- * 501 - Syntax error in parameters or arguments.
- * 502 - Command not implemented.
- * 503 - Bad sequence of commands.
- * 504 - Command not implemented for that parameter.
- * 530 - Not logged in.
- * 532 - Need account for storing files.
- * 550 - Requested action not taken.
- * 551 - Requested action aborted: page type unknown.
- * 552 - Requested file action aborted.
- * 553 - Requested action not taken.
- */
+# Network Utilities / `ftpc` FTP Client
+
+## FTP Commands
+
+- `ABOR` – abort a file transfer
+- `ACCT` – send account information
+- `APPE` – append to a remote file
+- `CDUP` – CWD to the parent of the current directory
+- `CWD` – change working directory
+- `DELE` – delete a remote file
+- `HELP` – return help on using the server
+- `LIST` – list remote files
+- `MDTM` – return the modification time of a file
+- `MKD` – make a remote directory
+- `MLSD` – Standardized directory listing (instead of `LIST`)
+- `MLST` – Standardized object listing (instead of `LIST`)
+- `MODE` – set transfer mode
+- `NLST` – name list of remote directory
+- `NOOP` – do nothing
+- `PASS` – send password
+- `PASV` – enter passive mode
+- `PORT` – open a data port
+- `PWD` – print working directory
+- `QUIT` – terminate the connection
+- `REIN` – reinitialize the connection
+- `RETR` – retrieve a remote file
+- `REST` – Sets the point at which a file transfer should start
+- `RMD` – remove a remote directory
+- `RNFR` – rename from
+- `RNTO` – rename to
+- `SITE` – site-specific commands
+- `SIZE` – return the size of a file
+- `STOR` – store a file on the remote host
+- `STOU` – store a file uniquely
+- `STRU` – set file transfer structure
+- `STAT` – return server status
+- `SYST` – return system type
+- `TYPE` – set transfer type
+- `USER` – send username
+
+## FTP Replies
+
+- `110` – Restart marker reply.
+- `120` – Service ready in nnn minutes.
+- `125` – Data connection already open; transfer starting.
+- `150` – File status okay; about to open data connection.
+- `200` – Command okay.
+- `202` – Command not implemented, superfluous at this site.
+- `211` – System status, or system help reply.
+- `212` – Directory status.
+- `213` – File status.
+- `214` – Help message.
+- `215` – NAME system type.
+- `220` – Service ready for new user.
+- `221` – Service closing control connection.
+- `225` – Data connection open; no transfer in progress.
+- `226` – Closing data connection.
+- `227` – Entering Passive Mode (`h1`, `h2`, `h3`, `h4`, `p1`, `p2`).
+- `230` – User logged in, proceed.
+- `250` – Requested file action okay, completed.
+- `257` – `PATHNAME` created.
+- `331` – User name okay, need password.
+- `332` – Need account for login.
+- `350` – Requested file action pending further information.
+- `421` – Service not available, closing control connection.
+- `425` – Can't open data connection.
+- `426` – Connection closed; transfer aborted.
+- `450` – Requested file action not taken.
+- `451` – Requested action aborted: local error in processing.
+- `452` – Requested action not taken.
+- `500` – Syntax error, command unrecognized.
+- `501` – Syntax error in parameters or arguments.
+- `502` – Command not implemented.
+- `503` – Bad sequence of commands.
+- `504` – Command not implemented for that parameter.
+- `530` – Not logged in.
+- `532` – Need account for storing files.
+- `550` – Requested action not taken.
+- `551` – Requested action aborted: page type unknown.
+- `552` – Requested file action aborted.
+- `553` – Requested action not taken.
diff --git a/netutils/telnetd/README.md b/netutils/telnetd/README.md
index 367cef0..3013554 100644
--- a/netutils/telnetd/README.md
+++ b/netutils/telnetd/README.md
@@ -1,4 +1,3 @@
-README.txt
-^^^^^^^^^^
+# Network Utilities / `telnetd` Telnet Daemon
This directly contains a generic Telnet daemon.
diff --git a/nshlib/README.md b/nshlib/README.md
index a6379d1..c711e16 100644
--- a/nshlib/README.md
+++ b/nshlib/README.md
@@ -1,213 +1,235 @@
-apps/nshlib
-^^^^^^^^^^^
-
- This directory contains the NuttShell (NSH) library. This library can be
- linked with other logic to provide a simple shell application for NuttX.
-
- - Console/NSH Front End
- - Command Overview
- - Conditional Command Execution
- - Looping
- - Built-In Variables
- - Current Working Directory
- Environment Variables
- - NSH Start-Up Script
- - Simple Commands
- - Built-In Applications
- - NSH Configuration Settings
- Command Dependencies on Configuration Settings
- Built-in Application Configuration Settings
- NSH-Specific Configuration Settings
- - Common Problems
-
-Console/NSH Front End
-^^^^^^^^^^^^^^^^^^^^^
-
- Using settings in the configuration file, NSH may be configured to
- use either the serial stdin/out or a telnet connection as the console
- or BOTH. When NSH is started, you will see the following welcome on
- either console:
-
- NuttShell (NSH)
- nsh>
-
- 'nsh>' is the NSH prompt and indicates that you may enter a command
- from the console.
-
-Command Overview
-^^^^^^^^^^^^^^^^
-
- This directory contains the NuttShell (NSH). This is a simple
- shell-like application. At present, NSH supports the following commands
- forms:
-
- Simple command: <cmd>
- Command with re-directed output: <cmd> > <file>
- <cmd> >> <file>
- Background command: <cmd> &
- Re-directed background command: <cmd> > <file> &
- <cmd> >> <file> &
+# `nshlib` NuttShell (NSH)
- Where:
+This directory contains the NuttShell (NSH) library. This library can be linked
+with other logic to provide a simple shell application for NuttX.
- <cmd> is any one of the simple commands listed later.
- <file> is the full or relative path to any writeable object
- in the file system name space (file or character driver).
- Such objects will be referred to simply as files throughout
- this README.
+- Console/NSH Front End
+- Command Overview
+- Conditional Command Execution
+- Looping
+- Built-In Variables
+- Current Working Directory
+ - Environment Variables
+- NSH Start-Up Script
+- Simple Commands
+- Built-In Applications
+- NSH Configuration Settings
+ - Command Dependencies on Configuration Settings
+ - Built-in Application Configuration Settings
+ - NSH-Specific Configuration Settings
+- Common Problems
- NSH executes at the mid-priority (128). Backgrounded commands can
- be made to execute at higher or lower priorities using nice:
+## Console / NSH Front End
- [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
+Using settings in the configuration file, NSH may be configured to use either
+the serial `stdin`/`out` or a telnet connection as the console or BOTH. When NSH
+is started, you will see the following welcome on either console:
- Where <niceness> is any value between -20 and 19 where lower
- (more negative values) correspond to higher priorities. The
- default niceness is 10.
+```
+NuttShell (NSH)
+nsh>
+```
- Multiple commands per line. NSH will accept multiple commands per
- command line with each command separated with the semi-colon character (;).
+`nsh>` is the NSH prompt and indicates that you may enter a command from the
+console.
- If CONFIG_NSH_CMDPARMS is selected, then the output from commands, from
- file applications, and from NSH built-in commands can be used as arguments
- to other commands. The entity to be executed is identified by enclosing
- the command line in back quotes. For example,
+## Command Overview
- set FOO `myprogram $BAR`
+This directory contains the NuttShell (NSH). This is a simple shell-like
+application. At present, NSH supports the following commands forms:
- Will execute the program named myprogram passing it the value of the
- environment variable BAR. The value of the environment variable FOO
- is then set output of myprogram on stdout. Because this feature commits
- significant resources, it is disabled by default.
-
- If CONFIG_NSH_ARGCAT is selected, the support concatenation of strings
- with environment variables or command output. For example:
-
- set FOO XYZ
- set BAR 123
- set FOOBAR ABC_${FOO}_${BAR}
-
- would set the environment variable FOO to XYZ, BAR to 123 and FOOBAR
- to ABC_XYZ_123. If NSH_ARGCAT is not selected, then a slightly small
- FLASH footprint results but then also only simple environment
- variables like $FOO can be used on the command line.
-
- CONFIG_NSH_QUOTE enables back-slash quoting of certain characters within
- the command. This option is useful for the case where an NSH script is
- used to dynamically generate a new NSH script. In that case, commands
- must be treated as simple text strings without interpretation of any
- special characters. Special characters such as $, `, ", and others must
- be retained intact as part of the test string. This option is currently
- only available is CONFIG_NSH_ARGCAT is also selected.
-
-Conditional Command Execution
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- An if-then[-else]-fi construct is also supported in order to
- support conditional execution of commands. This works from the
- command line but is primarily intended for use within NSH scripts
- (see the sh command). The syntax is as follows:
-
- if [!] <cmd>
- then
- [sequence of <cmd>]
- else
- [sequence of <cmd>]
- fi
-
-Looping
-^^^^^^^
-
- while-do-done and until-do-done looping constructs are also supported.
- These works from the command line but are primarily intended for use
- within NSH scripts (see the sh command). The syntax is as follows:
-
- while <test-cmd>; do <cmd-sequence>; done
-
- Execute <cmd-sequence> as long as <test-cmd> has an exit status of
- zero.
-
- until <test-cmd>; do <cmd-sequence>; done
-
- Execute <cmd-sequence> as long as <test-cmd> has a non-zero exit
- status.
-
- A break command is also supported. The break command is only meaningful
- within the body of the a while or until loop, between the do and done
- tokens. If the break command is executed within the body of a loop, the
- loop will immediately terminate and execution will continue with the
- next command immediately following the done token.
+- Simple command:
+
+ ```
+ <cmd>
+ ```
+
+- Command with re-directed output:
+
+ ```
+ <cmd> > <file>
+ <cmd> >> <file>
+ ```
+
+- Background command:
+
+ ```
... 6851 lines suppressed ...