Rebuild docs to make them easier to maintain

_posts/2000-01-01-PubSubClient.md

@@ -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
+}
+```

_posts/2000-01-02-PubSubClient1.md

@@ -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
+}
+```

_posts/2000-01-03-PubSubClient2.md

@@ -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.

_posts/2000-02-01-connect.md

@@ -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.
+

_posts/2000-02-02-disconnect.md

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

_posts/2000-03-01-publish.md

@@ -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.
+

_posts/2000-03-02-publish_p.md

@@ -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.

_posts/2000-03-03-beginPublish.md

@@ -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>.

_posts/2000-03-04-write1.md

@@ -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>.

_posts/2000-03-05-write2.md

@@ -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>.

_posts/2000-03-06-endPublish.md

@@ -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>.

_posts/2000-04-01-subscribe.md

@@ -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.
+

_posts/2000-04-02-unsubscribe.md

@@ -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.

_posts/2000-05-01-loop.md

@@ -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.
+

_posts/2000-05-02-connected.md

@@ -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.

_posts/2000-05-03-state.md

@@ -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>.

_posts/2000-06-01-setCallback.md

@@ -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>.

_posts/2000-06-02-setClient.md

@@ -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.

_posts/2000-06-02-setServer.md

@@ -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.

_posts/2000-06-04-setStream.md

@@ -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.
+

_posts/2000-06-05-getBufferSize.md

@@ -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`.

_posts/2000-06-05-setBufferSize.md

@@ -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.

_posts/2000-06-06-setKeepAlive.md

@@ -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`.

_posts/2000-06-07-setSocketTimeout.md

@@ -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`.

_posts/2000-10-01-configoptions.md

@@ -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>

_posts/2000-10-02-callback.md

@@ -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.