noelgeorgi / arduino-mqtt

MQTT library for Arduino based on the Eclipse Paho projects

arduino-mqtt

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.

This library is an alternative to the pubsubclient library by knolleary which uses a custom protocol implementation.

Download version 1.9.3 of the library.

Or even better use the newly available Library Manager in the Arduino IDE.

Compatibility

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

• Arduino Yun (MQTTClient)
• Arduino Yun (YunMQTTClient)
• Arduino Ethernet Shield
• Arduino WiFi Shield
• Adafruit HUZZAH ESP8266

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 128 bytes. To change that value, you need to download the library manually and change the value in the following file: https://github.com/256dpi/arduino-mqtt/blob/master/src/MQTTClient.h#L5.

• On the ESP8266 it has been reported that an additional delay(10); after client.loop(); fixes many stability issues with WiFi connections.

Example

The following example uses an Arduino Yun and the MQTTClient to connect to shiftr.io. 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(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();
}

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

The specialYunMQTTClient 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:

void publish(String topic);
void publish(String topic, String payload);
void publish(const char * topic, String payload);
void publish(const char * topic, const char * payload);
void publish(const char * topic, char * payload, unsigned int length)

Subscribe to a topic:

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

Unsubscribe from a topic:

void unsubscribe(String topic);
void 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:

void disconnect();