From a9d9bad1ff103bc4ba0c2a5d0e22b58a9a72fd28 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Thu, 21 May 2020 01:17:42 +0100 Subject: [PATCH] Rebuild docs to make them easier to maintain --- .gitignore | 4 + _includes/paramsList.html | 11 + _includes/paramsListLong.html | 12 + _layouts/default.html | 2 +- _posts/2000-01-01-PubSubClient.md | 21 ++ _posts/2000-01-02-PubSubClient1.md | 23 ++ _posts/2000-01-03-PubSubClient2.md | 25 ++ _posts/2000-02-01-connect.md | 48 +++ _posts/2000-02-02-disconnect.md | 9 + _posts/2000-03-01-publish.md | 34 ++ _posts/2000-03-02-publish_p.md | 34 ++ _posts/2000-03-03-beginPublish.md | 28 ++ _posts/2000-03-04-write1.md | 16 + _posts/2000-03-05-write2.md | 19 + _posts/2000-03-06-endPublish.md | 14 + _posts/2000-04-01-subscribe.md | 23 ++ _posts/2000-04-02-unsubscribe.md | 18 + _posts/2000-05-01-loop.md | 15 + _posts/2000-05-02-connected.md | 14 + _posts/2000-05-03-state.md | 32 ++ _posts/2000-06-01-setCallback.md | 16 + _posts/2000-06-02-setClient.md | 16 + _posts/2000-06-02-setServer.md | 20 + _posts/2000-06-04-setStream.md | 17 + _posts/2000-06-05-getBufferSize.md | 15 + _posts/2000-06-05-setBufferSize.md | 29 ++ _posts/2000-06-06-setKeepAlive.md | 20 + _posts/2000-06-07-setSocketTimeout.md | 21 ++ _posts/2000-10-01-configoptions.md | 40 ++ _posts/2000-10-02-callback.md | 24 ++ api.html | 522 -------------------------- api.md | 53 +++ index.html | 67 ---- index.md | 41 ++ style.css | 3 + 35 files changed, 716 insertions(+), 590 deletions(-) create mode 100644 _includes/paramsList.html create mode 100644 _includes/paramsListLong.html create mode 100644 _posts/2000-01-01-PubSubClient.md create mode 100644 _posts/2000-01-02-PubSubClient1.md create mode 100644 _posts/2000-01-03-PubSubClient2.md create mode 100644 _posts/2000-02-01-connect.md create mode 100644 _posts/2000-02-02-disconnect.md create mode 100644 _posts/2000-03-01-publish.md create mode 100644 _posts/2000-03-02-publish_p.md create mode 100644 _posts/2000-03-03-beginPublish.md create mode 100644 _posts/2000-03-04-write1.md create mode 100644 _posts/2000-03-05-write2.md create mode 100644 _posts/2000-03-06-endPublish.md create mode 100644 _posts/2000-04-01-subscribe.md create mode 100644 _posts/2000-04-02-unsubscribe.md create mode 100644 _posts/2000-05-01-loop.md create mode 100644 _posts/2000-05-02-connected.md create mode 100644 _posts/2000-05-03-state.md create mode 100644 _posts/2000-06-01-setCallback.md create mode 100644 _posts/2000-06-02-setClient.md create mode 100644 _posts/2000-06-02-setServer.md create mode 100644 _posts/2000-06-04-setStream.md create mode 100644 _posts/2000-06-05-getBufferSize.md create mode 100644 _posts/2000-06-05-setBufferSize.md create mode 100644 _posts/2000-06-06-setKeepAlive.md create mode 100644 _posts/2000-06-07-setSocketTimeout.md create mode 100644 _posts/2000-10-01-configoptions.md create mode 100644 _posts/2000-10-02-callback.md delete mode 100644 api.html create mode 100644 api.md delete mode 100644 index.html create mode 100644 index.md diff --git a/.gitignore b/.gitignore index 57510a2..9631e87 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ _site/ +.jekyll-cache +.DS_Store +.ruby-version +tests/bin diff --git a/_includes/paramsList.html b/_includes/paramsList.html new file mode 100644 index 0000000..cc7b5b7 --- /dev/null +++ b/_includes/paramsList.html @@ -0,0 +1,11 @@ +{% + for param in include.params +%}{% + if param.optionalGroup +%}[{% include paramsList.html params=param.params %}]{% + else +%}{% + if param.optional %}[{%endif %}{{param.name}}{% if param.optional %}]{%endif +%}{%endif +%}{% if forloop.last == false %}, {%endif%}{% endfor +%} \ No newline at end of file diff --git a/_includes/paramsListLong.html b/_includes/paramsListLong.html new file mode 100644 index 0000000..58648fb --- /dev/null +++ b/_includes/paramsListLong.html @@ -0,0 +1,12 @@ +{% + for param in include.params +%}
  • {% + if param.optionalGroup +%}{{param.name}} - (optional){% + else +%} +{{param.name}} {% if param.type %}{{param.type}} {% endif %} {% if param.optional %}(optional) {%endif %} - +{{param.description}} + +{% endif %}
    • {% endfor +%} diff --git a/_layouts/default.html b/_layouts/default.html index 52670ca..cc03d75 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -13,7 +13,7 @@

    {{ page.title }}

    diff --git a/_posts/2000-01-01-PubSubClient.md b/_posts/2000-01-01-PubSubClient.md new file mode 100644 index 0000000..d6c86d6 --- /dev/null +++ b/_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 +} +``` diff --git a/_posts/2000-01-02-PubSubClient1.md b/_posts/2000-01-02-PubSubClient1.md new file mode 100644 index 0000000..4179bbf --- /dev/null +++ b/_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 WiFiClient +--- + + +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 +} +``` diff --git a/_posts/2000-01-03-PubSubClient2.md b/_posts/2000-01-03-PubSubClient2.md new file mode 100644 index 0000000..f2a8ec3 --- /dev/null +++ b/_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 message callback function called when a message arrives for a subscription created by this client + type: function* + - name: client + description: the network client to use, for example WiFiClient + - name: stream + optional: true + description: a stream to write received messages to + type: Stream +--- + + +Creates a fully configured client instance. diff --git a/_posts/2000-02-01-connect.md b/_posts/2000-02-01-connect.md new file mode 100644 index 0000000..8ffe24c --- /dev/null +++ b/_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 NULL, no username or password is used + type: const char[] + - name: password + description: the password to use. If NULL, 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. + diff --git a/_posts/2000-02-02-disconnect.md b/_posts/2000-02-02-disconnect.md new file mode 100644 index 0000000..f10a368 --- /dev/null +++ b/_posts/2000-02-02-disconnect.md @@ -0,0 +1,9 @@ +--- +tag: api +type: function +name: disconnect +returns: + type: void +--- + +Disconnects the client. diff --git a/_posts/2000-03-01-publish.md b/_posts/2000-03-01-publish.md new file mode 100644 index 0000000..6dcf2ea --- /dev/null +++ b/_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 payload is a byte[] + type: unsigned int +- name: retained + optional: true + description: whether the message should be retained + + 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. + diff --git a/_posts/2000-03-02-publish_p.md b/_posts/2000-03-02-publish_p.md new file mode 100644 index 0000000..361e181 --- /dev/null +++ b/_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 payload is a byte[] + type: unsigned int +- name: retained + optional: true + description: whether the message should be retained + + 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. diff --git a/_posts/2000-03-03-beginPublish.md b/_posts/2000-03-03-beginPublish.md new file mode 100644 index 0000000..04d288b --- /dev/null +++ b/_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 + + 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 write followed by a call to endPublish. diff --git a/_posts/2000-03-04-write1.md b/_posts/2000-03-04-write1.md new file mode 100644 index 0000000..e5d05c5 --- /dev/null +++ b/_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 beginPublish. \ No newline at end of file diff --git a/_posts/2000-03-05-write2.md b/_posts/2000-03-05-write2.md new file mode 100644 index 0000000..3deb17b --- /dev/null +++ b/_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 beginPublish. \ No newline at end of file diff --git a/_posts/2000-03-06-endPublish.md b/_posts/2000-03-06-endPublish.md new file mode 100644 index 0000000..ede8b18 --- /dev/null +++ b/_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 beginPublish. \ No newline at end of file diff --git a/_posts/2000-04-01-subscribe.md b/_posts/2000-04-01-subscribe.md new file mode 100644 index 0000000..f61b556 --- /dev/null +++ b/_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. + diff --git a/_posts/2000-04-02-unsubscribe.md b/_posts/2000-04-02-unsubscribe.md new file mode 100644 index 0000000..6b6b595 --- /dev/null +++ b/_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. diff --git a/_posts/2000-05-01-loop.md b/_posts/2000-05-01-loop.md new file mode 100644 index 0000000..e77bc05 --- /dev/null +++ b/_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. + diff --git a/_posts/2000-05-02-connected.md b/_posts/2000-05-02-connected.md new file mode 100644 index 0000000..12af98a --- /dev/null +++ b/_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. \ No newline at end of file diff --git a/_posts/2000-05-03-state.md b/_posts/2000-05-03-state.md new file mode 100644 index 0000000..2821897 --- /dev/null +++ b/_posts/2000-05-03-state.md @@ -0,0 +1,32 @@ +--- +tag: api +type: function +name: state +returns: + type: int + values: + - value: '-4 : MQTT_CONNECTION_TIMEOUT' + description: the server didn't respond within the keepalive time + - value: '-3 : MQTT_CONNECTION_LOST' + description: the network connection was broken + - value: '-2 : MQTT_CONNECT_FAILED' + description: the network connection failed + - value: '-1 : MQTT_DISCONNECTED' + description: the client is disconnected cleanly + - value: '0 : MQTT_CONNECTED' + description: the client is connected + - value: '1 : MQTT_CONNECT_BAD_PROTOCOL' + description: the server doesn't support the requested version of MQTT + - value: '2 : MQTT_CONNECT_BAD_CLIENT_ID' + description: the server rejected the client identifier + - value: '3 : MQTT_CONNECT_UNAVAILABLE' + description: the server was unable to accept the connection + - value: '4 : MQTT_CONNECT_BAD_CREDENTIALS' + description: the username/password were rejected + - value: '5 : MQTT_CONNECT_UNAUTHORIZED' + 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 PubSubClient.h. \ No newline at end of file diff --git a/_posts/2000-06-01-setCallback.md b/_posts/2000-06-01-setCallback.md new file mode 100644 index 0000000..d4ff0b7 --- /dev/null +++ b/_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 message callback function. diff --git a/_posts/2000-06-02-setClient.md b/_posts/2000-06-02-setClient.md new file mode 100644 index 0000000..022962a --- /dev/null +++ b/_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 WiFiClient + +returns: + type: PubSubClient* + values: + - value: PubSubClient* + description: the client instance, allowing the function to be chained +--- + +Sets the network client instance to use. \ No newline at end of file diff --git a/_posts/2000-06-02-setServer.md b/_posts/2000-06-02-setServer.md new file mode 100644 index 0000000..aed2478 --- /dev/null +++ b/_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. \ No newline at end of file diff --git a/_posts/2000-06-04-setStream.md b/_posts/2000-06-04-setStream.md new file mode 100644 index 0000000..3bb6215 --- /dev/null +++ b/_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. + diff --git a/_posts/2000-06-05-getBufferSize.md b/_posts/2000-06-05-getBufferSize.md new file mode 100644 index 0000000..b3f07c4 --- /dev/null +++ b/_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`. diff --git a/_posts/2000-06-05-setBufferSize.md b/_posts/2000-06-05-setBufferSize.md new file mode 100644 index 0000000..169e54f --- /dev/null +++ b/_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. diff --git a/_posts/2000-06-06-setKeepAlive.md b/_posts/2000-06-06-setKeepAlive.md new file mode 100644 index 0000000..6d444e6 --- /dev/null +++ b/_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`. \ No newline at end of file diff --git a/_posts/2000-06-07-setSocketTimeout.md b/_posts/2000-06-07-setSocketTimeout.md new file mode 100644 index 0000000..132acf5 --- /dev/null +++ b/_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`. \ No newline at end of file diff --git a/_posts/2000-10-01-configoptions.md b/_posts/2000-10-01-configoptions.md new file mode 100644 index 0000000..f20beef --- /dev/null +++ b/_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`. + +
    +
    MQTT_MAX_PACKET_SIZE
    +
    Sets the largest packet size, in bytes, the client will handle. Any + packet received that exceeds this size will be ignored. +

    This value can be overridden by calling setBufferSize(size).

    +

    Default: 128 bytes

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

    This value can be overridden by calling setKeepAlive(keepAlive).

    +

    Default: 15 seconds

    +
    +
    MQTT_VERSION
    +
    Sets the version of the MQTT protocol to use. +

    Default: MQTT 3.1.1

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

    Default: undefined (complete packet passed in each write call)

    +
    +
    MQTT_SOCKET_TIMEOUT
    +
    Sets the timeout when reading from the network. This also applies as + the timeout for calls to connect. +

    This value can be overridden by calling setSocketTimeout(timeout).

    +

    Default: 15 seconds

    +
    +
    \ No newline at end of file diff --git a/_posts/2000-10-02-callback.md b/_posts/2000-10-02-callback.md new file mode 100644 index 0000000..085d610 --- /dev/null +++ b/_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 + + - topic const char[] - the topic the message arrived on + - payload byte[] - the message payload + - length unsigned int - 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. diff --git a/api.html b/api.html deleted file mode 100644 index 7b5362f..0000000 --- a/api.html +++ /dev/null @@ -1,522 +0,0 @@ ---- -layout: default -title: API Documentation ---- - -
    -

    Constructors

    - -

    Functions

    - -

    Other

    - -
    - -
    -

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

    PubSubClient (client)

    -

    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
