git.piffa.net Git - arduino/blob - books/pdummies/Libraries/xively/README.md

   1 #Xively Arduino library
   2
   3 A library for Arduino to make it easier to talk to Xively.
   4
   5 _This library requires [_HTTP Client_](https://github.com/amcewen/HttpClient)._
   6
   7 ##Features
   8
   9    1. Generic functions for:
  10         - Uploading datapoints
  11         - Downloading datapoints
  12    2. Compatible with:
  13       - Arduino Ethernet shield
  14       - Arduino Ethernet board
  15       - Arduino Wifi shield
  16       - WiFly shield
  17
  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.
  20
  21 >In Arduino, go to Files > Examples and choose DatastreamUpload or DatastreamDownload from the xively-arduino library folder
  22
  23 ##Setup Your Sketch
  24
  25 **1. Specify your API key and Feed ID**
  26 ```c
  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
  31 ```
  32
  33 **2. Create IDs for your datastreams as `char` arrays (or `String` objects for a `String` datastream)**
  34
  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".
  36
  37 ```c
  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
  48 ```
  49
  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.
  51
  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.
  53
  54 **3. Create an array of `XivelyDatastream` objects**
  55
  56 ```c
  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),
  66 };
  67 ```
  68
  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):
  70
  71 | | Variable | Type | Description |
  72 |---|---|:---:|---|
  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
  78
  79
  80 **4. Last, wrap this array of `XivelyDatastream` objects into a `XivelyFeed`**
  81
  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.
  83
  84 ```c
  85 XivelyFeed feed(FEED_ID, datastreams, 4);
  86 ```
  87
  88 | | Variable | Type | Description |
  89 |---|---|:---:|---|
  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
  93
  94 **5. Instantiate the library's Xively client**
  95
  96 Connecting by ethernet:
  97
  98 >If you're using the Ethernet library:
  99 ```c
 100 EthernetClient client;
 101 XivelyClient xivelyclient(client);
 102 ```
 103
 104
 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:
 107 ```c
 108 WiFiClient client;
 109 XivelyClient xivelyclient(client);
 110 ```
 111
 112 ---
 113 >If you're using the [Sparkfun WiFly] [1] library:
 114 ```c
 115 WiFlyClient client;
 116 XivelyClient xivelyclient(client);
 117 ```
 118 [1]: https://github.com/jmr13031/WiFly-Shield
 119
 120 ##Sending and Retrieving Xively Datapoints
 121
 122 ###Read a Datapoint
 123 ```c
 124 Serial.print("My return is: ");
 125
 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
 130 ```
 131
 132 ###Update a Datapoint
 133
 134 The library makes it easy to upload data as strings or numbers.
 135 ```c
 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
 140 ```