TED PRO Third Party Posting API Based on ECC Firmware Revision R400

Transcription

1 TED PRO Third Party Psting API Based n ECC Firmware Revisin R400 Table f Cntents Intrductin... 1 Activatin... 1 Sample Activatin XML... 2 Sample Activatin Respnse XML... 2 Psting Data... 3 Sample Pst XML... 3 Debugging... 5 Quick Start... 6 Sample Activatin Respnse XML... 6 Sample PHP Pst Data Script... 6 Intrductin Starting with ECC versin 400 and later, it s pssible t pst cumulative usage data frm the TEDPRO t a 3rd party server. The MTUPRO can pst cumulative usage data starting with versin 443 and later. This feature allws develpers t create remte services that can receive TEDPRO data, withut requiring end users t place their TEDPRO n the internet. Third-party psting cnsists f tw phases: Activatin A user registers their TEDPRO with a remte server. Pst An activated TEDPRO psts cumulative usage data fr ne r mre MTU s t the server In this dcument yu will ntice that many f the XML elements start with <ted5000>. This is t help ensure backwards cmpatibility w/ lder mdel TED devices. Activatin T cnfigure the TEDPRO t pst t a 3rd party service, the fllwing steps will need t be executed by the user: 1. User selects "Activate Energy Psting" frm the main menu. 2. User is prmpted with a screen t enter 3rd party activatin infrmatin: Cpyright The Energy Detective. All Rights Reserved. Page 1 f 6

2 URL f the authenticatin service. Unique Identifier (prvided by the 3rd party) t uniquely identify this ted n their system. This can be as simple at the GW ID, r a passwrd (20 character max). A disclaimer abut data security will is presented via this ppup; activatin means they acknwledge the privacy risks. 3. User hits submit. TEDPRO makes a HTTP POST request t the 3rd party authenticatin service sending the unique identifier supplied in sectin 2. The mime type f this pst is applicatin/xml. Sample Activatin XML <ted5000activatin> <Gateway>210000</Gateway> <Unique>123456</Unique> </ted5000activatin> Gateway is the hardware identifier (Serial Number) f the ECC unit making the pst Ver is the versin f the firmware running n the ECC (r the versin f the firmware running n the MTUPRO if its psting directly) Unique is the unique identifier that was supplied in step 2. This is ptinal and is meant as an extra security tken t be prvided t the 3rd party service if they wish t use it. 4. The third-party server will need t prvide an activatin respnse t this request in the frm f the fllwing XML. Activatin can be perfrmed by the user mre than nce. Sample Activatin Respnse XML <ted5000activatinrespnse> <PstServer> <UseSSL>T</UseSSL> <PstPrt>443</PstPrt> <PstURL>/pstdata.cgi</PstURL> <AuthTken>MySecurityTten</AuthTken> <PstRate>10</PstRate> <HighPrec>T</HighPrec> </ted5000activatinrespnse> PstServer- The ip address r dns reslvable name f the server (80 character max) PstPrt - the prt that the server is running n PstURL - the path f the service receiving the pst (80 character max) UseSSL - whether r nt t pst data via SSL Cpyright The Energy Detective. All Rights Reserved. Page 2 f 6

3 AuthTken- Unique tken prvided by the 3rd party used t as an authenticatin mechanism when data is submitted by the TEDPRO (ptinal) (20 character max) PstRate - The number f minutes between data psts. (1-15) HighPrec Enables/disables High Precisin mde. A value f T enables High Precisin mde which will include fractinal watt-hurs. Any ther value will flr each value t the nearest watt hur. Psting Data Once activated, the TEDPRO will begin t pst the fllwing data t the service defined abve. This will be psted as an HTTP POST and will use the mime type applicatin/xml: The data will be in the fllwing frmat: Sample Pst XML <ted5000 GWID="200000" auth="mysecuritytken"> <COST mrd="15" fixed="10.00" min="5.00"/> <DEMAND kva="0"> <demandcst timestamp=" " peak="12.184" cst="22.36"/> </DEMAND> <MTU ID= type="0"> <cumulative timestamp=" " watts="10000" rate=" " pf= 99.9 /> <cumulative timestamp=" " watts="10005" rate=" " pf= 99.9 /> <cumulative timestamp=" " watts="10010" rate=" " pf= 99.9 /> </MTU> <MTU ID= type="0"> <cumulative timestamp=" " watts="10000" rate=" " pf= 99.9 /> <cumulative timestamp=" " watts="10005" rate=" " pf= 99.9 /> <cumulative timestamp=" " watts="10010" rate=" " pf= 99.9 /> </MTU> </ted5000> The COST element is used t prvide infrmatin fr calculating mnthly cst. Data psted frm an MTUPRO will shw these fields zered ut. The fllwing attributes are present: mrd (Meter Read Date): This is the first day f the next billing cycle where all mnthly values reset t zer. fixed (Fixed Amunt): If the utility charges a fixed amunt, this value is displayed here (0 if nt specified). min (Minimum Amunt): If the utility charges a minimum amunt per mnth, the value is displayed here (0 if nt specified) Cpyright The Energy Detective. All Rights Reserved. Page 3 f 6

