Documentaion: migrate netutils/readme

Documentation/applications/netutils/cjson/index.rst

@@ -0,0 +1,11 @@
+=======================
+``cjson`` cJSON library
+=======================
+
+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.

Documentation/applications/netutils/dhcpc/index.rst

@@ -0,0 +1,6 @@
+=====================
+``dhcpc`` DHCP client
+=====================
+
+Dynamic Host Configuration Protocol (DHCP) client. See
+``apps/include/netutils/dhcpc.h`` for interface information.

Documentation/applications/netutils/dhcpd/index.rst

@@ -0,0 +1,20 @@
+=====================
+``dhcpd`` DHCP server
+=====================
+
+See ``apps/include/netutils/dhcpd.h`` for interface information.
+
+Tips for Using DHCPC
+--------------------
+
+If you use DHCPC/D, then some special configuration network options are
+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.

Documentation/applications/netutils/discover/index.rst

@@ -0,0 +1,12 @@
+======================================
+``discover`` Network Discovery Utility
+======================================
+
+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.
+
+(Contributed by Max Holtzberg).

Documentation/applications/netutils/esp8266/index.rst

@@ -0,0 +1,5 @@
+===================
+``esp8266`` ESP8266
+===================
+
+An ESP8266 networking layer contributed by Pierre-Noel Bouteville.

Documentation/applications/netutils/ftpc/index.rst

@@ -0,0 +1,87 @@
+===================
+``ftpc`` FTP client
+===================
+
+FTP client. See ``apps/include/netutils/ftpc.h`` for interface information.
+
+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.

Documentation/applications/netutils/ftpd/index.rst

@@ -0,0 +1,5 @@
+===================
+``ftpd`` FTP server
+===================
+
+FTP server. See ``apps/include/netutils/ftpd.h`` for interface information.

Documentation/applications/netutils/index.rst

@@ -2,39 +2,41 @@
 Network Utilities
 =================
 
