PubSubClient

https://pubsubclient.knolleary.net/
Admin
PubSubClient is an Arduino library that provides a client for simple publish and subscribe messaging...
Tokens:7,327
Snippets:83
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### int state()

Source: https://pubsubclient.knolleary.net/api.html

Returns the current state of the client. If a connection attempt fails, this can be used to get more information about the failure.

```APIDOC
## int 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`.

### Method
state

### 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
```

--------------------------------

### int write(byte)

Source: https://pubsubclient.knolleary.net/api.html

Writes a byte as a component of a publish started with a call to `beginPublish`.

```APIDOC
## int write(byte)

### Description
Writes a byte as a component of a publish started with a call to `beginPublish`.

### Method
write

### Parameters
#### Parameters
- **byte** (uint8_t) - Required - A byte to write to the publish payload

### Returns
- int - the number of bytes written
```

--------------------------------

### int write(payload, length)

Source: https://pubsubclient.knolleary.net/api.html

Writes an array of bytes as a component of a publish started with a call to `beginPublish`.

```APIDOC
## int write(payload, length)

### Description
Writes an array of bytes as a component of a publish started with a call to `beginPublish`.

### Method
write

### Parameters
#### Parameters
- **payload** (byte[]) - Required - The bytes to write
- **length** (unsigned int) - Required - The length of the payload to be sent

### Returns
- int - the number of bytes written
```

--------------------------------

### boolean endPublish()

Source: https://pubsubclient.knolleary.net/api.html

Finishing sending a message that was started with a call to `beginPublish`.

```APIDOC
## boolean endPublish()

### Description
Finishing sending a message that was started with a call to `beginPublish`.

### Method
endPublish

### Returns
- false - publish failed, either connection lost or message too large
- true - publish succeeded
```

--------------------------------

### uint16_t getBufferSize()

Source: https://pubsubclient.knolleary.net/api.html

Gets the current size of the internal buffer.

```APIDOC
## uint16_t getBufferSize()

### Description
Gets the current size of the internal buffer. By default, it is set to `256` bytes - as defined by the `MQTT_MAX_MESSAGE_SIZE` constant in `PubSubClient.h`.

### Method
getBufferSize

### Returns
- uint16_t - the size of the internal buffer
```

--------------------------------

### PubSubClient (server, port, [callback], client, [stream])

Source: https://pubsubclient.knolleary.net/api.html

Creates a fully configured client instance.

```APIDOC
## PubSubClient (server, port, [callback], client, [stream])

### Description
Creates a fully configured client instance.

### Method
Constructor

### Parameters
- **server** (IPAddress, uint8_t[] or const char[]) - Required - the address of the server
- **port** (int) - Required - the port to connect to
- **callback** (function*) - Optional - a pointer to a message callback function called when a message arrives for a subscription created by this client
- **client** - Required - the network client to use, for example `WiFiClient`
- **stream** (Stream) - Optional - a stream to write received messages to

```

--------------------------------

### boolean connect (clientID, [username, password], [willTopic, willQoS, willRetain, willMessage], [cleanSession])

Source: https://pubsubclient.knolleary.net/api.html

Connects the client.

```APIDOC
## boolean connect (clientID, [username, password], [willTopic, willQoS, willRetain, willMessage], [cleanSession])

### Description
Connects the client.

### Method
connect

### Parameters
- **clientID** (const char[]) - Required - the client ID to use when connecting to the server
- **username** (const char[]) - Optional - the username to use. If `NULL`, no username or password is used
- **password** (const char[]) - Optional - the password to use. If `NULL`, no password is used
- **willTopic** (const char[]) - Optional - the topic to be used by the will message
- **willQoS** (int: 0,1 or 2) - Optional - the quality of service to be used by the will message
- **willRetain** (boolean) - Optional - whether the will should be published with the retain flag
- **willMessage** (const char[]) - Optional - the payload of the will message
- **cleanSession** (boolean) - Optional - whether to connect clean-session or not

### Returns
- **false** - connection failed
- **true** - connection succeeded