4 The DEMAND element is used t prvide infrmatin regarding the demand charge rate and value fr a given minute. If Demand charges are nt enabled fr the gateway, this value is nt displayed. In additin, if n demand charges have been calculated since the Gateway s last rebt (e.g. still cllecting 15 minutes wrth f data) this element will nt be present either. This data is nt available n the MTUPRO. The DEMAND element has ne attribute: kva :if a value f 1 is specified, Demand Charge is being calculated based n kva. Otherwise, Demand Charge is being calculated based n kwh. The demandrate element will be repeated fr each minute reading since the last pst. It cntains the Demand Charge rate in effect fr that particular minute. timestamp: the "Unix Epch" based timestamp f the reading. peak: The Demand being used t calculate the rate. If kva is 1, this value is units f kva. Otherwise, it s in units f kwh. cst: The demand charge when the reading was made (units f dllars) The "MTU" element will be repeated fr each MTU in the system. If the gateway is nly cnfigured fr 1 MTU, this blck will nly be repeated nce. This element has tw attributes: ID: the unique hardware id f the MTU VER: The versin f the MTU firmware TYPE: the cnfiguratin type f the MTU 0 = Net :Psitive values are cnsidered cnsumptin, negative values are cnsidered generatin 1 = Lad: All values are cnsidered t be generatin. Develpers are encuraged t take the abslute psitive value f the number psted t cmpensate fr end users having their CT s installed backwards. 2 = Generatin: All values are cnsidered t be generatin. Develpers are encuraged t take the abslute negative value f the number psted t cmpensate fr end users having their CT s installed backwards. 3 = Stand-Alne: All values are cnsidered t be generatin. Develpers are encuraged t take the abslute psitive value f the number psted t cmpensate fr end users having their CT s installed backwards. 255 = MTUPRO: All values are psted directly frm an MTUPRO s Net, Lad, Generatin need t be cnfigured n the 3 rd party server. The "cumulative" element will be repeated fr each queued "minute" reading since the last pst. The device can stre up t 15 "minute" readings. If mre than 15 minutes elapse between successful psts, nly last 15 minutes will be resent. Each cumulative element has the fllwing attributes: Cpyright The Energy Detective. All Rights Reserved. Page 4 f 6

5 timestamp: the "Unix Epch" based timestamp f the reading. watts: the cumulative reading in watt hurs by the MTU (since its creatin) at the specified timestamp. Fractinal Watt-Hurs are represented as a decimal value up t 4 digits f precisin. rate: The rate in effect when the reading was made (based n GW Utility cnfiguratin). Pf: The average Pwer Factr fr the crrespnding minute. Vltage: the average vltage fr the crrespnding minute. The 3 rd Party Server shuld respnd w/ a HTTP 200 cde if successful. Any cde >= 300 will be cnsidered t be an errr cde. Debugging Psting statistics as well as errr cdes can be viewed n the stats.htm page (e.g. The errr cdes are: Activatin Errr Cdes 0 success Parsing errr f activatin xml file Timeut accessing activatin file (als file nt fund) Psting Errr Cdes Typically this cde will be the result cde f whatever was returned by the server after the pst (e.g. 200 = Success, 400= Bad Request). In additin t these cdes, the TEDPRO may als return ne f the fllwing cdes: Scket errr cnnecting t the server Timeut psting data t the server SSL Handshake timeut Psting Data (Nt an errr cde, just an indicatin that data is currently psting) Cpyright The Energy Detective. All Rights Reserved. Page 5 f 6

6 Quick Start T start yur 3rd party psting develpment, it may be best t try a static xml file fr activatin, and a simple server-side PHP script t receive psts frm yur TEDPRO. Sample Activatin Respnse XML <ted5000activatinrespnse> <PstServer>dem.theenergydetective.cm</PstServer> <UseSSL>F</UseSSL> <PstPrt>80</PstPrt> <PstURL>/pstData.php</PstURL> <AuthTken>myTken</AuthTken> <PstRate>1</PstRate> <HighPrec>T</HighPrec> </ted5000activatinrespnse> Cpy this file t yur web server. Please make sure that yur webserver is cnfigured allw this file t be accessed via HTTP POST. Be sure t test it in IE r Firefx t make sure it s visible via yur web cnnectin: i.e. This URL is what will be used fr the "Activatin URL" when yu activate 3rd party psting via Ftprints. On the server, yu can use the fllwing PHP script t receive the XML pst frm the TEDPRO, and write the XML file t a directry. Sample PHP Pst Data Script <?php #change the /hme/dem/xml path t the directry yu wish t have xml psts #written t. $utp = fpen("/hme/dem/xml/xmlfile.". date("ymdhis"). ".xml", "w"); fwrite($utp, $HTTP_RAW_POST_DATA); fclse($utp);?> The URL path t this file is what is used fr the PstServer and PstURL fields f the static activatin xml file. Once activated yu shuld see XML files being written within a few minutes. Cpyright The Energy Detective. All Rights Reserved. Page 6 f 6