Robots + Big Data: Arduino Serial Manager Docs

Arduino Libraries

Components

Sensors

Additional Libraries

Arduino

Serial ManagerAPI DOCUMENTATION

A simple interface for serial communication.

See Example Public Methods Release Notes

Overview

The Arduino Serial object provides a great general purpose interface for sending and receiving serial commands. This library takes care of the details and allows you to quickly define and consume an event-based serial protocol.

This is an alpha release, which means this library is functional but likely to change. Please post feedback, questions, and issues to this GitHub issues page.

Note: this library will look for a \n newline character at the end of each command. You must configure the Arduino Serial Monitor to include a \n newline character (next to baud rate), or call setFlag() to change the default value.

Example Wiring

This library communicates over the Arduino USB port set at 115200 baud:

A USB cord plugged into an Arduino Micro.

Example Setup

Install this library and load the Example Sketch onto an Arduino
Open a serial connection at 115200 baud
Set the Arduino Serial Monitor to include a \n newline (next to baud rate)
Type something into the serial console then hit enter
Example command: pwm,123
Watch for a response printed to the serial console

Example SketchArduinoC++

#include <RBD_SerialManager.h>

RBD::SerialManager serial_manager;

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    if(serial_manager.isCmd("on")) {
      serial_manager.println("IT'S ON!");
    }

    if(serial_manager.isCmd("pwm")) {
      int value = serial_manager.getParam().toInt();
      serial_manager.print("SET PWM ");
      serial_manager.println(value);
    }
  }
}

#include <RBD_SerialManager.h>
#include <RBD_Timer.h>
#include <RBD_Light.h>

RBD::SerialManager usb;
RBD::Light light(13);

void setup() {
  usb.start();
}

void loop() {
  if(usb.onReceive()) {
    // example serial command: on
    if(usb.isCmd("on")) {
      light.on();
    }

    // example serial command: off
    if(usb.isCmd("off")) {
      light.off();
    }

    // example serial command: pwm,123
    if(usb.isCmd("pwm")) {
      int pwm = usb.getParam().toInt();
      light.setBrightness(pwm);
    }
  }
}

#include <RBD_SerialManager.h>
#include <RBD_Servo.h>

RBD::SerialManager usb;
RBD::Servo servo(2, 700, 2300); // digital pin 2, 700ms - 2300ms pulse

void setup() {
  usb.start();
}

void loop() {
  servo.update();

  if(usb.onReceive()) {
    // example serial command: up
    if(usb.isCmd("up")) {
      servo.moveToDegrees(180);
    }

    // example serial command: down
    else if(usb.isCmd("down")) {
      servo.moveToDegrees(0);
    }

    // example serial command: move,90
    else if(usb.isCmd("move")) {
      int _position = usb.getParam().toInt();
      servo.moveToDegrees(_position);
    }
  }
}

Public Methods

RBD::SerialManager

constructor()
.start()
.setFlag(value)
.setDelimiter(value)
.onReceive()Event
.getValue()Real-Time
.getCmd()Real-Time
.getParam()Real-Time
.isCmd(value)Real-Time
.isParam(value)Real-Time
.print(value)
.println(value)

RBD::SerialManager constructor()

Create a new Serial Manager instance.

EXAMPLE SKETCH

RBD::SerialManager serial_manager;

void setup() {
  ...
}

serial_manager

.start()

Begin serial communication over the Arduino USB cable at 115200 baud. This method must be called in setup() in order to use this library.

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

serial_manager

.setFlag(value)

Provide a char to change the identifier that denotes the end of each serial command. This library defaults to having a terminating flag of \n newline character. You must configure the Arduino Serial Monitor to include a newline (next to baud rate) for this library to work by default.

EXAMPLE SKETCH

void setup() {
  serial_manager.setFlag(";"); // default flag \n newline
}

serial_manager

.setDelimiter(value)

Provide a char to change the identifier between parameters in serial commands. This library defaults to having a delimiter of , comma.

EXAMPLE SKETCH

void setup() {
  // example serial command: pwm,123
  serial_manager.setDelimiter(","); // default delimiter
}

serial_manager

.onReceive() Update

Event

Returns true when a setFlag() has been identified in the serial communication input stream and the parsed data is available from getValue().

In order for this library to behave correctly; you must wrap all real-time methods in a conditional with this method (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // example serial command: hello world
    serial_manager.getValue(); // returns: hello world
  }
}

serial_manager

.getValue()Real-Time

Returns a String of data parsed in chunks between setFlag() from the serial communication input stream. This method must be used with onReceive() for this library to behave correctly (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // example serial command: hello world
    serial_manager.getValue(); // returns: hello world
  }
}

serial_manager

.getCmd()Real-Time

Returns a String of data that is the first (or only) parameter parsed from getValue(). This enables a serial command structure that follows a cmd,param template. This method must be used with onReceive() for this library to behave correctly (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // example serial command: pwm,123
    serial_manager.getCmd(); // returns: pwm
  }
}

serial_manager

.getParam()Real-Time

Returns a String of data that is the second parameter parsed from getValue(). This enables a serial command structure that follows a cmd,param template. This method must be used with onReceive() for this library to behave correctly (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // example serial command: pwm,123
    serial_manager.getParam().toInt(); // returns: 123
  }
}

serial_manager

.isCmd(value)Real-Time

Provide a String to see if it matches the current getCmd(). This method must be used with onReceive() for this library to behave correctly (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {

    // example serial command: on
    if(serial_manager.isCmd("on")) {
      // something.on();
    }

    // example serial command: off
    if(serial_manager.isCmd("off")) {
      // something.off();
    }
  }
}

serial_manager

.isParam(value)Real-Time

Provide a String to see if it matches the current getParam(). This method must be used with onReceive() for this library to behave correctly (as shown below).

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // example serial command: servo,up
    if(serial_manager.isCmd("servo")) {
      if(serial_manager.isParam("up")) {
        // servo.moveToDegrees(180);
      }
    }
  }
}

serial_manager

.print(value)

Provide any value to print to serial output. This is identical to the documented Arduino Serial.print() function.

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // echo command to serial
    serial_manager.print(serial_manager.getValue());
  }
}

serial_manager

.println(value)

Provide any value to print to serial output, then a carriage return and newline character will be appended. This is identical to the documented Arduino Serial.println() function.

EXAMPLE SKETCH

void setup() {
  serial_manager.start();
}

void loop() {
  if(serial_manager.onReceive()) {
    // echo command to serial with new line
    serial_manager.println(serial_manager.getValue());
  }
}

Arduino Libraries