EAGLE™ REST API Manual - Rainforest Automation
Contents
1. TierLabel gt lt RateLabel gt string lt RateLabel gt lt PriceCluster gt Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio MeterMacld 16 hex digits MAC Address of Meter UTC Time offset in seconds from 00 00 00 TimeStamp Up to 8 hex digits 01Jan2000 when price data was received from meter or set by user Price from meter or set by user will be Zero if Price Up to 8 hex digits no price is set Currency Up to 4 hex digits Currency being used value of this field matches the values defined by ISO 4217 The number of implicit decimal places in the Manos See edie price e g 2 means divide Price by 100 Tier 1 5 The price Tier in effect Rate label for the current price tier will be Set RateLabel Text Optional by User if a user defined price is set 11 Command get_message Send the get message command to get the current text message from the meter The EAGLE will send a MessageCluster notification in response lt Command gt lt Name gt get message lt Name gt lt MacId gt 0xFFFFFFFFFFFFFFFF lt MacId gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio www rainforestautomation com 15 N rainforest omatiooioon 12 Notify MessageCluster EAGLE REST API Manual MessageCluster notifications provide the current text message from the meter If a confirmation is required the ConfirmationRequired fl2. rainforest EAGLE Energy Access Gateway Link to Ethernet REST API Manual Version 1 1 July 2015 EAGLE N rainforest REST API Manual Copyright 2015 by RAINFOREST AUTOMATION INC RFA All rights reserved No part of this manual may be reproduced or transmitted in any from without the expressed written permission of RFA Under copyright law this manual or the software described within cannot be copied in whole or part without the written consent of the manufacturer except in the normal use of the software to make a backup copy The same proprietary and copyright notices must be affixed to any permitted copies as were affixed to the original This exception does not allow copies to be made for others whether or not sold but all of the material purchased with all backup copies can be sold given or loaned to another person Under the law copying includes translating into another language or format Rainforest Automation may have patents patent applications trademarks copyrights or other intellectual property rights covering subject matter in this document Except as expressly provided in any written license agreement from Rainforest Automation the furnishing of this document does not give you any license to these patents trademarks copyrights or other intellectual property Trademarks Third party brands and company Names mentioned herein may be trademarks and or registered trademarks of their respect
3. be included in the headers e Cloud ID xxxxxx where xxxxxx is the 6 digit Cloud ID for the target EAGLE e User user_name where user name is the user email address registered with this EAGLE on rainforestcloud com s Password user password where user password Is the user password registered with this EAGLE on rainforestcloud com lt blank gt Is a blank line consisting only of the carriage return and line feed characters 0x0D 0x0A lt body gt is the main text of the POST request which has the structure shown below www rainforestautomation com EAGLE REST API Manual automat rainforest The body of the POST consists of XML Fragments An XML Fragment is a stripped down XML Element The EAGLE uses XML Fragments to simplify the parsing of the data stream while providing a data structure that is flexible and human readable The XML Fragments have the following structure lt tag gt lt element gt value lt element gt lt tag gt Where Every line ends with the carriage return and line feed characters 0x0D OxOA lt tag gt is the start tag for the XML Fragment each type will have a unique tag name lt element gt is the start tag for an element there will be one or more child elements in the fragment each element will have a unique element name indicates the variable number of specific elements Element values can be of various types string
4. gt enumeration lt SuppressLeadingZero gt lt CurrenctSummation gt lt HistoryData gt www rainforestautomation com 19 a tion rainforest 18 Command set schedule EAGLE REST API Manual Send the set_schedule command to change how the EAGLE polls the meter The rate at which each type of meter reading is polled can be set lt Command gt lt Name gt set schedule lt Name gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt Event gt enumeration lt Event gt lt Frequency gt 0Oxffff lt Frequency gt lt FEnabled gt enumeration lt Enabled gt lt Command gt Element Range Macld 16 hex digits Event Frequency Enabled time message price Summation demand scheduled_prices profile data billing period block_period 4 hex digits YIN 19 Command get_schedule Send the get_schedule command to get the EAGLE scheduler information The EAGLE will send the Schedule nfo notification in response or the EAGLE will send a series of Schedule nfo notifications if the Event field is omitted lt Command gt lt Name gt get schedule lt Name gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt Event gt enumeration lt Event gt lt Command gt Element DeviceMacld Event Range 16 hex digits time message price Summation demand scheduled_prices profile_data billing period block_period Description MAC Addre
5. indicates an element consisting of Extended ASCII text enumeration indicates an element that can have a specific list of values OxFFFFF indicates an element consisting of a base16 hex number 00 indicates an element consisting of an integer 000 000 indicates an element consisting of a signed decimal number lt element gt square brackets indicate optional elements valuel value2 value3 vertical bars separate valid values in an enumeration list Note that element names are case insensitive the case is used strictly for legibility The EAGLE will ignore case when receiving POST requests Example Here is an example of a POST request POST sample php HTTP 1 0 Hose 192 160 211 325 000 Accept Content Length 55 Content Type text xml Cloud Id OO0ce69 Password myl23password User me my email com lt Command gt lt Name gt get instantaneous demand lt Name gt lt MacId gt 0x00178d0000000004 lt MacId gt lt Command gt Note that every line in the above example actually ends with the carriage return and line feed characters OxOD OxOA These are not shown explicitly for clarity www rainforestautomation com At rainforest EAGLE oma REST API Manual 2 Notifications The EAGLE generates a valid HTTP response to each POST request These look like HTTP 1 0 lt code gt lt headers gt lt blank gt lt body gt Where Every line ends with the carriage return and line feed chara
6. integers and are converted into a decimal number by using the multiplier and divisor i e Summation Reading summation value X multiplier divisor lt CurrentSummation gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt SummationDelivered gt OxFFFFFFFF lt SummationDelivered gt lt SummationReceived gt OxFFFFFFFF lt SummationReceived gt lt Multiplier gt OxFFFFFFFF lt Multiplier gt lt Divisor gt OxFFFFFFFF lt Divisor gt lt DagitsRight gt OxFF lt DigitsRight gt lt DigitsLeft gt 0xFF lt DigitsLeft gt lt SuppressLeadingZero gt enumeration lt SuppressLeadingZero gt lt CurrentSummation gt www rainforestautomation com 17 i rainforest o mat o n EAGLE REST API Manual Element Range Description DeviceMacld 16 hex digits MeterMacld 16 hex digits TimeStamp Up to 8 hex digits Summation E Delivered Up to 8 hex digits Summation E Received Up to 8 hex digits Multiplier Up to 8 hex digits Divisor Up to 8 hex digits DigitsRight Up to 2 hex digits DigitsLeft Up to 2 hex digits Suppress LeadingZero ME 16 Command get_history_data MAC Address of EAGLE ZigBee radio MAC Address of Meter UTC Time offset in seconds from 00 00 00 01Jan2000 when data was received from meter The raw value of the total summation of commodity delivered from the utility to the user Th
7. TInstallCode 0x91b98cd9cld8aa9b LinkKeyHigh 0xba8al4c201230175 TLinkKeyLow 0x8936044f99acc c45 FPWVersion 1 4 45 6564 HWVersion 3 2 1 Manufacturer Rainforest Automation Inc ModelId Z109 EAGLE DateCode 20120923ABCDEFGH TmageType 0x1l001 Protocol Zigbee www rainforestautomation com EAGLE X r ainfores REST API Manual COMMANDS amp NOTIFICATIONS 1 Command get_network_info Send the get_network_info command to get information about a network interface on the EAGLE The EAGLE will send a Networkinfo notification in response lt Command gt lt Name gt get network info lt Name gt lt Protocol gt enumeration lt Protocol gt lt MacId gt OxFFFFFFFFFFFFFFFF lt MacId gt lt Command gt Element Range Deseiption o o Type of network interface only ZigBee Protocol ZigBee Optional supported at this time if not specified the default is ZigBee Macld 16 hex digits Optional MAC Address of ZigBee radio if Protocol ZigBee 2 Notification NetworkIinfo Network nfo notifications provide basic information about an EAGLE network interface lt NetworkiInfo gt lt Protocol gt enumeration lt Protocol gt protocol specific elements lt NetworkiInfo gt Element Range Description Protocol ZigBee Type of network interface only ZigBee supported at this time 2a NetworkInfo Protocol ZigBee lt NetworkiInfo gt lt DeviceMacId
8. ag is set If the user has already confirmed the message then the Confirmed flag is set to Y The ID is the reference to a particular message The message text is HTML escape encoded lt MessageCluster gt lt DeviceMacId gt 0xFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt 0OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt Id gt OxFFFFFFFF lt Id gt lt Priority gt enumeration lt Priority gt lt Text gt String lt Text gt lt ConfirmationReguired gt enumeration lt ConfirmationRegquired gt lt Confirmed gt enumeration lt Confirmed gt lt Read gt enumeration lt Read gt lt Queue gt enumeration lt Queue gt lt MessageCluster gt Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio MeterMacld 16 hex digits MAC Address of Meter UTC Time offset in seconds from 00 00 00 TimeStamp Up to 8 hex digits 01Jan2000 when message was received from meter Id Up to 8 hex digits Message ID from meter SES Low Medium High ee Priority Critical Message priority Contents of message HTML encoded amp gt replaces the gt character Text Text amp lt replaces the lt character amp amp replaces the amp character amp quot replaces the character Confirmation YIN Y a user confirmation is required Required N a user confirmation is not required default Y the user confirmation has been sent Confirmed Y N N the user confirmation has n
9. cters 0x0D OxOA lt code gt is an HTTP status code which consists of a 3 digit number and a short text phrase This is usually 200 OK lt headers gt are a variable number of HTTP headers each header is on its own line lt blank gt Is a blank line consisting only of the carriage return and line feed characters 0x0D 0x0A lt body gt is the main text of the response which contains the Notification which has the structure shown below Example Here is an example of a reply HTTP 1 0 200 OK Date Wed 18 Dec 2013 21 28 44 GMT Server Apache 2 2 15 CentOS X Powered By PHP 5 3 3 Content Length 379 Connection close Content Type text html charset UTF 8 lt InstantaneousDemand gt lt DeviceMacId gt 0x00158d0000000004 lt DeviceMacId gt lt MeterMacId gt 0x00178d0000000004 lt MeterMacId gt lt TimeStamp gt 0x185adcld lt TimeStamp gt lt Demand gt 0x001738 lt Demand gt lt Multiplier gt 0x00000001 lt Multiplier gt lt Divisor gt 0x000003e8 lt Divisor gt lt DigitsRight gt 0x03 lt DigitsRight gt lt DigitsLeft gt 0x00 lt DigitsLeft gt lt SuppressLeadingZero gt Y lt SuppressLeadingZero gt lt InstantaneousDemand gt Note that every line in the above example actually ends with the carriage return and line feed characters OxOD OxOA These are not shown explicitly for clarity www rainforestautomation com EAGLE j rainforest REST API Manual 3 HTTP 1 1 An HTTP POST can al
10. e raw value of the total summation of commodity received from the user by the utility The multiplier if zero use 1 The divisor if zero use 1 Number of digits to the right of the decimal point to display Number of digits to the left of the decimal point to display Y Do not display leading zeros N Display leading zeros Send the get_history_data command to get a series of summation values over an interval of time In response the EAGLE will send a HistoryData notification containing a series of CurrentSummation fragments one for each sample over the interval lt Command gt lt Name gt get history data lt Name gt lt MacId gt OxFFFFFFFFFFFFFFFF lt MacId gt lt StartTime gt OxFFFFFFFF lt StartTime gt lt EndTime gt OxFFFFFFFF lt EndTime gt lt Frequency gt 0x0000 lt Frequency gt lt Command gt Element Range Macld 16 hex digits StartTime Up to 8 hex digits Description MAC Address of EAGLE ZigBee radio UTC Time offset in seconds from 00 00 00 01Jan2000 of the start of the history interval If StartTime is older than the oldest sample then the interval will start from the oldest sample www rainforestautomation com 18 EAGLE X r ainfores REST API Manual EndTime Frequency UTC Time offset in seconds from 00 00 00 01Jan2000 of the end of the history interval If not specified EndTime will be the current time Requested number of seconds between samples Availability limi
11. forest REST API Manual HANDLING THE NUMBERS Summation and Demand Readings Summation and Demand readings from the meter are reported as hexadecimal integers with formatting instructions to calculate the decimal value Here is a typical nstantaneousDemand notification lt InstantaneousDemand gt lt DeviceMacId gt 0x00158d0000000004 lt DeviceMacId gt lt MeterMacId gt 0x00178d0000000004 lt MeterMacId gt lt TimeStamp gt 0x185adcld lt TimeStamp gt lt Demand gt 0x001738 lt Demand gt lt Mu ultiplier gt 0x00000001 lt Multiplier gt lt Divisor gt 0x000003e8 lt Divisor gt lt DigitsRight gt 0x03 lt DigitsRight gt lt DigitsLeft gt 0x00 lt DigitsLeft gt lt SuppressLeadingZero gt Y lt SuppressLeadingZero gt lt InstantaneousDemand gt The values from this notification are e Demand reading 1738 hex 5944 decimal e Multiplier 1 e Divisor 3E8 hex 1000 decimal The actual Demand value is calculated by using the multiplier and divisor e 5944 x 1 1000 5 944 lf the multiplier or divisor is zero then use a value of one instead For Summation the same process is used and the multiplier and divisor are used by both the SummationDelivered and SummationReceived readings in the CurrentSummation notification The other formatting values DigitsRight DigitsLeft SupressLeadingZeros are the preferred display settings set by the utility and can be ignored for the purposes of calculating values Price Read
12. gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt InstallCode gt 0OxFFFFFFFFFFFFFFFF lt InstallCode gt lt LinkKeyHigh gt 0OxFFFFFFFFFFFFFFFF lt LinkKeyHigh gt lt LinkKeyLow gt 0OxFFFFFFFFFFFFFFFF lt LinkKeyLow gt lt FWVersion gt string lt FWVersion gt lt HWVersion gt string lt HWVersion gt lt Manufacturer gt string lt Manufacturer gt lt ModeliId gt string lt ModellId gt lt DateCode gt string lt DateCode gt lt ImageType gt 0OxFFFF lt ImageType gt lt Protocol gt ZigBee lt Protocol gt lt NetworkInfo gt www rainforestautomation com 10 EAGLE rainforest near eweg Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio InstallCode 16 hex digits Install Code for EAGLE ZigBee radio LinkKeyHigh 16 hex digits Upper 16 digits of ZigBee radio Link Key LinkKeyLow 16 hex digits Lower 16 digits of ZigBee radio Link Key FWVersion Text Firmware Version HWvVersion Text Hardware Version Manufacturer Text Rainforest Automation Modelld Text RFA Z109 DateCode YYYYMMDDZZZZZZZZ Manufacturer s date code and lot number ImageType 4 hex digits ZigBee code image type 3 Command list_network Send the list network command to get information about all of the EAGLE network interfaces The EAGLE will send a NetworkList notification in response lt Command gt lt Name gt list network lt Name gt lt Command gt 4 Notification NetworkList NetworkLi
13. ings Price readings from the meter are reported as a hexadecimal integer with a format instruction to place the decimal point Here is a typical PriceCluster notification lt PriceCluster gt lt DeviceMacId gt 0x00158d0000lab01le lt DeviceMacId gt lt MeterMacId gt 0x00078100011c 431 lt MeterMacId gt lt TimeStamp gt 0x1a462b4d lt TimeStamp gt lt Price gt 0x0000007d lt Price gt lt Currency gt 0x0348 lt Currency gt Trai lingbDigi ts gt 0x03 lt TrailingbDigits gt lt Tier gt 0x01 lt Tier gt www rainforestautomation com 23 EAGLE rainforest REST API Manual lt RateLabel gt Set by User lt RateLabel gt lt PriceCluster gt The values from this notification are e Price reading 7D hex 125 decimal e Trailing Digits 3 e Currency Code 348 hex 840 decimal The actual value of the Price is determined by placing the decimal point 3 digits from the right The Currency Code indicates that the value is in US Dollars see ISO 4217 So the final price is 0 125 www rainforestautomation com 24
14. ive companies and are the sole property of their respective manufacturers Notice The author s assumes no responsibility for any errors or omissions that may appear in this document nor does it make a commitment to update the information contained herein www rainforestautomation com EAGLE rainforest REST API Manual EAGLE Energy Access Gateway Link to Ethernet RFA Z109 Version 1 1 REST API Table of Contents AAA E 4 SERA RE Wl ne 4 Communications Model E 4 Data Giruchures EEEE 5 er inn un ele 5 2 NOCAS ee ee 7 CH RRE a easier teeters vente teen E TE ETE ETTE 8 rR WE 9 a aera amp NOTIFICA THONS serrare 10 Command get_Network mio 10 INGUTICATION NEIWOIKIN O EE 10 2a Networklnfo Protocol Zgb eel 10 3 Command get network _ Status ccccccccccssececseeeseeeeceeceseeeeeeeeeaeeesseeesaeeetaeeeas 12 4 Notification NEtWOrk Status ccccccccecceseececeeeeceeeeseeeeseeeeseeeesaeeeseeesaeeesseeesaeeeeas 12 4a NetworkStatus Protocol Zgob eei 12 5 Command get_iInstantaneOUS demand 13 O Notify INSTANIANCOUSUDOCMANG EE 14 7 Command get price 14 SR Te dt E lee 15 9 Command get EE ae eee ene ee ee ee eee ee eee 15 10 Notify Message uster c ccc ccccecccceeccceeeceeeeeaeeesaeeesaeeesaeeesaaeesaaeesaeesaeeesaeeeeas 16 Te ee Tune nie COMMA IMCSSAOS ease cacocecaccascecaccaseeaaceesazcaceacesesacesqeasnensccececececouacea 17 12 Command get Curre
15. mand data was received from meter Demand Up to 6 hex digits The raw instantaneous demand value Multiplier Up to 8 hex digits The multiplier if zero use 1 Divisor Up to 8 hex digits The divisor if zero use 1 Number of digits to the right of the decimal DigitsRight Up to 2 hex digits point to display SS Ka Number of digits to the left of the decimal point DigitsLeft Up to 2 hex digits to display Suppress YIN Y Do not display leading zeros LeadingZero N Display leading zeros 9 Command get_price Send the get_price command to get price information from the meter The EAGLE will send an PriceCluster notification in response lt Command gt lt Name gt get price lt Name gt lt MacId gt OxFFFFFFFFFFFFFFFF lt MacId gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio www rainforestautomation com 14 EAGLE j rainforest REST API Manual 10 Notify PriceCluster PriceCluster notification provides the current price in effect in the meter If the meter price is not set then the price returned is zero lt PriceCluster gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt 0OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt Price gt OxFFFFFFFF lt Price gt lt Currency gt OxFFFF lt Currency gt lt TrailingDigits gt UxFr lt TrailingbDigits gt lt Tier gt 00 lt Tier gt lt TierLabel gt string lt
16. mmand gt lt Name gt reboot lt Name gt lt MacId gt OxFFFFFFFFFFFFFFFF lt MaclId gt lt Target gt enumeration lt Target gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio Target Zigbee Eagle All Part of the device to be restarted Zigbee ZigBee radio Eagle Linux system All every part of the device www rainforestautomation com 21 EAGLE rainforest near eweg 22 Command get_demand_peaks Send the get_demand_peaks command io retrieve the largest positive and negative instantaneous demand values ever recorded by the EAGLE The EAGLE will send a DemandPeaks notification in response lt Command gt lt Name gt get demand peaks lt Name gt lt Command gt 23 Notify DemandPeaks A DemandPeaks notification provides the largest positive and negative instantaneous demand values ever recorded by the EAGLE lt DemandPeaks gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt PeakDelivered gt 00 000000 lt PeakDelivered gt lt PeakReceived gt 00 000000 lt PeakReceived gt lt DemandPeaks gt Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio PeakDelivered 7 digit floating point Highest value of demand in kW delivered to the premise PeakReceived Negative 7 digit floating Largest value of demand in kW received by the point grid www rainforestautomation com 22 EAGLE rain
17. nt eummaion oannnennennennnannnnnnrnnnnnrrnnrnrrnnnrennrnrrnnnno 17 13 Notify CGurmentGummaton 17 14 Command get history data 18 15 Notify HiStOry Data 0 cc cece ccccc cece eeeseeeceeeeneesaeeseueeseeeseesaueeseeesaeesneeseeeseeesaneens 19 16 Command EE 20 M7 OMME En En EE 20 18 Notify Schedulelnfo occ cceccccceeccccececceeeeeceeeeeseeeesseeeesaaeeseaeeessaeeesaeeeesaeeeeas 21 19 COMMING ee EE 21 HANDLING THE NUMBERS ccccccseseeeceeseeeseenseeseenseeseeseeseeaseeseoseeseoaseessonneesees 23 Summation and Demand Headmgs 23 PUCE TEAC INGS teachers edeiriderte E aire ned eke tees 23 www rainforestautomation com i EAGLE rainforest REST API Manual OVERVIEW EAGLE REST Interface The EAGLE is an Ethernet device that communicates with a smart meter over a secured ZigBee wireless network The EAGLE is an endpoint on the ZigBee network that is authorized and authenticated to communicate with the smart meter The EAGLE is also an endpoint on an Ethernet network that uses HTTP Hypertext Transfer Protocol over TCP IP Transmission Control Protocol Internet Protocol to communicate with web enabled entities The REST Representational State Transfer API Application Programming Interface described in this document provides a mechanism to allow external applications to pull smart meter data from the EAGLE Communications Model The EAGLE is a web enabled device that
18. ot been sent default Y message has been viewed by user DEn kt N message has not been viewed by user Active Indicates message is in active queue Queue Active Cancel Pending Cancel Pending Indicates message Is in cancel pending queue www rainforestautomation com 16 EAGLE r ainfores z REST API Manual 13 Command confirm_message Send the confirm_message command to have the EAGLE confirm the message as indicated by the ID To verify that the message confirmation was sent use a get_message command The resulting MessageCluster notification should show Confirmed Y lt Command gt lt Name gt confirm message lt Name gt lt MacId gt 0xFFFFFFFFFFFFFFFF lt MacId gt lt Id gt 0xFFFFFFFF lt Id gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio ID 0x0 OxFFFFFFFF Message ID to confirm 14 Command get_current_summation Send the get_current_summation command to get the total consumption to date as recorded by the meter The EAGLE will send a CurrentSummation notification in response lt Command gt lt Name gt get current summation lt Name gt lt MacId gt 0OxFFFFFFFFFFFFFFFF lt MacIlid gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio 15 Notify CurrentSummation CurrentSummation notification provides the total consumption to date as recorded by the meter Note that readings are recorded as
19. otocol gt ZigBee lt Protocol gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt Status gt enumeration lt Status gt lt CoordMacIlId gt OxFFFFFFFFFFFFFFFF lt CoordMacId gt lt Description gt string lt Description gt lt StatusCode gt 0xFF lt StatusCode gt lt ExtPanId gt OxFFFFFFFFFFFFFFFF lt ExtPanId gt lt ShortAddr gt 0xFFFF lt ShortAddr gt lt Channel gt 00 lt Channel gt lt LinkStrength gt 0OxFF lt LinkStrength gt lt NetworkStatus gt www rainforestautomation com 12 EAGLE rainforest REST API Manual Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio Initializing Network Discovery Joining Join Fail Join Success Status Authenticating Indicates the current state of the EAGLE Authenticating Success ZigBee radio Authenticating Fail Connected Disconnected Rejoining CoordMacld 16 hex digits MAC Address of Meter Description Text Optional Description of ZigBee radio state StatusCode 2 hex digits Optional Status code for the current state ExtPanld 16 hex digits Optional Extended PAN ID of the ZigBee network rb g The short address assigned to the REISE le erg EAGLE by the network coordinator Indicates the radio channel on which the Channel 11 26 Optional EAGLE is operating LinkStrength 0x00 0x64 Indicates the strength of the radio link 7 Command get_instantaneous_demand Send the get_ instantane
20. ous demand command to get the real time demand from the meter The EAGLE will send an nstantaneousDemand notification in response lt Command gt lt Name gt get instantaneous demand lt Name gt lt MacId gt 0xFFFFFFFFFFFFFFFF lt Macid gt lt Command gt Element Range Description Macld 16 hex digits MAC Address of EAGLE ZigBee radio www rainforestautomation com 13 EAGLE rainforest near eng 8 Notify InstantaneousDemand InstantaneousDemand notification provides the current consumption rate as recorded by the meter Note that readings are recorded as integers and are converted into a decimal number by using the multiplier and divisor i e Demand Reading demand value X multiplier divisor lt InstantaneousDemand gt lt DeviceMacId gt 0OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt 0OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt Demand gt 0OxFFFFFF lt Demand gt lt Multiplier gt OxFFFFFFFF lt Multiplier gt lt Divisor gt OxFFFFFFFF lt Divisor gt lt xDigitsRight gt 0xFF lt DigitsRight gt lt DigitsLeft gt 0xFF lt DigitsLeft gt lt SuppressLeadingZero gt enumeration lt SuppressLeadingZero gt lt InstantaneousDemand gt Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio MeterMacld 16 hex digits MAC Address of Meter UTC Time offset in seconds from 00 00 00 TimeStamp Up to 8 hex digits 01Jan2000 when de
21. rest ar The registration process will associate a user email address and password with the EAGLE These will be needed to access the EAGLE through the Relay Server The Relay Server connection has the following characteristics Host rainforestcloud com Port 9445 Protocol HTTPS URL cgi bin post_manager The EAGLE is also a ZigBee device It is ZigBee Smart Energy 1 x compliant and is certified by the ZigBee Alliance to operate according to that standard Therefore the API options are restricted to what is allowed by the ZigBee Smart Energy 1 x standard The EAGLE must be authorized and authenticated by the ZigBee Coordinator before the EAGLE can communicate with the smart meter Generally the smart meter is also the ZigBee Coordinator In this case the EAGLE is authorized by the owner of the smart meter i e the electric utility the owner needs the MAC ID and Install Code for the EAGLE in order to set up the authorization Data Structures 1 Commands The Application sends Commands in HTTP POST requests POST requests have the following structure POST lt URL gt HTTP 1 0 lt headers gt lt blank gt lt body gt Where Every line ends with the carriage return and line feed characters Ox0D OxOA lt URL gt is the Uniform Resource Locator web address of the Relay Server lt headers gt are a variable number of HTTP headers each header is on its own line The following items must
22. sits on an Ethernet network and communicates with an external Relay Server using a VPN connection which is initiated by the EAGLE Applications can connect to the Relay Server using the REST API and the Relay Server will route commands from the Application to the EAGLE and will route notifications from the EAGLE to the Application Application REST API firewall ZigBee wireless D customer premise Internet EAGLE Applications that connect in this way can effectively communicate with the EAGLE using 8 bit Extended ASCII characters code page 1252 formed into HTTP POST requests The body of these POST requests contains XML eXtensible Markup Language fragments These XML fragments contain Commands for the EAGLE The Relay Server responds to POSTs from the Application with valid HTTP responses The body of these responses contains XML fragments that make up Notifications from EAGLE which are in response to the Commands sent by the Application The EAGLE is identified by using its Cloud ID which is made up of the last 6 digits of the Ethernet MACID that is shown on the label on the underside of the device In order to be accessed remotely through the Relay Server the EAGLE must be registered with a Cloud Account on rainforestcloud com Instructions for this registration can be found in the EAGLE User Manual version 2 20 www rainforestautomation com r EAGLE rainfo
23. so specify that HTTP 1 1 be used In this case the reply generated by the EAGLE will contain the header element Transfer Encoding chunked in place of the Content Length header element This indicates that the body of the response will be divided into chunks Each chunk of data will be preceded by the chunk length on a line by itself as a hexadecimal number Each chunk will also be followed by a blank line The end of the message will be indicated by a zero on a line by itself www rainforestautomation com EAGLE rainforest near eweg 4 JSON Any of the Commands described in this document can include an optional XML tag lt Format gt JSON lt Format gt This will cause the Notification generated by the EAGLE to be in JSON JavaScript Object Notation format If no Format tag is found the EAGLE will use the default XML format Example POST sample post manager HTTP 1 1 Host server rainforestautomation com Accept 7 Content Type text xml Content Length 80 Cloud 1d 000306 Password 123asdf User eko email com Connection keep alive Pragma no cache Cache Control no cache lt Command gt lt Name gt get network info lt Name gt lt Format gt JSON lt Format gt lt Command gt BYUP sel 200 0K Content type text html Transfer Encoding chunked Date Wed 09 Jul 2014 22 30 23 GMT Server lighttpd 1 4 35 LS Notification NetworkIinfo DeviceMacId 0x00158d0000l1laba29
24. ss of EAGLE ZigBee radio Type of meter reading to schedule Frequency to poll meter in seconds Y Set this rate for this type of reading N Disable polling for this type of reading Description MAC Address of EAGLE ZigBee radio Type of meter reading to get schedule info for If this is omitted then schedule info for all events is requested www rainforestautomation com 20 EAGLE j rainforest REST API Manual 20 Notify Schedulelnfo A Schedulelnfo notification provides the frequency at which a certain event is scheduled to happen and if it is enabled lt ScheduleiInfo gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt Event gt enumeration lt Event gt lt Frequency gt 0x00000000 lt Frequency gt lt Enabled gt enumeration lt Enabled gt lt SchneduLelnro gt Element Range Description DeviceMacld 16 hex digits MAC Address of EAGLE ZigBee radio MeterMacld 16 hex digits Unique MAC Address of meter time message price Summation demand scheduled_prices Event Type of event scheduled profile data billing period block_period Frequency 4 hex digits The frequency in seconds the event will be executed Enabled Y N Y the scheduled event will execute N the scheduled event will not execute 21 Command reboot Send the reboot command to get the EAGLE to restart the specified part of its system lt Co
25. st notifications provide a list of Network nfo notifications showing all of the network interfaces on the EAGLE including those connected to the USB port lt NetworkList gt lt NetworkIinfo gt elements lt NetworkInfo gt lt NetworkIinfo gt elements lt NetworkInfo gt lt NetworkList gt www rainforestautomation com 11 EAGLE X r ainforest REST API Manual 5 Command get_network_status Send the get_network_status command to get detailed information about the status of a network that the EAGLE is connected to In response the EAGLE will send a NetworkStatus notification lt Command gt lt Name gt get network status lt Name gt lt Protocol gt enumeration lt Protocol gt lt MacId gt OxFFFFFFFFFFFFFFFF lt MacId gt lt Command gt Element Range Description Type of network interface only ZigBee Protocol ZigBee Optional supported at this time if not specified the default is ZigBee Macld 16 hex digits Optional etter ve ZigBee radio if 6 Notification NetworkStatus NetworkStatus notifications provide detailed information about a network that the EAGLE is connected to lt NetworkStatus gt lt Protocol gt enumeration lt Protocol gt ProLocol specific elements lt NetworkStatus gt Element Range Description Protocol ZigBee Type of network interface only ZigBee supported at this time 4a NetworkStatus Protocol ZigBee lt NetworkStatus gt lt Pr
26. ted by what has been collected by EAGLE Default is Up to 8 hex digits Optional 4 hex digits Optional all of the existing samples in the interval 17 Notify HistoryData A HistoryData notification contains a series of elements each element is a CurrentsSummation fragment It is sent in response to a get_history_data command lt HistoryData gt lt CurrentSummation gt lt DeviceMacId gt 0OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt SummationDelivered gt OxFFFFFFFF lt SummationDelivered gt lt SummationReceived gt OxFFFFFFFF lt SummationReceived gt lt Multiplier gt OxFFFFFFFF lt Multiplier gt lt Divisor gt OxFFFFFFFF lt Divisor gt lt DigitsRight gt OxFr lt DigitsRight gt lt Digitsheft gt UxFF lt Digitshert gt lt SuppressLeadingZero gt enumeration lt SuppressLeadingZero gt lt CurrentSummation gt lt CurrentSummation gt lt DeviceMacId gt OxFFFFFFFFFFFFFFFF lt DeviceMacId gt lt MeterMacId gt OxFFFFFFFFFFFFFFFF lt MeterMacId gt lt TimeStamp gt OxFFFFFFFF lt TimeStamp gt lt SummationDelivered gt OxFFFFFFFF lt SummationDelivered gt lt SummationReceived gt OxFFFFFFFF lt SummationReceived gt lt Multiplier gt OxFFFFFFFF lt Multiplier gt lt Divisor gt OxFFFFFFFF lt Divisor gt lt DigitsRight gt 0OxFF lt DigitsRight gt lt DigitsLeft gt 0xFF lt DigitsLeft gt lt SuppressLeadingZero
Download Pdf Manuals
Related Search