Rainforest Automation RAVEn User manual

www.rainforestautomation.com
RAVEn™
Radio Adaptor for Viewing Energy
XML API Manual
Version 1.27
March 2013

Rainforest Automation,Inc.
RAVEn™ ™
XML API Manual
2
Copyright © 2013 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 respective 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.

Rainforest Automation,Inc.
RAVEn™
XML API Manual
3
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!
Features ....................................................................................................................... 8!
FEATURES...................................................................................................................... 9!
RAVEn™ Feature ........................................................................................................ 9!
1.!Command: INITIALIZE ........................................................................ 9!
2.!Command: RESTART ......................................................................... 9!
3.!Command: FACTORY_RESET ........................................................... 9!
4.!Command: GET_CONNECTION_STATUS ...................................... 10!
5.!Notify: ConnectionStatus ................................................................... 10!
6.!Command: GET_DEVICE_INFO....................................................... 11!
7.!Notify: DeviceInfo............................................................................... 11!
8.!Command: GET_SCHEDULE ........................................................... 11!
9.!Notify: ScheduleInfo........................................................................... 12!
10.!Command: SET_SCHEDULE.......................................................... 12!
11.!Command: SET_SCHEDULE_DEFAULT ....................................... 13!
12.!Command: GET_METER_LIST....................................................... 13!
13.!Notify: MeterList............................................................................... 13!
Meter Feature............................................................................................................. 14!
1.!Command: GET_METER_INFO........................................................ 14!
2.!Notify: MeterInfo ................................................................................ 14!
3.!Command: GET_NETWORK_INFO.................................................. 15!
4.!Notify: NetworkInfo ............................................................................ 15!
5.!Command: SET_METER_INFO ........................................................ 16!
Time Feature .............................................................................................................. 17!
1.!Command: GET_TIME ...................................................................... 17!
2.!Notify: TimeCluster ............................................................................ 17!
Message Feature ....................................................................................................... 18!
1.!Command: GET_MESSAGE ............................................................. 18!
2.!Notify: MessageCluster...................................................................... 18!

Rainforest Automation,Inc.
RAVEn™
XML API Manual
4
3.!Command: CONFIRM_MESSAGE.................................................... 19!
Price Feature.............................................................................................................. 20!
1.!Command: GET_CURRENT_PRICE ................................................ 20!
2.!Command: SET_CURRENT_PRICE................................................. 20!
3.!Notify: PriceCluster ............................................................................ 21!
Simple Metering Feature ............................................................................................ 22!
1.!Command: GET_INSTANTANEOUS_DEMAND............................... 23!
2.!Notify: InstantaneousDemand ........................................................... 23!
3.!Command: GET_CURRENT_SUMMATION_DELIVERED............... 24!
4.!Notify: CurrentSummationDelivered .................................................. 24!
5.!Command: GET_CURRENT_PERIOD_USAGE............................... 25!
6.!Notify: CurrentPeriodUsage............................................................... 25!
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.
RAVEn™
XML API Manual
5
OVERVIEW
RAVEn™ XML API
The RAVEn™ is a USB device that communicates with a smart meter over a secured ZigBee
wireless network. The RAVEn™ is an endpoint on the network that is authorized and
authenticated to communicate with the smart meter. The XML (eXtensible Markup Language)
API (Application Programming Interface) described in this document provides a mechanism to
allow external applications to receive smart meter data from the 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™. The RAVEn™ sends and receives data as a serial stream. The RAVEn™ uses an 8
bit Extended ASCII character set (code page 1252) to encode the data. This may change in the
future in order to support UTF-8.
Settings for the virtual serial COM port:
•PORT NAME: determined by OS
•BAUD RATE: 115,200
•DATA BITS: 8
•PARITY: N
•STOP BITS: 1
The RAVEn™ uses an asynchronous serial communications model. This means that the
transmit and receive data streams are independent; the RAVEn™ can be sending and receiving
data at the same time. The RAVEn™ does not use hand shaking, acknowledgements, or time
synchronization.
The RAVEn™ is also a ZigBee device. It is ZigBee Smart Energy 1.0 compliant, and is certified
by the ZigBee Alliance to operate according to that standard. Therefore, the XML API options
are restricted to what is allowed by the ZigBee Smart Energy 1.0 standard. The RAVEn™ must
be authorized and authenticated by the ZigBee Coordinator before the RAVEn™ can
communicate with the smart meter. Generally, the smart meter is also the ZigBee Coordinator.
The RAVEn™ 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 RAVEn™ in order to set up the authorization.

