heman4t / Arduino-pubsubclient

A client library for the ESP8266 that provides support for MQTT

A client library for the ESP8266 (using the Arduino environment) that provides support for MQTT.

Modified from Nicholas O'Leary's original for the Arduino + Ethernet shield: http://knolleary.net/arduino-client-for-mqtt/

See here for the ESP8266-Arduino work: https://github.com/esp8266/Arduino

Table of Contents MQTT version New features Setting options on messages Publishing and receiving large messages

MQTT version

Note that for now PubSubClient requires a broker that supports version 3.1.1 of the MQTT standard, not 3.1 or earler.

For Mosquitto, this means version 1.3 or later. Although version 1.3 only officially supports MQTT 3.1, it does accept the "MQTT" protocol name string in the CONNECT message (MQTT 3.1 uses "MQIsdp"). Version 1.4 is recommended however, as it fully supports MQTT 3.1.1.

New features

A whole set of MQTT classes has been added, one for each message type. This moved a good amount of code out of the PubSubClient class, leaving it to handle the high-level flow of the protocol. The MQTT classes handle getting data into and out of the messages.

Setting options on messages

The PubSubClient class operates mostly as it did before. However, the connect(), publish(), subscribe(), and unsubscribe() methods can now take an appropriate MQTT object. This allows extra options to be set e.g QoS on publish, or multiple topics with one (un)subscribe message.

You can use the MQTT classes and their chainable setter methods like this:

 client.connect(MQTT::Connect("clientId")
                .set_clean_session()
                .set_will("status", "down")
                .set_auth("username", "password)
                .set_keepalive(30)
               );

 client.publish(MQTT::Publish("topic", "payload")
                .set_retain()
                .set_qos(1)
                .set_dup()
               );

 client.subscribe(MQTT::Subscribe()
                  .add_topic("topic1")
                  .add_topic("topic2", 1)	// optional qos value
                 );

 client.unsubscribe(MQTT::Unsubscribe()
                    .add_topic("topic")
                   );

For details see the MQTT::Connect, MQTT::Publish, MQTT::Subscribe, and MQTT::Unsubscribe classes in the Doxygen-generated documentation.

See also the mqtt_auth or mqtt_qos example sketches for how this is used.

Publishing and receiving large messages

Messages are normally held completely in memory. This can obviously be a problem on microcontrollers, with a very limited amount of RAM. To get around this limitation, Publish payloads can be sent or received using callbacks, which have access to the bare network Client object.

To publish a large payload:

 bool write_payload(Client& payload_stream) {
   uint8_t buffer[64];
   for (int i = 0; i < 1024; i++) {
     // put something in buffer[]
     uint32_t sent = payload_stream.write(buffer, 64);
     if (sent < 64)
       return false;
   }
   return true;
 }
 ...
   client.publish("topic", write_payload, 64 * 1024);

Or see the mqtt_publish_large example.

To receive a large payload:

 void recv_payload(const MQTT::Publish& pub) {
   if (pub.has_stream()) {
     uint8_t buffer[64];
     int read;
     while (read = pub.payload_stream()->read(buffer, 64)) {
       // Do something with data in buffer
     }
     pub.payload_stream()->stop();
   }
 }
 ...
   client.set_callback(recv_payload);
   client.subscribe("inTopic");

Or see the mqtt_subscriber example.