Processing

This manual will help you to get started with Processing and the processing-mqtt library.

Get Started

You first need to make sure that you are running the latest 3.x version of Processing. If you have an old version or haven’t Processing installed at all, get it from their website.

Afterwards, download the processing-mqtt library from the GitHub repository. When the download has finished, move the library to your sketch folders libraries directory. More information about installing a library can be found here.

To verify that everything worked as expected, go to Files > Examples and open the MQTT > PublishSubscribe example. This example sketch will connect to the try namespace and send a hello world message on every keypress. Run the example and check the console for the following line: [MQTT] connected to: broker.shiftr.io. If you see the connected client and the messages flowing in the real-time graph, you are ready to go!

In Detail

In the following section, we will look at the following example sketch line by line.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import mqtt.*;

MQTTClient client;

void setup() {
  client = new MQTTClient(this);
  client.connect("mqtt://try:try@broker.shiftr.io", "processing");
  client.subscribe("/example");
  // client.unsubscribe("/example");
}

void draw() {}

void keyPressed() {
  client.publish("/hello", "world");
}

void messageReceived(String topic, byte[] payload) {
  println("new message: " + topic + " - " + new String(payload));
}

A detailed description of the libraries API can also be found in repository on GitHub.

To use the library you first need to import it:

1
import mqtt.*;

To allocate a new client add the following line to the top of your sketch:

1
MQTTClient client;

In your setup function, initialize the client by passing a reference to your current sketch:

1
client = new MQTTClient(this);
  • Among other things, this call will look for the messageReceived callback and internally store a reference.

Finally, you can connect to shiftr.io:

1
client.connect("mqtt://try:try@broker.shiftr.io", "processing");
  • The first argument is the MQTT URI which you can get from your namespace on shiftr.io.
  • The second argument is the clientId, which will be displayed as the connections name in the real-time graph.

Make subscriptions to receive messages from other clients:

1
client.subscribe("/example");
  • The first argument is the name of the topic to subscribe.

Of course, you can always cancel a subscription by unsubscribing it:

1
client.unsubscribe("/example");
  • The first argument is the name of the topic to unsubscribe.

Most importantly, publish messages to shiftr.io:

1
client.publish("/hello", "world");
  • The first argument is the topic to publish the message to.
  • The second argument is the payload of the message.

And last but not least, receive messages from other clients by implementing the callback:

1
2
3
void messageReceived(String topic, byte[] payload) {
  println("new message: " + topic + " - " + new String(payload));
}
  • The first parameter is the topic of the message.
  • The second parameter is the payload in the form of a byte array. As in the example you can transform the byte array to a string using the following: new String(payload).

Congratulations, now you are able to work with shiftr.io in your Processing projects!

Notes

Couple of notes on the usage of the library:

  • It isn’t recommended to use more than one client per sketch, as the callback is shared and you can’t distinguish the client between the messages received.
  • The client will automatically try to reconnect if there was an connection problem or the connection has been dropped. If the client has to reconnect, all active subscriptions will be restored.