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 here.

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 File > Examples and open an example from the MQTT category. All examples will connect to the public instance 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 line by line:

#include <WiFi.h>
#include <MQTT.h>

const char ssid[] = "ssid";
const char pass[] = "pass";

WiFiClient net;
MQTTClient client;

unsigned long lastMillis = 0;

void connect() {
  Serial.print("checking wifi...");
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print(".");
    delay(1000);
  }

  Serial.print("\nconnecting...");
  while (!client.connect("arduino", "public", "public")) {
    Serial.print(".");
    delay(1000);
  }

  Serial.println("\nconnected!");

  client.subscribe("hello");
}

void messageReceived(String &topic, String &payload) {
  Serial.println(topic + ": " + payload);
}

void setup() {
  Serial.begin(115200);

  // start wifi and mqtt
  WiFi.begin(ssid, pass);
  client.begin("public.cloud.shiftr.io", net);
  client.onMessage(messageReceived);

  connect();
}

void loop() {
  client.loop();
  delay(10);

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

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

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:

#include <WiFi.h>
#include <MQTTClient.h>

• The first line imports the network client library which is different from board to board. Consult the Arduino reference to learn how to connect with your board.

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

WiFiClient net;
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:

client.begin("public.cloud.shiftr.io", net);

• The first argument is your instance domain.
• Depending on the chosen network client you may need to provide additional information in the second argument.

Finally, you can connect to your shiftr.io instance:

client.connect("arduino", "public", "public");

• The first argument is the client ID, which will be displayed as the connections name in the real-time graph.
• The second argument is the name of your instance.
• The third argument is the token secret as configured in the settings panel.
• The return value reflects whether the client has successfully connected.

Make subscriptions to receive messages from other clients:

client.subscribe("hello");

• The first argument is the name of the topic to subscribe.

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

client.unsubscribe("hello");

• The first argument is the name of the topic to unsubscribe.

Most importantly, publish messages to shiftr.io:

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:

client.loop();

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

void messageReceived(String &topic, String &payload) {
  Serial.println(topic + ": " + payload);
}

• The first parameter is the topic of the message.
• The second parameter is the payload in the form of a string.

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