```

--------------------------------

### PubSubClient (client) - partially initialised client

Source: https://pubsubclient.knolleary.net/api.html

Creates a partially initialised client instance. Before it can be used, the server details must be configured with setServer().

```cpp
EthernetClient ethClient;
PubSubClient client(ethClient);

void setup() {
    client.setServer("broker.example.com",1883);
    // client is now ready for use
}

```

--------------------------------

### PubSubClient () - uninitialised client

Source: https://pubsubclient.knolleary.net/api.html

Creates an uninitialised client instance. Before it can be used, it must be configured with the property setters: setClient() and setServer().

```cpp
EthernetClient ethClient;
PubSubClient client;

void setup() {
    client.setClient(ethClient);
    client.setServer("broker.example.com",1883);
    // client is now configured for use
}

```

--------------------------------

### PubSubClient ()

Source: https://pubsubclient.knolleary.net/api.html

Creates an uninitialised client instance. Before it can be used, it must be configured with the property setters.

```APIDOC
## PubSubClient ()

### Description
Creates an uninitialised client instance. Before it can be used, it must be configured with the property setters.

### Method
Constructor

### Parameters
None

### Example
```cpp
EthernetClient ethClient;
PubSubClient client;

void setup() {
    client.setClient(ethClient);
    client.setServer("broker.example.com",1883);
    // client is now configured for use
}
```

```

--------------------------------

### PubSubClient (client)

Source: https://pubsubclient.knolleary.net/api.html

Creates a partially initialised client instance. Before it can be used, the server details must be configured.

```APIDOC
## PubSubClient (client)

### Description
Creates a partially initialised client instance. Before it can be used, the server details must be configured.

### Method
Constructor

### Parameters
- **client** - the network client to use, for example `WiFiClient`

### Example
```cpp
EthernetClient ethClient;
PubSubClient client(ethClient);

void setup() {
    client.setServer("broker.example.com",1883);
    // client is now ready for use
}
```

```

--------------------------------

### boolean beginPublish (topic, length, retained)

Source: https://pubsubclient.knolleary.net/api.html

Begins publishing a message to the specified topic.

```APIDOC
## boolean beginPublish (topic, length, retained)

### Description
Begins publishing a message to the specified topic.

### Method
beginPublish

### Parameters
- **topic** (const char[]) - Required - the topic to publish to
- **length** (unsigned int) - Required - the length of the payload
- **retained** (boolean) - Required - whether the message should be retained

```

--------------------------------

### int state ()

Source: https://pubsubclient.knolleary.net/api.html

Returns the current state of the client.

```APIDOC
## int state ()

### Description
Returns the current state of the client.

### Method
state

### Parameters
None

```

--------------------------------

### PubSubClient* setServer(server, port)

Source: https://pubsubclient.knolleary.net/api.html

Sets the server details.

```APIDOC
## PubSubClient* setServer(server, port)

### Description
Sets the server details.

### Method
setServer

### Parameters
#### Parameters
- **server** (IPAddress, uint8_t[] or const char[]) - Required - The address of the server
- **port** (int) - Required - The port to connect to

### Returns
- PubSubClient* - the client instance, allowing the function to be chained
```

--------------------------------

### boolean beginPublish(topic, length, retained)

Source: https://pubsubclient.knolleary.net/api.html

Begins sending a publish message. The payload of the message is provided by one or more calls to `write` followed by a call to `endPublish`.

```APIDOC
## boolean beginPublish(topic, length, retained)

### Description
Begins sending a publish message. The payload of the message is provided by one or more calls to `write` followed by a call to `endPublish`.

### Method
beginPublish

### Parameters
#### Parameters
- **topic** (const char[]) - Required - The topic to publish to
- **length** (unsigned int) - Required - The length of the payload to be sent
- **retained** (boolean) - Required - 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
```

--------------------------------

### PubSubClient* setServer (server, port)

Source: https://pubsubclient.knolleary.net/api.html

Sets the server address and port.

```APIDOC
## PubSubClient* setServer (server, port)

### Description
Sets the server address and port.

### Method
setServer

