1 #Xively Arduino library
3 A library for Arduino to make it easier to talk to Xively.
5 _This library requires [_HTTP Client_](https://github.com/amcewen/HttpClient)._
9 1. Generic functions for:
10 - Uploading datapoints
11 - Downloading datapoints
13 - Arduino Ethernet shield
14 - Arduino Ethernet board
18 ##For a Quickstart Example
19 Look no further! If you want a quick example, connect your Arduino board to your computer and an ethernet cable and try out one of the examples included with this library.
21 >In Arduino, go to Files > Examples and choose DatastreamUpload or DatastreamDownload from the xively-arduino library folder
25 **1. Specify your API key and Feed ID**
27 char xivelyKey[] = "YOUR_XIVELY_API_KEY";
28 // Should be something like "HsNiCoe_Es2YYWltKeRFPZL2xhqSAKxIV21aV3lTL2h5OD0g"
29 #define FEED_ID XXXXXX
30 // The 3 to 6-digit number (like 504 or 104097), that identifies the Xively Feed you're using
33 **2. Create IDs for your datastreams as `char` arrays (or `String` objects for a `String` datastream)**
35 In Xively, the name of a datastream is known as the **Stream ID**. In the example below, we'll give the datastreams names by setting their **Stream IDs** as "humidity", "temperature", "my_thoughts_on_the_temperature" and "more_thoughts".
38 // For datastreams of floats:
39 char myFloatStream[] = "humidity";
40 // For datastreams of ints:
41 char myIntStream[] = "temperature";
42 // For datastreams of Strings:
43 String myStringStream("my_thoughts_on_the_temperature");
44 // For datastreams of char buffers:
45 char myCharBufferStream[] = "more_thoughts"; // ID of the array
46 const int bufferSize = 140; // size of the array
47 char bufferValue[bufferSize]; // the array of chars itself
50 `String` datastreams and `char` buffer datastreams are similar: both will be able to send strings to Xively datastreams. For beginners, using `String` datastreams will be fine much of the time.
52 Using char buffers reduces the memory footprint of your sketch by not requiring the String library. Also, using char buffers allows you to specify exactly how much memory is used for a datapoint, so you don't accidentally overflow the Arduino's mem capacity with a huge string datapoint. It's a little bit harder to understand for beginners -- consult XivelyDatastream.cpp for info.
54 **3. Create an array of `XivelyDatastream` objects**
57 XivelyDatastream datastreams[] = {
58 // Float datastreams are set up like this:
59 XivelyDatastream(myFloatStream, strlen(myFloatStream), DATASTREAM_FLOAT),
60 // Int datastreams are set up like this:
61 XivelyDatastream(myIntStream, strlen(myIntStream), DATASTREAM_INT),
62 // String datastreams are set up like this:
63 XivelyDatastream(myStringStream, DATASTREAM_STRING),
64 // Char buffer datastreams are set up like this:
65 XivelyDatastream(myCharBufferStream, strlen(myCharBufferStream), DATASTREAM_BUFFER, bufferValue, bufferSize),
69 `XivelyDatastream` objects can contains some or all of the following variables, depending on what type of datapoints are in the datastream (see above example for which are required):
71 | | Variable | Type | Description |
73 | 1 | aIdBuffer | char*|`char` array containing the ID of the datastream
74 | 2 | aIdBufferLength | int |for `int` or `float` datastreams only: the number of `char` in the datastream's ID
75 | 3 | aType | int |**0** or DATASTREAM_STRING for a String; **1** or DATASTREAM_BUFFER for a char buffer; **2** or DATASTREAM_INT for an int; **3** or DATASTREAM_FLOAT for a float
76 | 4 | aValueBuffer | char* | A `char` array, _aValueBufferLength_ elements long
77 | 5 | aValueBufferLength | int | The number of elements in the `char` array
80 **4. Last, wrap this array of `XivelyDatastream` objects into a `XivelyFeed`**
82 Unlike the **Stream ID**, which is what a _Datastream's_ name is stored as, the **ID** of a _Feed_ is a number which is used to uniquely identify which Xively Feed you are addressing. For example, a Feed **ID** of 504 would mean that you were using the feed at xively.com/feeds/504.
85 XivelyFeed feed(FEED_ID, datastreams, 4);
88 | | Variable | Type | Description |
90 | 1 | aID | unsigned long | The Feed's **ID**, as defined at the top of your sketch
91 | 2 | aDatastreams | XivelyDatastream* |Your `XivelyDatastream` array
92 | 3 | aDatastreamsCount | int | How many datastreams are in the array
94 **5. Instantiate the library's Xively client**
96 Connecting by ethernet:
98 >If you're using the Ethernet library:
100 EthernetClient client;
101 XivelyClient xivelyclient(client);
105 If you're on wireless, be sure to enter your SSID and password as the library requires, and then:
106 >If you're using the built-in WiFi library:
109 XivelyClient xivelyclient(client);
113 >If you're using the [Sparkfun WiFly] [1] library:
116 XivelyClient xivelyclient(client);
118 [1]: https://github.com/jmr13031/WiFly-Shield
120 ##Sending and Retrieving Xively Datapoints
124 Serial.print("My return is: ");
126 float float_value = datastreams[0].getFloat(); // Retrieve the latest datapoint in a float datastream
127 int int_value = datastreams[1].getInt(); // Retrieve the latest datapoint in an int datastream
128 String string_value = datastreams[2].getString(); // Retrieve the latest datapoint in a String datastream
129 char[140] char_buffer = datastreams[3].getBuffer(); // Retrieve the latest datapoint in a char buffer datastream
132 ###Update a Datapoint
134 The library makes it easy to upload data as strings or numbers.
136 datastreams[0].setFloat(1.5); // Push a float datapoint
137 datastreams[1].setInt(23); // Push an int datapoint
138 datastreams[2].setString("Pretty comfy temperature"); // Push a String datapoint
139 datastreams[3].setBuffer("But quite dry"); // Push a char buffer datapoint