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