Starting with gateway version 400 and later, it’s also possible to post data to a 3rd party server. This will allow developers to create remote services that can receive TED5000 data, without requiring end users to place their TED5000 on the internet.
The latest firmware and release notes is available here:
http://forums.theenergydetective.com/index.php/topic,3.0.htmlA PDF Version of this API is now available:
http://files.theenergydetective.com/docs/TED5000ThirdPartyPostingAPI-R452.pdfTechnical Description
------------------------------------
Activation
==================
To configure the TED5000 to post to a 3rd party service, the following steps will need to be executed:
1. User selects "Activate Energy Posting" from the main menu.
2. User is prompted with a screen to enter 3rd party activation information:
- URL of the authentication service.
- Unique Identifier (provided by the 3rd party) to uniquely identify this ted on their system. This can be as simple at the GW ID, or a password - 20 character max
A disclaimer about data security will also be presented via this popup, activation means they acknowledge the privacy risks.
3. User hits submit. TED5000 makes a POST request to the 3rd party authentication service sending the unique identifier supplied in section 2.
XML Sent will be:
<ted5000Activation>
<Gateway>210000</Gateway>
<Unique>123456</Unique>
</ted5000Activation>
Gateway is the hardware identifier (Serial Number) of the unit making the request
Unique is the unique identifier that was supplied in step 2. This is optional and is meant as an extra security token to be provided to the 3rd party service if they wish to use it.
4. The activation service will respond back w/ the following
<ted500ActivationResponse>
<PostServer>www.theenergydetective.com</PostServer >
<UseSSL>true</UseSSL >
<PostPort>443</PostPort >
<PostURL>/postdata.cgi</PostURL>
<AuthToken>MySecurityToten</AuthToken>
<PostRate>10</PostRate>
</ted500ActivationResponse>
PostServer- The ip address or dns resolvable name of the server (80 character max)
PostPort - the port that the server is running on
PostURL - the path of the service receiving the post (80 character max)
UseSSL - whether or not to post data via SSL
AuthToken- Unique token provided by the 3rd party used to as an authentication mechanism when data is submitted by the TED5000 (optional) (20 character max)
PostRate - The number of minutes between data posts. (1 - 15)
Activation can be performed by the user more than once.
Data
======================
Once activated, the TED5000 will begin to post the following data to the service defined above. The data will be in the following format:
------------------------------
<ted5000 GWID="200000" auth="MySecurityToken">
<MTU ID=100000 type="0">
<cumulative timestamp="123456000" watts="10000" rate="0.12345"/>
<cumulative timestamp="123456060" watts="10005" rate="0.12345"/>
<cumulative timestamp="123456120" watts="10010" rate="0.12345"/>
</MTU>
<MTU ID=100001 type="0">
<cumulative timestamp="123456000" watts="10000" rate="0.12345"/>
<cumulative timestamp="123456060" watts="10005" rate="0.12345"/>
<cumulative timestamp="123456120" watts="10010" rate="0.12345"/>
</MTU>
</ted5000>
--------------------------------
The "MTU" element will be repeated for each MTU in the system. If the gateway is only configured for 1 MTU, this block will only be repeated once.
- ID: the unique hardware id of the MTU
-type: the configuration type of the mtu (0=load, 1=solar, 2=net, 3=stand-alone, 5=stand-alone-net)
The "cumulative" element will be repeated for each queued "minute" reading since the last post. The device can store up to 15 "minute" readings . If more than 15 minutes elapse between successful posts, only last 15 minutes will be resent.
-timestamp is the "Unix Epoch" based timestamp of the reading.
-watts is the cumulative reading in watts by the MTU (since its creation) at the specified time. Using the above example, each MTU is reporting 5watts of use since the previous minute’s data was sent (5W/min or 300W/hr (multiplied by 60))
-cost is the "rate in effect" when the reading was made.
So, in the above example, for the first MTU, the readings show that the usage is 5 watts per minute for the last 3 minutes at a rate of $0.12345).
The service should respond w/ a HTTP 200 code if successful. Any code >= 300 will be considered to be an error code.
Posting statistics as well as error codes can be viewed on the stats.htm page (e.g.
http://ted5000/stats.htm)
The error codes are:
Activation Error Codes:
0 - success
100 - Parsing error of activation xml file
101 - Timeout accessing activation file (also file not found)
Posting Error Codes:
These are the same response codes sent by the server. In addition, some codes are:
1000 - Socket error connecting to the server
2000 - Timeout posting data to the server
3100 - SSL Handshake timeout
4000 - Posting Data (Not an error code, just an indication that data is currently posting)
====
Quick Start
======================
To start your 3rd party posting development, it may be best to try a static xml file for activation, and a simple server-side PHP script to receive posts from your TED5000.
Below is a simple activation XML:
<ted500ActivationResponse>
<PostServer>demo.theenergydetective.com</PostServer>
<PostURL>/postData.php</PostURL>
<UseSSL>F</UseSSL>
<PostPort>80</PostPort>
<AuthToken>myToken</AuthToken>
<PostRate>1</PostRate>
<SSLKey>NOT IMPLEMENTED</SSLKey>
</ted500ActivationResponse>
Copy this file to your web server. Be sure to test it in IE or Firefox to make sure its visible via your web connection:
i.e.
http://demo.theenergydetective.com/act.xmlThis url is what will be used for the "Activation URL" when you activate 3rd party posting via Footprints.
On the server, you can use the following PHP script to receive the XML post from the TED5000, and write the XML file to a directory.
postData.php
------
<?php
#change the /home/demo/xml path to the directory you wish to have xml
#posts written to.
$outp = fopen("/home/demo/xml/xmlfile." . date("YmdHis") . ".xml", "w");
fwrite($outp, $HTTP_RAW_POST_DATA);
fclose($outp);
?>
The URL path to this file is what is used for the PostServer and PostURL fields of the static activation xml file. Once activated you should see XML files being written within a few minutes.
