This document describes the TCP/IP protocol used by caiman or other implementing clients to communicate with Streamline version 5.24 and later. Use this information to build a customized client to communicate energy data to Streamline. The caiman source code, distributed as part of DS-5, is the reference implementation of this protocol. The protocol may change with future releases of Streamline, but Streamline will maintain backwards compatibility with this version of the protocol so that clients need only implement one version of the protocol. Streamline requires that your client is able to parse and generate simple XML and ignore additional or unexpected nodes or attributes. Because the XML features described in this protocol documentation are the only ones used, this protocol does not require the more complex features of XML.
A handshake is required so that your client and Streamline can recognize each other. It consists of ASCII newline (\n) delimited strings. If the client receives a string it does not recognize, the string must be discarded and another string is read.
The standard Streamline client is caiman. But, as you can customize caiman and call it what you wish, the term client is used generically to refer to your customized protocol.
Further communication from Streamline comes as Commands
Streamline issues commands that consist of a header and a body. Streamline expects a Response to these commands from the client.
| Name | Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Code | int8 | The type of command
|
||||||||||
| Length | Little Endian int32 | Number of bytes in the body |
If the client receives an unrecognized command, it should respond with a NAK.
Command code 0 is a request from Streamline for XML. The root node is request and it has the type attribute that tells the client which XML is required. For example, this is a request for Captured XML
<?xml version="1.0" encoding="US-ASCII"?>
<request type="captured">
</request>
| Request | Response Code | Response Body |
|---|---|---|
| <request type="captured"> | XML | Captured XML Streamline requests Captured XML prior to starting a capture. |
The APC Start command does not have a body. This command initiates a capture and readies Streamline to receive APC Data Responses. No ACK is expected and no further XML exchange takes place. If a failure occurs, the client should send an Error.
The APC Stop command also does not have a body. This command triggers the end of the APC and no ACK is expected. APC Data Responses can continue to arrive until all captured data is sent, then the connection should be closed. If a failure occurs, the client should send an Error.
The Disconnect command, which closes the connection to the target, does not contain a command body. No ACK is expected.
The Ping command does not have a body. Send an ACK response to this command.
Responses consist of a header followed by a body
The format for the response header is identical to that of the Command Header but the Codes are different
| Name | Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Code | int8 | The type of command
|
||||||||||
| Length | Little Endian int32 | Number of bytes in the body |
The body should contain XML, the format of which is dependent on the Request type. For a list of types, see Request XML Body
If the length is zero, it is the End of Sequence message which indicates that all APC data has been transmitted to Streamline. Otherwise it is the sample stream where each sample contains one little-endian value of size bytes for every source as specified in Captured XML. So a sample consists of size*source bytes. All values are represented in thousandths, i.e. in milli-volts, amps, and watts.
This response, which indicates the Command was successful, does not have a response body.
Indicates a synchronous non-fatal error occurred when handling a request. It can contain a UTF-8 error message. The length is specified in the header, so no NULL character is expected. Indicates that the Command failed, but that the connection can continue.
Indicates a synchronous fatal error occurred when responding to a request. A UTF-8 error message. The length is specified in the header, so no NULL character is expected. Use this response when the error is terminal and the connection must be closed. Errors may be sent without a request, but Streamline may not process them immediately.
Captured XML contains information about a capture session.
captured
The captured root node of Captured XML has one target child node, one counters child node, and the following attributes:
| Name | Type | Description |
|---|---|---|
| version | Integer | 240 |
target
The captured node always contains one target child node. The target child node has the following attributes:
| Name | Type | Description |
|---|---|---|
| name | String | The name of the energy capture device |
| sample_rate | Integer | Number of samples collected per second |
| sources | Integer | Number of counters collected per sample |
| size | Integer | Number of bytes per sample source, one of 1, 2 or 4. |
counters
The captured node always contains one counters node. The counters node has the following child node:
counter
The counters node can contain any number of counter child nodes. The counter child node contains the following attributes:
| Name | Type | Description |
|---|---|---|
| source | Integer | Order of this counter in the APC data |
| channel | Integer | Channel this counter corresponds to |
| type | String | One of Power, Voltage or Current |
| resistance | Integer | The resistance that corresponds to the channel |
Example:
<?xml version="1.0" encoding='UTF-8'?>
<captured version="240">
<target name="ARM Streamline Energy Probe" sample_rate="10000" sources="6" size="4"/>
<counters>
<counter source="0" channel="0" type="Power" resistance="20"/>
<counter source="2" channel="0" type="Current" resistance="20"/>
<counter source="1" channel="0" type="Voltage" resistance="20"/>
<counter source="3" channel="1" type="Power" resistance="20"/>
<counter source="5" channel="1" type="Current" resistance="20"/>
<counter source="4" channel="1" type="Voltage" resistance="20"/>
</counters>
</captured>