Rainforest Automation,Inc.
RAVEn™
XML API Manual
6
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.
The rules for XML Fragments are:
1. XML Fragments are transmitted as a stream; there are no BOF or EOF markers.
2. An XML Fragment is a well formed XML Element.
3. XML Elements do not have XML Attributes.
4. Only the root XML Element has child XML Elements.
5. There is no XML Declaration Section.
6. There are no XML Name spaces.
The RAVEn™ receives commands and sends notifications. A command is a request to the
RAVEn™ to do something. The RAVEn™ will execute the command, which will trigger an
event. RAVEn™ events send out notifications that contain information about the event.
For example:
1. Send a GET_CURRENT_PRICE command, which causes the RAVEn™ to request the
current price stored in the meter;
2. RAVEn™ returns a PriceCluster notification with the current price received from the
meter.
The RAVEn™ will also send notifications when events are triggered by something other than a
command. For instance, when the RAVEn™ receives a new text message from the smart
meter, the RAVEn™ will send a MessageCluster notification. This is why the communications
model is asynchronous; the RAVEn™ sends notifications whenever an event occurs, in addition
to when a command is received.
The format of an XML Fragment is
<tag>
[<string>text</string>]
[<hex>0xFFEEDDCCBBAA99887766554433221100</hex>]
[<int>-987654321</int>]
[<decimal>-7654321.12345</decimal>]
[<![CDATA[binary]]>]
[<enumeration>{A|B|C}</enumeration>]
</tag>
Where:
- <tag> is the tag for the root XML Element
- <string>is the start tag for an element with Extended ASCII string
- <hex> is the start tag for an element with a hexadecimal data
- <int> is the start tag for an element with a signed 32bit integer

Rainforest Automation,Inc.
RAVEn™
XML API Manual
7
- <decimal> is the start tag for an element with a signed decimal(12.5)
- <base64>is the start tag for an element with Base64 data
- <![CDATA[binary]]> is the tag for a CDATA section
- binary is the binary content of the CDATA section
- [ ] brackets indicate optional elements
- <enumeration>is the start tag for an element that can have a specific list of
values.
- {A|B|C} are the different options for the element value
- [<Element> | <Element>] are the different optional elements
- Element names are case insensitive; the case is used strictly for legibility
RAVEN™ receives commands with the following XML Fragment structure:
<Command>
<Name>text</Name>
…
</Command>
Where:
- <Command> is the start tag for the command XML Fragment
- <Name> is the start tag for the name of the command
- …indicates the variable number of command specific parameters
RAVEN™ sends notifications with the following XML Fragment structure:
<tag>
<element>value</element>
…
</tag>
Where:
- <tag> is the start tag for the XML Fragment; each notification will have a unique
tag name;
- <element> is the start tag for an element; there will be one or more child
elements in the fragment; each notification element will have a unique element
name.
- …indicates the variable number of notification specific elements
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.

Rainforest Automation,Inc.
RAVEn™
XML API Manual
8
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
Time
Time and Date information
Message
Text Message information
Price
Price information
Simple Metering
Metering data information
Firmware Update
Firmware upgrade procedure

Rainforest Automation,Inc.
RAVEn™
XML API Manual
9
FEATURES
RAVEn™ Feature
The RAVEn™ Feature provides the commands and notifications for managing the configuration
of the RAVEn™ and diagnosing the communications to the smart meter.
Key commands and notifications include:
•Start up, joining, and connectivity status notifications
•Restarting the RAVEn™ (Soft Reboot)
•Resetting the RAVEn™ (Factory Reset, will Decommission device)
•Get revision information for RAVEn™
•Configuring the scheduler on the RAVEn™
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.
<Command>
<Name>initialize</Name>
</Command>
2. Command: RESTART
Send the RESTART command to have the RAVEn™ go through the start-up sequence. This
command is useful for capturing any diagnostic information sent during the start-up sequence.
<Command>
<Name>restart</Name>
</Command>
3. Command: FACTORY_RESET
Send the FACTORY_RESET command to decommission the RAVEn™. This command erases
the commissioning data and forces a restart. On restart, the RAVEn™ will begin the
commissioning cycle.
<Command>
<Name>factory_reset</Name>
</Command>

Rainforest Automation,Inc.
RAVEn™
XML API Manual
10
4. Command: GET_CONNECTION_STATUS
Send the GET_CONNECTION_STATUS command to get the RAVEn™ connection information.
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>
[<Description>{string}</Description>]
[<StatusCode>0xFF</StatusCode>]
[<ExtPanId>0xFFFFFFFFFFFFFFFF</ExtPanId>]
[<Channel>00</Channel>]
[<ShortAddr>0xFFFF</ShortAddr>]
<LinkStrength>0xFF</LinkStrength>
</ConnectionStatus>
Element
Range
Description
DeviceMacId
0xFFFFFFFFFFFFFFFF
Unique MAC Address of the RAVEn™
MeterMacId
0xFFFFFFFFFFFFFFFF
Unique MAC Address of meter
Status
Initializing | Network
Discovery | Joining | Join:
Fail | Join: Success |
Authenticating |
Authenticating: Success |
Authenticating: Fail |
Connected | Disconnected |
Rejoining
Indicates the current state of the device
Description
Text; Optional
Gives a description of the device state
StatusCode
0x00 – 0xFF; Optional
If available, provides a status code for the
current state
ExtPanId
0x0 -
0xFFFFFFFFFFFFFFFF;
Optional
Provides the extended PAN ID of the
network the device is trying to join or has
joined
Channel
11 – 26; Optional
Indicates the channel on which the device is
operating
ShortAddr
0x0000 – 0xFFFF; Optional
The short address assigned to the
RAVEn™ by the network coordinator
LinkStrength
0x00 – 0x64
Indicates the strength of the link