-
Notifications
You must be signed in to change notification settings - Fork 7
API
Commander is highly configurable and included methods of extracting the configuration settings from one Commander object and applying them to another.
Additional configuration methods relating specifically to the stream objects Commander is attached to can be found in the Stream objects section.
These methods can be used to query and extract items from the payload. The payload is anything that is found in the buffer after a command has been identified. The command will always be at the start of the buffer and the payload comes after it. The payload can be processed as discrete 'items' and each item is defined as a group of characters that have a delimiter at each end, or a delimiter at the start and an end of line at the end. The exception is when characters are enclosed with quote marks.
Here is an example payload:
Hi my name is bill
It contains five items, so the method countItems() will return 5.
Here is another payload example:
Hi my "name is bill"
This contains three items because the last three words are enclosed in quotes, so countItems() will return 3.
Commander has several methods for extracting payload items and it uses an internal variable to keep track of where it is in the buffer so that repeated calls to these methods can be used to extract items in sequence.
If autochain is enabled, unprocessed parts of the payload will be reloaded as a new command line and then processed when update() is next called. This allows multiple commands and their payloads to be 'chained' together on a single line. Automatic chaining can be surpressed for specific user commands by calling the unchain() method at the end of the command handler. You can also invoke command chaining when autochain is disabled by calling chain() at the end of specific command handlers.
Chaining of internal commands will only work when autochain is enabled.
Commander has a set of print methods which, when called, invoke the same methods for whatever outgoing Stream object is attached to the Commander object. These print methods should always be used within command handler functions to ensure that the command list and its handlers can work transparently with any Stream object. This way the same command list can serve a USB serial port, a Bluetooth SSP connection, and a hardware UART serial port, and all responses to commands sent from any of those streams will be sent back to the stream that the command came from.
Commander also uses some internal checks to apply prefix and postfix formatting where user sp0ecified tect is applied at the start and end of any line. It relies on the user of its own print methods to correctly apply formatting.
Commander can prefix outgoing data with user defined text, and attach more postfix text to the end of a line. One of the ways this can be used is to enclose evey line with opening and closing HTML formatting tags.
Commander can be locked and unlocked. If an optional passphrase is set then it must be used to unlock the command system.
There are two lock levels, soft or hard. A soft lock allows internal commands to be used and will print help data. A hard lock prevents all internal commands except the unlock command. HARD_LOCK and SOFT_LOCK are defined as macros for true and false.
Commander can be used to create multi layer command structures allowing you to enter and leave sub command menus. The help system works across all sub menus and it is possuble to invoke a sub command by including it in a payload when invoking the sub command from the main menu.
There are two ways of creating multi layer command structures, each with advantages and disadvantagesa. Method one involves creating multiple instances of a Commander object, each with its own command list, and passing control between each instance. Method two involves dynamically attaching new command lists to the same Commander object.
Using multiple Commander objects is faster at switching between command lists because command lists are only loaded once when the system starts up. Multiple Commander objects can consume more memory.
Using a single Commander object is slower because there are a number of things the Commander object must do to initialise a new command list when it is loaded. It also had to dynamically allocate memory for some variables associated with the command list.
(This is still a bit experimental) Commander has some special methods for dealing with streams of data. There may be instances where you want to use Commander to write data to a file on an SD card and you don't want it trying to process the data you are sending. You can attach a special stream function to Commander which can handle and streaming data in the way that you want.
Commander can have three Stream objects attached. Command data is read from the incoming Stream (the input port) and replies are sent to the outgoing stream (the output port) The incoming and outgoing streams can both be attached to the same Stream object.
A third alt or alternative port can optionally have another Stream attached to it.
One way the alt port can be used is for debugging so that data going in and out of the other ports can be monitored, or logged to an SD card.
The quick set and get system is designed to make it easier to create commsnds for reading and writing variables whilst preserving a basic help system. Rather than creating a command handler for reading from and writing to each variable, a single command handler can be used for reading, and another for writing.
Commander has a sophisticated help system that can generate a help file for all or some of the commands in a command list, as well as internal commands.