Smart Energy Groups is an on-line community for energy aware people to work together to share information on how to use energy more efficiently and reduce energy consumption.

To learn more about the why and where of Smart Energy Groups, rock over here

 

We use an open RESTul web service for our entire API to put data into your things, and get it out again.

There is also an Arduino an event driven framework for colelcting data and executing commands available.  This framework is compatable with our OpenWRT build and uses the Aiko framework made by Andy Gelme @geekscape (we have forked and modified it somewhat for SEG needs...)

http://github.com/samotage/Aiko

Inside this git repository are:

- the Arduino sketches we use

- The LUA gateway module that we use

This framework froms part of the Melbourne based Connected Community Hackerspaces group which is developing the Instrumented and Distributed community, open sourcing and building devices for the common good.

You can learn more, and participate in the project at the connected community hackerspaces here:

http://groups.google.com/group/connected-community-hackerspace/

So get involved, and help particpate to make this awesome!

There is also the OpenWRT Build that has all the stuff needed to make and bake an OpenWRT based SEGbox here, this includes our special image and other stuff:

http://smartenergygroups.com/forums/10-The-Open-Grid/topics/16-OpenWrt-Asus-WL-52-GU

 

Pre-requisites:

1. A site has been created, it has a device and some streams.

If you haven't already, go here: 
https://smartenergygroups.com/sites
 

2. You will need to know some details of your tokens.

All the relevant details of your stuff can be found here: https://smartenergygroups.com/my_things/show_keys 

This is quite a good page, not only does it tell about all the relvant tokens, but it also gives useful XML and JSON resources for getting data out of SEG
 

3. Then all you need to do is start sending data. It's simple!RESTful web service

 

RESTful Web Service

Now, streams are that, streams of data, each with a point in time, and a corresponding value. Streams are defined for units, i.e. kWh etc as part of the stream type associated for the device.

1. The Resource is:

http://api.smartenergygroups.com/api_sites/stream

2. The Method to use is:
:PUT

3. The body of the request is:
data_post = “(site  <your site's site_token>  (node <your device's node_name> <a date time stamp e.g. 2010-01-10T23:22:12 or a ? if you want SEG server time>  (<your devices stream_name> <value>)(<your devices stream_name> <value>)))”

a working example for a device sending data to 4 streams on a device may be:

data_post = "(site 7adfe67f35a (node segmeter ? (p_1 567.00)(e_1 2.70)(p_2 402.00)(e_2 2.2)))"

or with the time specified

data_post = "(site 7adfe67f35a (node segmeter 2010-01-10T23:22:12 (p_1 567.00)(e_1 2.70)(p_2 402.00)(e_2 2.2)))"

some notes on sending the time... The SEG server runs all data at UTC, so make sure to send UTC time - that is unless you would like some headaches!

and, it's as simple as that!

4. The Response
You will also get a response back from SEG telling you what's happened, such as
(status success <your current site api hit count>)
or
(status error )
or perhaps a command?
5. questions?

If you get stumped, want to help etc, contact use here

 

 

Overview

You've connected your device to Smart Energy Groups, and enjoying out lovelly graphs and other wonderful things.

Then in the middle of the night, you have had a brainwave!  What if I could get my data out, into my computer or other device and so some special magic?

Well, you can!  SEG has a basic API which we are making better for just this reason.

Here are some things it can do, let us know if you'd like more and we can get to it!

Stream Data

Your stream's data can be accessed from the Stream's token.  This can be worked out from editing your data stream, where there is a little helper section or from your keys page at:

https://smartenergygroups.com/my_things/show_keys

Find your stream's token and format it into a restful call as following.  Note the api.smartenergygroups subdomain!

http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml

This will return the last couple of hundred raw data poings for the stream, magic eh?

Options

There are some other options that could be used, by extending the query string for example:

source=

By default, data returned will be the raw data, as it comes in.  However this can be specified e.g:

Raw, as it has arrived
http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?source=raw

Aggregate, typically half hour summaries of the data
http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?source=aggregate

Days, daily totals
http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?source=day

start_date_time=

specify a start date time on a proper date format, e.g. rfc 2822.  It can support some other things as well.

http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?start_date_time=2011-03-04

http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?start_date_time=2011-03-04 07:29:59 +1100

end_date_time=

same as above, but specifiying an end date time.

point_limit=

how many points would you like?  The default is about 100.  Though it's possible to get more or less. e.g.

http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?point_limit=10

sort_option=

by default, the data is sorted with the most recent first.  This may not be to everyone's taste, so this can be specified with this parameter.  Options are:

dd - date descending
da - date ascending
vd - value descending
va - value ascending

http://api.smartenergygroups.com/api_streams/1bf60838538e73f.xml?sort_option=vd

Some notes... for value sorting, vd and va this will sort the results of the points selected by a date range, point limit or other in the specified value order.

Stream Information

Allows the retrieval of processed stream informaiton, as a number of additional resources for the stream.  Available options are:

current_value

this gets the last raw value for a stream.  e.g
http://api.smartenergygroups.com/api_streams/1bf60838538e73f/current_value.xml

day_value

this gets todays total or average (depending on kW or kWh or other rule) for the stream.  It can be also ranged back in time with an additional option.  Examples:

http://api.smartenergygroups.com/api_streams/12801e11b966c54/day_value.xml

and the same service called for 110 days ago

http://api.smartenergygroups.com/api_streams/12801e11b966c54/day_value.xml?range=110_d

day_cost

gets the cost for the current day, very similar in operation as the day_value method but it uses your defined energy rate to calculate the daily cost.  This also supports the range option too.  Works best with kWh unit type streams.

http://api.smartenergygroups.com/api_streams/12801e11b966c54/day_cost.xml

day_carbon

gets today's carbon emissions for the stream, also works best with kWh unit type streams.  The range option is also supported too.

http://api.smartenergygroups.com/api_streams/12801e11b966c54/day_carbon.xml

About

The site level API service is designed around our OpenWRT gateway, that will send data for a number of devices, and manage large scope data and command interchanges.

This powerful API sometimes is a little bit of overkill, when considering simple internet connected things.  Examples are Arduino's with ethernet of wifi shields.  We all know Arduino is a limited resource computer, and sometimes the extra buffer sizes, and PUT method pre-amble and headers can cause issues.

Usage

This API is designed for this type of device, it's a simple GET method to the stream's resource, with the value on the parameter string, e.g.

http://api.smartenergygroups.com/api_streams/<stream_token>/add_point?value=47.2

This will add a data point to the stream identified by the <stream_token> with the date time taken from the SEG server date time.  Simple!

You can get your stream_token from the my_keys, or by editiing your stream.