Home

Welcome! Log in or Join us

call: 1300 889 851

contact us

Sam Sabey

10a Croydon rd
Croydon, Victoria 3136
Australia

in Australia

1300 889 851

international

+61 403 245 139

owned by

Smart Energy Groups Pty Ltd
ABN: 30 151 207 822

operated by

Esskware Pty Ltd
ABN: 62 113 534 919

The Smart Energy Groups API

What is Smart Energy Groups?

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

 

SEG Energy Management

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 firmware and related supporting files for the SEGmeter code etc:

http://github.com/samotage/Aiko

Inside this git repository are:

- the Arduino sketches we use

- The LUA gateway module that we use

- Other useful and perhaps interesting things like bike_duino! 

API Documentation for sending data to SEG

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

 

 

For your stream data

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

The Simple Stream API

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.

 

Other useful API's

There are a bunch of other useful API's that can help with things like working out if the SEG API is up and time synchronisation useful for NTP problems and other stuff.

Is Up

http://api.smartenergygroups.com/api/is_up     

using a GET request

This API returns either true, false or other HTTP error code like 500 etc.

SEG Time

http://api.smartenergygroups.com/api/seg_time

using a GET request

This API returns an S-Expression such as: 

(seg_time "2013-07-25 01:46:55")

This is the current server time the UTC time zone.

Check Time

http://api.smartenergygroups.com/api/check_time?remote_time="2013-07-25 01:46:55"

using a GET request

Notes, make sure the parameter remote_time is YOUR time correctly encoded, example for the above time is %222013-07-25%2001:46:55%22

This will return an S-Expression with either ok or fail and the SEG time in UTC and time difference (within a tolerance) and the time difference.

(time_sync ok "2013-07-25 01:54:11" -12)
(time_sync fail "2013-07-25 01:55:10" 46)

This can be used to determine if your clock is ok or not, and or the current SEG time to set it appropriately if NTP is not available.

 

API Discovery

Smart Energy Groups Discovery

The SEG API can discover your sites, and automatically create devices and streams based on the data coming in from your s-expressions.  This makes life really easy for everyone!

The SEGbox code is made to work seamlessly with all this fandango, however if you feel like getting smart, you can use the API features to make your gear work better.

An overview of the discovery process is this:

1.  Ensure you are browsing SEG from the same internet based IP as your device is sending data, use a what's my IP service if you are in doubt.  

2.  Make sure your site is in discovery mode, go to the tools -> discoveries or if it's a new site it will be automatically be put in discovery mode after create.

3.  Sit back, relax and watch the discovery screens to see what happens, the discovery will be active for around 5 minutes before time out.  If it goes into time out after taking too long, it can be cancelled or restarted from the tools menu. 

Site Token Vending

If you are discovering anmd sending a message with a special site token, site_unknown SEG will send the response from the api of:

(site= <your site token>)

Parse out this token and include it in future requests for automatic linking to your site.

Device Creation

SEG will create a new device for you based on the device's node_name sent in with the message if one does not exist, and it will be named after this node name, note it can be changed to after discovery is complete to your own special name.

Stream Creation

SEG will automatically create, and setup your data streams with defaults based on the type of data being sent.  This is done by convention from of the stream_name coming in with the s-expression.

The following are the established conventions for automatic stream creation, note all these are based on the following, <prefix>_<your channel index>_<suffix>, e.g. p_1 or p_10_a

Prefixes:

p_ Power stream with the unit of watts
e_ Energy stream with the unit prefixed to kilowatt hours
a_ or amps_ Current stream with the unit of amps
c_ Power stream identified with the Phase based on the channel number, with the same settings as a normal power stream
temperature_ Temperature stream with default units of Celcius
v_ or voltage_ Voltage stream with the units being volts
state_ Switch state stream to determine if a switch is on or off
seconds_ Seconds stream representitive of an elapsed time in seconds
boot_ or heartbeat_ Boot Event stream to determine if your device has booted and also records a heartbeat to check things are still ticking
pulse_ Count of pulses output from a device

 

Suffixes:

_a will add a commment that the stream is calculated by the device through adding channels
_g will add a commment that the stream calculated total for green channels
_sub or _st will add a comment that the stream is a subtotal of channels
_s will add a comment that the stream is calculated by the device by subtracting channels

 

API Response Codes

SEG API Response Codes

These are useful for working out what happened with your call to the SEG API.  Note the SEGbox uses these codes for seamless control and integration.

All is Ok  
(status ok) Processed by SEG without fail
(status ok request_delayed) SEG has the data, and it's in the queus for processing, usually because it's a large request.
   
Failure  
(status fail seg_internal) Fail in the SEG API, somepthing borked out, we may have caught it, retry the request.
(status fail invalid_site_token) Self explainatory, your site could not be found!  Go check
(status fail no_data_sent) Self explanatory, your request contained no useful data to process.
(status fail discovery_not_started) From discovery on token site_unknown, start discovery with matching IP address
(status fail api_timeout) The API timed out, retry
(status fail writing_response) SEG could not write the response for some reason.
   
Discovery  
(site= <your site token>) Your site token vended by SEG with a discovery process running
(site= site_unknown) What SEG will send you when it is unlinking a site, either because it's not found, or the site has been unlinked in SEG.
   

 

 

 

 

copyright © 2013 Smart Energy Groups pty ltd