25 Blossom st
Mitcham, Victoria 3132
0403 245 139international
+61 403 245 139
Smart Energy Groups Pty Ltd
ABN: 30 151 207 822
Esskware Pty Ltd
ABN: 62 113 534 919
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 firmware and related supporting files for the SEGmeter code etc:
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!
1. A site has been created, it has a device and some streams.
If you haven't already, go here:
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
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:
2. The Method to use is:
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>)
(status error )
or perhaps a command?
If you get stumped, want to help etc, contact use here
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!
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:
Find your stream's token and format it into a restful call as following. Note the api.smartenergygroups subdomain!
This will return the last couple of hundred raw data poings for the stream, magic eh?
There are some other options that could be used, by extending the query string for example:
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
Aggregate, typically half hour summaries of the data
specify a start date time on a proper date format, e.g. rfc 2822. It can support some other things as well.
same as above, but specifiying an end date time.
how many points would you like? The default is about 100. Though it's possible to get more or less. e.g.
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
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.
Allows the retrieval of processed stream informaiton, as a number of additional resources for the stream. Available options are:
this gets the last raw value for a stream. e.g
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:
and the same service called for 110 days ago
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.
gets today's carbon emissions for the stream, also works best with kWh unit type streams. The range option is also supported too.
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.
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.
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.
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.
using a GET request
This API returns either true, false or other HTTP error code like 500 etc.
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.
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.
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.
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.
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.
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
|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|
|_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|
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.|
|(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.|
|(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.|