A simple command handler for arduino - handling command from serial, string, or char by char
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples/Demo
wstring_fix
CommandHandler.cpp
CommandHandler.h
LICENSE
README.md
keywords.txt

README.md

CommandHandler

A Wiring/Arduino library to tokenize, parse and relay commands received either by the serial port, as a string, or char by char.

The message format is:

CmdString,arg1,[...],argN;

Although the field separator ',' and command separator ';' can be changed.

The library can:

  • Attach callback functions to received command
  • Relay the remaining of a command to attached callback functions (typically another CommandHandler)
  • Parse a command char by char
  • Parse a string command
  • Receive commands through the serial port
  • Read multiple arguments
  • Read all primary data types
  • Forging of string packet with multiple arguments of different primary type

Features and main difference with SerialCommand and CmdMessenger

Unlike CmdMessenger, the command identifier can be any string, which make your code more readable

It differs with SerialCommand by the ability to nest commandHandlers. This has been made possible by a simple change: adding the ability to read from string. While not being at all a technical challenge to implement, it can be really useful to modularize your code.

Imagine your main program receiving "M1,P,2000;" command through Serial. The main program could redirect the "P,2000;" string command to the a sub-device called "M1". The M1 device can then use its own commandHandler to handle the sub command "P,2000;". To extract the remaining of a command, you can use the function remaining(), give that remaining to another commandHandler instance (e.g. the one associated to M1) through the processString() function. The command handler of M1 can then parse it and enjoy all the feature of the commandHandler, i.e. callback and casting of arguments.

Please refer, and read through, the Demo example for practical usage of this library.

All the above steps can be encapsulated by registering relay callback function. When triggered by the associated command, the command handler with call the relay command, passing in argument the remaining of the command.

This behavior is illustrated in the Arduino-CommandTools libraries, a set of modular librairies build on top of this message parsing library.

Getting started

Download or clone this repository, rename the folder as CommandHandler and move it to your Arduino libraries folder. You need to restart the Arduino IDE for the library to be loaded and recognized by Arduino.

Please refer to https://www.arduino.cc/en/Guide/Libraries#toc5 for manual installation of libraries.

Inspiration

This is derived from the SerialCommand library whose original version was written by Steven Cogswell (published May 23, 2011 in his blog post "A Minimal Arduino Library for Processing Serial Commands"). It is based on the SerialCommand heavily modified version with smaller footprint and a cleaned up code by Stefan Rado.

Some features are also extracted from CmdMessenger, such as the function returning next arg already casted in types, e.g. readInt16Arg

Author

Jonathan Grizou while working in the Cronin Group.

License

GPL V3