402 lines
21 KiB
HTML
402 lines
21 KiB
HTML
---
|
|
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="#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, length)</span></a></li>
|
|
<li><a href="#publish3"><span class="methodreturn">int</span> <span class="methodname">publish</span> <span class="methodparams">(topic, payload, length, retained)</span></a></li>
|
|
<li><a href="#publish4"><span class="methodreturn">int</span> <span class="methodname">publish_P</span> <span class="methodparams">(topic, payload, length, retained)</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="#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. As per MQTT, this must be between 1 and 23 characters long.</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. As per MQTT, this must be between 1 and 23 characters long.</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. As per MQTT, this must be between 1 and 23 characters long.</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. As per MQTT, this must be between 1 and 23 characters long.</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="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.</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, 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 array)</li>
|
|
<li>length - the length of the message (byte)</li>
|
|
</ul>
|
|
<h5>Returns</h5>
|
|
<ul>
|
|
<li>false - publish failed.</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, 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 array)</li>
|
|
<li>length - the length of the message (byte)</li>
|
|
<li>retained - whether the message should be retained (byte)
|
|
<ul>
|
|
<li>0 - not retained</li>
|
|
<li>1 - 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="publish4">
|
|
<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 array)</li>
|
|
<li>length - the length of the message (byte)</li>
|
|
<li>retained - whether the message should be retained (byte)
|
|
<ul>
|
|
<li>0 - not retained</li>
|
|
<li>1 - 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="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.</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.</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 cient 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<br />
|
|
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. This defaults to interval, in seconds, the client will use. This is used to maintain the connection when no other packets are being<br />
|
|
sent or received.</p>
|
|
<p>Default: MQTT 3.1.1</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>
|