High-level documentation for the shell library

doc/mainpage.dox

@@ -103,6 +103,20 @@ realtime clock and the LCD library to implement an alarm clock.
 
 More information can be found on the \ref crypto "Cryptographic Library" page.
 
+\section main_Terminal Terminal Library
+
+\li Terminal class that extends Stream with functions suitable for
+interfacing to a VT100-compatible terminal program like PuTTY.
+\li Shell class that manages a Unix-like command-line shell for executing
+commands via a serial port or telnet session.  Shell is built on top of
+the functionality of Terminal.
+\li LoginShell class that extends Shell to provide a simple username and
+password login mechanism.
+\li \ref shell_serial "SerialShell" example that shows how to use Shell to
+provide command-line access via a serial port.
+\li \ref shell_telnet "TelnetServer" example that shows how to use
+LoginShell to provide command-line access via the telnet protocol.
+
 \section main_IR Infrared Control Library
 
 \li IRreceiver class that receives incoming RC-5 commands from an

doc/shell-serial.dox

@@ -0,0 +1,80 @@
+/*
+ * Copyright (C) 2016 Southern Storm Software, Pty Ltd.
+ *
+ * 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.
+ */
+
+/**
+\file shell-serial.dox
+\page shell_serial Serial port Shell example
+
+The Shell class provides a Unix-like shell for issuing commands to
+the Arduino.  This example shows how to use Shell to provide command-line
+access via a serial port.  The example has one command "led" for turning
+the status LED on D13 on and off.
+
+We start by including the shell library definitions and declaring a
+variable of type Shell:
+
+\dontinclude Terminal/examples/SerialShell/SerialShell.ino
+\skip #include
+\until Shell shell;
+
+Next we need to initialize the serial port and tell the shell object
+to use it for communications:
+
+\dontinclude Terminal/examples/SerialShell/SerialShell.ino
+\skip void setup()
+\until }
+
+The call to \link Shell::setPrompt() shell.setPrompt()\endlink specifies
+the prompt to display whenever a new line of input is required.  The
+default value is "$ " but we have changed it to "Command: " in this example.
+The string can be anything and can be changed later if necessary.
+
+The call to \link Shell::begin() shell.begin()\endlink starts the actual
+shell.  The first argument is the underlying stream to use for
+communications, the Serial port in our case.  The second argument sets the
+size of the history stack so that Shell can remember previous commands
+and let the user navigate back to them with the up/down arrow keys.
+
+The shell needs to regularly process input from the serial port and
+handle commands.  We accomplish this by calling
+\link Shell::loop() shell.loop()\endlink from the application's main
+loop() function:
+
+\dontinclude Terminal/examples/SerialShell/SerialShell.ino
+\skip void loop()
+\until }
+
+At this point the application will have two builtin commands, "help" and
+"exit".  But we also want a command of our own.  We do this by declaring a
+command handler:
+
+\dontinclude Terminal/examples/SerialShell/SerialShell.ino
+\skip int ledPin
+\until ShellCommand
+
+The ShellCommand() macro informs the shell of a new command with its name,
+help string, and the name of the handler function.
+
+The full source code for the example follows:
+
+\include Terminal/examples/SerialShell/SerialShell.ino
+*/

doc/shell-telnet.dox

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2016 Southern Storm Software, Pty Ltd.
+ *
+ * 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.
+ */
+
+/**
+\file shell-telnet.dox
+\page shell_telnet Telnet server example
+
+The Shell class provides a Unix-like shell for issuing commands to
+the Arduino.  The LoginShell class extends Shell to also include login
+functionality.  The user is prompted for username and password before
+access is granted to shell commands.
+
+This example shows how to use LoginShell to provide command-line access
+over the Internet via the telnet protocol.  The example has one command
+"led" for turning the status LED on D13 on and off.
+
+The full source code for the example follows:
+
+\include Terminal/examples/TelnetServer/TelnetServer.ino
+*/

libraries/Terminal/examples/SerialShell/SerialShell.ino

@@ -6,10 +6,10 @@ This example is placed into the public domain.
 
 #include <Shell.h>
 
-int ledPin = 13;
-
 Shell shell;
 
+int ledPin = 13;
+
 void cmdLed(Shell &shell, int argc, const ShellArguments &argv)
 {
     if (argc > 1 && !strcmp(argv[1], "on"))

libraries/Terminal/keywords.txt

@@ -0,0 +1,4 @@
+Shell	KEYWORD1
+LoginShell	KEYWORD1
+Terminal	KEYWORD1
+loop	KEYWORD2