Video!

Watch video on YouTube

Arduino

Before we jump into the boilerplate Promulgate code, be sure to install the Promulgate and Streaming library first. Here are instructions on how to do this.

These next few steps will guide you through adding Promulgate to your code. Now let's create a new sketch!

Specify Includes

Add this block of code to the top of this sketch. This is what tells Arduino to import the libraries.

#include <Streaming.h>
#include "Promulgate.h"
#include <SoftwareSerial.h>

Set up Promulgate with Hardware Serial

Add this block of code below the previous block. This sets up a new promulgate object. The hardware serial will be used for reading messages and sending out messages.

Promulgate promulgate = Promulgate(&Serial, &Serial); // Input, Output

OR with SoftwareSerial

You can also use software serial too! Here we are setting up an LCD software serial object, and using it as the output for promulgate.

SoftwareSerial lcd(3, 2);  // RX, TX
Promulgate promulgate = Promulgate(&Serial, &lcd); // Input, Output

Inside void setup()

Add this block of code inside of your void setup() function. It should go below the initialisation of your serial objects.

This sets the stream for seeing debug messages. If you only want to see error messages, you can set the log level to Promulgate::_ERROR.

It also sets the callback functions for when it receives an action, and when it transmits an action.

  promulgate.set_debug_stream(&Serial);
  promulgate.LOG_LEVEL = Promulgate::DEBUG;
  promulgate.set_rx_callback(received_action);
  promulgate.set_tx_callback(transmit_complete);

Sending a message

This line of code can go anywhere where applicable in your sketch. You could put it somewhere inside of void loop() for example.

This is how you can send a message via promulgate!

  promulgate.transmit_action('@', 'A', 3, 1, '!');

void serialEvent()

Add this block of code after the void loop() function. (After it, not inside of it).

This function allows Arduino to check incoming data on your Serial line.

Inside of the function, we read the incoming data as a character, then send it to promulgate to be organized.

void serialEvent() {
  while(Serial.available()) {
    char c = Serial.read();
    promulgate.organize_message(c);
  }  
}

received_action Callback

Add this block of code anywhere outside of any functions in your sketch.

This function is what promulgate calls when it parses a message successfully. You will receive all of the data you need from it!

In this example we are showing all the data being printed out, but you can remove this and add your own code to organise the messages based off of action or command as you wish.

void received_action(char action, char cmd, uint8_t key, uint16_t val, char delim) {
  Serial << "---CALLBACK---" << endl;
  Serial << "action: " << action << endl;
  Serial << "command: " << cmd << endl;
  Serial << "key: " << key << endl;
  Serial << "val: " << val << endl;
  Serial << "delim: " << delim << endl;
}

transmit_complete Callback

Add this block of code anywhere outside of any functions in your sketch.

This function is what promulgate calls when it sends a message.

You could ring a bell if you like, or blink an LED, or just do nothing!

void transmit_complete() {
  // do whatever you want!
}

Done!

That is all there is to add promulgate to your Arduino code. Next up is the same deal, for Processing!

Processing

The Processing boilerplate code is a little different than the Arduino. First, you will need to install the controlP5 library

Next, download the Promulgate_Processing_Boilerplate and open it in Processing.

Notice how there are multiple tabs- the main sketch, Arduino, Promulgate, and controlP5. We will be focussing on the main sketch and the Promulgate tabs.

Let's begin with the main tab! There actually isn't much involved with this, but anyway...

Inside void draw()

Somewhere inside of draw() we need to place a call to readData().

This will tell Promulgate to keep an eye out on the serial line for the data.

  readData();

transmit_action

To tell Processing to send back data to the Arduino, we can use the transmit_action function.

You can place this function call anywhere. It best makes sense if it is triggered via a key press or mouse press.

  transmit_action('@', 'U', 1, 100, '!');

Now let's switch to the Promulgate tab.

received_action

Here is where you can do your parsing of the incomming messages based on their action specifier or command.

Inside of the function we are simply printing out the data, but you can remove this and add your own code.

void received_action(char action, char cmd, int key_msg, int val, char delim) {
  
  if(DEBUG) {
    println("---RECEIVED ACTION!---");
    println("action: " + action);
    println("cmd: " + cmd);
    println("key: " + key_msg);
    println("val: " + val);
    println("delim: " + delim);
  }
  
}

transmit_complete

Whenever you send a message from Processing to the Arduino, this function will be called.

You can put whatever you want in this function, like printing to the console or playing a little sound.

void transmit_complete() {
  if(DEBUG) println("message sent");
}

Done!

The rest is taken care of, thanks to the Arduino and controlP5 tabs. ;) Check it out if you are feeling adventurous!

w00t!

Thanks for reading this webpage and using Promulgate!

If you would like to support us to make more open source hardware, consider buying something from our store. Our OSHW Patronage item is a great way to chip in. :)

Or consider becoming our patron on Patreon. Thank you for the support!