523 lines
28 KiB
HTML
523 lines
28 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="#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>
|