README.md

#Xively Arduino library

A library for Arduino to make it easier to talk to Xively.

This library requires HTTP Client.

##Features

1. Generic functions for: - Uploading datapoints - Downloading datapoints
2. Compatible with:
   • Arduino Ethernet shield
   • Arduino Ethernet board
   • Arduino Wifi shield
   • WiFly shield

##For a Quickstart Example
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.

In Arduino, go to Files > Examples and choose DatastreamUpload or DatastreamDownload from the xively_arduino library folder

##Setup Your Sketch

1. Specify your API key and Feed ID

char xivelyKey[] = "YOUR_XIVELY_API_KEY";
// Should be something like "HsNiCoe_Es2YYWltKeRFPZL2xhqSAKxIV21aV3lTL2h5OD0g"
#define FEED_ID XXXXXX 
// The 3 to 6-digit number (like 504 or 104097), that identifies the Xively Feed you're using

2. Create IDs for your datastreams as char arrays (or String objects for a String datastream)

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

// For datastreams of floats:
char myFloatStream[] = "humidity";
// For datastreams of ints:
char myIntStream[] = "temperature";
// For datastreams of Strings:
String myStringStream("my_thoughts_on_the_temperature");
// For datastreams of char buffers:
char myCharBufferStream[] = "more_thoughts";  // ID of the array
const int bufferSize = 140;                   // size of the array
char bufferValue[bufferSize];                 // the array of chars itself

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.

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.

3. Create an array of XivelyDatastream objects

XivelyDatastream datastreams[] = {
  // Float datastreams are set up like this:
  XivelyDatastream(myFloatStream, strlen(myFloatStream), DATASTREAM_FLOAT),
  // Int datastreams are set up like this:
  XivelyDatastream(myIntStream, strlen(myIntStream), DATASTREAM_INT),
  // String datastreams are set up like this:
  XivelyDatastream(myStringStream, DATASTREAM_STRING),
  // Char buffer datastreams are set up like this:
  XivelyDatastream(myCharBufferStream, strlen(myCharBufferStream), DATASTREAM_BUFFER, bufferValue, bufferSize),
};

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

	Variable	Type	Description
1	aIdBuffer	char*	char array containing the ID of the datastream
2	aIdBufferLength	int	for int or float datastreams only: the number of char in the datastream's ID
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
4	aValueBuffer	char*	A char array, aValueBufferLength elements long
5	aValueBufferLength	int	The number of elements in the char array

4. Last, wrap this array of XivelyDatastream objects into a XivelyFeed

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.

XivelyFeed feed(FEED_ID, datastreams, 4);

	Variable	Type	Description
1	aID	unsigned long	The Feed's ID, as defined at the top of your sketch
2	aDatastreams	XivelyDatastream*	Your XivelyDatastream array
3	aDatastreamsCount	int	How many datastreams are in the array

5. Instantiate the library's Xively client

Connecting by ethernet:

If you're using the Ethernet library:

EthernetClient client;
XivelyClient xivelyclient(client);

If you're on wireless, be sure to enter your SSID and password as the library requires, and then:

If you're using the built-in WiFi library:

WiFiClient client;
XivelyClient xivelyclient(client);

---

If you're using the [Sparkfun WiFly] 1 library:

WiFlyClient client;
XivelyClient xivelyclient(client);	

##Sending and Retrieving Xively Datapoints

###Read a Datapoint

Serial.print("My return is: ");

float float_value = datastreams[0].getFloat();        // Retrieve the latest datapoint in a float datastream
int int_value = datastreams[1].getInt();              // Retrieve the latest datapoint in an int datastream
String string_value = datastreams[2].getString();     // Retrieve the latest datapoint in a String datastream
char[140] char_buffer = datastreams[3].getBuffer();   // Retrieve the latest datapoint in a char buffer datastream

###Update a Datapoint

The library makes it easy to upload data as strings or numbers.

datastreams[0].setFloat(1.5);                           // Push a float datapoint
datastreams[1].setInt(23);                              // Push an int datapoint
datastreams[2].setString("Pretty comfy temperature");   // Push a String datapoint
datastreams[3].setBuffer("But quite dry");              // Push a char buffer datapoint

##Error codes

This library uses amcewen/HttpClient which has following error codes:

• HTTP_SUCCESS = 0 - no error
• HTTP_ERROR_CONNECTION_FAILED = -1 - connection to api.xively.com has failed
• HTTP_ERROR_API = -2 - a method of HttpClient class was called incorrectly
• HTTP_ERROR_TIMED_OUT = -3 - connection with api.xively.com has timed-out
• HTTP_ERROR_INVALID_RESPONSE = -4 - invalid or unexpected response from the server

Apart from the above, the library will convert any non-2xx status code to a nagative value like so:

ret = http.responseStatusCode();
if ((ret < 200) || (ret > 299))
{

  if (ret > 0)
  {
    ret = ret * -1;
  }
}

Therefore:

• if we got a 2xx, we will return that as is
• if we got a negative value (e.g. HTTP_ERROR_CONNECTION_FAILED, HTTP_ERROR_TIMED_OUT or other), we will return that as is
• any non-2xx status code is returned multiplied by -1, i.e. a 403 (Authentication error) will be returned as -403