PubSubClient Class

PubSubClient Class

Description
A class used for implementing MQTT for Ameba.

Syntax
class PubSubClient

Members

Public Constructors 
PubSubClient::PubSubClientConstructs a PubSubClient object.
Public Methods 
PubSubClient::setServerDefine the server to connect to.
PubSubClient::setCallbackSet callback function.
PubSubClient::setClientSet the network client to be used.
PubSubClient::setStreamSet the message stream to store received messages.
PubSubClient::setKeepAliveSet the keep alive interval used by the client.
PubSubClient::setSocketTimeoutSet the socket timeout used by the client.
PubSubClient::setBufferSizeSet the size, in bytes, of the internal send/receive buffer.
PubSubClient::getBufferSizeGet the current size of the internal buffer.
PubSubClient::connectConnect the client to the server.
PubSubClient::disconnectDisconnect the client from the server.
PubSubClient::publishPublish a message to a specific topic
PubSubClient::publish_PPublish a message stored in PROGMEM to a specific topic.
PubSubClient::writeWrite to the publish payload.
PubSubClient::subscribeSubscribe to a specified topic.
PubSubClient::unsubscribeUnsubscribe to from a specified topic.
PubSubClient::loopKeep MQTT session alive and process any queuing tasks.
PubSubClient::connectedCheck if client still connected.
PubSubClient::stateGet current state of the client.

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/ambd_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/ambd_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/ambd_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::setKeepAlive

Description
Set the keep alive interval used by the client

Syntax
PubSubClient& setKeepAlive(uint16_t keepAlive);

Parameters
keepAlive: the keep alive interval, in seconds.

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::setSocketTimeout

Description
Set the socket timeout used by the client.

Syntax
PubSubClient& setSocketTimeout(uint16_t timeout);

Parameters
Timeout: the socket timeout, in seconds.

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::setBufferSize

Description
Set the size, in bytes, of the internal send/receive buffer.

Syntax
PubSubClient& setBufferSize(uint16_t size);

Parameters
size: the size, in bytes, for the internal buffer.

Returns
This function returns false when the buffer could not be resized, returns true when the buffer was resized.

Example Code
NA

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

PubSubClient::getBufferSize

Description
Get the current size of the internal buffer.

Syntax
PubSubClient& getBufferSize(void);

Parameters
NA

Returns
This function returns the size of the internal buffer.

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/ambd_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
Publishes 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
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/ambd_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
Publishes 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::write

Description
Write a byte from the buffer into the payload.

Syntax
size_t write(uint8_t data);

Parameters
data: a byte to write to the publish payload.

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 to
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/ambd_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
Unsubscribes from the specified topic.

Syntax
boolean unsubscribe (const char* topic);

Parameters
topic: the topic to unsubscribe to.

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::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/ambd_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
Checks 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/ambd_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/ambd_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.

请先确认已安装QQ通讯软体