From cc0e2ae5cd867302f7cc783729f9e9d9a88d0438 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 28 Aug 2015 16:32:45 +0100 Subject: [PATCH] Update docs --- _layouts/default.html | 74 ++---- api.html | 575 +++++++++++++++++++++++++----------------- index.html | 55 +++- style.css | 77 +++++- tutorial.html | 6 - 5 files changed, 479 insertions(+), 308 deletions(-) delete mode 100644 tutorial.html diff --git a/_layouts/default.html b/_layouts/default.html index af49912..52670ca 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -1,61 +1,25 @@ - - Arduino Client for MQTT « knolleary - - - - - - - - - - - - + + Arduino Client for MQTT + + + + + - - -
- -
-
-
{{ page.title }}
- -
{{ content }} -
-
-
-
- - -
- - - - - - - +
+ +

{{ page.title }}

+
+ {{ content }} +
+
+ diff --git a/api.html b/api.html index 5e41377..4c319ba 100644 --- a/api.html +++ b/api.html @@ -1,278 +1,401 @@ --- layout: default -title: API Docs +title: API Documentation --- -

These docs refer to the latest version of the library on GitHub

-
Constructors
- -
Functions
- -
Other
- +

Constructors

+ +

Functions

+ +

Other

+
-

PubSubClient (server, port, callback, client)

-

Creates a client instance, with the server specified by IP address.

-
Parameters
- +

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 (serverDNS, port, callback, client)

-

Creates a client instance, with the server specified by DNS name.

-
Parameters
- +

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

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

+

Creates a fully configured client instance.

+
Parameters
+
-

boolean connect (clientID)

-

Connects the client.

-
Parameters
- -
Returns
- +

boolean connect (clientID)

+

Connects the client.

+
Parameters
+ +
Returns
+
-

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

-

Connects the client with a Will message specified.

-
Parameters
- -
Returns
- +

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

+

Connects the client with a Will message specified.

+
Parameters
+ +
Returns
+
-

boolean connect (clientID, username, password)

-

Connects the client with a username and password specified.

-
Parameters
- -
Returns
- +

boolean connect (clientID, username, password)

+

Connects the client with a username and password specified.

+
Parameters
+ +
Returns
+
-

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

-

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

-
Parameters
- -
Returns
- +

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

+

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

+
Parameters
+ +
Returns
+
-

void disconnect ()

-

Disconnects the client.

+

void disconnect ()

+

Disconnects the client.

-

int publish (topic, payload)

-

Publishes a string message to the specified topic.

-
Parameters
- -
Returns
- +

int publish (topic, payload)

+

Publishes a string message to the specified topic.

+
Parameters
+ +
Returns
+
-

int publish (topic, payload, length)

-

Publishes a message to the specified topic.

-
Parameters
- -
Returns
- +

int publish (topic, payload, length)

+

Publishes a message to the specified topic.

+
Parameters
+ +
Returns
+
-

int publish (topic, payload, length, retained)

-

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

-
Parameters
- -
Returns
- +

int publish (topic, payload, length, retained)

+

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

+
Parameters
+ +
Returns
+
-

int publish_P (topic, payload, length, retained)

-

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

-
Parameters
- -
Returns
- +

int publish_P (topic, payload, length, retained)

+

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

+
Parameters
+ +
Returns
+
-

boolean subscribe (topic)

-

Subscribes to messages published to the specified topic.

-
Parameters
- -
Returns
- +

boolean subscribe (topic, [qos])

+

Subscribes to messages published to the specified topic.

+
Parameters
+ +
Returns
+ +
+ +
+

boolean unsubscribe (topic)

+

Unsubscribes from the specified topic.

+
Parameters
+ +
Returns
+
-

boolean loop ()

-

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

-
Returns
- +

boolean loop ()

+

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

+
Returns
+
-

int connected ()

-

Checks whether the client is connected to the server.

-
Returns
- +

int connected ()

+

Checks whether the client is connected to the server.

