Arduino PubSubClient | Arduino Client for MQTT

Description

The PubSubClient for the Arduino open-source electronics platform has been available since 2009. At the time, Arduino had recently released its first Ethernet Shield and it seemed a natural fit to run use MQTT.

With such a constrained environment, it was important to keep the library as small as possible. This could be achieved by only implementing the features of the protocol that made sense. In particular, it only supports Clean Sessions and does not support QoS 2 messages as there is such limited memory and no standard persistence mechanism.

The Arduino platform defines a standard api for network client libraries to implement. By allowing sketches to pass in any implementation of the API, the PubSubClient is able to support a wide range of Arduino-compatible hardware out of the box.

It has been used in a number of production systems and has recently been updated to support MQTT 3.1.1.

There are other constants defined it that file to control the version of MQTT used and the keepalive time, as well as constants that reflect the different connection states the client can be in.

Information

Arduino PubSubClient
Language C++ / Arduino
License MIT
Website http://pubsubclient.knolleary.net
API Style Blocking

Features

Feature
MQTT 3.1 Yes
MQTT 3.1.1 Yes
LWT Yes
SSL/TLS Yes
Automatic Reconnect No
QoS 0 Yes
QoS 1 Yes
QoS 2 No
Authentication Yes
Throttling No

Usage

Installation

The library can be installed into the Arduino IDE using the built-in Library Manager.

Open the Library Manager by selecting Sketch -> Include Library -> Manage Libraries… Search for “PubSubClient” Click the “Install” button

The latest release can also be downloaded directly from GitHub

Maximum Message Size As part of minimising its footprint, it limits the size of any MQTT packet it can send or receive to 128 bytes. If you want to send or receive messages larger than this, you must change the value of MQTT_MAX_PACKET_SIZE in PubSubClient.h. The library allocates this much memory in its internal buffer, which reduces the memory available to the sketch itself.

Connect

The following example assumes you are using the standard Ethernet Shield. For other hardware types, refer to its documentation on how to initialise the appropriate network client.

 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
#include <SPI.h>
#include <Ethernet.h>
#include <PubSubClient.h>

// Update these with values suitable for your network.
byte mac[]    = {  0xDE, 0xED, 0xBA, 0xFE, 0xFE, 0xED };
IPAddress ip(172, 16, 0, 100);
const char* server = "broker.example.com";

EthernetClient ethClient;
PubSubClient mqttClient(ethClient);

