PubSubClient Class

Description
A class used for implementing MQTT for Ameba.

Syntax
class PubSubClient

Members

PubSubClient::PubSubClient

Description
Constructs a PubSubClient object and, if applicable, sets server address, port, callback function, data stream and WiFi client.

Syntax
PubSubClient(void);
PubSubClient(Client& client);
PubSubClient(IPAddress, uint16_t, Client& client);
PubSubClient(IPAddress, uint16_t, Client& client, Stream&);
PubSubClient(IPAddress, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client);
PubSubClient(IPAddress, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client, Stream&);
PubSubClient(uint8_t *, uint16_t, Client& client);
PubSubClient(uint8_t *, uint16_t, Client& client, Stream&);
PubSubClient(uint8_t *, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client);
PubSubClient(uint8_t *, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client, Stream&);
PubSubClient(const char*, uint16_t, Client& client);
PubSubClient(const char*, uint16_t, Client& client, Stream&);
PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client);
PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE,Client& client, Stream&);

Parameters
client: the network client to be used, for example WiFiClient
IPAddress: MQTT server address
port: the port to connect to for MQTT, usually 1883 for unencrypted connection
MQTT_CALLBACK_SIGNATURE: a pointer to a message callback function called when a message arrives for a subscription created by this client.
Stream: a message stream to store received messages.

Returns
NA

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
PubSubClient::PubSubClient(Client& client) would suffice for normal MQTT connection.
“PubSubClient.h” must be included to use the class function.

PubSubClient::setServer

Description
Define the server to connect to by setting the parameters such as IP address, port number and domain.

Syntax
PubSubClient& setServer(IPAddress ip, uint16_t port);
PubSubClient& setServer(uint8_t * ip, uint16_t port);
PubSubClient& setServer(const char * domain, uint16_t port);

Parameters
ip: the address of the server.
port: the port to connect to for MQTT, usually 1883 for unencrypted connection. Default: 1883.
domain: name of the server.

Returns
This function returns the parameters such as ip address, port number and domain, allowing the function to be chained.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::setCallback

Description
Sets the message callback function.

Syntax
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
This function returns the client instance, allowing the function to be chained.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::setClient

Description
Set the network client to be used .

Syntax
PubSubClient& setClient(Client& client);

Parameters
client: the network client to be used, for example WiFiClient.

Returns
This function returns the client instance, allowing the function to be chained.

Example Code
NA

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::setStream

Description
Set the message stream to store received messages.

Syntax
PubSubClient& setStream(Stream& stream);

Parameters
stream: a message stream to store received messages.

Returns
This function returns the client instance, allowing the function to be chained.

Example Code
NA

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::connect

Description
Connects the client to the server.

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

Parameters
id: the client ID to be used when connecting to the server.
user: username used for authentication. If NULL, no username is used.
pass: password used for authentication. If NULL, no password is used.
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
This function returns true if the connection is successful, else, return false.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
Client ID is required and should always be unique else connection might be rejected by the server. “PubSubClient.h” must be included to use the class function.

PubSubClient::disconnect

Description
Disconnect the client from the server.

Syntax
void disconnect(void);

Parameters
NA

Returns
NA

Example Code
NA

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::publish

Description
Publish a message to a specified topic.

Syntax
boolean publish(const char* topic, const char* payload);
boolean publish(const char* topic, const char* payload, boolean retained);
boolean publish(const char* topic, const uint8_t * payload, unsigned int plength);
boolean 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
The function returns true if it published successfully, else returns false. If publishing fails, it is either due to connection lost or messages too large.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
Default max packet size is 128 bytes. “PubSubClient.h” must be included to use the class function.

PubSubClient::publish_P

Description
Publish a message stored in PROGMEM to the specified topic.

Syntax
boolean publish_P(const char* topic, const char* payload, boolean retained);
boolean publish_P(const char* topic, const uint8_t * payload, unsigned int plength, boolean retained);

Parameters
topic: the topic that the message will be publishing to.
payload: the contents/messages that will be published to the topic.
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
This function returns true if it published successfully, else returns false. If publishing fails, it is either due to connection lost or messages too large.

Example Code
NA

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::subscribe

Description
Subscribe to a specified topic.

Syntax
boolean subscribe(const char* topic);
boolean subscribe(const char* topic, uint8_t qos);

Parameters
topic: the topic to subscribe.
qos: MQTT quality of service. Valid value: 0 or 1. 0 – At most once (no guarantee of delivery) 1- At least once (guaranteed).

Returns
This function returns true if it published successfully, else returns false. If publishing fails, it is either due to connection lost or messages too large.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::unsubscribe

Description
Unsubscribe from the specified topic.

Syntax
boolean unsubscribe (const char* topic);

Parameters
topic: the topic to unsubscribe.

Returns
The function returns true if it published successfully, else returns false. If publishing fails, it is either due to connection lost or messages too large.

Example Code
NA

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::loop

Description
A method that should be called regularly to allow the client to process incoming messages and maintain its connection to the server.

Syntax
boolean loop(void);

Parameters
NA

Returns
This function returns true if the client is still connected to the server else return false.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
A required method that should not be blocked for too long. “PubSubClient.h” must be included to use the class function.

PubSubClient::connected

Description
Check whether the client is still connected to the server.

Syntax
boolean connected(void);

Parameters
NA

Returns
This function returns true if the client is connected to the server else return false.

Example Code
Example: MQTT_Basic
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::state

Description
Get the current state of the client. For example, 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);
int state(void);

Parameters
NA

Returns
This function returns the current state of the client as an integer from -4 to 5 representing different definition.
-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
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/mqtt_basic/mqtt_basic.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::waitForAck

Description
Wait for an ACK sent from a host.

Syntax
void waitForAck(uint8_t enable)

Parameters
enable: whether or not to enable the function feature of “wait for Acknowledgement”. Valid value: true or false.

Returns
NA

Example Code
Example: amazon_awsiot_with_ack
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/amazon_awsiot_with_ack/amazon_awsiot_with_ack.ino)

Notes and Warnings
“PubSubClient.h” must be included to use the class function.

PubSubClient::setPublishQos

Description
Set Quality of Service to publish.

Syntax
uint8_t setPublishQos(uint8_t qos_level)

Parameters
qos_level: Quality of Service. Valid value: 0, 1 or 2.

Returns
This function returns the QoS of publishing.

Example Code
Example: amazon_awsiot_with_ack
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/MQTTClient/examples/amazon_awsiot_with_ack/amazon_awsiot_with_ack.ino)

Notes and Warnings
QoS can only be,
0: at most once
1: at least once
2: exactly once
“PubSubClient.h” must be included to use the class function.