Arduino Client for MQTT

These docs refer to the latest version of the library on GitHub

PubSubClient (server, port, callback, client)

Creates a client instance, with the server specified by IP address.

Parameters
  • server : the IP address of the server (array of 4 bytes)
  • port : the port to connect to (int)
  • callback : a pointer to a function called when a message arrives for a subscription created by this client. If no callback is required, set this to 0
  • client : an instance of Client, typically EthernetClient.

The callback function has the following signature:

 void callback(char* topic, byte* payload, unsigned int length)

PubSubClient (serverDNS, port, callback, client)

Creates a client instance, with the server specified by DNS name.

Parameters
  • serverDNS : the DNS name of the server (char*)
  • port : the port to connect to (int)
  • callback : a pointer to a function called when a message arrives for a subscription created by this client. If no callback is required, set this to 0
  • client : an instance of Client, typically EthernetClient.

The callback function has the following signature:

 void callback(char* topic, byte* payload, unsigned int length)

boolean connect (clientID)

Connects the client.

Parameters
  • clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.
Returns
  • false – connection failed.
  • true – connection succeeded.

boolean connect (clientID, willTopic, willQoS, willRetain, willMessage)

Connects the client with a Will message specified.

Parameters
  • clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.
  • willTopic : the topic to be used by the will message (char*)
  • willQoS : the quality of service to be used by the will message (int : 0,1 or 2)
  • willRetain : whether the will should be published with the retain flag (int : 0 or 1)
  • willMessage : the payload of the will message (char*)
Returns
  • false – connection failed.
  • true – connection succeeded.

boolean connect (clientID, username, password)

Connects the client with a username and password specified.

Parameters
  • clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.
  • username : the username to use. If NULL, no username or password is used (char*)
  • password : the password to use. If NULL, no password is used (char*)
Returns
  • false – connection failed.
  • true – connection succeeded.

boolean connect (clientID, username, password, willTopic, willQoS, willRetain, willMessage)

Connects the client with a Will message, username and password specified.

Parameters
  • clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.
  • username : the username to use. If NULL, no username or password is used (char*)
  • password : the password to use. If NULL, no password is used (char*)
  • willTopic : the topic to be used by the will message (char*)
  • willQoS : the quality of service to be used by the will message (int : 0,1 or 2)
  • willRetain : whether the will should be published with the retain flag (int : 0 or 1)
  • willMessage : the payload of the will message (char*)
Returns
  • false – connection failed.
  • true – connection succeeded.

void disconnect ()

Disconnects the client.

int publish (topic, payload)

Publishes a string message to the specified topic.

Parameters
  • topic – the topic to publish to (char*)
  • payload – the message to publish (char*)
Returns
  • false – publish failed.
  • true – publish succeeded.

int publish (topic, payload, length)

Publishes a message to the specified topic.

Parameters
  • topic – the topic to publish to (char*)
  • payload – the message to publish (byte array)
  • length – the length of the message (byte)
Returns
  • false – publish failed.
  • true – publish succeeded.

int publish (topic, payload, length, retained)

Publishes a message to the specified topic, with the retained flag as specified.

Parameters
  • topic – the topic to publish to (char*)
  • payload – the message to publish (byte array)
  • length – the length of the message (byte)
  • retained – whether the message should be retained (byte)
    • 0 – not retained
    • 1 – retained
Returns
  • false – publish failed.
  • true – publish succeeded.

int publish_P (topic, payload, length, retained)

Publishes a message stored in PROGMEN to the specified topic, with the retained flag as specified.

Parameters
  • topic – the topic to publish to (char*)
  • payload – the message to publish (PROGMEM byte array)
  • length – the length of the message (byte)
  • retained – whether the message should be retained (byte)
    • 0 – not retained
    • 1 – retained
Returns
  • false – publish failed.
  • true – publish succeeded.

boolean subscribe (topic)

Subscribes to messages published to the specified topic.

Parameters
  • topic – the topic to publish to (char*)
Returns
  • false – sending the subscribe failed.
  • true – sending the subscribe succeeded. The request completes asynchronously.

boolean loop ()

This should be called regularly to allow the client to process incoming messages and maintain its connection to the server.

Returns
  • false – the client is no longer connected
  • true – the client is still connected

int connected ()

Checks whether the client is connected to the server.

Returns
  • false – the client is no longer connected
  • true – the client is still connected

Configuration Options

The following configuration options can be used to configure the library. They are contained in PubSubClient.h.

MQTT_MAX_PACKET_SIZE
Sets the largest packet size, in bytes, the client will handle. Any packet received that exceeds this size will be ignored.

Default: 128 bytes

MQTT_KEEPALIVE
Sets the keepalive interval, in seconds, the client will use. This is used to maintain the connection when no other packets are being
sent or received.

Default: 15 seconds