Command Handler Reference

Using the Serial Command Handler

To use the serial command handler in your program you need to:

1. #include "CommandHandler.h" to make the library available to your program
2. Create a CommandHandler<> SerialCommandHandler; variable
3. Add the commands you want to handle
   • To call a function when a command is received use SerialCommandHandler.AddCommand(F("CommandName"), Cmd_FunctionToCall)
   • To update a variable when a command is received use SerialCommandHandler.AddVariable(F("CommandName"), VariableName)
4. Implement the command functions. Each must take a single CommandParameter reference, even if it isn’t used.
5. Call SerialCommandHandler.Process() in your main loop function to receive and decode commands

For a detailed walk through see Getting started processing serial commands

Serial Command Handler Reference

The CommandHandler is implemented as a C++ template:
template <int MAX_COMMANDS = 10, int CP_SERIAL_BUFFER_SIZE = 30, int MAX_VARIABLES=10> class CommandHandler{…}

Command Store Size

The CommandHandler uses a fixed size array to store the command names and functions to call. By default 10 commands can be added to the handler. This can be changed using the first template parameter. You would need to increase this if you want to handle more commands. You could decrease this to save a little bit of memory. Each command slot uses 4 bytes.

See command handler constructor for examples.

Command Buffer Size

The CommandHandler uses a fixed-size buffer to store characters as they are received from the serial port until a complete message is received. By default this buffer is 30 characters long. This can be changed using the second template parameter. You could increase this if you are sending long commands, or commands with lots of parameters. You could decrease this to save memory. The buffer has to be large enough to contain the start of message character (‘!’) and the terminator (‘\r’) and all the characters in between.

See command handler constructor for examples.

Variable Store Size

The CommandHandler uses a fixed-size buffer to store the map from command name to variable. By default 10 variables can be added to the handler. This can be changed using the third template parameter. You’d need to increase this if you want to handle more variables. Decreasing this would save a little bit of memory. Each command slot uses 7 bytes.

See command handler constructor for examples.

Adding Commands

To add a command, call SerialCommandHandler.AddCommand(F("CommandName"), Cmd_CommandFunction);. This would typically be used in the setup function of your program.

CommandName is the text the command handler will look for between the start of a command message and the first space (or end of the command message). Normally a ‘!’ marks the start of the command message and a ‘\r’ marks the end of the command message. So, for example, On is the command in each of these messages: !On\r, !On 23\r. But not in this one: !Onguard 12\r. The command handler will print AddCommand: full if there isn’t enough space to store another command.

Cmd_CommandFunction is the Arduino function in your program that will be called whenever the command message is found. It can have any name you like, but it must take one parameter, a CommandParameter &. So the function should look like this:

The parameter variable lets you get any parameters that came with the command. See working with parameters below.

Adding Variables

To add a variable, call SerialCommandHandler.AddVariable(F("VariableName"), Variable);. This would typically be used in the setup function of your program. The command handler will print AddVariable: full if there isn’t enough space to store the variable.

VariableName is the text the command handler will look for between the start of a command message and the first space (or end of the command message). Normally a ‘!’ marks the start of the command message and a ‘\r’ marks the end of the command message.

Variable is the variable you want the command handler to update when the variable name in the command matches a registered variable. This variable should be in the global scope of your program. For example, a variable declared at the top of your program outside any functions.

So, for example, if you register SerialCommandHandler.AddVariable(F("SetPoint"), SetPoint) the command !SetPoint 20\r would update the SetPoint variable to 20.

Default Handler

When first setting up a new program it can be helpful to know if messages are received that don’t match any known commands. This can point to errors in the commands you are sending, differences in spelling or case (capital vs lower case letters) or too many commands/variables were registered (by default only 10 commands and 10 variables are supported). By default, the command handler will print Unknown command if an unrecognized command is encountered.

Use SerialCommandHandler.SetDefaultHandler(UnknownMessageHandler); to register a default message handler. UnknownMessageHandler is a function in your program that will be called whenever an unrecognized command is encountered. It shouldn’t take any parameters. A typically unknown message handler would be:

Clearing Registered Commands

You can clear all the registered commands using the SerialCommandHandler.ClearCommands(); function.

Error Messages

Error messages reported by the command handler are summarized in the table below.

Working with Parameters

When the handler matches a command it will call the function registered for that command. This function must take a single parameter, a CommandParameter &. So a typical command handler function would look like this:

You need to include the parameter, even it is not used in the command handler function. Otherwise your program won’t build.

The CommandParameter provides access to any parameters that were included in the serial message. Parameters are separated by spaces.

A CommandParameter supports the following methods:

• NextParameter() returns the next parameter (as text) in the serial message
• RemainingParameters() returns the rest of the message as text
• NextParameterAsInteger(Default) interprets the next parameter as an integer (16 bit) value; returns Default if the next parameter isn’t a valid integer
• NextParameterAsLong(Default) interprets the next parameter as an long (32 bit) value; returns Default if the next parameter isn’t a valid integer
• NextParameterAsUnsignedLong(Default) interprets the next parameter as an unsigned long (32 bit) value; returns Default if the next parameter isn’t valid
• NextParameterAsDouble(Default) interprets the next parameter as an double value; returns Default if the next parameter isn’t valid

Example

Sending !SetTurtleCount 5\r from MegunoLink Pro will update the NumberOfTurtles variable in this simple example. Sending !GetTurtleCount\r will print the current value of the NumberOfTurtles variable to the serial port.

These commands can be sent from the Arduino serial monitor or MegunoLink’s serial monitor. Or you can build a custom user interface with buttons that send commands so you don’t have to remember them all.