GettingStarted

The goal of Commander was quite simple. Make it quick, and relatively easy, to build flexible and useful text based command systems for Arduinos.

Commander does this by reading a Stream object, usually a Serial port, but it can also read File Streams, or any other Stream object. When it reads a Stream it adds incoming bytes to its internal buffer, a String object called bufferString. When Commander encounters an end of line character (usually an ASCII newline character) it checks to see if the contents of the buffer begin with any of its user commands or internal commands. If it finds a match it then calls the command handler.

This command handler is written by the user to do whatever job they want doing when that command is sent.

The process of building your command system has two parts - the command list, and the command handlers.

Command lists

Command lists are arrays of data, each item in the array contains three pieces of data:

• The command text
• The command handler function name
• Some optional help text that explains what the command does

The command list needs to be declared in your sketch, here is an example of a command list with a single command:

const commandList_t commands[] = {
  {"hello",      helloHandler, "Say hello"},
};

The process of adding a new command to the list is just a matter of copying the first item, pasting it into the list, and editing the contents, for example here we will add a command called goodbye:

const commandList_t commands[] = {
  {"hello",      helloHandler, "Say hello"},
  {"goodbye",      goodbyeHandler, "Say goodbye"},
};

This has added a new command called goodbye, but on its own this won't compile because we also need to create functions - command handlers - that will be called when these commands are sent.

Command handlers

Command handlers are functions that will be called when a particular command is found. These will do whatever you want to do when their command is issued, but the function needs to have the right format. It needs to return a boolean value, and it needs to have a single argument - a reference to a Commander object.

Here is an example of a blank template for a command handler, you can base all your own commands on this template by copying and pasting it, and editing the function name to match the item in your command list, and the contents to do whatever you want.

bool myFunc(Commander &Cmdr){
  //put your command handler code here
  return 0;
}

To make command handlers to work with the command list above, we need to create two handlers, one for hello and one for goodbye. We start by creating two of these functions, and changing their names as follows

bool helloHandler(Commander &Cmdr){
  //put your command handler code here
  return 0;
}

bool goodbyeHandler(Commander &Cmdr){
  //put your command handler code here
	return 0;
}

Now, when Commander identifies the 'hello' command it will be able to call the helloHandler function, or the goodbyeHandler function if it finds the command 'goodbye'.