Our command handler is one of the easiest ways to receive and process serial commands in your Arduino sketch. The command handler is an Arduino library, bundled with MegunoLink, to simplify receiving and decoding serial commands. It supports setting the value of variables in your program and calling functions when a command is received.

You can send commands with any serial tool including:

  • Interface Panel Visualizer: setup a GUI with buttons and controls to send commands to your Arduino sketch,
  • Raw Serial Monitor: similar to the Arduino IDE’s serial monitor, MegunoLink’s raw serial monitor also time-stamps each line received,
  • Message Monitor Visualizer: lets you create separate serial ‘channels’ over a single serial connection,
  • The Arduino IDE’s serial monitor.
Blink-Interface

A simple user interface created with MegunoLink’s interface panel. Clicking the buttons sends commands to the Arduino to set and get values on the GUI.

Quick Start Guide to Handling Serial Commands

To use the command handler, you need to:

  1. install the MegunoLink Arduino library
  2. #include "CommandHandler.h"
  3. Create a CommandHandler<> SerialCommandHandler; variable
  4. 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)
  5. Implement the command functions. Each must take a single CommandParameter reference, even if it isn’t used. For example: void Cmd_ListAll(CommandParameter &parameters)
  6. Call SerialCommandHandler.Process() in your main loop function to receive and decode commands

Arduino Serial Processing Example

This example extends the classic Arduino blink program with serial commands to control the blink rate. It uses the command handler library to process serial commands. First we’ll look at the entire sketch and then break it down.

The sketch accepts these commands to change the amount of time the LED spends on and off, and to print the current settings:

  • !OnTime 40\r\n Sets the time the LED remains on to 40 ms
  • !OffTime 100\r\n Sets the time the LED remains off to 100 ms
  • !ListAll\r\n Lists the current setting of all parameters

Follow along

To follow along with the Arduino command handler example:

  1. Download and Install MegunoLink
  2. Install MegunoLink’s Arduino Integration libraries
  3. Download the Blink2.ino Arduino code and open it in your Arduino IDE.
  4. Download the Blink2.mlx project and open it in MegunoLink

You can also find the Arduino code and MegunoLink project for this example in MegunoLink’s Library Examples menu at Library Examples→MegunoLink Pro→InterfacePanel→Blink2. The Blink2.ino file will open in your Arduino IDE; the Blink2.mlx file will open in MegunoLink.

Arduino Command Handler Example Walk-through

Setup

The first line imports definitions for the command handler from the MegunoLink Arduino library. The next line creates a CommandHandler (SerialCommandHandler) we can use in the sketch. Notice there are angle brackets after the CommandHandler type.

The angle brackets are needed because the CommandHandler is a template. You can change the maximum number of commands supported (10) and the size of the serial buffer (30 characters) by putting values between the angle brackets. Check out the command handler reference for more information.

Next, define variables to keep track of which pin the LED is attached to and how long the LED should remain on and off.

The original Arduino sketch to blink an LED uses the delay function. But the delay stops the program from doing anything else, including processing serial commands.

To make sure no serial commands are lost, our new blink program, a variable (LastBlink) keeps track of when we last turned the LED on. This time gets used later on to decide if the LED should still be on, should be turned off, or should be turned back on again. Check out our tips for Arduino programs for more on this trick.

Registering Commands and Variables with the Arduino Command Handler

The commands and variables the SerialCommandHandler will process are setup in the Arduino setup() function. The AddVariable function registers variables, while the AddCommand registers functions that will be called when a command is received. Calling SetDefaultHandler registers a function that will be called if an unknown command is received. This is really useful in debugging!

Each call to AddVariable will register a variable with the command handler. The value of these variables can be set and printed using serial commands. The variable is set using a command like !OnTime 10\r\n and printed using !OffTime ?\r\n. The \r\n are escape codes for carriage return and new-line characters respectively.

If you are entering the command using the monitor visualizer, the carriage return and line feed (\r\n) characters are added automatically (provided the +CR and +LF boxes are checked). If you are building an interface panel to send the commands, you’ll need to include them. Leaving off the carriage return is the most common reason for commands not being processed by the Arduino.

Each call to AddCommand will register a function with the command handler. This function will get called whenever the command is received. So here, the Cmd_ListAll function will get called whenever you send the !ListAll\r\n command from MegunoLink. This function is going to print out the values of all the variables, and is defined below.

Putting F("…") around each variable and command name — the first parameter to the AddVariable and AddCommand functions — stores the name in program memory. This helps save RAM, which is in short supply on most Arduinos. Check out our tips for Arduino programs for more on this trick.

Processing Commands

Adding SerialCommandHandler.Process() handles the serial commands. That one line is all you need in the sketch loop for the command handler library to receive, decode and dispatch serial commands!

Command Functions

Command functions are called by the SerialCommandHandler when the corresponding serial command is received. In this example, the Cmd_ListAll function gets called when the !ListAll\r\n command, registered on line 20, is received.

You must include CommandParameter &parameters as a parameter, even if you don’t use it in the function. For more complex commands, you can use parameters to retrieve parameters that were sent with the command. Check out the command handler documentation for more details.

Handling Unknown Commands

Sending incorrect commands is the most common problem when using the serial command handler. Building an Interface Panel visualizer to send the commands is an easy way to avoid typing mistakes when sending commands. You can also setup a function to handle unknown commands. It can print an error message to let the user know the command was received, but not understood.

More Information

Recent Posts

Leave a Comment

Start typing and press Enter to search