PubSubClient Class
PubSubClient Class
Description
Defines a class of MQTT implementation for Ameba.
Syntax
class PubSubClient
Members
Public Constructors | |
PubSubClient::PubSubClient | Constructs a PubSubClient object |
Public Methods | |
PubSubClient::setServer | Set MQTT server address and port |
PubSubClient::setCallback | Set callback function |
PubSubClient::setClient | Set WiFi client |
PubSubClient::setStream | Set data stream |
PubSubClient::connect | Attempt to connect to server |
PubSubClient::disconnect | Disconnect from current session |
PubSubClient::publish | Publish a message to server |
PubSubClient::publish_P | Same as above |
PubSubClient::subscribe | Subscribe to a topic |
PubSubClient::unsubscribe | Unsubscribe to a topic |
PubSubClient::loop | Keep MQTT session alive and process any queuing tasks |
PubSubClient::connected | Check if client still connected |
PubSubClient::state | Return connection state |
PubSubClient::PubSubClient
Description
Constructs a PubSubClient object and, if applicable, sets server address, port, callback function, data stream and wifi client.
Syntax
PubSubClient::PubSubClient();
PubSubClient::PubSubClient(Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t, Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(IPAddress, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
PubSubClient::PubSubClient(uint8_t *, uint16_t, Client& client);
PubSubClient::PubSubClient(uint8_t *, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(uint8_t *, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(uint8_t *, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
PubSubClient::PubSubClient(const char*, uint16_t, Client& client);
PubSubClient::PubSubClient(const char*, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
Parameters
client: the network client to use, for example WiFiClient
IPAddress: MQTT server address
port: port for MQTT, usually 1883 for unencrypted connection
MQTT_CALLBACK_SIGNATURE: callback function for MQTT
Stream: a stream to write received messages to
Returns
The function returns nothing.
Example Code
Example: MQTT_Basic
#include <WiFi.h> #include <PubSubClient.h> // Update these with values suitable for your network. char ssid[] = "yourNetwork"; // your network SSID (name) char pass[] = "secretPassword"; // your network password int status = WL_IDLE_STATUS; // the Wifi radio's status char mqttServer[] = "test.mosquitto.org"; char clientId[] = "amebaClient"; char publishTopic[] = "outTopic"; char publishPayload[] = "hello world"; char subscribeTopic[] = "inTopic"; void callback(char* topic, byte* payload, unsigned int length) { Serial.print("Message arrived ["); Serial.print(topic); Serial.print("] "); for (int i=0;i<length;i++) { Serial.print((char)payload[i]); } Serial.println(); } WiFiClient wifiClient; PubSubClient client(wifiClient); void reconnect() { // Loop until we're reconnected while (!client.connected()) { Serial.print("Attempting MQTT connection..."); // Attempt to connect if (client.connect(clientId)) { Serial.println("connected"); // Once connected, publish an announcement... client.publish(publishTopic, publishPayload); // ... and resubscribe client.subscribe(subscribeTopic); } else { Serial.print("failed, rc="); Serial.print(client.state()); Serial.println(" try again in 5 seconds"); // Wait 5 seconds before retrying delay(5000); } } } void setup() { Serial.begin(38400); while (status != WL_CONNECTED) { Serial.print("Attempting to connect to SSID: "); Serial.println(ssid); // Connect to WPA/WPA2 network. Change this line if using open or WEP network: status = WiFi.begin(ssid, pass); // wait 10 seconds for connection: delay(10000); } client.setServer(mqttServer, 1883); client.setCallback(callback); // Allow the hardware to sort itself out delay(1500); } void loop() { if (!client.connected()) { reconnect(); } client.loop(); }
Notes and Warnings
PubSubClient::PubSubClient(Client& client) would suffice for normal MQTT connection
PubSubClient::setServer
Description
Sets the server details.
Syntax
PubSubClient& PubSubClient::setServer(uint8_t * ip, uint16_t port)
PubSubClient& PubSubClient::setServer(IPAddress ip, uint16_t port)
PubSubClient& PubSubClient::setServer(const char * domain, uint16_t port)
Parameters
ip: the address of the server
port: the port to connect to, default 1883
domain: the address of the server
Returns
The client instance, allowing the function to be chained
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
PubSubClient::setCallback
Description
Sets the message callback function.
Syntax
PubSubClient& PubSubClient::setCallback(MQTT_CALLBACK_SIGNATURE)
Parameters
MQTT_CALLBACK_SIGNATURE: a pointer to a message callback function called when a message arrives for a subscription created by this client.
Returns
The client instance, allowing the function to be chained.
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
PubSubClient::setClient
Description
Sets the network client instance to use.
Syntax
PubSubClient& PubSubClient::setClient(Client& client)
Parameters
client: the network client to use, for example WiFiClient
Returns
The client instance, allowing the function to be chained
Example Code
NA
Notes and Warnings
NA
PubSubClient::setStream
Description
Sets the stream to write received messages to.
Syntax
PubSubClient& PubSubClient::setStream(Stream& stream)
Parameters
stream: a stream to write received messages to
Returns
The client instance, allowing the function to be chained.
Example Code
NA
Notes and Warnings
NA
PubSubClient::connect
Description
Connects the client to the server.
Syntax
boolean PubSubClient::connect(const char *id)
boolean PubSubClient::connect(const char *id, const char *user, const char *pass)
boolean PubSubClient::connect(const char *id, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
boolean PubSubClient::connect(const char *id, const char *user, const char *pass, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
Parameters
id: Client ID, a unique string identifier
user: Username for authentication, default NULL
pass: Password for authentication, default NULL
willTopic: the topic to be used by the will message
willQoS: the quality of service to be used by the will message
willRetain: whether the will should be published with the retain flag
willMessage: the payload of the will message
Returns
True – connection succeeded
False – connection failed
Example Code
Example: MQTT_Basic
Notes and Warnings
Client ID is required and should always be unique else connection might be rejected by the server.
PubSubClient::disconnect
Description
Disconnect the client
Syntax
void PubSubClient::disconnect(void)
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
PubSubClient::publish
Description
Publishes a message to the specified topic.
Syntax
boolean PubSubClient::publish(const char* topic, const char* payload)
boolean PubSubClient::publish(const char* topic, const char* payload, boolean retained)
boolean PubSubClient::publish(const char* topic, const uint8_t* payload, unsigned int plength)
boolean PubSubClient::publish(const char* topic, const uint8_t* payload, unsigned int plength, boolean retained)
Parameters
topic: the topic to publish to
payload: the message to publish
plength: the length of the payload. Required if payload is a byte[]
retained: whether the message should be retained
– false – not retained
– true – retained
Returns
False – publish failed, either connection lost or message too large
True – publish succeeded
Example Code
Example: MQTT_Basic
Notes and Warnings
Default max packet size is 128 bytes.
PubSubClient::publish_P
Description
Publishes a message stored in PROGMEM to the specified topic.
Syntax
boolean PubSubClient::publish_P(const char* topic, const uint8_t* payload, unsigned int plength, boolean retained)
Parameters
topic: the topic to publish to
payload: the message to publish
plength: the length of the payload. Required if payload is a byte[]
retained: whether the message should be retained
– false – not retained
– true – retained
Returns
False – publish failed, either connection lost or message too large
True – publish succeeded
Example Code
NA
Notes and Warnings
NA
PubSubClient::subscribe
Description
Subscribes to messages published to the specified topic.
Syntax
boolean PubSubClient::subscribe(const char* topic)
boolean PubSubClient::subscribe(const char* topic, uint8_t qos)
Parameters
topic: the topic to subscribe to
qos: the qos to subscribe at
Returns
False – sending the subscribe failed, either connection lost or message too large
True – sending the subscribe succeeded
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
PubSubClient::unsubscribe
Description
Unsubscribes from the specified topic.
Syntax
boolean PubSubClient::unsubscribe(const char* topic)
Parameters
topic: the topic to unsubscribe to
Returns
False – sending the unsubscribe failed, either connection lost or message too large
True – sending the unsubscribe succeeded
Example Code
NA
Notes and Warnings
NA
PubSubClient::loop
Description
A must method called regularly to allow the client to process incoming messages and maintain its connection to the server.
Syntax
boolean PubSubClient::loop(void)
Parameters
The function requires no input parameter.
Returns
False – the client is no longer connected
True – the client is still connected
Example Code
Example: MQTT_Basic
Notes and Warnings
A required method that should not be blocked for too long.
PubSubClient::connected
Description
Checks whether the client is connected to the server.
Syntax
boolean PubSubClient::connected(void)
Parameters
The function requires no input parameter.
Returns
False – the client is not connected
True – the client is connected
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
PubSubClient::state
Description
Returns the current state of the client. If a connection attempt fails, this can be used to get more information about the failure.
All of the values have corresponding constants defined in PubSubClient.h.
Syntax
int PubSubClient::state(void)
Parameters
The function requires no input parameter.
Returns
-4 : MQTT_CONNECTION_TIMEOUT – the server didn’t respond within the keepalive time
-3 : MQTT_CONNECTION_LOST – the network connection was broken
-2 : MQTT_CONNECT_FAILED – the network connection failed
-1 : MQTT_DISCONNECTED – the client is disconnected cleanly
0 : MQTT_CONNECTED – the client is connected
1 : MQTT_CONNECT_BAD_PROTOCOL – the server doesn’t support the requested version of MQTT
2 : MQTT_CONNECT_BAD_CLIENT_ID – the server rejected the client identifier
3 : MQTT_CONNECT_UNAVAILABLE – the server was unable to accept the connection
4 : MQTT_CONNECT_BAD_CREDENTIALS – the username/password were rejected
5 : MQTT_CONNECT_UNAUTHORIZED – the client was not authorized to connect
Example Code
Example: MQTT_Basic
Notes and Warnings
NA