Quickstart for beta testers

If you are comfortable with coding then you can use the guidelines below to get going. If you want a nudge in the right direction and you intend to use Arduino/Processing (or a similar setup) have a look at the tutorial on using Arduino for Pachube.

1. To use Pachube, you can signup here: http://www.pachube.com/signup. Please note that registering for Pachube, the service, is different from registering here to write in the community/forum/tutorials/comments, etc.
2. Once you have signed up, you will receive an email to say "Your account has been activated!", which will contain details of your username and API key. Your username (and the password you supplied during signup) are used for accessing various features on the Pachube website including adding and editing feeds. The API key however is what you need in your code to authenticate your application's access the Pachube service. Don't share this with anyone: it's just like any other password.
3. Determine whether you will be making inputs to or using outputs from Pachube (or both). If you have a microcontroller and sensors and you want to make real time data available to others, this would be considered an input to Pachube. If you want to make visualisations from other people's real time data or have remote sensor data trigger things in your microcontroller this would be considered an output from Pachube.

For a quick way to check that its all working correctly, have a look here: http://community.pachube.com/?q=node/9#commandline.

At this stage, feed updates and feed requests are limited (server-side) to once every 5 seconds, and each individual API key will be rate limited at 50 requests every 3 minutes, so there is no point in requesting data more frequently.

Configuring an INPUT to Pachube

To create a new INPUT feed, you need to can either make a POST request to the API or login to Pachube and use the interface to create a new feed.

Using the Pachube interface to create a new feed

When logged in to Pachube, use this link to create a new feed: http://www.pachube.com/feeds/new

There are two ways to make your real time data available to Pachube and to other Pachube users: either by automatic update (i.e. if your device, building or installation is able to serve data automatically as and when Pachube requests it); or by manual update (i.e. by making an HTTP PUT request, containing your latest data, as and when you want to -- this is particularly useful when you are behind a firewall).

Update Pachube automatically, by serving data when requested

If your device, building, installation or environment can serve data (i.e. so that it is accessible to Pachube via HTTP GET request) and you are not behind a firewall, this may be the simplest option for you. The Processing EEML library and the Arduino ethernet are able to do this as long as a firewall doesn't prevent you from doing so. You can then provide data in one of two ways:

1. By serving data in EEML format: EEML is written in XML and enables you to add a lot of contextual meta-data to your sensor stream (including GPS location, data tagging, etc). See the EEML website for examples of complete instances, but at its simplest your EEML can look a little like this:
   <?xml version="1.0" encoding="UTF-8"?>
<eeml xmlns="http://www.eeml.org/xsd/005">
  <environment>
    <data id="0">
      <value>36.2</value>
    </data>
  </environment>
</eeml>

   ... though it should ideally include full namespace information as detailed in this minimal example on the EEML website. A "complete" EEML document can be seen here. (A big advantage of EEML is the ability to define metadata including tags for each data stream within your serving application). See this document about EEML for more info on how it operates with construction industry standards: http://community.pachube.com/files/EEML_and_IFC.pdf . Also, see A note on units if you will be using units in your EEML.

2. By serving data in CSV (comma-separated values) format: This is faster and simpler but also less easy to debug. The number of data streams is also fixed; i.e. you cannot add new streams on the fly. Three individual data streams could be served like this:
   0.2,34,56


Which way you choose depends upon your needs. If you want to be able to change meta-data on the fly, then use EEML. On the other hand if you are working with a microcontroller which needs low overheads then use CSV. In this last case, meta-data can be entered when you add the feed to the Pachube website. Either way, Pachube will make the conversion automatically for other people depending on their particular needs (e.g. if you serve in CSV but someone requests EEML).

If you are building your own server application, remember that you'll need to include HTTP headers depending on what type of data you're serving:

• HTTP/1.1 200 OK\n
Content-Type: application/xml\n\n

  or

• HTTP/1.1 200 OK\n
Content-Type: text/csv\n\n

There is an EEML library for Processing available which makes it easy to create EEML feeds without knowing or understanding EEML.

When your feed is ready and you know both the URL or IP address and port that you are serving on, login to Pachube, and connect to an input.

Update Pachube manually, by uploading data when you determine it to be necessary

This method may be more appropriate if your device, building, installation or environment is behind a firewall; or if its processing or energy capacity, or data stream variance, is such that frequent updates would be undesirable; or if it is unable to serve data for any other reason. In this case you would simply make an authenticated PUT to Pachube with either CSV or EEML as necessary. (See above for a discussion on the benefits of each).

Here is a sample PUT request:

In this case, you will receive a response code (200 means that the resource was updated successfully; 404 means that the resource could not be found). For a complete list or status codes, see here: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

Note, if you are unable to set custom headers you can also authenticate by putting your Pachube API key in the URL as a parameter, though there may be a small impact on performance. A complete request might look something like:

For example, in LSL for Second Life, where custom headers are not currently possible, the PUT request might look something like this:

Connecting to an OUTPUT from Pachube

Similarly, if you are making use of an output from Pachube then you need to be able either to parse EEML (i.e. XML) or CSV data. EEML enables you to make use of contextual data about the feed. Go to the Pachube website, connect to an output and browse for a feed that you are interested in. Copy its feed url which will look something like one of these two:

1. For data in EEML format:
   
   http://pachube.com/api/feeds/15.xml
2. For data in CSV format:
   
   http://pachube.com/api/feeds/15.csv

When you request the feed data, you need to authenticate your request. This is achieved in one of three ways. You can either:

1. add your API key to the URL (as well as any other Pachube modifiers you would like to use). Your request URL would look therefore something like this:
   http://pachube.com/api/feeds/138.xml?key=ENTER_YOUR_PACHUBE_KEY_HERE

   (where, of course, you supply your own API key).

2. Or if your code is capable of setting and sending standard HTTP headers, then you can include the key as an HTTP header, separating authentication from the URL request. For example,
   GET /api/feeds/138.xml
X-PachubeApiKey: ENTER_YOUR_PACHUBE_KEY_HERE

3. Or, finally, if your client software can send HTTP basic authentication requests, then you can submit your normal login and password to authenticate yourself once; this starts a new session on the server, and while you remain connected, you would not need to keep sending credentials.

Again, the EEML library for Processing makes some of this relatively straightforward.