AceRoutine
0.1
A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.
|
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.
StreamReader
- a class that provided non-blocking methods for reading various types of input tokens from the Serial
port. Supported tokens include whole lines (terminated by newline), words (separated by whitespace), and integers.CommandDispatcher
- a class that uses the StreamReader
and the AceRoutine
library to read command lines from the Serial
port, parse the command line string, then dispatch to the appropriate CommandHandler
to perform the associated command.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: (2018-07-20)
The basic steps for adding a command line interface to an Arduino sketch using the cli/
library is the following:
StreamReader
, giving it the buffers that it needs.DispatchTable
containing the list of commands whose signature matches CommandHandler
.CommanDispatcher
which reads a whole line from the Serial port, and dispatches to the appropriate command.CommandDispatcher
as an AceRoutine
coroutine in the global loop()
.The CommandDispatcher
is a subclass of the Coroutine
class and implements a coroutine in the run()
method. This is a manually created coroutine, not managed by the COROUTINE()
macro, so the the resume()
method must be called to add it to the CoroutineScheduler
.
The calling client is expected to create one of 2 subclasses of CommandDispatcher
:
CommandDispatcherC
: accepts an array of DispatchRecordC
objects which hold normal C-strings (i.e. const char*
)CommandDispatcherF
: accepts an array of DispatchRecordF
objects which hold PROGMEM strings stored in flash memory (i.e. const __FlashStringHelper*
)On devices with limited static RAM like AVR boards, using flash strings can be critical to allowing the program to run.
The CommandHandler
typedef is a pointer to a user-defined function that has the following signature:
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).Both the StreamReader
and CommandDispatcher
perform no memory allocations internally (no malloc()
, no new
operator) to avoid memory problems. All data structures used by these classes must be pre-allocated by the calling code. Normally they will be created at static initialization time (before the global setup()
method is called), but the calling code is allowed to create them on the heap if it wants or needs to.
An Arduino .ino
file that uses the CLI classes to implement a commmand line shell will look something like this:
See examples/CommandLineInterface/ for an demo program that implements 5 commands:
help [command]
list
free
echo [args ...]
delay (on | off) millis