+
Returns
+ +
+ +
+

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

PubSubClient setServer (server, port)

+

Sets the server details.

+
Parameters
+ +
Returns
+ +
+ +
+

PubSubClient setCallback (callback)

+

Sets the message callback function.

+
Parameters
+ +
Returns
+ +
+ +
+

PubSubClient setClient (client)

+

Sets the client.

+
Parameters
+ +
Returns
+ +
+ +
+

PubSubClient setStream (stream)

+

Sets the stream.

+
Parameters
+ +
Returns
+
-

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 -

-
+

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. This defaults to interval, in seconds, the client will use. This is used to maintain the connection when no other packets are being
+ sent or received.

+

Default: MQTT 3.1.1

+
+
- -
-

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(char* topic, byte* payload, unsigned int length)
-
-
Parameters
- -

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.

-
- +
+

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

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/index.html b/index.html index 5bd8152..f488de0 100644 --- a/index.html +++ b/index.html @@ -2,26 +2,64 @@ layout: default title: Arduino Client for MQTT --- -

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

+

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

+

Download

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

-

Documentation

+

Documentation

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

Full API Documentation

-
-

License

-

This library is released under the MIT License.

-
+
+

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: +

+ +

+ 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

+

Change History

The complete change history is available on GitHub.

+
2.0
+
+
    +
  • Add (and default to) MQTT 3.1.1 support
    • +
  • Fix PROGMEM handling for Intel Galileo/ESP8266
    • +
  • Add overloaded constructors for convenience
    • +
  • Add chainable setters for server/callback/client/stream
    • +
  • Add state function to return connack return code
    • +
+
1.9
    @@ -100,4 +138,3 @@ title: Arduino Client for MQTT
- diff --git a/style.css b/style.css index 3f8817d..df3fa01 100644 --- a/style.css +++ b/style.css @@ -1,20 +1,74 @@ +body { + font-family: 'Arial', sans-serif; + font-size: 16px; +} +h1,h2,h3,h4,h5 { + font-family: 'Questrial', serif; +} +h1 { + font-size: 1.953em; +} +h2 { + font-size: 1.563em; +} +h3 { + font-size: 1.25em; +} +h4 { + font-size: 1.15em; +} +pre, code { + font-family: 'Cutive Mono',monospace; +} +pre { + border: 1px solid #aaa; + padding: 10px; + margin: auto 10px; + overflow-x: auto; +} +a, a:visited{ + color: #4178BE; +} +#content { + max-width: 900px; + padding: 10px; + margin: auto; +} + section { padding-top:40px; margin-top: -40px; } - -.method { - border-bottom: 3px solid #eee; + +#header ul { + list-style-type: none; + padding: 0; + margin: 10px 0; +} +#header li { + display: inline-block; + padding: 0 10px; + margin: 0; +} +#header li:not(:first-child) { + border-left: 1px solid #999; +} +#header li:first-child { + padding-left: 0; +} +.method { + border-bottom: 2px solid #eee; margin-bottom: 20px; padding-bottom: 15px; } -.methodname {} +.methodname { font-weight: bold;color: #333;} .methodreturn { font-weight: normal; color: #777;} .methodparams { font-weight: normal; color: #777;} - -li.active { - font-weight: bold; - text-decoration: underline !important; +ul a { + text-decoration: none; +} +ul a:hover { + text-decoration: underline; } #ChangeHistory * dd { margin-left: 25px;} @@ -22,14 +76,13 @@ li.active { #toc a { color: #333; } - -h4 { font-size: 1.3em; } h5 { - margin: 0px; + margin: 15px 0px 5px 0; padding: 0px; - font-size: 1.0em; + font-size: 1.1em; } #content ul { margin: 0px; + line-height: 1.4em; } diff --git a/tutorial.html b/tutorial.html deleted file mode 100644 index 5c35c0e..0000000 --- a/tutorial.html +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: default -title: Tutorial ---- -

The little book of MQTT on Arduino

-

More to come...