AceUtils
0.3
Useful Arduino utilties which are too small as separate libraries, but complex enough to have external dependencies to other libraries.
|
These classes implement a non-blocking command line interface on the Serial port. In ther words, you can implement a primitive "shell" for the Arduino.
These classes were initially an experiment to validate the AceRoutine
macros and classes but they seem to be useful as an independent library. They may be moved to a separate project/repository later.
Version: (2019-07-23)
The basic steps for adding a command line interface to an Arduino sketch using the cli/
library is the following:
CommandHandler
class for each command, defining its name
and helpString
.CommandHandler*
pointers with all the commands that you would like to suport.CommandManager
object, giving it the CommandHandler*
array, and a number of size parameters for various internal buffers (maximum line buffer length, and maximum number of argv
parameters for a command).CommandManager
into the CoroutineScheduler
by calling commandManager.setupCoroutine()
just before CoroutineScheduler::setup()
.CoroutineScheduler::loop()
in the global loop()
method to run the CommandManager
as a coroutine.The CommandHandler
class defines the command's name
, helpString
and the run()
method that implements the command. It takes the following parameters:
printer
is the output device, which will normally be the global Serial
objectargc
is the number of argv
argumentsargv
is the array of cont char*
pointers, each pointing to the words of the command line delimited by whitespaces. These are identical to the argc
and argv
parameters passed to the C-language main(argc, argv)
function. For example, argv[0]
is the name of the command, and argv[1]
is the first argument after the command (if it exists).The CommandManager
is a templatized convenience class that creates all the helper objects and buffers needed to read and parse the command line input. It includes:
StreamLineReader
coroutine that reads the input lines from Serial
CommandDispatcher
coroutine that parses the input linesChannel<InputLine>
from StreamLineReader
to CommandDispatcher
(const char*)
to hold the command line arguments of the commandYou don't have to use the CommandManager
, but it greatly simplies the creation and usage of the CommandDispatcher
.
An Arduino .ino
file that uses the CLI classes to implement a commmand line shell will look something like this:
Within the CommandHandler
, there are several helper routines which are useful for processing the argc
and argv
arguments:
SHIFT_ARGC_ARGV(argc, argv)
macro shifts the input tokens by 1, incrementing argv
and decrementing argc
bool isArgEqual(const char*, const char*);
bool isArgEqual(const char*, const __FlashHelperString*);
Here is the sketch of the Command that will parse a command whose syntax is delay [(on | off) {millis}]
, where the on {millis}
and off {millis}
arguments to the delay
command are optional:
See examples/CommandLineShell/ for an demo program that implements 5 commands:
help [command]
list
free
echo [args ...]
delay [(on | off) millis]