279 lines
13 KiB
HTML
279 lines
13 KiB
HTML
---
|
|
layout: default
|
|
title: API Docs
|
|
---
|
|
<p><i>These docs refer to the latest version of the library on <a href="https://github.com/knolleary/pubsubclient">GitHub</a></i></p>
|
|
|
|
<section class="method" id="toc">
|
|
<h5>Constructors</h5>
|
|
<ul>
|
|
<li><a href="#PubSubClient"><span class="methodname">PubSubClient</span> <span class="methodparams">(server, port, callback, client)</span></a></li>
|
|
<li><a href="#PubSubClient2"><span class="methodname">PubSubClient</span> <span class="methodparams">(serverDNS, port, callback, client)</span></a></li>
|
|
</ul>
|
|
<h5>Functions</h5>
|
|
<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)</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>
|
|
</ul>
|
|
<h5>Other</h5>
|
|
<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">(server, port, callback, client)</span></h4>
|
|
<p>Creates a client instance, with the server specified by IP address.</p>
|
|
<h5>Parameters</h5>
|
|
<ul>
|
|
<li>server : the IP address of the server (array of 4 bytes)</li>
|
|
<li>port : the port to connect to (int)</li>
|
|
<li>callback : a pointer to a function called when a message arrives for a subscription created by this client. If no callback is required, set this to 0. See <a href="#callback">Subscription Callback</a>.</li>
|
|
<li>client : an instance of <code>Client</code>, typically <code>EthernetClient</code>.</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section class="method" id="PubSubClient2">
|
|
<h4><span class="methodname">PubSubClient</span> <span class="methodparams">(serverDNS, port, callback, client)</span></h4>
|
|
<p>Creates a client instance, with the server specified by DNS name.</p>
|
|
<h5>Parameters</h5>
|
|
<ul>
|
|
<li>serverDNS : the DNS name of the server (char*)</li>
|
|
<li>port : the port to connect to (int)</li>
|
|
<li>callback : a pointer to a function called when a message arrives for a subscription created by this client. If no callback is required, set this to 0. See <a href="#callback">Subscription Callback</a>.</li>
|
|
<li>client : an instance of <code>Client</code>, typically <code>EthernetClient</code>.</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>clientID : 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>clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.</li>
|
|
<li>willTopic : the topic to be used by the will message (char*)</li>
|
|
<li>willQoS : the quality of service to be used by the will message (int : 0,1 or 2)</li>
|
|
<li>willRetain : whether the will should be published with the retain flag (int : 0 or 1)</li>
|
|
<li>willMessage : the payload of the will message (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>clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.</li>
|
|
<li>username : the username to use. If NULL, no username or password is used (char*)</li>
|
|
<li>password : the password to use. If NULL, no password is used (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>clientID : the client ID to use when connecting to the server. As per MQTT, this must be between 1 and 23 characters long.</li>
|
|
<li>username : the username to use. If NULL, no username or password is used (char*)</li>
|
|
<li>password : the password to use. If NULL, no password is used (char*)</li>
|
|
<li>willTopic : the topic to be used by the will message (char*)</li>
|
|
<li>willQoS : the quality of service to be used by the will message (int : 0,1 or 2)</li>
|
|
<li>willRetain : whether the will should be published with the retain flag (int : 0 or 1)</li>
|
|
<li>willMessage : the payload of the will message (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 (char*)</li>
|
|
<li>payload – the message to publish (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 (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 (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 (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)</span></h4>
|
|
<p>Subscribes to messages published to the specified topic.</p>
|
|
<h5>Parameters</h5>
|
|
<ul>
|
|
<li>topic – the topic to publish to (char*)</li>
|
|
</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="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="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
|
|
</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
|
|
</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:
|
|
<pre>
|
|
void callback(char* topic, byte* payload, unsigned int length)
|
|
</pre>
|
|
<h5>Parameters</h5>
|
|
<ul>
|
|
<li>topic – the topic the message arrived on (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>
|
|
|
|
|