-}
    -
    Parameters
    -
      -
    • client : an instance of Client, typically EthernetClient.
      • -
    - -
    - -
    -

    PubSubClient (server, port, [callback], client, [stream])

    -

    Creates a fully configured client instance.

    -
    Parameters
    -
      -
    • server : the address of the server (IPAddress, uint8_t[] or const char[])
      • -
    • port : the port to connect to (int)
      • -
    • callback : optional a pointer to a message callback function called when a message arrives for a subscription created by this client.
      • -
    • client : an instance of Client, typically EthernetClient.
      • -
    • stream : optional an instance of Stream, used to store received messages. See the mqtt_stream example for more information.
      • -
    -
    - -
    -

    boolean connect (clientID)

    -

    Connects the client.

    -
    Parameters
    -
      -
    • clientID : the client ID to use when connecting to the server.
      • -
    -
    Returns
    -
      -
    • false - connection failed.
      • -
    • true - connection succeeded.
      • -
    -
    - -
    -

    boolean connect (clientID, willTopic, willQoS, willRetain, willMessage)

    -

    Connects the client with a Will message specified.

    -
    Parameters
    -
      -
    • clientID : the client ID to use when connecting to the server.
      • -
    • willTopic : the topic to be used by the will message (const char[])
      • -
    • willQoS : the quality of service to be used by the will message (int : 0,1 or 2)
      • -
    • willRetain : whether the will should be published with the retain flag (boolean)
      • -
    • willMessage : the payload of the will message (const char[])
      • -
    -
    Returns
    -
      -
    • false - connection failed.
      • -
    • true - connection succeeded.
      • -
    -
    - -
    -

    boolean connect (clientID, username, password)

    -

    Connects the client with a username and password specified.

    -
    Parameters
    -
      -
    • clientID : the client ID to use when connecting to the server.
      • -
    • username : the username to use. If NULL, no username or password is used (const char[])
      • -
    • password : the password to use. If NULL, no password is used (const char[])
      • -
    -
    Returns
    -
      -
    • false - connection failed.
      • -
    • true - connection succeeded.
      • -
    -
    - -
    -

    boolean connect (clientID, username, password, willTopic, willQoS, willRetain, willMessage)

    -

    Connects the client with a Will message, username and password specified.

    -
    Parameters
    -
      -
    • clientID : the client ID to use when connecting to the server.
      • -
    • username : the username to use. If NULL, no username or password is used (const char[])
      • -
    • password : the password to use. If NULL, no password is used (const char[])
      • -
    • willTopic : the topic to be used by the will message (const char[])
      • -
    • willQoS : the quality of service to be used by the will message (int : 0,1 or 2)
      • -
    • willRetain : whether the will should be published with the retain flag (int : 0 or 1)
      • -
    • willMessage : the payload of the will message (const char[])
      • -
    -
    Returns
    -
      -
    • false - connection failed.
      • -
    • true - connection succeeded.
      • -
    -
    - -
    -

    boolean connect (clientID, username, password, willTopic, willQoS, willRetain, willMessage, cleanSession)

    -

    Connects the client with a Will message, username, password and clean-session flag specified.

    -

    Note : even if the cleanSession is set to false/0 the client - will not retry failed qos 1 publishes. This flag is only of use to maintain subscriptions on the broker.

    -
    Parameters
    -
      -
    • clientID : the client ID to use when connecting to the server.
      • -
    • username : the username to use. If NULL, no username or password is used (const char[])
      • -
    • password : the password to use. If NULL, no password is used (const char[])
      • -
    • willTopic : the topic to be used by the will message (const char[])
      • -
    • willQoS : the quality of service to be used by the will message (int : 0,1 or 2)
      • -
    • willRetain : whether the will should be published with the retain flag (int : 0 or 1)
      • -
    • willMessage : the payload of the will message (const char[])
      • -
    • cleanSession : whether to connect clean-session or not (boolean)
      • -
    -
    Returns
    -
      -
    • false - connection failed.
      • -
    • true - connection succeeded.
      • -
    -
    - -
    -

    void disconnect ()

    -

    Disconnects the client.

    -
    - -
    -

    int publish (topic, payload)

    -

    Publishes a string message to the specified topic.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payload - the message to publish (const char[])
      • -
    -
    Returns
    -
      -
    • false - publish failed, either connection lost, or message too large
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    int publish (topic, payload, retained)

    -

    Publishes a string message to the specified topic.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payload - the message to publish (const char[])
      • -
    • retained - whether the message should be retained (boolean) -
        -
      • false - not retained
        • -
      • true - retained
        • -
      -
      • -
    -
    Returns
    -
      -
    • false - publish failed, either connection lost, or message too large
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    int publish (topic, payload, length)

    -

    Publishes a message to the specified topic.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payload - the message to publish (byte[])
      • -
    • length - the length of the message (byte)
      • -
    -
    Returns
    -
      -
    • false - publish failed, either connection lost, or message too large
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    int publish (topic, payload, length, retained)

    -

    Publishes a message to the specified topic, with the retained flag as specified.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payload - the message to publish (byte[])
      • -
    • length - the length of the message (byte)
      • -
    • retained - whether the message should be retained (boolean) -
        -
      • false - not retained
        • -
      • true - retained
        • -
      -
      • -
    -
    Returns
    -
      -
    • false - publish failed, either connection lost, or message too large
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    int publish_P (topic, payload, length, retained)

    -

    Publishes a message stored in PROGMEN to the specified topic, with the retained flag as specified.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payload - the message to publish (PROGMEM byte[])
      • -
    • length - the length of the message (byte)
      • -
    • retained - whether the message should be retained (boolean) -
        -
      • false - not retained
        • -
      • true - retained
        • -
      -
      • -
    -
    Returns
    -
      -
    • false - publish failed
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    boolean beginPublish (topic, payloadLength, retained)

    -

    Begins sending a publish message. The payload of the message is provided by one or more calls to write followed by a call to endPublish.

    -
    Parameters
    -
      -
    • topic - the topic to publish to (const char[])
      • -
    • payloadLength - the length of the message to publish
      • -
    • retained - whether the message should be retained (boolean) -
        -
      • false - not retained
        • -
      • true - retained
        • -
      -
      • -
    -
    Returns
    -
      -
    • false - publish failed
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    size_t write (uint8_t)

    -

    Writes a byte as a component of a publish started with a call to beginPublish.

    -
    Parameters
    -
      -
    • uint8_t - the byte to write
      • -
    -
    Returns
    -
      -
    • false - publish failed
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    size_t write (payload, length)

    -

    Writes an array of bytes as a component of a publish started with a call to beginPublish.

    -
    Parameters
    -
      -
    • payload - the bytes to write (byte[])
      • -
    • length - the length of the byte array (byte)
      • -
    -
    Returns
    -
      -
    • false - publish failed
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    boolean endPublish ()

    -

    Finishing sending a message that was started with a call to beginPublish.

    -
    Returns
    -
      -
    • false - publish failed
      • -
    • true - publish succeeded
      • -
    -
    - -
    -

    boolean subscribe (topic, [qos])

    -

    Subscribes to messages published to the specified topic.

    -
    Parameters
    -
      -
    • topic - the topic to subscribe to (const char[])
      • -
    • qos - optional the qos to subscribe at (int: 0 or 1 only) -
    -
    Returns
    -
      -
    • false - sending the subscribe failed, either connection lost, or message too large.
      • -
    • true - sending the subscribe succeeded. The request completes asynchronously.
      • -
    -
    - -
    -

    boolean unsubscribe (topic)

    -

    Unsubscribes from the specified topic.

    -
    Parameters
    -
      -
    • topic - the topic to unsubscribe from (const char[])
      • -
    -
    Returns
    -
      -
    • false - sending the unsubscribe failed, either connection lost, or message too large.
      • -
    • true - sending the unsubscribe succeeded. The request completes asynchronously.
      • -
    -
    - -
    -

    boolean loop ()

    -

    This should be called regularly to allow the client to process incoming messages and maintain its connection to the server.

    -
    Returns
    -
      -
    • false - the client is no longer connected
      • -
    • true - the client is still connected
      • -
    -
    - -
    -

    int connected ()

    -

    Checks whether the client is connected to the server.

    -
    Returns
    -
      -
    • false - the client is no longer connected
      • -
    • true - the client is still connected
      • -
    -
    - -
    -

    int state ()

    -

    Returns the current state of the client. If a connection attempt fails, - this can be used to get more information about the failure.

    -
    Returns
    -
      -
    • int - the client state, which can take the following values (constants defined in PubSubClient.h):
        -
      • -4 : MQTT_CONNECTION_TIMEOUT - the server didn't respond within the keepalive time
        • -
      • -3 : MQTT_CONNECTION_LOST - the network connection was broken
        • -
      • -2 : MQTT_CONNECT_FAILED - the network connection failed
        • -
      • -1 : MQTT_DISCONNECTED - the client is disconnected cleanly
        • -
      • 0 : MQTT_CONNECTED - the client is connected
        • -
      • 1 : MQTT_CONNECT_BAD_PROTOCOL - the server doesn't support the requested version of MQTT
        • -
      • 2 : MQTT_CONNECT_BAD_CLIENT_ID - the server rejected the client identifier
        • -
      • 3 : MQTT_CONNECT_UNAVAILABLE - the server was unable to accept the connection
        • -
      • 4 : MQTT_CONNECT_BAD_CREDENTIALS - the username/password were rejected
        • -
      • 5 : MQTT_CONNECT_UNAUTHORIZED - the client was not authorized to connect
        • -
      • -
    -
    - -
    -

    PubSubClient setServer (server, port)

    -

    Sets the server details.

    -
    Parameters
    -
      -
    • server : the address of the server (IPAddress, uint8_t[] or const char[])
      • -
    • port : the port to connect to (int)
      • -
    -
    Returns
    -
      -
    • PubSubClient - the client instance, allowing the function to be chained
      • -
    -
    - -
    -

    PubSubClient setCallback (callback)

    -

    Sets the message callback function.

    -
    Parameters
    -
      -
    • callback : a pointer to a message callback function called when a message arrives for a subscription created by this client.
      • -
    -
    Returns
    -
      -
    • PubSubClient - the client instance, allowing the function to be chained
      • -
    -
    - -
    -

    PubSubClient setClient (client)

    -

    Sets the client.

    -
    Parameters
    -
      -
    • client : an instance of Client, typically EthernetClient.
      • -
    -
    Returns
    -
      -
    • PubSubClient - the client instance, allowing the function to be chained
      • -
    -
    - -
    -

    PubSubClient setStream (stream)

    -

    Sets the stream.

    -
    Parameters
    -
      -
    • stream : an instance of Stream, used to store received messages. See the mqtt_stream example for more information.
      • -
    -
    Returns
    -
      -
    • PubSubClient - the client instance, allowing the function to be chained
      • -
    -
    - -
    -

    Configuration Options

    -

    The following configuration options can be used to configure the library. - They are contained in PubSubClient.h.

    -
    -
    MQTT_MAX_PACKET_SIZE
    -
    Sets the largest packet size, in bytes, the client will handle. Any - packet received that exceeds this size will be ignored.

    -

    Default: 128 bytes

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

    -

    Default: 15 seconds

    -
    -
    MQTT_VERSION
    -
    Sets the version of the MQTT protocol to use.

    -

    Default: MQTT 3.1.1

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

    -

    Default: undefined (complete packet passed in each write call)

    -
    -
    MQTT_SOCKET_TIMEOUT
    -
    Sets the timeout when reading from the network. This also applies as - the timeout for calls to connect. -

    Default: 15 seconds

    -
    -
    -
    - -
    -

    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
    -
      -
    • topic - the topic the message arrived on (const char[])
      • -
    • payload - the message payload (byte array)
      • -
    • length - the length of the message payload (unsigned int)
      • -
    -

    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 beyond this. -

    -
    diff --git a/api.md b/api.md new file mode 100644 index 0000000..fc574e9 --- /dev/null +++ b/api.md @@ -0,0 +1,53 @@ +--- +layout: default +title: API Documentation +--- + +### Library version: 2.8 + +{% assign sorted = site.posts | reverse %} +{% assign currentType = "" %} +{% for post in sorted %} + {% if post.tags contains 'api' or post.tags contains 'docs' %} + {% unless post.type == currentType%} + {%if currentType != "" %}{%endif%} +

    {{post.type | capitalize}}

    + {% assign currentType = post.type %} + + +--- + +{% for post in sorted %} + {% if post.tags contains 'api' or post.tags contains 'docs'%} + +
    +{% if post.tags contains 'api' %} +

    {% if post.returns %}{{ post.returns.type }} {% endif %}{{ post.name }} ({% include paramsList.html params=post.params %})

    + {{ post.content }} + {% if post.params %} +
    Parameters
    +
      + {% include paramsListLong.html params=post.params %} +
    + {% endif %} + {% if post.returns and post.returns.values %} +
    Returns
    +
      + {% for return in post.returns.values %}
    • {% if return.value %}{{ return.value }} - {%endif%}{{ return.description}}
      • {% endfor %} +
    + {% endif %} +{% else %} +

    {{post.title}}

    + {{post.content}} +{% endif %} +
    + + {% endif %} +{% endfor %} diff --git a/index.html b/index.html deleted file mode 100644 index 1d4e601..0000000 --- a/index.html +++ /dev/null @@ -1,67 +0,0 @@ ---- -layout: default -title: Arduino Client for MQTT ---- -

    This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT

    -

    For more information about MQTT, visit mqtt.org.

    - -
    -

    Download

    -

    The latest version of the library can be downloaded from GitHub.

    -
    -
    -

    Documentation

    -

    The library comes with a number of example sketches. See File > Examples > PubSubClient within the Arduino application.

    -

    Full API Documentation

    -
    -
    -

    Compatible Hardware

    -

    - The library uses the Arduino Ethernet Client api for interacting with the - underlying network hardware. This means it Just Works with a growing number of - boards and shields, including: -

    -
      -
    • Arduino Ethernet
      • -
    • Arduino Ethernet Shield
      • -
    • Arduino YUN – use the included YunClient in place of EthernetClient, and - be sure to do a Bridge.begin() first
      • -
    • Arduino WiFi Shield - if you want to send packets greater than 90 bytes with this shield, - enable the MQTT_MAX_TRANSFER_SIZE option in PubSubClient.h.
      • -
    • Sparkfun WiFly Shield – when used with this library
      • -
    • Intel Galileo/Edison
      • -
    • ESP8266
      • -
    • ESP32
      • -
    -

    - The library cannot currently be used with hardware based on the ENC28J60 chip – - such as the Nanode or the Nuelectronics Ethernet Shield. For those, there is an - alternative library available. -

    -
    - -
    -

    Author

    -

    Nick O'Leary - @knolleary

    -
    -
    -

    License

    -

    This library is released under the MIT License.

    -
    -
    -

    Change History

    -

    The complete change history is available on GitHub.

    -
    -
    2.7
    -
    -
      -
    • Fix remaining-length handling to prevent buffer overrun
      • -
    • Add large-payload API - beginPublish/write/publish/endPublish
      • -
    • Add yield call to improve reliability on ESP
      • -
    • Add Clean Session flag to connect options
      • -
    • Add ESP32 support for functional callback signature
      • -
    • Various other fixes
      • -
    -
    -
    -
    diff --git a/index.md b/index.md new file mode 100644 index 0000000..0d6eb7d --- /dev/null +++ b/index.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Arduino Client for MQTT +--- + +This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT + +For more information about MQTT, visit [MQTT.org](http://mqtt.org). + +## Download + +The latest version of the library can be downloaded from [GitHub](https://github.com/knolleary/pubsubclient/releases/latest). + +## Documentation + +The library comes with a number of example sketches. See `File > Examples > PubSubClient` within the Arduino application. + +Full [API Documentation](/api) is available. + +## Author + + - Nick O'Leary - [@knolleary](https://twitter.com/knolleary) + +## License + +This library is released under the [MIT License](http://www.opensource.org/licenses/mit-license.php). + + +## Change History + + The complete change history is available on [GitHub](https://github.com/knolleary/pubsubclient/commits/master). + +#### Latest version: 2.8 - released 2020-05-20 + + - Add `setBufferSize()` to override `MQTT_MAX_PACKET_SIZE` + - Add `setKeepAlive()` to override `MQTT_KEEPALIVE` + - Add `setSocketTimeout()` to overide `MQTT_SOCKET_TIMEOUT` + - Added check to prevent subscribe/unsubscribe to empty topics + - Declare wifi mode prior to connect in ESP example + - Use `strnlen` to avoid overruns + - Support pre-connected Client objects diff --git a/style.css b/style.css index df3fa01..0f0c294 100644 --- a/style.css +++ b/style.css @@ -64,6 +64,9 @@ section { .methodname { font-weight: bold;color: #333;} .methodreturn { font-weight: normal; color: #777;} .methodparams { font-weight: normal; color: #777;} +.methodparamstype { font-size: 13px; font-family: monospace; color: #979;} +.methodreturnvalue { font-family: monospace; color: #979; } +.methodparamoptional { font-size: 13px; font-style: italic; color: #777} ul a { text-decoration: none; }