### Parameters
- **server** (IPAddress, uint8_t[] or const char[]) - Required - the address of the server
- **port** (int) - Required - the port to connect to

```

--------------------------------

### PubSubClient* setClient(client)

Source: https://pubsubclient.knolleary.net/api.html

Sets the network client instance to use.

```APIDOC
## PubSubClient* setClient(client)

### Description
Sets the network client instance to use.

### Method
setClient

### Parameters
#### Parameters
- **client** - Required - The network client to use, for example `WiFiClient`

### Returns
- PubSubClient* - the client instance, allowing the function to be chained
```

--------------------------------

### PubSubClient* setClient (client)

Source: https://pubsubclient.knolleary.net/api.html

Sets the network client.

```APIDOC
## PubSubClient* setClient (client)

### Description
Sets the network client.

### Method
setClient

### Parameters
- **client** - Required - the network client to use

```

--------------------------------

### boolean subscribe (topic, [qos])

Source: https://pubsubclient.knolleary.net/api.html

Subscribes to a topic.

```APIDOC
## boolean subscribe (topic, [qos])

### Description
Subscribes to a topic.

### Method
subscribe

### Parameters
- **topic** (const char[]) - Required - the topic to subscribe to
- **qos** (int) - Optional - the quality of service for the subscription

```

--------------------------------

### boolean publish_P (topic, payload, [length], [retained])

Source: https://pubsubclient.knolleary.net/api.html

Publishes a message stored in PROGMEM to the specified topic.

```APIDOC
## boolean publish_P (topic, payload, [length], [retained])

### Description
Publishes a message stored in PROGMEM to the specified topic.

### Method
publish_P

### Parameters
- **topic** (const char[]) - Required - the topic to publish to
- **payload** (const char[], byte[]) - Required - the message to publish
- **length** (unsigned int) - Optional - the length of the payload. Required if payload is a byte[]
- **retained** (boolean) - Optional - 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

```

--------------------------------

### boolean subscribe(topic, [qos])

Source: https://pubsubclient.knolleary.net/api.html

Subscribes to messages published to the specified topic.

```APIDOC
## boolean subscribe(topic, [qos])

### Description
Subscribes to messages published to the specified topic.

### Method
subscribe

### Parameters
#### Parameters
- **topic** (const char[]) - Required - The topic to subscribe to
- **qos** (int) - Optional - The qos to subscribe at (0 or 1 only)

### Returns
- false - sending the subscribe failed, either connection lost or message too large
- true - sending the subscribe succeeded
```

--------------------------------

### boolean connected ()

Source: https://pubsubclient.knolleary.net/api.html

Checks if the client is connected.

```APIDOC
## boolean connected ()

### Description
Checks if the client is connected.

### Method
connected

### Parameters
None

```

--------------------------------

### uint16_t getBufferSize ()

Source: https://pubsubclient.knolleary.net/api.html

Returns the current buffer size.

```APIDOC
## uint16_t getBufferSize ()

### Description
Returns the current buffer size.

### Method
getBufferSize

### Parameters
None

```

--------------------------------

### boolean loop()

Source: https://pubsubclient.knolleary.net/api.html

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

```APIDOC
## boolean loop()

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

### Method
loop

### Returns
- false - the client is no longer connected
- true - the client is still connected
```

--------------------------------

### boolean connected()

Source: https://pubsubclient.knolleary.net/api.html

Checks whether the client is connected to the server.

```APIDOC
## boolean connected()

### Description
Checks whether the client is connected to the server.

### Method
connected

### Returns
- false - the client is not connected
- true - the client is connected
```

--------------------------------

### boolean loop ()

Source: https://pubsubclient.knolleary.net/api.html

Processes incoming messages and maintains the connection.

```APIDOC
## boolean loop ()

### Description
Processes incoming messages and maintains the connection.

### Method
loop

### Parameters
None

```

--------------------------------

### boolean setBufferSize (size)

Source: https://pubsubclient.knolleary.net/api.html

Sets the buffer size.

```APIDOC
## boolean setBufferSize (size)

