---
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 &#8211; connection failed.</li>
<li>true &#8211; 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 &#8211; connection failed.</li>
<li>true &#8211; 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 &#8211; connection failed.</li>
<li>true &#8211; 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 &#8211; connection failed.</li>
<li>true &#8211; 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 &#8211; the topic to publish to (char*)</li>
<li>payload &#8211; the message to publish (char*)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false &#8211; publish failed.</li>
<li>true &#8211; 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 &#8211; the topic to publish to (char*)</li>
<li>payload &#8211; the message to publish (byte array)</li>
<li>length &#8211; the length of the message (byte)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false &#8211; publish failed.</li>
<li>true &#8211; 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 &#8211; the topic to publish to (char*)</li>
<li>payload &#8211; the message to publish (byte array)</li>
<li>length &#8211; the length of the message (byte)</li>
<li>retained &#8211; whether the message should be retained (byte)
<ul>
<li>0 &#8211; not retained</li>
<li>1 &#8211; retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false &#8211; publish failed.</li>
<li>true &#8211; 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 &#8211; the topic to publish to (char*)</li>
<li>payload &#8211; the message to publish (PROGMEM byte array)</li>
<li>length &#8211; the length of the message (byte)</li>
<li>retained &#8211; whether the message should be retained (byte)
<ul>
<li>0 &#8211; not retained</li>
<li>1 &#8211; retained</li>
</ul>
</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false &#8211; publish failed.</li>
<li>true &#8211; 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 &#8211; the topic to publish to (char*)</li>
</ul>
<h5>Returns</h5>
<ul>
<li>false &#8211; sending the subscribe failed.</li>
<li>true &#8211; 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 &#8211; the client is no longer connected</li>
<li>true &#8211; 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 &#8211; the client is no longer connected</li>
<li>true &#8211; 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 &#8211; the topic the message arrived on (char*)</li>
<li>payload &#8211; the message payload (byte array)</li>
<li>length &#8211; 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>