doc improvements

diff --git a/README.rst b/README.rst
index 53dc1bf2689a6e74c576c4afd77bcdaaf329cf60..08d09531ca811bc1101d183df6b7617fbf5e85e9 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -32,7 +32,7 @@ Generic Utilities
 * ``host/pushinit.sh`` -- a host-side utility to push a minimum set of files
   up to the device, either via `luatool
   <https://github.com/4refr0nt/luatool>`_ or via an existing telnet server
-  with file overlay (see below).
+  with file overlay (see below).  See the readme in ``host/`` for more.
 
 Timer Queue
 -----------
@@ -84,13 +84,7 @@ Telnet Server
 -------------
 
 * ``telnetd/telnetd.lua`` -- the main telnet server.  Use as
-  ``tcpserv:listen(23,telnetd.server)``.
-
-* ``telnetd/telnetd-diag.lua`` -- overlay for interpreting "diag" commands;
-  automatically run by ``telnetd``.
-
-* ``telnetd/telnetd-file.lua`` -- overlay for interpreting "file" commands;
-  automatically run by ``telnetd``.
+  ``tcpserv:listen(23,telnetd.server)``.  See the readme in its directory.
 
 cap1188 driver
 --------------

diff --git a/host/readme.rst b/host/readme.rst
new file mode 100644 (file)
index 0000000..21021bd
--- /dev/null
+++ b/host/readme.rst
@@ -0,0 +1,15 @@
+Useful commands
+###############
+
+Pushing a single file from the shell, over telnet::
+
+  (MCUHOST=192.168.0.1 LUADIET=" " ; . ./host/pushcommon.sh; dopushlua init.lua )
+  (MCUHOST=192.168.0.1 LUADIET=" " ; . ./host/pushcommon.sh; dopushcompile net/nwfnet.lua )
+  (MCUHOST=192.168.0.1             ; . ./host/pushcommon.sh; dopushtext net/conf/nwfnet.conf )
+
+Or over serial::
+
+  (MCUPORT=/dev/ttyUSB0 MCUBAUD=115200 LUADIET=" " ; . ./host/pushcommon.sh; dopushlua init.lua )
+  (MCUPORT=/dev/ttyUSB0 MCUBAUD=115200 LUADIET=" " ; . ./host/pushcommon.sh; dopushcompile net/nwfnet.lua )
+  (MCUPORT=/dev/ttyUSB0 MCUBAUD=115200             ; . ./host/pushcommon.sh; dopushtext net/conf/nwfnet.conf )
+

diff --git a/telnetd/readme.rst b/telnetd/readme.rst
new file mode 100644 (file)
index 0000000..0a237d6
--- /dev/null
+++ b/telnetd/readme.rst
@@ -0,0 +1,46 @@
+.. warning::
+
+   Every line must fit within one TCP packet; ``telnetd`` does only very
+   minimal parsing and will not reassemble an over-long line!  Typically,
+   a line-buffered program like ``nc`` will be good enough about this that
+   it's OK in practice, so long as you send short enough lines!
+
+Overlay Modules
+###############
+
+Files of the form ``telnetd-${foo}.lc`` are consulted by ``telnetd`` if the
+first word of a line is ``${foo}``; the next word is used to pull a function
+from a dictionary, and the rest of the line, together with a function for
+sending a response, is passed in to the function so retrieved.
+
+* ``telnetd/telnetd-diag.lua`` -- overlay for interpreting "diag" commands.
+
+  * ``boot`` returns the bootreason values (``node.bootreason()``)
+  * ``heap`` shows how much heap is available (``node.heap()``)
+  * ``info`` displays ``node.info()``
+  * ``fifo`` shows ``rtcfifo.count()`` if ``rtcfifo`` has been initialized
+  * ``exec`` is the most useful: it runs ``loadstring`` and ``pcall`` on the remainder of the line.
+
+* ``telnetd/telnetd-file.lua`` -- overlay for interpreting "file" commands.
+
+  * ``info`` shows bytes allocated and free
+  * ``list`` dumps a list of files and their sizes
+  * ``remove`` does what it says on the tin
+  * ``compile`` likewise
+  * ``pwrite`` is a positional-write command, used by ``host/pushvia.expect``; it
+    takes an offset, file name, and a base64-encoded blob.  The
+    all-in-one-packet requirement of ``telnetd`` limits the length of the
+    blob; ``host/pushvia.expect`` tries to be quite conservative.
+  * ``pread`` is the read dual of ``pwrite``; takes a length, an offset, and
+    a file name, and returns a base64-encoded blob.  Be careful that length
+    is reasonable, to minimize heap usage.
+  * ``cert`` loads a file in its entirety and passes it to ``net.cert.verify``.
+    Be careful, as this can use a lot of heap.
+
+Some useful commands
+####################
+
+Schedule a reboot of the node "soon"; we need to give the ESP stack enough
+time to write back the prompt, or we risk racing and panic-ing the stack::
+
+  diag exec tmr.alarm(tmr.create(), 1000, tmr.ALARM_SINGLE, node.restart)