Cosm Arduino library

A library for Arduino to make it easier to talk to Cosm (the service formerly known as Pachube).

This library requires the HTTP Client library at https://github.com/amcewen/HttpClient

##Features

1. Generic functions for: - Uploading datapoints - Downloading datapoints
2. Compatible with - Ethernet connections - 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 cosm-arduino library folder

##Setup Your Sketch

1. Specify your API key and Feed ID

char cosmKey[] = "YOUR_COSM_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 Cosm Feed you're using

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

In Cosm, 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 Cosm 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 CosmDatastream.cpp for info.

3. Create an array of CosmDatastream objects

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

CosmDatastream 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 CosmDatastream objects into a CosmFeed

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 Cosm Feed you are addressing. For example, a Feed ID of 504 would mean that you were using the feed at cosm.com/feeds/504.

CosmFeed 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	CosmDatastream*	Your CosmDatastream array
3	aDatastreamsCount	int	How many datastreams are in the array

5. Instantiate the library's Cosm client

Connecting by ethernet:

If you're using the Ethernet library:

EthernetClient client;
CosmClient cosmclient(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;
CosmClient cosmclient(client);

---

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

WiFlyClient client;
CosmClient cosmclient(client);	

##Sending and Retrieving Cosm 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