### Description
Sets the buffer size.

### Method
setBufferSize

### Parameters
- **size** (uint16_t) - Required - the new buffer size

```

--------------------------------

### boolean publish (topic, payload, [length], [retained])

Source: https://pubsubclient.knolleary.net/api.html

Publishes a message to the specified topic.

```APIDOC
## boolean publish (topic, payload, [length], [retained])

### Description
Publishes a message to the specified topic.

### Method
publish

### Parameters
- **topic** (const char[]) - Required - the topic to publish to
- **payload** (const char[], byte[]) - Required - the message to publish
- **length** (unsigned int) - Optional - the length of the payload. Required if payload is a byte[]
- **retained** (boolean) - Optional - 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

```

--------------------------------

### Subscription Callback

Source: https://pubsubclient.knolleary.net/api.html

Describes the callback function signature that must be provided when subscribing to topics. The callback is invoked when new messages arrive.

```APIDOC
## Subscription Callback

### Description
If the client is used to subscribe to topics, a callback function must be provided in the constructor. This function is called when new messages arrive at the client.

### Callback Signature
```
void callback(const char[] topic, byte* payload, unsigned int length)
```

### Parameters
- **topic** (const char[]) - Required - the topic the message arrived on
- **payload** (byte[]) - Required - the message payload
- **length** (unsigned int) - Required - the length of the message payload
```

--------------------------------

### void disconnect ()

Source: https://pubsubclient.knolleary.net/api.html

Disconnects the client.

```APIDOC
## void disconnect ()

### Description
Disconnects the client.

### Method
disconnect

### Parameters
None

```

--------------------------------

### PubSubClient* setCallback (callback)

Source: https://pubsubclient.knolleary.net/api.html

Sets the message callback function.

```APIDOC
## PubSubClient* setCallback (callback)

### Description
Sets the message callback function.

### Method
setCallback

### Parameters
- **callback** (function*) - Required - a pointer to a message callback function

```

--------------------------------

### PubSubClient* setCallback(callback)

Source: https://pubsubclient.knolleary.net/api.html

Sets the message callback function.

```APIDOC
## PubSubClient* setCallback(callback)

### Description
Sets the message callback function.

### Method
setCallback

### Parameters
#### Parameters
- **callback** (function*) - Required - A pointer to a message callback function called when a message arrives for a subscription created by this client.

### Returns
- PubSubClient* - the client instance, allowing the function to be chained
```

--------------------------------

### PubSubClient* setSocketTimeout (timeout)

Source: https://pubsubclient.knolleary.net/api.html

Sets the socket timeout.

```APIDOC
## PubSubClient* setSocketTimeout (timeout)

### Description
Sets the socket timeout.

### Method
setSocketTimeout

### Parameters
- **timeout** (unsigned int) - Required - the timeout in milliseconds

```

--------------------------------

### Subscription callback signature

Source: https://pubsubclient.knolleary.net/api.html

Defines the signature for the subscription callback. The client invokes this function when a message arrives on a subscribed topic. The topic, payload, and length parameters are only valid until the callback returns or until a publish or subscribe call is made from within the callback; the application must copy them if needed later.

```cpp
void callback(const char[] topic, byte* payload, unsigned int length)

```

--------------------------------

### int write (payload, length)

Source: https://pubsubclient.knolleary.net/api.html

Writes a payload to the current message.

```APIDOC
## int write (payload, length)

### Description
Writes a payload to the current message.

### Method
write

### Parameters
- **payload** (byte[]) - Required - the payload to write
- **length** (unsigned int) - Required - the length of the payload

```

--------------------------------

### setBufferSize(size)

Source: https://pubsubclient.knolleary.net/api.html

Sets the size of the internal send/receive buffer in bytes. Returns a boolean indicating whether the buffer was successfully resized.

```APIDOC
## setBufferSize(size)

### Description
Sets the size, in bytes, of the internal send/receive buffer. This must be large enough to contain the full MQTT packet. When sending or receiving messages, the packet will contain the full topic string, the payload data and a small number of header bytes.

### Method
setBufferSize

### Parameters
- **size** (uint16_t) - Required - the size, in bytes, for the internal buffer

### Returns
- **false** - the buffer could not be resized
- **true** - the buffer was resized
```

--------------------------------

### PubSubClient* setKeepAlive (keepAlive)

Source: https://pubsubclient.knolleary.net/api.html

Sets the keep-alive interval.

```APIDOC
## PubSubClient* setKeepAlive (keepAlive)

### Description
Sets the keep-alive interval.

### Method
setKeepAlive

### Parameters
- **keepAlive** (uint16_t) - Required - the keep-alive interval in seconds

```

--------------------------------

### setSocketTimeout(timeout)

Source: https://pubsubclient.knolleary.net/api.html

Sets the socket timeout used by the client. Returns a pointer to the client instance for chaining.

```APIDOC
## setSocketTimeout(timeout)

### Description
Sets the socket timeout used by the client. This determines how long the client will wait for incoming data when it expects data to arrive - for example, whilst it is in the middle of reading an MQTT packet.

### Method
setSocketTimeout

### Parameters
- **timeout** (uint16_t) - Required - the socket timeout, in seconds

### Returns
- **PubSubClient*** - the client instance, allowing the function to be chained
```

--------------------------------

### boolean endPublish ()

Source: https://pubsubclient.knolleary.net/api.html

Ends the publishing process.

```APIDOC
## boolean endPublish ()

### Description
Ends the publishing process.

### Method
endPublish

### Parameters
None

```

--------------------------------

### boolean unsubscribe (topic)

Source: https://pubsubclient.knolleary.net/api.html

Unsubscribes from a topic.

```APIDOC
## boolean unsubscribe (topic)

### Description
Unsubscribes from a topic.

### Method
unsubscribe

### Parameters
- **topic** (const char[]) - Required - the topic to unsubscribe from

```

--------------------------------

### boolean unsubscribe(topic)

Source: https://pubsubclient.knolleary.net/api.html

Unsubscribes from the specified topic.

```APIDOC
## boolean unsubscribe(topic)

### Description
Unsubscribes from the specified topic.

### Method
unsubscribe

### Parameters
#### Parameters
- **topic** (const char[]) - Required - The topic to unsubscribe from

### Returns
- false - sending the unsubscribe failed, either connection lost or message too large
- true - sending the unsubscribe succeeded
```

--------------------------------

### int write (byte)

Source: https://pubsubclient.knolleary.net/api.html

Writes a single byte to the current message payload.

```APIDOC
## int write (byte)

### Description
Writes a single byte to the current message payload.

### Method
write

### Parameters
- **byte** (byte) - Required - the byte to write

```

--------------------------------

### PubSubClient* setStream(stream)

Source: https://pubsubclient.knolleary.net/api.html

Sets the stream to write received messages to.

```APIDOC
## PubSubClient* setStream(stream)

### Description
Sets the stream to write received messages to.

### Method
setStream

### Parameters
#### Parameters
- **stream** (Stream) - Required - A stream to write received messages to

### Returns
- PubSubClient* - the client instance, allowing the function to be chained
```

--------------------------------

### PubSubClient* setStream (stream)

Source: https://pubsubclient.knolleary.net/api.html

Sets the stream to write received messages to.

```APIDOC
## PubSubClient* setStream (stream)

### Description
Sets the stream to write received messages to.

### Method
setStream

### Parameters
- **stream** (Stream) - Required - a stream to write received messages to

```

--------------------------------

### setKeepAlive(keepAlive)

Source: https://pubsubclient.knolleary.net/api.html

Sets the keep alive interval used by the client. Returns a pointer to the client instance for chaining.

```APIDOC
## setKeepAlive(keepAlive)

### Description
Sets the keep alive interval used by the client. This value should only be changed when the client is not connected.

### Method
setKeepAlive

### Parameters
- **keepAlive** (uint16_t) - Required - the keep alive interval, in seconds

### Returns
- **PubSubClient*** - the client instance, allowing the function to be chained
```
Tokens:
Raw