From ba399acb5ce1507c1e1b7872749a272a638b5a1a Mon Sep 17 00:00:00 2001 From: Nathaniel Wesley Filardo Date: Sun, 30 Jul 2017 03:20:14 -0400 Subject: [PATCH] doc improvements --- README.rst | 10 ++-------- host/readme.rst | 15 +++++++++++++++ telnetd/readme.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+), 8 deletions(-) create mode 100644 host/readme.rst create mode 100644 telnetd/readme.rst diff --git a/README.rst b/README.rst index 53dc1bf..08d0953 100644 --- 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 `_ 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 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 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) -- 2.50.1