[211] | 1 | #PubNub Arduino Library
|
---|
| 2 |
|
---|
| 3 | This library allows your sketches to communicate with the PubNub cloud
|
---|
| 4 | message passing system using an Ethernet shield. Your application can
|
---|
| 5 | receive and send messages.
|
---|
| 6 |
|
---|
| 7 | ##Copy-and-Paste-Ready Code!
|
---|
| 8 | See how easy it is to [Publish](examples/PubNubPublisher) and [Subscribe](examples/PubNubSubscriber)!
|
---|
| 9 |
|
---|
| 10 | ###Synopsis
|
---|
| 11 |
|
---|
| 12 |
|
---|
| 13 | void setup() {
|
---|
| 14 | Serial.begin(9600);
|
---|
| 15 | Ethernet.begin(mac);
|
---|
| 16 | PubNub.begin(pubkey, subkey);
|
---|
| 17 | }
|
---|
| 18 |
|
---|
| 19 | void loop() {
|
---|
| 20 | /* Maintain DHCP lease. */
|
---|
| 21 | Ethernet.maintain();
|
---|
| 22 |
|
---|
| 23 | /* Publish message. */
|
---|
| 24 | EthernetClient *pclient = PubNub.publish(pubchannel, "\"message\"");
|
---|
| 25 | if (pclient)
|
---|
| 26 | pclient->stop();
|
---|
| 27 |
|
---|
| 28 | /* Wait for news. */
|
---|
| 29 | PubSubClient *sclient = PubNub.subscribe(subchannel);
|
---|
| 30 | if (!sclient) return; // error
|
---|
| 31 | char buffer[64]; size_t buflen = 0;
|
---|
| 32 | while (sclient->wait_for_data()) {
|
---|
| 33 | buffer[buflen++] = sclient->read();
|
---|
| 34 | }
|
---|
| 35 | buffer[buflen] = 0;
|
---|
| 36 | sclient->stop();
|
---|
| 37 |
|
---|
| 38 | /* Print received message. You will want to look at it from
|
---|
| 39 | * your code instead. */
|
---|
| 40 | Serial.println(buffer);
|
---|
| 41 | delay(10000);
|
---|
| 42 | }
|
---|
| 43 |
|
---|
| 44 | ##Library Reference
|
---|
| 45 |
|
---|
| 46 | ``bool PubNub.begin(char *publish_key, char *subscribe_key, char *origin)``
|
---|
| 47 |
|
---|
| 48 | To start using PubNub, use PubNub.begin(). This should be called after
|
---|
| 49 | Ethernet.begin().
|
---|
| 50 |
|
---|
| 51 | Note that the string parameters are not copied; do not overwrite or free the
|
---|
| 52 | memory where you stored the keys! (If you are passing string literals, don't
|
---|
| 53 | worry about it.) Note that you should run only one of publish, subscribe and
|
---|
| 54 | history requests each at once.
|
---|
| 55 |
|
---|
| 56 | The origin parameter is optional, defaulting to "pubsub.pubnub.com".
|
---|
| 57 |
|
---|
| 58 | ``EthernetClient *publish(char *channel, char *message, int timeout)``
|
---|
| 59 |
|
---|
| 60 | Send a message (assumed to be well-formed JSON) to a given channel.
|
---|
| 61 |
|
---|
| 62 | Returns NULL in case of error, instead an instance of EthernetClient
|
---|
| 63 | that you can use to read the reply to the publish command. If you
|
---|
| 64 | don't care about it, call ``client->stop()`` right away.
|
---|
| 65 |
|
---|
| 66 | The timeout parameter is optional, defaulting to 305. See also
|
---|
| 67 | a note about timeouts below.
|
---|
| 68 |
|
---|
| 69 | ``PubSubClient *subscribe(char *channel)``
|
---|
| 70 |
|
---|
| 71 | Listen for a message on a given channel. The function will block
|
---|
| 72 | and return when a message arrives. NULL is returned in case of error.
|
---|
| 73 | The return type is PubSubClient, but from user perspective, you can
|
---|
| 74 | work with it exactly like with EthernetClient; it also provides
|
---|
| 75 | an extra convenience method ``wait_for_data()`` that allows you
|
---|
| 76 | to wait for more data with sensible timeout.
|
---|
| 77 |
|
---|
| 78 | Typically, you will run this function from loop() function to keep
|
---|
| 79 | listening for messages indefinitely.
|
---|
| 80 |
|
---|
| 81 | As a reply, you will get a JSON array with messages, e.g.:
|
---|
| 82 |
|
---|
| 83 | ```
|
---|
| 84 | ["msg1",{msg2:"x"}]
|
---|
| 85 | ```
|
---|
| 86 |
|
---|
| 87 | and so on. Empty reply [] is also normal and your code must be
|
---|
| 88 | able to handle that. Note that the reply specifically does not
|
---|
| 89 | include the time token present in the raw reply from PubNub;
|
---|
| 90 | no need to worry about that.
|
---|
| 91 |
|
---|
| 92 | The timeout parameter is optional, defaulting to 305. See also
|
---|
| 93 | a note about timeouts below.
|
---|
| 94 |
|
---|
| 95 | ``EthernetClient *history(char *channel, int limit, int timeout)``
|
---|
| 96 |
|
---|
| 97 | Receive list of the last messages published on the given channel.
|
---|
| 98 | The limit argument is optional and defaults to 10.
|
---|
| 99 |
|
---|
| 100 | The timeout parameter is optional, defaulting to 305. See also
|
---|
| 101 | a note about timeouts below.
|
---|
| 102 |
|
---|
| 103 | ##Installation
|
---|
| 104 |
|
---|
| 105 | Move the contents of the ``pubnub/arduino/`` directory to
|
---|
| 106 | ``~/sketchbook/libraries/PubNub/`` and restart your Arduino IDE.
|
---|
| 107 | Try out the examples!
|
---|
| 108 |
|
---|
| 109 | ##Supported Hardware
|
---|
| 110 |
|
---|
| 111 | The Arduino ecosystem features a multitude of platforms that
|
---|
| 112 | have significant differences regarding their hardware capabilities;
|
---|
| 113 | here, we list the status of PubNub support for various platforms:
|
---|
| 114 |
|
---|
| 115 | * ATMega168-based generic boards (Duemilanove, Diecimila...):
|
---|
| 116 | Not supported due to too small RAM and flash memory size.
|
---|
| 117 | * ATMega328-based generic boards (Duemilanove, Uno), Arduino
|
---|
| 118 | Ethernet: Supported. The space for user code may be somewhat limited.
|
---|
| 119 | When using the aJson library, some memory saving tricks are required,
|
---|
| 120 | see the top of the PubNubJson example.
|
---|
| 121 |
|
---|
| 122 | * Arduino Mega (ATMega2560): Supported.
|
---|
| 123 | * Arduino Mega (ATMega1280): Untested, but should work just fine.
|
---|
| 124 |
|
---|
| 125 | Except Arduino Ethernet, network connectivity is provided by
|
---|
| 126 | an external board ("shield"):
|
---|
| 127 |
|
---|
| 128 | * Arduino Ethernet Shield: Supported. We tested only a shield that
|
---|
| 129 | is based on the WizNet W5100 chip - but this should be the case for
|
---|
| 130 | all but some ancient non-official ethernet shields.
|
---|
| 131 | * Arduino WiFi Shield: Supported, but new enough firmware and software
|
---|
| 132 | is required. The support must be enabled in the PubNub library.
|
---|
| 133 | Please see the "WiFi Shield Support" section for details.
|
---|
| 134 |
|
---|
| 135 | ##WiFi Shield Support
|
---|
| 136 |
|
---|
| 137 | The PubNub library supports the WiFi shield as well. In order
|
---|
| 138 | to use the library with a WiFi-enabled Arduino, you will need
|
---|
| 139 | to edit the file PubNub.h, commenting out the line
|
---|
| 140 |
|
---|
| 141 | //#define PubNub_Ethernet
|
---|
| 142 |
|
---|
| 143 | and uncommenting
|
---|
| 144 |
|
---|
| 145 | #define PubNub_WiFi
|
---|
| 146 |
|
---|
| 147 | It is essential to use a new enough Arduino version so that
|
---|
| 148 | the WiFi library actually works properly. Most notably, version 1.0.5
|
---|
| 149 | has been confirmed to work while Arduino 1.0.4 is broken!
|
---|
| 150 |
|
---|
| 151 | The WiFi shield carries its own microcontroller dedicated to the network
|
---|
| 152 | communication and this microcontroller has upgradeable firmware.
|
---|
| 153 | If some of the PubNub calls fail with your WiFi shield (e.g. you
|
---|
| 154 | see "subscribe error" and similar messages in serial console),
|
---|
| 155 | the firmware loaded on your WiFi shield may be buggy - e.g. a WiFi
|
---|
| 156 | shield bought commercially in May 2013 came preloaded with firmware
|
---|
| 157 | that had to be upgraded. This is not so difficult to do, simply follow:
|
---|
| 158 |
|
---|
| 159 | http://arduino.cc/en/Hacking/WiFiShieldFirmwareUpgrading
|
---|
| 160 |
|
---|
| 161 |
|
---|
| 162 | ## WiFi Shield Support for "WiFi Shield 101"
|
---|
| 163 |
|
---|
| 164 | If you are using [Arduino WiFi Shield 101](https://www.arduino.cc/en/Main/ArduinoWiFiShield101), use WiFi101 library, instead of the WiFi library.
|
---|
| 165 |
|
---|
| 166 | Download a zip from Download a [zipped WiFi101 library](https://github.com/arduino-libraries/WiFi101/releases)
|
---|
| 167 | and import the lib.
|
---|
| 168 |
|
---|
| 169 | To enable it in PubNub Library, edit `PubNub.h`:
|
---|
| 170 |
|
---|
| 171 | Comment out line 12:
|
---|
| 172 |
|
---|
| 173 | //#define PubNub_Ethernet
|
---|
| 174 |
|
---|
| 175 | and uncomment line 13:
|
---|
| 176 |
|
---|
| 177 | #define PubNub_WiFi
|
---|
| 178 |
|
---|
| 179 | then at line 21, where it says `#include <WiFi.h>`, replace it with:
|
---|
| 180 |
|
---|
| 181 | #include <WiFi101.h>
|
---|
| 182 |
|
---|
| 183 | Now the `#define PubNub_WiFi` block should look like:
|
---|
| 184 |
|
---|
| 185 | ```c
|
---|
| 186 | #define PubNub_WiFi
|
---|
| 187 |
|
---|
| 188 | #if defined(PubNub_Ethernet)
|
---|
| 189 | #include <Ethernet.h>
|
---|
| 190 | #define PubNub_BASE_CLIENT EthernetClient
|
---|
| 191 |
|
---|
| 192 | #elif defined(PubNub_WiFi)
|
---|
| 193 | #include <WiFi101.h>
|
---|
| 194 | #define PubNub_BASE_CLIENT WiFiClient
|
---|
| 195 |
|
---|
| 196 | #else
|
---|
| 197 | #error PubNub_BASE_CLIENT set to an invalid value!
|
---|
| 198 | #endif
|
---|
| 199 | ```
|
---|
| 200 |
|
---|
| 201 | ##Notes
|
---|
| 202 |
|
---|
| 203 | * There is no SSL support on Arduino, it is unfeasible with
|
---|
| 204 | Arduino Uno or even Arduino Mega's computing power and memory limits.
|
---|
| 205 | All the traffic goes on the wire unencrypted and unsigned.
|
---|
| 206 |
|
---|
| 207 | * We re-resolve the origin server IP address before each request.
|
---|
| 208 | This means some slow-down for intensive communication, but we rather
|
---|
| 209 | expect light traffic and very long-running sketches (days, months),
|
---|
| 210 | where refreshing the IP address is quite desirable.
|
---|
| 211 |
|
---|
| 212 | * We let the users read replies at their leisure instead of
|
---|
| 213 | returning an already preloaded string so that (a) they can do that
|
---|
| 214 | in loop() code while taking care of other things as well (b) we don't
|
---|
| 215 | waste precious RAM by pre-allocating buffers that are never needed.
|
---|
| 216 |
|
---|
| 217 | * If you are having problems connecting, maybe you have hit
|
---|
| 218 | a bug in Debian's version of Arduino pertaining the DNS code. Try using
|
---|
| 219 | an IP address as origin and/or upgrading your Arduino package.
|
---|
| 220 |
|
---|
| 221 | * The optional timeout parameter allows you to specify a timeout
|
---|
| 222 | period after which the subscribe call shall be retried. Note
|
---|
| 223 | that this timeout is applied only for reading response, not for
|
---|
| 224 | connecting or sending data; use retransmission parameters of
|
---|
| 225 | the Ethernet library to tune this. As a rule of thumb, timeout
|
---|
| 226 | smaller than 30 seconds may still block longer with flaky
|
---|
| 227 | network. Default server-side timeout of PubNub API is 300s.
|
---|
| 228 |
|
---|
| 229 | * The vendor firmware for the WiFi shield has dubious TCP implementation;
|
---|
| 230 | for example, TCP ports of outgoing connections are always chosen from the
|
---|
| 231 | same sequence, so if you reset your Arduino, some of the new connections
|
---|
| 232 | may interfere with an outstanding TCP connection that has not been closed
|
---|
| 233 | before the reset; i.e. you will typically see a single failed request
|
---|
| 234 | somewhere down the road after a reset.
|
---|