From 4c51be9ae8709ad4855ea3644cd307fed54a104c Mon Sep 17 00:00:00 2001 From: Rhys Weatherley Date: Sun, 13 Mar 2016 07:20:03 +1000 Subject: [PATCH] High-level documentation for the shell library --- doc/mainpage.dox | 14 ++++ doc/shell-serial.dox | 80 +++++++++++++++++++ doc/shell-telnet.dox | 39 +++++++++ .../examples/SerialShell/SerialShell.ino | 4 +- libraries/Terminal/keywords.txt | 4 + 5 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 doc/shell-serial.dox create mode 100644 doc/shell-telnet.dox create mode 100644 libraries/Terminal/keywords.txt diff --git a/doc/mainpage.dox b/doc/mainpage.dox index b6b2339a..836a5a65 100644 --- a/doc/mainpage.dox +++ b/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 diff --git a/doc/shell-serial.dox b/doc/shell-serial.dox new file mode 100644 index 00000000..8fb08be2 --- /dev/null +++ b/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 +*/ diff --git a/doc/shell-telnet.dox b/doc/shell-telnet.dox new file mode 100644 index 00000000..682b2726 --- /dev/null +++ b/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 +*/ diff --git a/libraries/Terminal/examples/SerialShell/SerialShell.ino b/libraries/Terminal/examples/SerialShell/SerialShell.ino index f65ce572..0fddb1d4 100644 --- a/libraries/Terminal/examples/SerialShell/SerialShell.ino +++ b/libraries/Terminal/examples/SerialShell/SerialShell.ino @@ -6,10 +6,10 @@ This example is placed into the public domain. #include -int ledPin = 13; - Shell shell; +int ledPin = 13; + void cmdLed(Shell &shell, int argc, const ShellArguments &argv) { if (argc > 1 && !strcmp(argv[1], "on")) diff --git a/libraries/Terminal/keywords.txt b/libraries/Terminal/keywords.txt new file mode 100644 index 00000000..cf6882e8 --- /dev/null +++ b/libraries/Terminal/keywords.txt @@ -0,0 +1,4 @@ +Shell KEYWORD1 +LoginShell KEYWORD1 +Terminal KEYWORD1 +loop KEYWORD2