User Tools

Site Tools


arduino:messenger_library

Messenger library for Arduino

What is it?

Messenger is a library that facilitates the parsing of ASCII messages received by Arduino from serial communication. Messenger buffers characters until it receives a carriage return (CR, ASCII 13). It then considers the message complete and available. The message is split into many elements as defined by a separator. The default separator is the space character, but can be any character other than NULL, LF or CR.

Commonly, it is useful for sending data/commands from one application on the computer to Arduino. The Arduino then interprets/parses the data in useful chunks or packets. It is up to the user to define their own packet structure and communication protocol.

Version 1.5 is preferred despite the newest CmdMessenger library. Version 1.5 is simpler to use and only requires one library on the Arduino side.

Download and documentation: http://arduino.cc/playground/Code/Messenger

Simple example

Processing sketch that checks for mouseOver on a rectangle. It sends the string “off” or “on” to Arduino over serial. Note that we are sending the CR (ascii 13) after the data, to signals the end of the packet/message. Arduino receives the message, checks it, and acts accordingly.

Processing code
import processing.serial.*;
 
Serial myPort;  // Create object from Serial class
 
void setup() 
{
  size(200, 200);
  println(Serial.list());
  String portName = Serial.list()[0];
  myPort = new Serial(this, portName, 115200);
}
 
void draw() {
  background(255);
  if (mouseOverRect() == true) {  // If mouse is over square,
    fill(204);                    // change color and
    myPort.write("on");              // send on
    myPort.write(13);
  } 
  else {                        // If mouse is not over square,
    fill(255);                      // change color and
    myPort.write("off");              // send off
    myPort.write(13);
  }
  rect(50, 50, 100, 100);         // Draw a square
}
 
boolean mouseOverRect() { // Test if mouse is over square
  return ((mouseX >= 50) && (mouseX <= 150) && (mouseY >= 50) && (mouseY <= 150));
}
Arduino code
// This example demonstrates Messenger's checkString method
// It turns on the LED attached to pin 13 if it receives "on"
// It turns it off if it receives "off"
#include <Messenger.h>
 
// Instantiate Messenger object with the message function and the default separator 
// (the space character)
Messenger message = Messenger(); 
 
// Define messenger function
void messageCompleted() {
  // This loop will echo each element of the message separately
  while ( message.available() ) {
    if ( message.checkString("on") ) {
      digitalWrite(13,HIGH);
    } else if ( message.checkString("off") ) {
      digitalWrite(13,LOW);
    }
  }
}
 
void setup() {
  // Initiate Serial Communication
  Serial.begin(115200); 
  message.attach(messageCompleted);
  pinMode(13,OUTPUT);
}
 
void loop() {
  // The following line is the most effective way of 
  // feeding the serial data to Messenger
  while ( Serial.available() ) message.process( Serial.read() );
 
}

Complex example

The Arduino code listens to commands from serial, and acts accordingly. The message structure dictates the action as follow:

  • r a → read analog pins
  • r d → read digital pins
  • w d [pin] [value] → write digital pin
  • w a [pin] [value] → write analog pin
  • p m [pin] [value] → set pin mode
Processing code
import processing.serial.*;
 
int lf = 10;    // Linefeed in ASCII
String myString = null;
Serial myPort;  // The serial port
float circleY = 100;
 
void setup() 
{
  size(800, 600);
  frameRate(30);
  println(Serial.list());
  String portName = Serial.list()[0];
  myPort = new Serial(this, portName, 115200);
 
  myPort.clear();
  myString = myPort.readStringUntil(lf);
  myString = null;
}
 
void draw() {
 
  background(255);
 
  while (myPort.available () > 0) {
    myString = myPort.readStringUntil(lf);
    if (myString != null) {
      myString = trim(myString);
      println(myString);
      String[] parts = split(myString, ' ');
      circleY = float(parts[1]);
    }
  }
 
  // draw circle based on analog pin 0 sensor value
  fill(100);
  circleY = map(circleY, 0, 1023, height, 0);
  ellipse(100, int(circleY), 20, 20);
 
  myPort.write("r a");              // send request to read analog values
  myPort.write(13);
}
Arduino code
/* 
 ---- basic communication example ----
 Control Arduino board functions with the following messages:
 
 r a -> read analog pins
 r d -> read digital pins
 w d [pin] [value] -> write digital pin
 w a [pin] [value] -> write analog pin
 p m [pin] [value] -> set pin mode
 
 Base: Thomas Ouellet Fredericks 
 Additions: Alexandre Quessy 
 */
#include <Messenger.h>
 
// Instantiate Messenger object with the message function and the default separator (the space character)
Messenger message = Messenger(); 
 
// Define messenger function
void messageCompleted() {
 
  if ( message.checkString("r") ) { // Read pins (analog or digital)
    if ( message.checkString("a") ) {
      Serial.print("a ");
      for (char i=0;i<6;i++) { // Read pins 2 to 13
        Serial.print(analogRead(i),DEC); // Send the pin value
        Serial.print(" "); // Add a space separator
      }
      Serial.println(); // Terminate message
    } 
    else if ( message.checkString("d") ) {
      Serial.print("d ");
      for (char i=2;i<14;i++) { // Read pins 2 to 13
        Serial.print(digitalRead(i),DEC); // Send the pin value
        Serial.print(" "); // Add a space separator
      }
      Serial.println(); // Terminate message
    }
  } 
  else if ( message.checkString("w") ) { // Write pin (analog or digital)
    if ( message.checkString("a") ) {
      int pin = message.readInt();
      int value = message.readInt();
      analogWrite(pin,value); //Sets the PWM of the pin 
    } 
    else if ( message.checkString("d") ) {
      int pin = message.readInt();
      if (message.checkString("HIGH")){
         digitalWrite(pin,HIGH); //Sets the state of the pin 
      }else{
         digitalWrite(pin,LOW); //Sets the state of the pin 
      }
 
    }
  } else if ( message.checkString("p") &&  message.checkString("m") ) { // Pin mode
      int pin = message.readInt();
      if (message.checkString("OUTPUT")){
        pinMode(pin, OUTPUT);
      }else{
        pinMode(pin, INPUT);
      }
  }
}
 
void setup() {
  // Initiate Serial Communication
  Serial.begin(115200); 
  message.attach(messageCompleted);
}
 
void loop() {
  // The following line is the most effective way of 
  // feeding the serial data to Messenger
  while ( Serial.available( ) ) message.process(Serial.read( ) );
}
arduino/messenger_library.txt · Last modified: 2011/08/14 15:54 by 128.189.165.239