PubSubClient

PubSubClient is an Arduino library that provides a client for simple publish/subscribe messaging with an MQTT-compatible server.

Note: This library is no longer maintained. The author recommends using an actively maintained alternative for new projects.

PubSubClient uses the Arduino Ethernet Client API. It is compatible with:

• Arduino Ethernet / Ethernet Shield
• Arduino YUN (requires using YunClient instead of EthernetClient and calling Bridge.begin() first)
• Arduino WiFi Shield (Note: To send packets > 90 bytes, you must enable the MQTT_MAX_TRANSFER_SIZE define in PubSubClient.h)
• Sparkfun WiFly Shield
• TI CC3000 WiFi
• Intel Galileo/Edison
• ESP8266
• ESP32

Incompatible Hardware: It cannot be used with hardware based on the ENC28J60 chip (e.g., Nanode or Nuelectronics Ethernet Shield).

Before implementation, be aware of the following constraints:

• QoS Support: Can only publish QoS 0 messages. It can subscribe at QoS 0 or QoS 1.
• Message Size: Default maximum is 256 bytes (configurable).
• Keepalive: Default is 15 seconds (configurable).

By default, the maximum message size (including header) is 256 bytes, and the keepalive interval is 15 seconds. You can change these settings using the following methods:

• Message Size: Call PubSubClient::setBufferSize(size) to change the buffer size at runtime, or define MQTT_MAX_PACKET_SIZE in PubSubClient.h.
• Keepalive: Call PubSubClient::setKeepAlive(keepAlive) to change the interval at runtime, or define MQTT_KEEPALIVE in PubSubClient.h.

Manage topic subscriptions using the following methods:

• subscribe(const char* topic): Subscribes to a topic with default QoS.
• subscribe(const char* topic, uint8_t qos): Subscribes to a topic with a specific Quality of Service.
• unsubscribe(const char* topic): Stops receiving messages from the specified topic.

Monitor the client's connection status using:

• connected(): Returns true if the client is currently connected.
• state(): Returns an integer representing the current connection state. See the connection status codes for details.

Use the following methods to configure the MQTT client's connection parameters:

• setServer(IPAddress ip, uint16_t port) or setServer(const char * domain, uint16_t port): Sets the MQTT broker address and port.
• setCallback(MQTT_CALLBACK_SIGNATURE): Sets the callback function used to handle incoming messages.
• setKeepAlive(uint16_t keepAlive): Sets the keep-alive interval in seconds.
• setSocketTimeout(uint16_t timeout): Sets the socket timeout interval in seconds.
• setBufferSize(uint16_t size): Sets the maximum packet size. Returns true if successful.
• setClient(Client& client): Sets the underlying network client.
• setStream(Stream& stream): Sets the stream to use.

Use publish() for standard messages or the beginPublish()/endPublish() pattern for large payloads that exceed the buffer size.

Standard Publish:

• publish(const char* topic, const char* payload)
• publish(const char* topic, const char* payload, boolean retained)
• publish(const char* topic, const uint8_t * payload, unsigned int plength)
• publish(const char* topic, const uint8_t * payload, unsigned int plength, boolean retained)
• publish_P(...): Use for PROGMEM strings.

Large Payload Publish (Streaming):

1. Call beginPublish(const char* topic, unsigned int plength, boolean retained).
2. Call write(uint8_t) or write(const uint8_t *buffer, size_t size) multiple times to stream the payload.
3. Call endPublish() to finalize the transmission.

The connect() method establishes a connection to the configured broker. You can provide a client ID, credentials, or a 'will' message (last will and testament).

Available signatures:

• connect(const char* id)
• connect(const char* id, const char* user, const char* pass)
• connect(const char* id, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
• connect(const char* id, const char* user, const char* pass, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
• connect(const char* id, const char* user, const char* pass, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage, boolean cleanSession)

Quality of Service (QoS) levels available for subscriptions and publishing:

• MQTTQOS0: (0 << 1)
• MQTTQOS1: (1 << 1)
• MQTTQOS2: (2 << 1)