Process Serial Commands with an Arduino

 In Arduino Libraries, Documentation

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.

To use the command handler, you need to:

  1. install the MegunoLink Arduino library
  2. #include "CommandHandler.h"

You can send the commands with any serial tool including MegunoLink. Use an MegunoLink interface panel to build a simple panel to send settings and commands to your Arduino program.


A simple user interface created with MegunoLink Pro’s interface panel for a Blink program.

Arduino Serial Processing Example

Here is an example sketch that uses the command handler library to control a blinking LED. 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

Example Walk-through

The first line imports definition for the command handler form the MegunoLink Arduino library. And the next line creates a command handler (SerialCommandHandler) that will look after receiving serial data and figuring out what to do with it.

You need to put the <> in when making a CommandHandler because it is a template. By default the command processor will handle up to 10 commands and 10 variables. The template takes extra parameters if you need to expand (or reduce) this. See the command handler documentation for more details.

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 delay function used in the original blink sketch stops the program for a short time. Using delay blocks the program getting in the way of processing serial data. So in the 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, or it should be turned off. Check out our tips for Arduino programs for more on this trick.

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 that can be set and printed using a serial command. The variable is set using a command like !OnTime 10\r\n and printed using !OffTime ?\r\n.

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.

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!
This is the function that will be 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.

More Information

Recent Posts

Leave a Comment

Contact Us

Send us an email and we will get back to you shortly.

Not readable? Change text.

Start typing and press Enter to search