Skip to content
A client library for the ESP8266 that provides support for MQTT
Branch: master
Clone or download
#89 Compare This branch is 198 commits ahead, 93 commits behind knolleary:master.
Imroy Test the return code of the CONNACK response to a connection attempt
CONNACK doesn't necessarily mean the connection was successful.
Latest commit beb81e3 May 16, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples this commit fixes #64 Mar 19, 2017
src Test the return code of the CONNACK response to a connection attempt Jun 24, 2017
tests Tests: Use std::string in the Buffer class instead of a fixed size bu… May 17, 2017
CHANGES.txt Move everything under PubSubClient into the root so it can server dir… Apr 23, 2015
Doxyfile Convert existing comments to Doxygen documentation, add Doxygen confi… Jun 22, 2015
README.mediawiki Join paragraphs of text into single lines Jul 20, 2015
keywords.txt Update Jan 14, 2017


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:

See here for the ESP8266-Arduino work:

Table of Contents

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:

                .set_will("status", "down")
                .set_auth("username", "password)

 client.publish(MQTT::Publish("topic", "payload")

                  .add_topic("topic2", 1)	// optional qos value


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

Or see the mqtt_subscriber example.

You can’t perform that action at this time.