+.. toctree::
+   :glob:
+   :maxdepth: 3
+   :titlesonly:
+   
+   */*
+
+
 - chat - Chat tool
-- cjson - cJSON library
 - codecs - CODEC Library: Base64 coding, URL coding, MD5
 - cwebsocket - WebSocket Client Library
 - dhcp6c - DHCPv6 client
-- dhcpc - DHCP client
-- dhcpd - DHCP server
-- discover - Network Discovery Utility
-- esp8266 - ESP8266
-- ftpc - FTP client
-- ftpd - FTP server
-- iperf - iperf example
 - iptables - iptables libary
 - libcurl4nx - cURL4nx HTTP client library
 - mqttc - MQTT-C library
-- netcat - NetCat tool
 - netinit - Network initialization
 - netlib - Network support library
 - nng - Nanomsg NG
-- ntpclient - NTP client
-- ping - ICMP ping support
 - pppd - PPP server
 - ptpd - PTPD client/server
 - rexec - Remote execution client
 - rexecd - Remote Execution Server
 - rtptools - RTP Tools
-- smtp - SMTP
-- telnetc - Telnet client library
-- telnetd - Telnet daemon
-- tftpc - TFTP client
-- thttpd - THTTPD webserver
 - wakaama - Eclipse Wakaama (formerly liblwm2m) - an implementation of LWM2M protocol.
 - wakeonlan - WakeOnLAN support
-- webclient - uIP web client
+
-- webserver - uIP web server
+uIP Applications
-- xmlrpc - XML RPC library
+----------------
+
+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``, ``smtp``,
+``webclient`` and ``webserver``
+
+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.

Documentation/applications/netutils/iper/index.rst

@@ -0,0 +1,98 @@
+===============
+``iperf`` iperf
+===============
+
+Overview
+--------
+
+This is a NuttX port of the ESP-IDF iperf example. [1]
+
+It doesn't support all features in standard iperf.
+It's supposed to be compatible with iperf version 2.x. [2]
+
+[1] https://github.com/espressif/esp-idf/tree/master/examples/wifi/iperf
+[2] https://sourceforge.net/projects/iperf2/
+
+Configuring NuttX to use your Wireless Router (aka Access Point)
+----------------------------------------------------------------
+
+Since you are already in the root of NuttX/ repository, execute
+make menuconfig to define your Wireless Router and your password::
+
+    $ make menuconfig
+
+    Browser the menus this way:
+
+    Application Configuration  --->
+        Network Utilities  --->
+            Networking Configuration  --->
+                WAPI Configuration  --->
+                    (myApSSID) SSID
+                    (mySSIDpassphrase) Passprhase
+
+Replace the SSID from myApSSID with your wireless router name and
+the Passprhase with your WiFi password.
+
+Exit and save your configuration.
+
+iperf Test Example
+------------------
+
+To set up, do ``make menuconfig`` and select the Apps > netutils > iperf example. 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.
+
+If you are using a wireless network card, you must first connect to the router:
+
+On host::
+
+    $ iperf -s -p 5471 -i 1 -w 416K
+    ------------------------------------------------------------
+    Server listening on TCP port 5471
+    TCP window size:  416 KByte
+    ------------------------------------------------------------
+
+On NuttX::
+
+    nsh> iperf -c 192.168.1.181 -p 5471 -i 1 -t 10
+    mode=tcp-client sip=192.168.1.198:5001, dip=192.168.1.181:5471, interval=1, time=10
+
+            Interval Bandwidth
+
+    0-   1 sec,  0.39 Mbits/sec
+    1-   2 sec,  0.26 Mbits/sec
+    2-   3 sec,  0.39 Mbits/sec
+    3-   4 sec,  0.26 Mbits/sec
+    4-   5 sec,  0.26 Mbits/sec
+    5-   6 sec,  0.26 Mbits/sec
+    6-   7 sec,  0.26 Mbits/sec
+    7-   8 sec,  0.26 Mbits/sec
+    8-   9 sec,  0.26 Mbits/sec
+    9-  10 sec,  0.26 Mbits/sec
+    0-  10 sec,  0.28 Mbits/sec
+
+Now on the host you should see something like::
+
+    $ iperf -s -p 5471 -i 1 -w 416K
+    ------------------------------------------------------------
+    Server listening on TCP port 5471
+    TCP window size:  416 KByte
+    ------------------------------------------------------------
+    [  5] local 192.168.1.181 port 5471 connected with 192.168.1.198 port 4210
+    [  5]  0.0- 1.0 sec  60.8 KBytes   498 Kbits/sec
+    [  5]  1.0- 2.0 sec  34.9 KBytes   286 Kbits/sec
+    [  5]  2.0- 3.0 sec  33.7 KBytes   276 Kbits/sec
+    [  5]  3.0- 4.0 sec  33.4 KBytes   274 Kbits/sec
+    [  5]  4.0- 5.0 sec  32.0 KBytes   262 Kbits/sec
+    [  5]  5.0- 6.0 sec  32.0 KBytes   262 Kbits/sec
+    [  5]  6.0- 7.0 sec  33.4 KBytes   274 Kbits/sec
+    [  5]  7.0- 8.0 sec  32.0 KBytes   262 Kbits/sec
+    [  5]  8.0- 9.0 sec  32.0 KBytes   262 Kbits/sec
+    [  5]  9.0-10.0 sec  33.4 KBytes   274 Kbits/sec
+    [  5]  0.0-10.3 sec   368 KBytes   292 Kbits/sec
+
+
+This will tell you the link speed in Kbits/sec – kilobits per second. If you want kilobytes, divide by 8.
+

Documentation/applications/netutils/netcat/index.rst

@@ -0,0 +1,81 @@
+======================
+``netcat`` NetCat tool
+======================
+
+netcat TCP/IP Swiss army knife.
+
+It was re-implemented from scratch for NuttX
+
+DEMO
+----
+
+.. image:: https://files.mastodon.social/media_attachments/files/105/163/916/892/863/178/original/05468e28b4463f95.png
+
+* https://mastodon.social/@rzr/105225153152922220#weboftwins-osvehicle-2020-rzr
+* https://purl.org/rzr/weboftwins
+
+USAGE
+-----
+
+Usage is straightforward::
+
+    nsh> help ; netcat
+    Usage: netcat [-l] [destination] [port] [file]
+
+    nsh> renew eth0 ; ifconfig
+
+    eth0    Link encap:Ethernet HWaddr 52:13:FF:FF:FF:FF at UP
+            inet addr:192.168.1.42 DRaddr:192.168.1.254 Mask:255.255.255.0
+
+In the following examples, following configuration is used:
+
+- target (nuttx) is 192.168.1.42
+- host (linux) is 192.168.1.55
+
+Server
+~~~~~~
+
+As a server on NuttX and Linux's netcat as client::
+
+    nsh> netcat -l
+
+    sh> cat /proc/version | netcat 192.168.1.42 31337
+    Linux ...
+
+Default port is 31337 but it can changed::
+
+    nsh> renew eth0 ; ifconfig ; netcat -l
+    log: net: listening on :31337
+    Linux ...
+
+Client
+~~~~~~
+
+Start Server on GNU/Linux::
+
+    sh> ip addr show && netcat -l 31337
+
+Client side on nuttx, we create::
+
+    nsh> help ; renew eth0 ; ifconfig
+    nsh> netcat 192.168.1.55 31337 /proc/version
+
+Using pipes
+~~~~~~~~~~~
+
+.. code-block:: bash
+
+   mkfifo /dev/fifo
+   netcat 192.168.1.55 31337 /proc/fifo
+   help > /dev/fifo
+
+   fxos8700cq > /dev/fifo &
+   fxos8700cq [7:100]
+   netcat 192.168.1.55 31337  /dev/fifo
+
+Resources
+~~~~~~~~~
+
+* <https://en.wikipedia.org/wiki/Netcat>
+* <https://purl.org/rzr/weboftwins>
+* <https://github.com/rzr/aframe-smart-home/issues/3>

Documentation/applications/netutils/ntpclient/index.rst

@@ -0,0 +1,6 @@
+========================
+``ntpclient`` NTP client
+========================
+
+This is a fragmentary NTP client. It neither well-tested nor
+mature nor complete at this point in time.

Documentation/applications/netutils/ping/index.rst

@@ -0,0 +1,11 @@
+==========================
+``ping`` ICMP ping support
+==========================
+
+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.

Documentation/applications/netutils/smtp/index.rst

@@ -0,0 +1,6 @@
+=============
+``smtp`` SMTP
+=============
+
+Simple Mail Transfer Protocol (SMTP) client. See ``apps/include/netutils/smtp.h``
+for interface information.

Documentation/applications/netutils/telnetc/index.rst

@@ -0,0 +1,10 @@
+=================================
+``telnetc`` Telnet client library
+=================================
+
+This is a port of libtelnet to NuttX. This is a public domain
+Telnet client library available from https://github.com/seanmiddleditch/libtelnet
+modified for use with NuttX.
+
+Original Authors: Sean Middleditch <sean@sourcemud.org>, Jack Kelly
+<endgame.dos@gmail.com> and Katherine Flavel <kate@elide.org>

Documentation/applications/netutils/telnetd/index.rst

@@ -0,0 +1,30 @@
+================================
+``telnetd`` Telnet server daemon
+================================
+
+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.
+
+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::
+
+  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
+(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.

Documentation/applications/netutils/tftpc/index.rst

@@ -0,0 +1,5 @@
+=====================
+``tftpc`` TFTP client
+=====================
+
+TFTP client. See ``apps/include/netutils/tftp.h`` for interface information.

Documentation/applications/netutils/thttpd/index.rst

@@ -0,0 +1,12 @@
+===========================
+``thttpd`` THTTPD webserver
+===========================
+
+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

Documentation/applications/netutils/webclient/index.rst

@@ -0,0 +1,6 @@
+============================
+``webclient`` uIP web client
+============================
+
+HTTP web client. See ``apps/include/netutils/webclient.h`` for interface information.
+

Documentation/applications/netutils/webserver/index.rst

@@ -0,0 +1,5 @@
+============================
+``webserver`` uIP web server
+============================
+
+HTTP web server. See ``apps/include/netutils/httpd.h`` for interface information.

Documentation/applications/netutils/xmlrpc/index.rst

@@ -0,0 +1,6 @@
+==========================
+``xmlrpc`` XML RPC library
+==========================
+
+The Embeddable Lightweight XML-RPC Server discussed at
+http://www.drdobbs.com/web-development/an-embeddable-lightweight-xml-rpc-server/184405364