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

== 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 [http://mosquitto.org/ 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 [http://imroy.github.io/pubsubclient/namespaceMQTT.html 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 [http://imroy.github.io/pubsubclient/classPubSubClient.html 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 [http://imroy.github.io/pubsubclient/classMQTT_1_1Connect.html MQTT::Connect], [http://imroy.github.io/pubsubclient/classMQTT_1_1Publish.html MQTT::Publish], [http://imroy.github.io/pubsubclient/classMQTT_1_1Subscribe.html MQTT::Subscribe], and [http://imroy.github.io/pubsubclient/classMQTT_1_1Unsubscribe.html MQTT::Unsubscribe] classes in the Doxygen-generated documentation.

See also the [[examples/mqtt_auth/mqtt_auth.ino|mqtt_auth]] or [[examples/mqtt_qos/mqtt_qos.ino|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 [[examples/mqtt_publish_large/mqtt_publish_large.ino|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 [[examples/mqtt_subscriber/mqtt_subscriber.ino|mqtt_subscriber]] example.