This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit a9a1d719dabf773344ee2bb49174c21be0a10cf6 Author: raiden00pl <raide...@railab.me> AuthorDate: Tue Oct 24 12:22:59 2023 +0200 Documentaion: migrate netutils/readme --- .../applications/netutils/cjson/index.rst | 11 +++ .../applications/netutils/dhcpc/index.rst | 6 ++ .../applications/netutils/dhcpd/index.rst | 20 +++++ .../applications/netutils/discover/index.rst | 12 +++ .../applications/netutils/esp8266/index.rst | 5 ++ .../applications/netutils/esp8266/index/rst | 0 Documentation/applications/netutils/ftpc/index.rst | 87 +++++++++++++++++++ Documentation/applications/netutils/ftpd/index.rst | 5 ++ Documentation/applications/netutils/index.rst | 40 ++++----- Documentation/applications/netutils/iper/index.rst | 98 ++++++++++++++++++++++ .../applications/netutils/netcat/index.rst | 81 ++++++++++++++++++ .../applications/netutils/ntpclient/index.rst | 6 ++ Documentation/applications/netutils/ping/index.rst | 11 +++ Documentation/applications/netutils/smtp/index.rst | 6 ++ .../applications/netutils/telnetc/index.rst | 10 +++ .../applications/netutils/telnetd/index.rst | 30 +++++++ .../applications/netutils/tftpc/index.rst | 5 ++ .../applications/netutils/thttpd/index.rst | 12 +++ .../applications/netutils/webclient/index.rst | 6 ++ .../applications/netutils/webserver/index.rst | 5 ++ .../applications/netutils/xmlrpc/index.rst | 6 ++ 21 files changed, 443 insertions(+), 19 deletions(-) diff --git a/Documentation/applications/netutils/cjson/index.rst b/Documentation/applications/netutils/cjson/index.rst new file mode 100644 index 0000000000..4f5c598c07 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/dhcpc/index.rst b/Documentation/applications/netutils/dhcpc/index.rst new file mode 100644 index 0000000000..a9984c8fe8 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/dhcpd/index.rst b/Documentation/applications/netutils/dhcpd/index.rst new file mode 100644 index 0000000000..26b102d47b --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/discover/index.rst b/Documentation/applications/netutils/discover/index.rst new file mode 100644 index 0000000000..f4ce04d410 --- /dev/null +++ b/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). diff --git a/Documentation/applications/netutils/esp8266/index.rst b/Documentation/applications/netutils/esp8266/index.rst new file mode 100644 index 0000000000..972980b912 --- /dev/null +++ b/Documentation/applications/netutils/esp8266/index.rst @@ -0,0 +1,5 @@ +=================== +``esp8266`` ESP8266 +=================== + +An ESP8266 networking layer contributed by Pierre-Noel Bouteville. diff --git a/Documentation/applications/netutils/esp8266/index/rst b/Documentation/applications/netutils/esp8266/index/rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/Documentation/applications/netutils/ftpc/index.rst b/Documentation/applications/netutils/ftpc/index.rst new file mode 100644 index 0000000000..21dd8aae1d --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/ftpd/index.rst b/Documentation/applications/netutils/ftpd/index.rst new file mode 100644 index 0000000000..42dea03f00 --- /dev/null +++ b/Documentation/applications/netutils/ftpd/index.rst @@ -0,0 +1,5 @@ +=================== +``ftpd`` FTP server +=================== + +FTP server. See ``apps/include/netutils/ftpd.h`` for interface information. diff --git a/Documentation/applications/netutils/index.rst b/Documentation/applications/netutils/index.rst index a5e5674cf0..610cc4a3b4 100644 --- a/Documentation/applications/netutils/index.rst +++ b/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 -- xmlrpc - XML RPC library + +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``, ``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. diff --git a/Documentation/applications/netutils/iper/index.rst b/Documentation/applications/netutils/iper/index.rst new file mode 100644 index 0000000000..6c8a077c55 --- /dev/null +++ b/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. + diff --git a/Documentation/applications/netutils/netcat/index.rst b/Documentation/applications/netutils/netcat/index.rst new file mode 100644 index 0000000000..15c1316da3 --- /dev/null +++ b/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> diff --git a/Documentation/applications/netutils/ntpclient/index.rst b/Documentation/applications/netutils/ntpclient/index.rst new file mode 100644 index 0000000000..222be2a946 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/ping/index.rst b/Documentation/applications/netutils/ping/index.rst new file mode 100644 index 0000000000..634cde7180 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/smtp/index.rst b/Documentation/applications/netutils/smtp/index.rst new file mode 100644 index 0000000000..7763c6d475 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/telnetc/index.rst b/Documentation/applications/netutils/telnetc/index.rst new file mode 100644 index 0000000000..70e034b629 --- /dev/null +++ b/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 <s...@sourcemud.org>, Jack Kelly +<endgame....@gmail.com> and Katherine Flavel <k...@elide.org> diff --git a/Documentation/applications/netutils/telnetd/index.rst b/Documentation/applications/netutils/telnetd/index.rst new file mode 100644 index 0000000000..9fe108f618 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/tftpc/index.rst b/Documentation/applications/netutils/tftpc/index.rst new file mode 100644 index 0000000000..ce0989569a --- /dev/null +++ b/Documentation/applications/netutils/tftpc/index.rst @@ -0,0 +1,5 @@ +===================== +``tftpc`` TFTP client +===================== + +TFTP client. See ``apps/include/netutils/tftp.h`` for interface information. diff --git a/Documentation/applications/netutils/thttpd/index.rst b/Documentation/applications/netutils/thttpd/index.rst new file mode 100644 index 0000000000..08e218a7d0 --- /dev/null +++ b/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 diff --git a/Documentation/applications/netutils/webclient/index.rst b/Documentation/applications/netutils/webclient/index.rst new file mode 100644 index 0000000000..ca0cfb96e5 --- /dev/null +++ b/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. + diff --git a/Documentation/applications/netutils/webserver/index.rst b/Documentation/applications/netutils/webserver/index.rst new file mode 100644 index 0000000000..9f48fafe81 --- /dev/null +++ b/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. diff --git a/Documentation/applications/netutils/xmlrpc/index.rst b/Documentation/applications/netutils/xmlrpc/index.rst new file mode 100644 index 0000000000..997e297c34 --- /dev/null +++ b/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