PubSubClient Class

PubSubClient Class

Description
Defines a class of MQTT implementation for Ameba.

Syntax
class PubSubClient

Members

Public Constructors 
PubSubClient::PubSubClientConstructs a PubSubClient object
Public Methods 
PubSubClient::setServerSet MQTT server address and port
PubSubClient::setCallbackSet callback function
PubSubClient::setClientSet WiFi client
PubSubClient::setStreamSet data stream
PubSubClient::connectAttempt to connect to server
PubSubClient::disconnectDisconnect from current session
PubSubClient::publishPublish a message to server
PubSubClient::publish_PSame as above
PubSubClient::subscribeSubscribe to a topic
PubSubClient::unsubscribeUnsubscribe to a topic
PubSubClient::loopKeep MQTT session alive and process any queuing tasks
PubSubClient::connectedCheck if client still connected
PubSubClient::stateReturn 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 

Please confirm that QQ communication software is installed