Arduino Library - Serial Command/Response Callback

This library allows you to interact with Arduino devices from a host computer over serial lines in a simple way. The library was designed for use with wireless serial ports such as the EWRF 3022(http://swechtrading.se/zencart/index.php?main_page=product_info&cPath=52&products_id=614) but can just as easily be used with the standard USB-Serial interface.

Core features

Attach your Arduino sketch functions to commands
The library parses commands and arguments
A matched keyword (command) with the correct number of arguments triggers a callback to the sketch function.
The argument vector is passed to the callback function.
Parse, validate and cast arguments (see examples in lib).
Use in point-to-point mode or one-to-many. The latter is useful for wireless serial port setups where one host computer controls a number of Arduino devices. Each device can be individually addressed or called all at once by group addressing.
Built in help system and configuration commands.
Persistent config storage in EEPROM.
Supports delays for individual devices to cater for group calls and responses in one-to many communication.

Download and give it a try! The library shall be placed in the library folder of your Arduino IDE.

#!C++

#include <CallBack.h>

// Compile and upload to arduino. Run the serial monitor and type command
// :help;

// Values for initiation of cmd/response interface. 
// After initial boot, id, gid and del are stored in eeprom.
// Change values by command. Make sure each device has a unique id.
String descr="Command/response test program v0.1";
String id="a1";
String gid="a";
int    del=0; //delayed response
byte   echo=1; // command back to host


// List of commands defined by keyword, funtion pointer, number of arguments 
// and description used in "help" command.
CallBackDef f[] = {
  {(String)"add",   (FunctionPointer)&add,  (int)2, (String)":num1:num2"}
};

// initiate command handler: function array, number of functions and intial values
CallBack cmd(f, sizeof(f) / sizeof(*f), id, gid, descr, del, echo);

void setup() {
  Serial.begin(9600);
  cmd.ok(); // say hello
}

void loop() {
  // Don't forget this line. Parse command if serial data is available.
  cmd.cmdCheck();

  // Put code here. Use timers instead of delay if possible as not to disrupt
  // command/response interaction with host


}


//   --------- command initiated callback functions below ---------
// callback functions all need to be defined void and with String argv
// argument list. The command parser will validate the number of input
// parameters but any additional validation has to be perfomed by each
// callback function. As the argument list is passed as strings, type
// casting to other types is the responsibility of the function.


void add(String argv[]) {
  int a = cmd.stoi(argv[0]);
  int b = cmd.stoi(argv[1]);
  cmd.respond(String(a + b));
}

The above code would give the following command interaction using the Arduino IDE Serial Monitor or equivalent.

#!


id=a1:ok;
>:help;
Command/response test program v0.1

Delayed group response: 0ms

Replace <addr> with id=a1 for this device
Replace <addr> with gid=a for this device group
Replace <addr> with empty string for local access

Device Commands: 
<addr>:help;
<addr>:ping;
<addr>:setid:<id>;
<addr>:setgid:<gid>;
<addr>:setdelay:<delay>;
<addr>:settings;

Application Commands: 
<addr>:add:num1:num2;

Use the user defined command "add" to add two values. Use local addressing ":" in point-to point mode.

#!

>:add:22:33;
id=a1:55;

Run the same command but with device specific addressing.

#!

>id=a1:add:33:44;
id=a1:77;

Run the same command but with device-group addressing. If more than one device have group id "a", all will be triggered to execute the same command - a broadcast. Note that each device responds with their unique id. Serial lines (even wireless) are designed for point-to-point communication. If both devices respond simultanously only one response will be seen by the host. Use the built in "setdelay" command to set individual delays for each device, thus creating a time slot for each.

#!

>gid=a:add:33:44;
id=a1:77;
id=a2:77;

Wiki

CmdCallBack / Home

Arduino Library - Serial Command/Response Callback

Core features