arduino-mqtt ("PahoMQTT") Arduino Library

MQTT library for Arduino, based on the Eclipse Paho projects

This library bundles the Embedded MQTT C/C++ Client library of the Eclipse Paho project and adds a thin wrapper to get an Arduino-like API. Additionally, there is an drop-in alternative for the Arduino Yùn that uses a python-based client on the Linux processor and a binary interface to lower program space usage on the Arduino side.

The first release of the library only supports QoS0 and the basic features to get going. In the next releases more of the features will be available. Please create an issue if you need a specific functionality.

INSTALLATION

Download version 1.10.2 of the library from GitHub as a ZIP file, and install the library manually via the Sketch --> Include Library --> Add .ZIP Library... menu entry in the Arduino IDE.

Please note that my modification of this library is currently not available in the Arduino Library Manager.

MODIFICATIONS

LIBRARY NAMING CONFLICT RESOLUTION

Note that the primary modification made is to resolve the library naming conflict.

All of the files in the library following the naming format MQTT_(...)_ been renamed to PahoMQTT_(...)_ to resolve naming conflicts with other Arduino libraries.

OTHER MODIFICATIONS

Additionally, some experimentation with QoS settings and buffer sizes has been occurring in the pahomqtt-tweaked branch.

COMPATIBILITY

This library is known to work with the following hardware:

• Arduino (AVR-based boards)
  • Arduino Ethernet Shield
  • Arduino WiFi Shield
  • Arduino WiFi101 Shield
  • Arduino Yùn Shield (as a process on the Linux core)
• Arduino Yùn (as a process on the Linux core)
• ESP8266 modules & boards

EXAMPLES

The following examples show how you can use the library with various Arduino compatible hardware:

• Arduino Yùn & Yùn-Shield (PahoMQTTClient)
• Arduino Yùn & Yùn-Shield (YunPahoMQTTClient)
  • With SSL support...
• Arduino Ethernet Shield
• Arduino WiFi Shield
• Adafruit HUZZAH ESP8266
  • With SSL support...
• Arduino/Genuino WiFi101 Shield
  • With SSL support...

Other shields and boards should work if they also provide a Client-based network implementation.

CAVEATS

• The maximum size for packets being published and received is set by default to 384 bytes. To change that value, you need to download the library manually and change the value in the following file: src/PahoMQTTClient.h.
• On the ESP8266, it has been reported that an additional delay(10); after client.loop(); fixes many stability issues with WiFi connections.

EXAMPLE IMPLEMENTATION

The following example uses an Arduino Yùn and the MQTTClient to connect to [shiftr.io][8]. You can check on your device after a successful connection here: https://shiftr.io/try.

#include <Bridge.h>
#include <YunClient.h>
#include <MQTTClient.h>

YunClient net;
MQTTClient client;

unsigned long lastMillis = 0;

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

	connect();
}

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

	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();
}

API

Initialize the object using the hostname of the broker, the brokers port (default: 1883) and the underlying Client class for network transport:

boolean begin(const char * hostname, Client& client);
boolean begin(const char * hostname, int port, Client& client);

• Specify port 8883 when using SSL clients for secure connections.
• The YunMQTTClient does not need the client parameter.

Set the will message that gets registered on a connect:

void setWill(const char * topic);
void setWill(const char * topic, const char * payload);

Connect to broker using the supplied client id and an optional username and password:

boolean connect(const char * clientId);
boolean connect(const char * clientId, const char * username, const char * password);

• This functions returns a value that indicates if the connection has been established successfully.

Publishes a message to the broker with an optional payload:

boolean publish(String topic);
boolean publish(String topic, String payload);
boolean publish(const char * topic, String payload);
boolean publish(const char * topic, const char * payload);
boolean publish(const char * topic, char * payload, unsigned int length);
boolean publish(MQTTMessage * message)

• The last function can be used to publish messages with more low level attributes like retained.

Subscribe to a topic:

boolean subscribe(String topic);
boolean subscribe(const char * topic);

Unsubscribe from a topic:

boolean unsubscribe(String topic);
boolean unsubscribe(const char * topic);

Sends and receives packets:

void loop();

• This function should be called in every loop.

Check if the client is currently connected:

boolean connected();

Disconnects from the broker:

boolean disconnect();

[8]: <htt[s://shiftr.io>]