Arduino

This manual will help you to get started with Arduino and the arduino-mqtt library.

Get Started

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

Afterwards, install the library using the built-in library manager by searching for MQTT.

Alternatively, download the arduino-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 manually can be found here.

To verify that everything worked as expected, go to Files > Examples and open the MQTT > MQTTClient example. This example program will connect to the try namespace and send a hello world message every second. Run the example and check the serial monitor for the following line: connected!. 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 program line by line.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#include <Bridge.h>
#include <YunClient.h>
#include <MQTTClient.h>

YunClient net;
MQTTClient client;

unsigned long lastMillis = 0;

void setup() {
  Bridge.begin();
  Serial.begin(9600);
  client.begin("broker.shiftr.io", net);

  connect();
}

void connect() {
  Serial.print("connecting...");
  while (!client.connect("arduino", "try", "try")) {
    Serial.print(".");
  }

  Serial.println("\nconnected!");

  client.subscribe("/example");
  // client.unsubscribe("/example");
}

void loop() {
  client.loop();

  if(!client.connected()) {
    connect();
  }

  // publish a message roughly every second.
  if(millis() - lastMillis > 1000) {
    lastMillis = millis();
    client.publish("/hello", "world");
  }
}

void messageReceived(String topic, String payload, char * bytes, unsigned int length) {
  Serial.print("incoming: ");
  Serial.print(topic);
  Serial.print(" - ");
  Serial.print(payload);
  Serial.println();
}

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

To use the library you first need to include it:

1
#include <MQTTClient.h>
  • The first line imports the network client library which is different if you are using an Arduino UNO with for example a WiFi shield. Look at the Arduino reference to learn how to connect with your board type and shield.

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

1
MQTTClient client;
  • Depending on the chosen network client you may need to allocate other objects as well.

Right after the initialization of the other subsystems you can initialize the client:

1
client.begin("broker.shiftr.io", net);
  • Depending on the chosen network client you may need to provide additional information in the second argument.

Finally, you can connect to shiftr.io:

1
client.connect("arduino", "try", "try");
  • The first argument is the clientId, which will be displayed as the connections name in the real-time graph.
  • The second and third argument are the username and password which holds your token credentials.
  • The return value reflects whether the client has successfully connected.

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.

To send messages out and check for incoming messages you need to run the loop function in every loop of your program:

1
client.loop();

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

1
2
3
4
5
6
7
void messageReceived(String topic, String payload, char * bytes, unsigned int length) {
  Serial.print("incoming: ");
  Serial.print(topic);
  Serial.print(" - ");
  Serial.print(payload);
  Serial.println();
}
  • The first parameter is the topic of the message.
  • The second parameter is the payload in the form of a string.
  • The third parameter is the pointer to the raw byte array.
  • The fourth parameter is the length of the received payload.

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

Notes

Couple of notes on the usage of the library:

  • You shouldn’t use multiple clients in one Arduino program.
  • The basic client will not automatically reconnect.
  • On the Arduino Yun you can use the YunClient which uses a python script on the linux side to manage the connection.