Summary of Contents for Rainforest Automation RAVEn
- Page 1 RAVEn™ Radio Adaptor for Viewing Energy XML API Manual Version 1.27 March 2013 www.rainforestautomation.com...
- Page 2 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.
-
Page 3: Table Of Contents
RAVEn™ XML API Manual RAVEn™ – Radio Adapter for Viewing Energy RFA-Z106 Version 1.27 XML API Manual Table of Contents OVERVIEW ........................5 RAVEn™ XML API ...................... 5 Communications Model ....................5 Data Structures ......................6 ... - Page 4 7. Command: GET_LAST_PERIOD_USAGE ........26 8. Notify: LastPeriodUsage ..............27 9. Command: CLOSE_CURRENT_PERIOD ......... 27 10. Command: SET_FAST_POLL ............28 11. Command: GET_PROFILE_DATA ..........28 12. Notify: ProfileData ................29 Rainforest Automation, Inc.
-
Page 5: Overview
RAVEn™. Communications Model The RAVEn™ is a USB device; the USB port is mapped to a virtual serial port, which shows up as a standard COM port. Applications that can connect to a COM port can also connect to the RAVEn™. -
Page 6: Data Structures
XML API Manual Data Structures The RAVEn™ sends and receives data as a serial stream. The data is structured as XML Fragments. An XML Fragment is a stripped down XML Element. The RAVEn™ uses XML Fragments to simplify the parsing of the data stream, while providing a data structure that is flexible and human readable. - Page 7 The first element of every notification is always the MAC ID of the RAVEn™ that generated the notification. Note: the RAVEn™ does not send or require the MAC ID of the meter when in single meter operation. This may change in the future. For multiple meters, the meter MAC ID will always be required.
-
Page 8: Features
RAVEn™ XML API Manual Features RAVEN™ XML Fragments are loosely organized as Features, where each Feature is a logical grouping of notifications and commands. The API is organized into these Features: Feature Description RAVEn™ RAVEn™ device specific information Meter Meter specific information... -
Page 9: Features
• 1. Command: INITIALIZE Send the INITIALIZE command to have the RAVEn™ reinitialize the XML parser. Use this command when first connecting to the RAVEn™ prior to sending any other commands. While initialization is not required, it will speed up the initial connection. -
Page 10: Command: Get_Connection_Status
The RAVEn™ will send a ConnectionStatus notification in response. <Command> <Name>get_connection_status</Name> </Command> 5. Notify: ConnectionStatus The RAVEn™ will send notifications during the start-up sequence and during the join/re-join sequence. These notifications are useful for diagnostic purposes. <ConnectionStatus> <DeviceMacId>0xFFFFFFFFFFFFFFFF</DeviceMacId> <MeterMacId>0xFFFFFFFFFFFFFFFF</MeterMacId> <Status>{enumeration}</Status>... -
Page 11: Command: Get_Device_Info
8. Command: GET_SCHEDULE Send the GET_SCHEDULE command to get the RAVEn™ scheduler information. The RAVEn™ will send the ScheduleInfo notification in response; or, RAVEn™ will send a series of ScheduleInfo notifications if the Event field is omitted. <Command>... -
Page 12: Notify: Scheduleinfo
N: the scheduled event will not execute. 10. Command: SET_SCHEDULE Send the SET_SCHEDULE command to update the RAVEn™ scheduler. The command options include setting the frequency of the command in seconds, and disabling the event. If the event is disabled the frequency is set to 0xFFFFFFFF. -
Page 13: Command: Set_Schedule_Default
The type of event being scheduled; if omitted, summation | message command applies to all scheduled items. 12. Command: GET_METER_LIST Send the GET_METER_LIST command to get the list of meters the RAVEn™ is connected to. The RAVEn™ will send a MeterList notification in response. <Command> <Name>get_meter_list</Name>... -
Page 14: Meter Feature
Getting information about the type of meter and its identifiers • Finding the status of the network connection and the quality of the link • 1. Command: GET_METER_INFO Send the GET_METER_INFO Command to get the meter information. The RAVEn™ will send a MeterInfo notification in response. <Command> <Name>get_meter_info</Name> [<MeterMacId>0xFFFFFFFFFFFFFFFF</MeterMacId>] </Command>... -
Page 15: Command: Get_Network_Info
Y: to start transmitting data to host N: to stop transmitting data to host 3. Command: GET_NETWORK_INFO Send the GET_NETWORK_STATUS Command to get the status of device on the network. The RAVEn™ will send a NetworkInfo notification in response. <Command> <Name>get_network_info</Name> </Command>... -
Page 16: Command: Set_Meter_Info
Meter nick name Account Text; Optional Account Identification Auth Text; Optional Authentication code Host Text; Optional Hosting Provider Enabled Y | N; Optional Y: to start transmitting data to host N: to stop transmitting data to host Rainforest Automation, Inc. -
Page 17: Time Feature
Notify what the time is on a smart meter • Ask for the latest time from a smart meter • 1. Command: GET_TIME Send the GET_TIME command to get the current time. The RAVEn™ will send a TimeCluster notification in response. <Command> <Name>get_time</Name> [<MeterMacId>0xFFFFFFFFFFFFFFFF</MeterMacId>] [<Refresh>{enumeration}</Refresh>]... -
Page 18: Message Feature
Message notifications when a smart meter receives a message • Message confirmation by the User • 1. Command: GET_MESSAGE Send the GET_MESSAGE command to have the RAVEn™ get the current text message. The RAVEn™ will send a MessageCluster notification in response. <Command> <Name>get_message</Name> [<MeterMacId>0xFFFFFFFFFFFFFFFF</MeterMacId>] [<Refresh>{text}</Refresh>]... -
Page 19: Command: Confirm_Message
Cancel Pending: Indicates message is in cancel pending queue 3. Command: CONFIRM_MESSAGE Send the CONFIRM_MESSAGE command to have the RAVEn™ confirm the message as indicated by the ID. To verify that the message confirmation was sent, use a GET_MESSAGE command with Refresh=Y. -
Page 20: Price Feature
The Price field is an integer; the Trailing Digits field indicates where the decimal place goes (i.e., the divisor). The user-defined price will override the meter price. Setting the user-defined price to zero will clear the user entered price in the RAVEn™, and the meter price will be used, if available. -
Page 21: Notify: Pricecluster
PriceCluster notification provides the current price in effect on the meter, or the user-defined price set on the RAVEn™. If the user-defined price is set, the meter price is ignored. If the user- defined price is not set and the meter price is not set, then the price returned is zero. Either the TierLabel or the RateLabel, or neither, may be provided;... -
Page 22: Simple Metering Feature
Last Period Summation notification from the RAVEn™ • Fast Poll mode allows the RAVEn™ to return almost real time data readings from the • smart meter; usually for when the User wants to see the effect of turning something on or off. -
Page 23: Command: Get_Instantaneous_Demand
Send the GET_INSTANTANEOUS_DEMAND command to get the demand information from the RAVEn™. Set the Refresh element to Y to force the RAVEn™ to get the information from the meter, rather than its local cache. The RAVEn™ will send an InstantaneousDemand notification in response. -
Page 24: Command: Get_Current_Summation_Delivered
Send the GET_CURRENT_SUMMATION_DELIVERED command to get the summation data from the RAVEn™. Set the Refresh element to Y to force the RAVEn™ to get the data from the meter, rather than its local cache. The RAVEn™ will send a CurrentSummationDelivered notification in response. -
Page 25: Command: Get_Current_Period_Usage
CurrentPeriodUsage notification provides the total consumption for the current accumulation period, as calculated by the RAVEn™. The Multiplier and Divisor are used to calculate the actual decimal value from the CurrentPeriod, which is an integer. If the Multiplier and Divisor are Zero, then ignore them for calculation purposes (i.e., treat them as a value of one). -
Page 26: Command: Get_Last_Period_Usage
UTC Time of the start of the current period data accumulation 7. Command: GET_LAST_PERIOD_USAGE Send the GET_LAST_PERIOD_USAGE command to get the previous period accumulation data from the RAVEn™. The RAVEn™ will send a LastPeriodUsage notification in response. <Command> <Name>get_last_period_usage</Name> [<MeterMacId>0xFFFFFFFFFFFFFFFF</MeterMacId>] </Command>... -
Page 27: Notify: Lastperiodusage
8. Notify: LastPeriodUsage LastPeriodUsage notification provides the total consumption for the previous accumulation period as calculated by the RAVEn™. The Start Date and End Date are UTC timestamps indicating the start and end times that define the previous period. <LastPeriodUsage>... -
Page 28: Command: Set_Fast_Poll
XML API Manual 10. Command: SET_FAST_POLL Send the SET_FAST_POLL command to have the RAVEn™ set the fast poll mode on the meter. In fast poll mode, the meter will send Instantaneous Demand updates at the frequency requested. This is a ZigBee Smart Energy 1.1 feature. -
Page 29: Notify: Profiledata
XML API Manual 12. Notify: ProfileData The RAVEn™ sends the ProfileData notification in response to the GET_PROFILE_DATA command. It provides a series of interval data as recorded by the meter. The interval data was captured with a periodicity specified by the ProfileIntervalPeriod field. The content of the interval data depends on the type of information requested using the IntervalChannel field in the GET_PROFILE_DATA command.
Need help?
Do you have a question about the RAVEn and is the answer not in the manual?
Questions and answers