void setup()
{
  Ethernet.begin(mac, ip);
  // Allow the hardware to sort itself out
  delay(1500);
  mqttClient.setServer(server, 1883);

  if (mqttClient.connect("myClientID")) {
    // connection succeeded
  } else {
    // connection failed
    // mqttClient.state() will provide more information
    // on why it failed.
}

void loop()
{
  mqttClient.loop();
}

The client connects with a default keepalive timer of 15 seconds. This can be configured by changing the value of MQTT_KEEPALIVE in PubSubClient.h.

If the call to mqttClient.connect returns false, the connection has failed for some reason. A call to mqttClient.state() will provide more information. PubSubClient.h defines a number of constants that can be used to determine why the connection failed – for example, whether it was a network issue or the server rejected the connection with a known reason code.

Once connected, the mqttClient.loop() function must be called regularly. This allows the client to maintain the connection and check for any incoming messages.

Connect with MQTT 3.1 or MQTT 3.1.1

In order to minimise the size of the library, the choice of MQTT version must be done at compile time. The version is chosen by changing the value of the MQTT_VERSION in PubSubClient.h – it defaults to MQTT 3.1.1:

// MQTT_VERSION : Pick the version
//#define MQTT_VERSION MQTT_VERSION_3_1
#define MQTT_VERSION MQTT_VERSION_3_1_1

Connect with LWT

1
2
3
4
5
6
byte willQoS = 0;
const char* willTopic = "willTopic";
const char* willMessage = "My Will Message";
boolean willRetain = false;

boolean rc = mqttClient.connect("myClientID", willTopic, willQoS, willRetain, willMessage); 

 

Connect with Username / Password

1
boolean rc = mqttClient.connect("myClientID", "myUsername", "myPassword");

Publish

The client only supports publishing at QoS 0:

1
boolean rc = mqttClient.publish("myTopic", "myMessage");

The function will return true if the message was successfully published to the server. It will return false if:

  • the client was not currently connected to the server, or
  • the resulting MQTT packet to exceeded the libraries maximum packet size

Publish a retained Message

1
2
3
4
char* message = "Hello World";
int length = strlen(message);
boolean retained = true;
mqttClient.publish("myTopic",(byte*)message,length,retained);

Subscribe

In order to subscribe to messages, a callback function must be set on the client. This is done using the setCallback function:

1
2
3
4
5
6
void callback(char* topic, byte* payload, unsigned int length)
{
    // handle received message
}

mqttClient.setCallback(callback);

Then, once the client is connected, it can subscribe to a topic:

1
2
3
4
5
// Defaults to QoS 0 subscription:
boolean rc = mqttClient.subscribe("myTopic");

// Specify the QoS to subscribe at. Only supports QoS 0 or 1:
boolean rc = mqttClient.subscribe("myOtherTopic",1);

The call to subscribe will return true if the subscribe packet was successfully sent to the server – it does not block until the acknowledgment is received from the server.

It will return false if:

  • the client was not currently connected to the server,
  • an invalid qos was specified, or
  • the topic was too long and caused the MQTT packet to exceed the libraries maximum packet size

If you want to publish a message from within the message callback function, it is necessary to make a copy of the topic and payload values as the client uses the same internal buffer for inbound and outbound messages:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
void callback(char* topic, byte* payload, unsigned int length) {
  // Allocate the correct amount of memory for the payload copy
  byte* p = (byte*)malloc(length);
  // Copy the payload to the new buffer
  memcpy(p,payload,length);
  // Republish the received message
  mqttClient.publish("outTopic", p, length);
  // Free the memory
  free(p);
}

Unsubscribe

1
boolean rc = mqttClient.unsubscribe("myTopic");

As with the call to subscribe, this function will return true if the unsubscribe packet was successfully sent to the server – it does not block until the acknowledgment is received from the server.

It will return false if:

  • the client was not currently connected to the server, or
  • the topic was too long and caused the MQTT packet to exceed the libraries maximum packet size

Disconnect

1
mqttClient.disconnect();

This will disconnect from the broker and close the network connection. The client can be reconnected with a subsequent call to mqttClient.connect()

Full example application

The library provides a number of examples when added to the Arduino IDE. They can be accessed by selecting “File” -> “Examples” -> “PubSubClient”

Full API documentation is available here: https://pubsubclient.knolleary.net

The following is a basic example that connects to a broker, publishes a message and then subscribes to a given topic. Whenever a message is received it is printed to the Serial console.

 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
51
52
53
54
55
56
57
58
59
60
61
62
#include <SPI.h>
#include <Ethernet.h>
#include <PubSubClient.h>

// Update these with values suitable for your network.
byte mac[]    = {  0xDE, 0xED, 0xBA, 0xFE, 0xFE, 0xED };
IPAddress ip(172, 16, 0, 100);
IPAddress server(172, 16, 0, 2);

void callback(char* topic, byte* payload, unsigned int length) {
  Serial.print("Message arrived [");
  Serial.print(topic);
  Serial.print("] ");
  for (int i=0;i<length;i++) {
    Serial.print((char)payload[i]);
  }
  Serial.println();
}

EthernetClient ethClient;
PubSubClient mqttClient(ethClient);

void reconnect() {
  // Loop until we're reconnected
  while (!mqttClient.connected()) {
    Serial.print("Attempting MQTT connection...");
    // Attempt to connect
    if (mqttClient.connect("arduinoClient")) {
      Serial.println("connected");
      // Once connected, publish an announcement...
      mqttClient.publish("outTopic","hello world");
      // ... and resubscribe
      mqttClient.subscribe("inTopic");
    } else {
      Serial.print("failed, rc=");
      Serial.print(mqttClient.state());
      Serial.println(" try again in 5 seconds");
      // Wait 5 seconds before retrying
      delay(5000);
    }
  }
}

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

  mqttClient.setServer(server, 1883);
  mqttClient.setCallback(callback);

  Ethernet.begin(mac, ip);
  // Allow the hardware to sort itself out
  delay(1500);
}

void loop()
{
  if (!mqttClient.connected()) {
    reconnect();
  }
  mqttClient.loop();
}

Limitations

  • It can only publish QoS 0 messages. It can subscribe at QoS 0 or QoS 1.
  • The maximum message size, including header, is 128 bytes by default. This is configurable via MQTT_MAX_PACKET_SIZE in PubSubClient.h.
  • The keepalive interval is set to 15 seconds by default. This is configurable via MQTT_KEEPALIVE in PubSubClient.h.
  • The client uses MQTT 3.1.1 by default. It can be changed to use MQTT 3.1 by changing value of MQTT_VERSION in PubSubClient.h.

Compatible Hardware

The library uses the Arduino Ethernet Client api for interacting with the underlying network hardware. This means it Just Works with a growing number of boards and shields, including:

  • Arduino Ethernet
  • Arduino Ethernet Shield
  • Arduino YUN – use the included YunClient in place of EthernetClient, and be sure to do a Bridge.begin() first
  • Arduino WiFi Shield – if you want to send packets > 90 bytes with this shield, enable the MQTT_MAX_TRANSFER_SIZE define in PubSubClient.h.
  • Sparkfun WiFly Shield – library
  • TI CC3000 WiFi – library
  • Intel Galileo/Edison
  • ESP8266
  • ESP32

The library cannot currently be used with hardware based on the ENC28J60 chip – such as the Nanode or the Nuelectronics Ethernet Shield. For those, there is an alternative library available.

Source – https://github.com/knolleary/pubsubclient


I hope you like this post. Do you have any questions? Leave a comment down below!

Thanks for reading. If you like this post probably you might like my next ones, so please support me by subscribing my blog.

Recommended:

Harshvardhan Mishra

Hi, I'm Harshvardhan Mishra. I am a tech blogger and an IoT Enthusiast. I am eager to learn and explore tech related stuff! also, I wanted to deliver you the same as much as the simpler way with more informative content. I generally appreciate learning by doing, rather than only learning. Thank you for reading my blog! Happy learning! Follow and send tweets me on @harshvardhanrvm

Leave a Reply

%d bloggers like this: