wn/pubsubclient
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rebuild docs to make them easier to maintain

Browse Source
This commit is contained in:
Nick O'Leary
2020-05-21 01:17:42 +01:00
parent 09a3de6a09
commit a9d9bad1ff
35 changed files with 716 additions and 590 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -1 +1,5 @@
_site/
.jekyll-cache
.DS_Store
.ruby-version
tests/bin

11
_includes/paramsList.html Normal file
View File

@@ -0,0 +1,11 @@
{%
for param in include.params
%}{%
if param.optionalGroup
%}[{% include paramsList.html params=param.params %}]{%
else
%}{%
if param.optional %}[{%endif %}{{param.name}}{% if param.optional %}]{%endif
%}{%endif
%}{% if forloop.last == false %}, {%endif%}{% endfor
%}

12
_includes/paramsListLong.html Normal file
View File

@@ -0,0 +1,12 @@
{%
for param in include.params
%}<li>{%
if param.optionalGroup
%}<span class="methodparams">{{param.name}}</span> - <span class="methodparamoptional">(optional)</span><ul>{% include paramsListLong.html params=param.params %}</ul>{%
else
%}
<span class="methodparams">{{param.name}}</span> {% if param.type %}<span class="methodparamstype">{{param.type}}</span> {% endif %} {% if param.optional %}<span class="methodparamoptional">(optional)</span> {%endif %} -
{{param.description}}
{% endif %}</li>{% endfor
%}

2
_layouts/default.html
View File

@@ -13,7 +13,7 @@
<div id="content">
<div id="header">
<ul>
<li><a href="index.html">Arduino Client for MQTT</a></li><li><a href="api.html">API Documentation</a></li>
<li><a href="/">Arduino Client for MQTT</a></li><li><a href="/api">API Documentation</a></li>
</ul>
</div>
<h1>{{ page.title }}</h1>

21
_posts/2000-01-01-PubSubClient.md Normal file
View File

@@ -0,0 +1,21 @@
---
tag: api
type: constructor
name: PubSubClient
---
Creates an uninitialised client instance.
Before it can be used, it must be configured with the property setters:
```
EthernetClient ethClient;
PubSubClient client;
void setup() {
client.setClient(ethClient);
client.setServer("broker.example.com",1883);
// client is now configured for use
}
```

23
_posts/2000-01-02-PubSubClient1.md Normal file
View File

@@ -0,0 +1,23 @@
---
tag: api
type: constructor
name: PubSubClient
params:
- name: client
description: the network client to use, for example <code>WiFiClient</code>
---
Creates a partially initialised client instance.
Before it can be used, the server details must be configured:
```
EthernetClient ethClient;
PubSubClient client(ethClient);
void setup() {
client.setServer("broker.example.com",1883);
// client is now ready for use
}
```

25
_posts/2000-01-03-PubSubClient2.md Normal file
View File

@@ -0,0 +1,25 @@
---
tag: api
type: constructor
name: PubSubClient
params:
- name: server
description: the address of the server
type: IPAddress, uint8_t[] or const char[]
- name: port
description: the port to connect to
type: int
- name: callback
optional: true
description: a pointer to a <a href="#callback">message callback function</a> called when a message arrives for a subscription created by this client
type: function*
- name: client
description: the network client to use, for example <code>WiFiClient</code>
- name: stream
optional: true
description: a stream to write received messages to
type: Stream
---
Creates a fully configured client instance.

48
_posts/2000-02-01-connect.md Normal file
View File

@@ -0,0 +1,48 @@
---
tag: api
type: function
name: connect
params:
- name: clientID
description: the client ID to use when connecting to the server
type: const char[]
- name: Credentials
optionalGroup: true
params:
- name: username
description: the username to use. If <code>NULL</code>, no username or password is used
type: const char[]
- name: password
description: the password to use. If <code>NULL</code>, no password is used
type: const char[]
- name: Will
optionalGroup: true
params:
- name: willTopic
description: the topic to be used by the will message
type: const char[]
- name: willQoS
description: the quality of service to be used by the will message
type: 'int: 0,1 or 2'
- name: willRetain
description: whether the will should be published with the retain flag
type: boolean
- name: willMessage
description: the payload of the will message
type: const char[]
- name: cleanSession
description: whether to connect clean-session or not
type: boolean
optional: true
returns:
type: boolean
values:
- value: 'false'
description: connection failed
- value: 'true'
description: connection succeeded
---
Connects the client.

9
_posts/2000-02-02-disconnect.md Normal file
View File

@@ -0,0 +1,9 @@
---
tag: api
type: function
name: disconnect
returns:
type: void
---
Disconnects the client.

34
_posts/2000-03-01-publish.md Normal file
View File

@@ -0,0 +1,34 @@
---
tag: api
type: function
name: publish
params:
- name: topic
description: the topic to publish to
type: const char[]
- name: payload
description: the message to publish
type: const char[], byte[]
- name: length
optional: true
description: the length of the payload. Required if <span class="methodparams">payload</span> is a <span class="methodparamstype">byte[]</span>
type: unsigned int
- name: retained
optional: true
description: whether the message should be retained
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
type: boolean
returns:
type: boolean
values:
- value: 'false'
description: publish failed, either connection lost or message too large
- value: 'true'
description: publish succeeded
---
Publishes a message to the specified topic.

34
_posts/2000-03-02-publish_p.md Normal file
View File

@@ -0,0 +1,34 @@
---
tag: api
type: function
type: function
name: publish_P
params:
- name: topic
description: the topic to publish to
type: const char[]
- name: payload
description: the message to publish
type: const char[], byte[]
- name: length
optional: true
description: the length of the payload. Required if <span class="methodparams">payload</span> is a <span class="methodparamstype">byte[]</span>
type: unsigned int
- name: retained
optional: true
description: whether the message should be retained
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
type: boolean
returns:
type: boolean
values:
- value: 'false'
description: publish failed, either connection lost or message too large
- value: 'true'
description: publish succeeded
---
Publishes a message stored in PROGMEM to the specified topic.

28
_posts/2000-03-03-beginPublish.md Normal file
View File

@@ -0,0 +1,28 @@
---
tag: api
type: function
name: beginPublish
params:
- name: topic
description: the topic to publish to
type: const char[]
- name: length
description: the length of the payload to be sent
type: unsigned int
- name: retained
description: whether the message should be retained
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
type: boolean
returns:
type: boolean
values:
- value: 'false'
description: publish failed, either connection lost or message too large
- value: 'true'
description: publish succeeded
---
Begins sending a publish message. The payload of the message is provided by one or more calls to <code>write</code> followed by a call to <code>endPublish</code>.

16
_posts/2000-03-04-write1.md Normal file
View File

@@ -0,0 +1,16 @@
---
tag: api
type: function
name: write
params:
- name: byte
description: a byte to write to the publish payload
type: uint8_t
returns:
type: int
values:
- value: int
description: the number of bytes written
---
Writes a byte as a component of a publish started with a call to <code>beginPublish</code>.

19
_posts/2000-03-05-write2.md Normal file
View File

@@ -0,0 +1,19 @@
---
tag: api
type: function
name: write
params:
- name: payload
description: the bytes to write
type: byte[]
- name: length
description: the length of the payload to be sent
type: unsigned int
returns:
type: int
values:
- value: int
description: the number of bytes written
---
Writes an array of bytes as a component of a publish started with a call to <code>beginPublish</code>.

14
_posts/2000-03-06-endPublish.md Normal file
View File

@@ -0,0 +1,14 @@
---
tag: api
type: function
name: endPublish
returns:
type: boolean
values:
- value: 'false'
description: publish failed, either connection lost or message too large
- value: 'true'
description: publish succeeded
---
Finishing sending a message that was started with a call to <code>beginPublish</code>.

23
_posts/2000-04-01-subscribe.md Normal file
View File

@@ -0,0 +1,23 @@
---
tag: api
type: function
name: subscribe
params:
- name: topic
description: the topic to subscribe to
type: const char[]
- name: qos
optional: true
description: the qos to subscribe at
type: 'int: 0 or 1 only'
returns:
type: boolean
values:
- value: 'false'
description: sending the subscribe failed, either connection lost or message too large
- value: 'true'
description: sending the subscribe succeeded
---
Subscribes to messages published to the specified topic.

18
_posts/2000-04-02-unsubscribe.md Normal file
View File

@@ -0,0 +1,18 @@
---
tag: api
type: function
name: unsubscribe
params:
- name: topic
description: the topic to unsubscribe from
type: const char[]
returns:
type: boolean
values:
- value: 'false'
description: sending the unsubscribe failed, either connection lost or message too large
- value: 'true'
description: sending the unsubscribe succeeded
---
Unsubscribes from the specified topic.

15
_posts/2000-05-01-loop.md Normal file
View File

@@ -0,0 +1,15 @@
---
tag: api
type: function
name: loop
returns:
type: boolean
values:
- value: 'false'
description: the client is no longer connected
- value: 'true'
description: the client is still connected
---
This should be called regularly to allow the client to process incoming messages and maintain its connection to the server.

14
_posts/2000-05-02-connected.md Normal file
View File

@@ -0,0 +1,14 @@
---
tag: api
type: function
name: connected
returns:
type: boolean
values:
- value: 'false'
description: the client is not connected
- value: 'true'
description: the client is connected
---
Checks whether the client is connected to the server.

32
_posts/2000-05-03-state.md Normal file
View File

@@ -0,0 +1,32 @@
---
tag: api
type: function
name: state
returns:
type: int
values:
- value: '-4 : <code>MQTT_CONNECTION_TIMEOUT</code>'
description: the server didn't respond within the keepalive time
- value: '-3 : <code>MQTT_CONNECTION_LOST</code>'
description: the network connection was broken
- value: '-2 : <code>MQTT_CONNECT_FAILED</code>'
description: the network connection failed
- value: '-1 : <code>MQTT_DISCONNECTED</code>'
description: the client is disconnected cleanly
- value: '0 : <code>MQTT_CONNECTED</code>'
description: the client is connected
- value: '1 : <code>MQTT_CONNECT_BAD_PROTOCOL</code>'
description: the server doesn't support the requested version of MQTT
- value: '2 : <code>MQTT_CONNECT_BAD_CLIENT_ID</code>'
description: the server rejected the client identifier
- value: '3 : <code>MQTT_CONNECT_UNAVAILABLE</code>'
description: the server was unable to accept the connection
- value: '4 : <code>MQTT_CONNECT_BAD_CREDENTIALS</code>'
description: the username/password were rejected
- value: '5 : <code>MQTT_CONNECT_UNAUTHORIZED</code>'
description: the client was not authorized to connect
---
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 <code>PubSubClient.h</code>.

16
_posts/2000-06-01-setCallback.md Normal file
View File

@@ -0,0 +1,16 @@
---
tag: api
type: function
name: setCallback
params:
- name: callback
description: a pointer to a message callback function called when a message arrives for a subscription created by this client.
type: function*
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
Sets the <a href="#callback">message callback function</a>.

16
_posts/2000-06-02-setClient.md Normal file
View File

@@ -0,0 +1,16 @@
---
tag: api
type: function
name: setClient
params:
- name: client
description: the network client to use, for example <code>WiFiClient</code>
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
Sets the network client instance to use.

20
_posts/2000-06-02-setServer.md Normal file
View File

@@ -0,0 +1,20 @@
---
tag: api
type: function
name: setServer
params:
- name: server
description: the address of the server
type: IPAddress, uint8_t[] or const char[]
- name: port
description: the port to connect to
type: int
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
Sets the server details.

17
_posts/2000-06-04-setStream.md Normal file
View File

@@ -0,0 +1,17 @@
---
tag: api
type: function
name: setStream
params:
- name: stream
description: a stream to write received messages to
type: Stream
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
Sets the stream to write received messages to.

15
_posts/2000-06-05-getBufferSize.md Normal file
View File

@@ -0,0 +1,15 @@
---
tag: api
type: function
name: getBufferSize
returns:
type: uint16_t
values:
- value: uint16_t
description: the size of the internal buffer
---
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`.

29
_posts/2000-06-05-setBufferSize.md Normal file
View File

@@ -0,0 +1,29 @@
---
tag: api
type: function
name: setBufferSize
params:
- name: size
description: the size, in bytes, for the internal buffer
type: uint16_t
returns:
type: boolean
values:
- value: 'false'
description: the buffer could not be resized
- value: 'true'
description: the buffer was resized
---
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.
By default, it is set to `256` bytes - as defined by the `MQTT_MAX_MESSAGE_SIZE`
constant in `PubSubClient.h`.
*Note* : `setBufferSize` returns a boolean flag to indicate whether it was able
to reallocate the memory to change the buffer size. This means, unlike the other
`setXYZ` functions that return a reference to the client, this function cannot be
chained with those functions.

20
_posts/2000-06-06-setKeepAlive.md Normal file
View File

@@ -0,0 +1,20 @@
---
tag: api
type: function
name: setKeepAlive
params:
- name: keepAlive
description: the keep alive interval, in seconds
type: uint16_t
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
Sets the keep alive interval used by the client. This value should only be changed
when the client is not connected.
By default, it is set to `15` seconds - as defined by the `MQTT_KEEPALIVE`
constant in `PubSubClient.h`.

21
_posts/2000-06-07-setSocketTimeout.md Normal file
View File

@@ -0,0 +1,21 @@
---
tag: api
type: function
name: setSocketTimeout
params:
- name: timeout
description: the socket timeout, in seconds
type: uint16_t
returns:
type: PubSubClient*
values:
- value: PubSubClient*
description: the client instance, allowing the function to be chained
---
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.
By default, it is set to `15` seconds - as defined by the `MQTT_SOCKET_TIMEOUT`
constant in `PubSubClient.h`.

40
_posts/2000-10-01-configoptions.md Normal file
View File

@@ -0,0 +1,40 @@
---
tag: docs
type: other
title: Configuration Options
---
The following configuration options can be used to configure the library.
They are contained in `PubSubClient.h`.
<dl>
<dt><code>MQTT_MAX_PACKET_SIZE</code></dt>
<dd>Sets the largest packet size, in bytes, the client will handle. Any
packet received that exceeds this size will be ignored.
<p>This value can be overridden by calling <a href="#setBufferSize"><code>setBufferSize(size)</code></a>.</p>
<p>Default: 128 bytes</p>
</dd>
<dt><code>MQTT_KEEPALIVE</code></dt>
<dd>Sets the keepalive interval, in seconds, the client will use. This
is used to maintain the connection when no other packets are being
sent or received.
<p>This value can be overridden by calling <a href="#setKeepAlive"><code>setKeepAlive(keepAlive)</code></a>.</p>
<p>Default: 15 seconds</p>
</dd>
<dt><code>MQTT_VERSION</code></dt>
<dd>Sets the version of the MQTT protocol to use.
<p>Default: MQTT 3.1.1</p>
</dd>
<dt><code>MQTT_MAX_TRANSFER_SIZE</code></dt>
<dd>Sets the maximum number of bytes passed to the network client in each
write call. Some hardware has a limit to how much data can be passed
to them in one go, such as the Arduino Wifi Shield.
<p>Default: undefined (complete packet passed in each write call)</p>
</dd>
<dt><code>MQTT_SOCKET_TIMEOUT</code></dt>
<dd>Sets the timeout when reading from the network. This also applies as
the timeout for calls to <code>connect</code>.
<p>This value can be overridden by calling <a href="#setSocketTimeout"><code>setSocketTimeout(timeout)</code></a>.</p>
<p>Default: 15 seconds</p>
</dd>
</dl>

24
_posts/2000-10-02-callback.md Normal file
View File

@@ -0,0 +1,24 @@
---
tag: docs
type: other
title: Subscription Callback
---
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.
The callback function has the following signature:
void callback(const char[] topic, byte* payload, unsigned int length)
##### Parameters
- <span class="methodparams">topic</span> <span class="methodparamstype">const char[]</span> - the topic the message arrived on
- <span class="methodparams">payload</span> <span class="methodparamstype">byte[]</span> - the message payload
- <span class="methodparams">length</span> <span class="methodparamstype">unsigned int</span> - the length of the message payload
Internally, the client uses the same buffer for both inbound and outbound
messages. After the callback function returns, or if a call to either `publish`
or subscribe is made from within the callback function, the `topic`
and `payload` values passed to the function will be overwritten. The application
should create its own copy of the values if they are required after the callback returns.

522
api.html
View File

@@ -1,522 +0,0 @@
---
layout: default
title: API Documentation
---
<section class="method" id="toc">
<h3>Constructors</h3>
<ul>
<li><a href="#PubSubClient"><span class="methodname">PubSubClient</span> <span class="methodparams">()</span></a></li>
<li><a href="#PubSubClient1"><span class="methodname">PubSubClient</span> <span class="methodparams">(client)</span></a></li>
<li><a href="#PubSubClient2"><span class="methodname">PubSubClient</span> <span class="methodparams">(server, port, [callback], client, [stream])</span></a></li>
</ul>
<h3>Functions</h3>
<ul>
<li><a href="#connect1"><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID)</span></a></li>
<li><a href="#connect2"><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, willTopic, willQoS, willRetain, willMessage)</span></a></li>
<li><a href="#connect3"><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password)</span></a></li>
<li><a href="#connect4"><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password, willTopic, willQoS, willRetain, willMessage)</span></a></li>
<li><a href="#connect5"><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password, willTopic, willQoS, willRetain, willMessage, cleanSession)</span></a></li>
<li><a href="#disconnect"><span class="methodreturn">void</span> <span class="methodname">disconnect</span> <span class="methodparams">()</span></a></li>
<li><a href="#publish1"><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload)</span></a></li>
<li><a href="#publish2"><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, retained)</span></a></li>
<li><a href="#publish3"><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, length)</span></a></li>
<li><a href="#publish4"><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, length, retained)</span></a></li>
<li><a href="#publish5"><span class="methodreturn">int</span> <span class="methodname">publish_P</span> <span class="methodparams">(topic, payload, length, retained)</span></a></li>
<li><a href="#beginPublish"><span class="methodreturn">boolean</span> <span class="methodname">beginPublish</span> <span class="methodparams">(topic, payloadLength, retained)</span></a></li>
<li><a href="#write1"><span class="methodreturn">size_t</span> <span class="methodname">write</span> <span class="methodparams">(uint8_t)</span></a></li>
<li><a href="#write2"><span class="methodreturn">size_t</span> <span class="methodname">write</span> <span class="methodparams">(payload, length)</span></a></li>
<li><a href="#endPublish"><span class="methodreturn">boolean</span> <span class="methodname">endPublish</span> <span class="methodparams">()</span></a></li>
<li><a href="#subscribe"><span class="methodreturn">boolean</span> <span class="methodname">subscribe</span> <span class="methodparams">(topic, [qos])</span></a></li>
<li><a href="#unsubscribe"><span class="methodreturn">boolean</span> <span class="methodname">unsubscribe</span> <span class="methodparams">(topic)</span></a></li>
<li><a href="#loop"><span class="methodreturn">boolean</span> <span class="methodname">loop</span> <span class="methodparams">()</span></a></li>
<li><a href="#connected"><span class="methodreturn">int</span> <span class="methodname">connected</span> <span class="methodparams">()</span></a></li>
<li><a href="#state"><span class="methodreturn">int</span> <span class="methodname">state</span> <span class="methodparams">()</span></a></li>
<li><a href="#setserver"><span class="methodreturn">PubSubClient</span> <span class="methodname">setServer</span> <span class="methodparams">(server, port)</span></a></li>
<li><a href="#setcallback"><span class="methodreturn">PubSubClient</span> <span class="methodname">setCallback</span> <span class="methodparams">(callback)</span></a></li>
<li><a href="#setclient"><span class="methodreturn">PubSubClient</span> <span class="methodname">setClient</span> <span class="methodparams">(client)</span></a></li>
<li><a href="#setstream"><span class="methodreturn">PubSubClient</span> <span class="methodname">setStream</span> <span class="methodparams">(stream)</span></a></li>
</ul>
<h3>Other</h3>
<ul>
<li><a href="#configoptions">Configuration Options</a></li>
<li><a href="#callback">Subscription Callback</a></li>
</ul>
</section>
<section class="method" id="PubSubClient">
<h4><span class="methodname">PubSubClient</span> <span class="methodparams">()</span></h4>
<p>Creates an uninitialised client instance.</p>
<p>Before it can be used, it must be configured with the property setters:</p>
<pre>EthernetClient ethClient;
PubSubClient client;
void setup() {
client.setClient(ethClient);
client.setServer("broker.example.com",1883);
// client is now configured for use
}</pre>
</section>
<section class="method" id="PubSubClient2">
<h4><span class="methodname">PubSubClient</span> <span class="methodparams">(client)</span></h4>
<p>Creates a partially initialised client instance.</p>
<p>Before it can be used, the server details must be configured:</p>
<pre>EthernetClient ethClient;
PubSubClient client(ethClient);
void setup() {
client.setServer("broker.example.com",1883);
// client is now ready for use
}</pre>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">client</span> : an instance of <code>Client</code>, typically <code>EthernetClient</code>.</li>
</ul>
</section>
<section class="method" id="PubSubClient3">
<h4><span class="methodname">PubSubClient</span> <span class="methodparams">(server, port, [callback], client, [stream])</span></h4>
<p>Creates a fully configured client instance.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">server</span> : the address of the server (IPAddress, uint8_t[] or const char[])</li>
<li><span class="methodparams">port</span> : the port to connect to (int)</li>
<li><span class="methodparams">callback</span> : <i>optional</i> a pointer to a <a href="#callback">message callback</a> function called when a message arrives for a subscription created by this client.</li>
<li><span class="methodparams">client</span> : an instance of <code>Client</code>, typically <code>EthernetClient</code>.</li>
<li><span class="methodparams">stream</span> : <i>optional</i> an instance of <code>Stream</code>, used to store received messages. See the <code>mqtt_stream</code> example for more information.</li>
</ul>
</section>
<section class="method" id="connect1">
<h4><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID)</span></h4>
<p>Connects the client.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">clientID</span> : the client ID to use when connecting to the server.</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - connection failed.</li>
<li>true - connection succeeded.</li>
</ul>
</section>
<section class="method" id="connect2">
<h4><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, willTopic, willQoS, willRetain, willMessage)</span></h4>
<p>Connects the client with a Will message specified.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">clientID</span> : the client ID to use when connecting to the server.</li>
<li><span class="methodparams">willTopic</span> : the topic to be used by the will message (const char[])</li>
<li><span class="methodparams">willQoS</span> : the quality of service to be used by the will message (int : 0,1 or 2)</li>
<li><span class="methodparams">willRetain</span> : whether the will should be published with the retain flag (boolean)</li>
<li><span class="methodparams">willMessage</span> : the payload of the will message (const char[])</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - connection failed.</li>
<li>true - connection succeeded.</li>
</ul>
</section>
<section class="method" id="connect3">
<h4><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password)</span></h4>
<p>Connects the client with a username and password specified.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">clientID</span> : the client ID to use when connecting to the server.</li>
<li><span class="methodparams">username</span> : the username to use. If NULL, no username or password is used (const char[])</li>
<li><span class="methodparams">password</span> : the password to use. If NULL, no password is used (const char[])</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - connection failed.</li>
<li>true - connection succeeded.</li>
</ul>
</section>
<section class="method" id="connect4">
<h4><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password, willTopic, willQoS, willRetain, willMessage)</span></h4>
<p>Connects the client with a Will message, username and password specified.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">clientID</span> : the client ID to use when connecting to the server.</li>
<li><span class="methodparams">username</span> : the username to use. If NULL, no username or password is used (const char[])</li>
<li><span class="methodparams">password</span> : the password to use. If NULL, no password is used (const char[])</li>
<li><span class="methodparams">willTopic</span> : the topic to be used by the will message (const char[])</li>
<li><span class="methodparams">willQoS</span> : the quality of service to be used by the will message (int : 0,1 or 2)</li>
<li><span class="methodparams">willRetain</span> : whether the will should be published with the retain flag (int : 0 or 1)</li>
<li><span class="methodparams">willMessage</span> : the payload of the will message (const char[])</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - connection failed.</li>
<li>true - connection succeeded.</li>
</ul>
</section>
<section class="method" id="connect5">
<h4><span class="methodreturn">boolean</span> <span class="methodname">connect</span> <span class="methodparams">(clientID, username, password, willTopic, willQoS, willRetain, willMessage, cleanSession)</span></h4>
<p>Connects the client with a Will message, username, password and clean-session flag specified.</p>
<p><b>Note</b> : even if the <code>cleanSession</code> is set to <code>false</code>/<code>0</code> the client
will <i>not</i> retry failed qos 1 publishes. This flag is only of use to maintain subscriptions on the broker.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">clientID</span> : the client ID to use when connecting to the server.</li>
<li><span class="methodparams">username</span> : the username to use. If NULL, no username or password is used (const char[])</li>
<li><span class="methodparams">password</span> : the password to use. If NULL, no password is used (const char[])</li>
<li><span class="methodparams">willTopic</span> : the topic to be used by the will message (const char[])</li>
<li><span class="methodparams">willQoS</span> : the quality of service to be used by the will message (int : 0,1 or 2)</li>
<li><span class="methodparams">willRetain</span> : whether the will should be published with the retain flag (int : 0 or 1)</li>
<li><span class="methodparams">willMessage</span> : the payload of the will message (const char[])</li>
<li><span class="methodparams">cleanSession</span> : whether to connect clean-session or not (boolean)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - connection failed.</li>
<li>true - connection succeeded.</li>
</ul>
</section>
<section class="method" id="disconnect">
<h4><span class="methodreturn">void</span> <span class="methodname">disconnect</span> <span class="methodparams">()</span></h4>
<p>Disconnects the client.</p>
</section>
<section class="method" id="publish1">
<h4><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload)</span></h4>
<p>Publishes a string message to the specified topic.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payload - the message to publish (const char[])</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed, either connection lost, or message too large</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="publish2">
<h4><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, retained)</span></h4>
<p>Publishes a string message to the specified topic.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payload - the message to publish (const char[])</li>
<li>retained - whether the message should be retained (boolean)
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed, either connection lost, or message too large</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="publish3">
<h4><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, length)</span></h4>
<p>Publishes a message to the specified topic.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payload - the message to publish (byte[])</li>
<li>length - the length of the message (byte)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed, either connection lost, or message too large</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="publish4">
<h4><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, length, retained)</span></h4>
<p>Publishes a message to the specified topic, with the retained flag as specified.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payload - the message to publish (byte[])</li>
<li>length - the length of the message (byte)</li>
<li>retained - whether the message should be retained (boolean)
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed, either connection lost, or message too large</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="publish5">
<h4><span class="methodreturn">int</span> <span class="methodname">publish_P</span> <span class="methodparams">(topic, payload, length, retained)</span></h4>
<p>Publishes a message stored in <code>PROGMEN</code> to the specified topic, with the retained flag as specified.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payload - the message to publish (PROGMEM byte[])</li>
<li>length - the length of the message (byte)</li>
<li>retained - whether the message should be retained (boolean)
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="beginPublish">
<h4><span class="methodreturn">boolean</span> <span class="methodname">beginPublish</span> <span class="methodparams">(topic, payloadLength, retained)</span></h4>
<p>Begins sending a publish message. The payload of the message is provided by one or more calls to <code>write</code> followed by a call to <code>endPublish</code>.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to publish to (const char[])</li>
<li>payloadLength - the length of the message to publish</li>
<li>retained - whether the message should be retained (boolean)
<ul>
<li>false - not retained</li>
<li>true - retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="write1">
<h4><span class="methodreturn">size_t</span> <span class="methodname">write</span> <span class="methodparams">(uint8_t)</span></h4>
<p>Writes a byte as a component of a publish started with a call to <code>beginPublish</code>.</p>
<h5>Parameters</h5>
<ul>
<li>uint8_t - the byte to write</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="write2">
<h4><span class="methodreturn">size_t</span> <span class="methodname">write</span> <span class="methodparams">(payload, length)</span></h4>
<p>Writes an array of bytes as a component of a publish started with a call to <code>beginPublish</code>.</p>
<h5>Parameters</h5>
<ul>
<li>payload - the bytes to write (byte[])</li>
<li>length - the length of the byte array (byte)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - publish failed</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="endPublish">
<h4><span class="methodreturn">boolean</span> <span class="methodname">endPublish</span> <span class="methodparams">()</span></h4>
<p>Finishing sending a message that was started with a call to <code>beginPublish</code>.</p>
<h5>Returns</h5>
<ul>
<li>false - publish failed</li>
<li>true - publish succeeded</li>
</ul>
</section>
<section class="method" id="subscribe">
<h4><span class="methodreturn">boolean</span> <span class="methodname">subscribe</span> <span class="methodparams">(topic, [qos])</span></h4>
<p>Subscribes to messages published to the specified topic.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to subscribe to (const char[])</li>
<li>qos - <i>optional</i> the qos to subscribe at (int: 0 or 1 only)
</ul>
<h5>Returns</h5>
<ul>
<li>false - sending the subscribe failed, either connection lost, or message too large.</li>
<li>true - sending the subscribe succeeded. The request completes asynchronously.</li>
</ul>
</section>
<section class="method" id="unsubscribe">
<h4><span class="methodreturn">boolean</span> <span class="methodname">unsubscribe</span> <span class="methodparams">(topic)</span></h4>
<p>Unsubscribes from the specified topic.</p>
<h5>Parameters</h5>
<ul>
<li>topic - the topic to unsubscribe from (const char[])</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false - sending the unsubscribe failed, either connection lost, or message too large.</li>
<li>true - sending the unsubscribe succeeded. The request completes asynchronously.</li>
</ul>
</section>
<section class="method" id="loop">
<h4><span class="methodreturn">boolean</span> <span class="methodname">loop</span> <span class="methodparams">()</span></h4>
<p>This should be called regularly to allow the client to process incoming messages and maintain its connection to the server.</p>
<h5>Returns</h5>
<ul>
<li>false - the client is no longer connected</li>
<li>true - the client is still connected</li>
</ul>
</section>
<section class="method" id="connected">
<h4><span class="methodreturn">int</span> <span class="methodname">connected</span> <span class="methodparams">()</span></h4>
<p>Checks whether the client is connected to the server.</p>
<h5>Returns</h5>
<ul>
<li>false - the client is no longer connected</li>
<li>true - the client is still connected</li>
</ul>
</section>
<section class="method" id="state">
<h4><span class="methodreturn">int</span> <span class="methodname">state</span> <span class="methodparams">()</span></h4>
<p>Returns the current state of the client. If a connection attempt fails,
this can be used to get more information about the failure.</p>
<h5>Returns</h5>
<ul>
<li>int - the client state, which can take the following values (constants defined in <code>PubSubClient.h</code>): <ul>
<li>-4 : <code>MQTT_CONNECTION_TIMEOUT</code> - the server didn't respond within the keepalive time</li>
<li>-3 : <code>MQTT_CONNECTION_LOST</code> - the network connection was broken</li>
<li>-2 : <code>MQTT_CONNECT_FAILED</code> - the network connection failed</li>
<li>-1 : <code>MQTT_DISCONNECTED</code> - the client is disconnected cleanly</li>
<li>0 : <code>MQTT_CONNECTED</code> - the client is connected</li>
<li>1 : <code>MQTT_CONNECT_BAD_PROTOCOL</code> - the server doesn't support the requested version of MQTT</li>
<li>2 : <code>MQTT_CONNECT_BAD_CLIENT_ID</code> - the server rejected the client identifier</li>
<li>3 : <code>MQTT_CONNECT_UNAVAILABLE</code> - the server was unable to accept the connection</li>
<li>4 : <code>MQTT_CONNECT_BAD_CREDENTIALS</code> - the username/password were rejected</li>
<li>5 : <code>MQTT_CONNECT_UNAUTHORIZED</code> - the client was not authorized to connect</li>
</ul></li>
</ul>
</section>
<section class="method" id="setserver">
<h4><span class="methodreturn">PubSubClient</span> <span class="methodname">setServer</span> <span class="methodparams">(server, port)</span></h4>
<p>Sets the server details.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">server</span> : the address of the server (IPAddress, uint8_t[] or const char[])</li>
<li><span class="methodparams">port</span> : the port to connect to (int)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>PubSubClient - the client instance, allowing the function to be chained</li>
</ul>
</section>
<section class="method" id="setcallback">
<h4><span class="methodreturn">PubSubClient</span> <span class="methodname">setCallback</span> <span class="methodparams">(callback)</span></h4>
<p>Sets the message callback function.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">callback</span> : a pointer to a <a href="#callback">message callback</a> function called when a message arrives for a subscription created by this client.</li>
</ul>
<h5>Returns</h5>
<ul>
<li>PubSubClient - the client instance, allowing the function to be chained</li>
</ul>
</section>
<section class="method" id="setclient">
<h4><span class="methodreturn">PubSubClient</span> <span class="methodname">setClient</span> <span class="methodparams">(client)</span></h4>
<p>Sets the client.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">client</span> : an instance of <code>Client</code>, typically <code>EthernetClient</code>.</li>
</ul>
<h5>Returns</h5>
<ul>
<li>PubSubClient - the client instance, allowing the function to be chained</li>
</ul>
</section>
<section class="method" id="setstream">
<h4><span class="methodreturn">PubSubClient</span> <span class="methodname">setStream</span> <span class="methodparams">(stream)</span></h4>
<p>Sets the stream.</p>
<h5>Parameters</h5>
<ul>
<li><span class="methodparams">stream</span> : an instance of <code>Stream</code>, used to store received messages. See the <code>mqtt_stream</code> example for more information.</li>
</ul>
<h5>Returns</h5>
<ul>
<li>PubSubClient - the client instance, allowing the function to be chained</li>
</ul>
</section>
<section class="method" id="configoptions">
<h4>Configuration Options</h4>
<p>The following configuration options can be used to configure the library.
They are contained in <code>PubSubClient.h</code>.</p>
<dl>
<dt><code>MQTT_MAX_PACKET_SIZE</code></dt>
<dd>Sets the largest packet size, in bytes, the client will handle. Any
packet received that exceeds this size will be ignored.</p>
<p>Default: 128 bytes</p>
</dd>
<dt><code>MQTT_KEEPALIVE</code></dt>
<dd>Sets the keepalive interval, in seconds, the client will use. This
is used to maintain the connection when no other packets are being
sent or received.</p>
<p>Default: 15 seconds</p>
</dd>
<dt><code>MQTT_VERSION</code></dt>
<dd>Sets the version of the MQTT protocol to use.</p>
<p>Default: MQTT 3.1.1</p>
</dd>
<dt><code>MQTT_MAX_TRANSFER_SIZE</code></dt>
<dd>Sets the maximum number of bytes passed to the network client in each
write call. Some hardware has a limit to how much data can be passed
to them in one go, such as the Arduino Wifi Shield.</p>
<p>Default: undefined (complete packet passed in each write call)</p>
</dd>
<dt><code>MQTT_SOCKET_TIMEOUT</code></dt>
<dd>Sets the timeout when reading from the network. This also applies as
the timeout for calls to <code>connect</code>.
<p>Default: 15 seconds</p>
</dd>
</dl>
</section>
<section class="method" id="callback">
<h4>Subscription Callback</h4>
<p>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.
</p>
<p>The callback function has the following signature:</p>
<pre>void callback(const char[] topic, byte* payload, unsigned int length)</pre>
<h5>Parameters</h5>
<ul>
<li>topic - the topic the message arrived on (const char[])</li>
<li>payload - the message payload (byte array)</li>
<li>length - the length of the message payload (unsigned int)</li>
</ul>
<p>Internally, the client uses the same buffer for both inbound and outbound
messages. After the callback function returns, or if a call to either <code>publish</code>
or <code>subscribe</code> is made from within the callback function, the <code>topic</code>
and <code>payload</code> values passed to the function will be overwritten. The application
should create its own copy of the values if they are required beyond this.
</p>
</section>

53
api.md Normal file
View File

@@ -0,0 +1,53 @@
---
layout: default
title: API Documentation
---
### Library version: 2.8
{% assign sorted = site.posts | reverse %}
{% assign currentType = "" %}
{% for post in sorted %}
{% if post.tags contains 'api' or post.tags contains 'docs' %}
{% unless post.type == currentType%}
{%if currentType != "" %}</ul>{%endif%}
<h3>{{post.type | capitalize}}</h3>
{% assign currentType = post.type %}
<ul class="post-list">
{% endunless %}
<li><a href="#{{post.slug}}">{%if post.tags contains 'api'
%}{% if post.returns %}<span class="methodreturn">{{ post.returns.type }}</span> {% endif %}<span class="methodname">{{ post.name }} </span> <span class="methodparams">({% include paramsList.html params=post.params %})</span>{%
else %}{{ post.title }}{%endif%}</a></li>
{% endif %}
{% endfor %}
</ul>
---
{% for post in sorted %}
{% if post.tags contains 'api' or post.tags contains 'docs'%}
<section class="method" id="{{post.slug}}">
{% if post.tags contains 'api' %}
<h4>{% if post.returns %}<span class="methodreturn">{{ post.returns.type }}</span> {% endif %}<span class="methodname">{{ post.name }}</span> <span class="methodparams">({% include paramsList.html params=post.params %})</span></h4>
{{ post.content }}
{% if post.params %}
<h5>Parameters</h5>
<ul>
{% include paramsListLong.html params=post.params %}
</ul>
{% endif %}
{% if post.returns and post.returns.values %}
<h5>Returns</h5>
<ul>
{% for return in post.returns.values %}<li>{% if return.value %}<span class="methodreturnvalue">{{ return.value }}</span> - {%endif%}{{ return.description}}</li>{% endfor %}
</ul>
{% endif %}
{% else %}
<h4>{{post.title}}</h4>
{{post.content}}
{% endif %}
</section>
{% endif %}
{% endfor %}

67
index.html
View File

@@ -1,67 +0,0 @@
---
layout: default
title: Arduino Client for MQTT
---
<p>This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT</p>
<p>For more information about MQTT, visit <a href="http://mqtt.org">mqtt.org</a>.</p>
<section id="Download">
<h2>Download</h2>
<p>The latest version of the library can be downloaded from <a href="https://github.com/knolleary/pubsubclient/releases/latest">GitHub</a>.</p>
</section>
<section id="Documentation">
<h2>Documentation</h2>
<p>The library comes with a number of example sketches. See <code>File &gt; Examples &gt; PubSubClient</code> within the Arduino application.</p>
<p>Full <a href="api.html">API Documentation</a></p>
</section>
<section id="Hardware">
<h2>Compatible Hardware</h2>
<p>
The library uses the Arduino Ethernet Client api for interacting with the
underlying network hardware. This means it Just Works with a growing number of
boards and shields, including:
</p>
<ul>
<li>Arduino Ethernet</li>
<li>Arduino Ethernet Shield</li>
<li>Arduino YUN – use the included <code>YunClient</code> in place of <code>EthernetClient</code>, and
be sure to do a <code>Bridge.begin()</code> first</li>
<li>Arduino WiFi Shield - if you want to send packets greater than 90 bytes with this shield,
enable the <a href="http://knolleary.github.io/pubsubclient/api.html#configoptions"><code>MQTT_MAX_TRANSFER_SIZE</code></code></a> option in <code>PubSubClient.h</code>.</li>
<li>Sparkfun WiFly Shield – when used with <a href="https://github.com/dpslwk/WiFly">this library</a></li>
<li>Intel Galileo/Edison</li>
<li>ESP8266</li>
<li>ESP32</li>
</ul>
<p>
The library cannot currently be used with hardware based on the ENC28J60 chip –
such as the Nanode or the Nuelectronics Ethernet Shield. For those, there is an
<a href="https://github.com/njh/NanodeMQTT">alternative library</a> available.
</p>
</section>
<section id="Author">
<h2>Author</h2>
<p>Nick O'Leary - <a href="https://twitter.com/knolleary">@knolleary</a></p>
</section>
<section id="License">
<h2>License</h2>
<p>This library is released under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>.</p>
</section>
<section id="ChangeHistory">
<h2>Change History</h2>
<p>The complete change history is available on <a href="https://github.com/knolleary/pubsubclient/commits/master">GitHub</a>.</p>
<dl>
<dt>2.7</dt>
<dd>
<ul>
<li>Fix remaining-length handling to prevent buffer overrun</li>
<li>Add large-payload API - beginPublish/write/publish/endPublish</li>
<li>Add yield call to improve reliability on ESP</li>
<li>Add Clean Session flag to connect options</li>
<li>Add ESP32 support for functional callback signature</li>
<li>Various other fixes</li>
</ul>
</dd>
</dl>
</section>

41
index.md Normal file
View File

@@ -0,0 +1,41 @@
---
layout: default
title: Arduino Client for MQTT
---
This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT
For more information about MQTT, visit [MQTT.org](http://mqtt.org).
## Download
The latest version of the library can be downloaded from [GitHub](https://github.com/knolleary/pubsubclient/releases/latest).
## Documentation
The library comes with a number of example sketches. See `File > Examples > PubSubClient` within the Arduino application.
Full <a href="api.html">[API Documentation](/api) is available.
## Author
- Nick O'Leary - [@knolleary](https://twitter.com/knolleary)
## License
This library is released under the [MIT License](http://www.opensource.org/licenses/mit-license.php).
## Change History
The complete change history is available on [GitHub](https://github.com/knolleary/pubsubclient/commits/master).
#### Latest version: 2.8 <small> - released 2020-05-20</small>
- Add `setBufferSize()` to override `MQTT_MAX_PACKET_SIZE`
- Add `setKeepAlive()` to override `MQTT_KEEPALIVE`
- Add `setSocketTimeout()` to overide `MQTT_SOCKET_TIMEOUT`
- Added check to prevent subscribe/unsubscribe to empty topics
- Declare wifi mode prior to connect in ESP example
- Use `strnlen` to avoid overruns
- Support pre-connected Client objects

3
style.css
View File

@@ -64,6 +64,9 @@ section {
.methodname { font-weight: bold;color: #333;}
.methodreturn { font-weight: normal; color: #777;}
.methodparams { font-weight: normal; color: #777;}
.methodparamstype { font-size: 13px; font-family: monospace; color: #979;}
.methodreturnvalue { font-family: monospace; color: #979; }
.methodparamoptional { font-size: 13px; font-style: italic; color: #777}
ul a {
text-decoration: none;
}