Codecore Logo
Quick Search
»
Advanced Search »

XML Communication Protocol

RSS

The XML Communication Protocol is one of several protocols which 3rd party developers can use to interface with the system and receive notifications. This is a richer alternative to the simple RESTful Web Service using a persistent TCP connection.

Protocol Basics

Connection

Transport: TCP
Port: 33905

The protocol uses an XML like message structure. The message container is an XML element, while the message data (or payload) can be anything.

Message Container Format

A message consists of an xml element container and a payload within it. At this time, only XML payloads are supported. All payloads sent and received must be wrapped as follows:


<J9Message len="123" cksum="234" id="1" async="true">
  ...
</J9Message>

len: The length of the payload (J9Message element's inner text). (REQUIRED)
cksum: The checksum of the payload. (REQUIRED)
id: An OPTIONAL identifier that identifies this command message. The response from the server will contain this id for reference and can be helpful when running commands asynchronously. (OPTIONAL)
async: An OPTIONAL value that indicates if the message should be processed asynchronously. Defaults to "false". true/false (OPTIONAL)

The xml examples here usually use white space for readability, however for better performance it is recommended that white space is not included.

Payload Format

The only supported payload format at this time is XML. Command payloads instruct the server to run a command.


<commandname>
  ...
</commandname>

commandname: The name of the command.

The content of the command name element is dependant on the command.

Command Response Format

The response will be sent after the command has completed.


<response cmd="commandname" id="123">
  ...
<response>

commandname: The name of the command that was run.
id: If an id was provided in the header, then it will be included in the response.

The innertext of the command response element is dependant on the command that was run.

Error Format

If an error occurs while processing a message the following will be sent to the client:


<error id="1">
  <message>blah blah blah</message>
  <payload><![CDATA[...abc...]]></payload>
</error>

id: If a message specified an id, this will be the same id.
message: The error message.
payload: The payload of the original message encoded using base64. Including the payload is optional, as some payloads may be larger than you want to send back. You may also consider truncating large payloads.

Example Session

The following transactions represent a standard session after a connection is established.

Please note that the checksums are not accurate in the examples.

Client sends:

<J9Message len="14" cksum="123" id="1">
  <hello/>
</J9Message>

Server responds with:

<J9Message len="86" cksum="123" id="1">
  <response cmd="hello">
    <t1>ED073BE23D668645AD16C00C359378F7</t1>   
  <response>
</J9Message>

Client sends:

<J9Message len="167" cksum="123" id="2">
  <auth>
    <u>Jim Smith</u>
    <t2>D96795323EFCA947B9B08BE912BFF49C</t2>
    <h>63C010350B1EB75212D4C40CAB8303BBFF7C1C1C47C5CCC8300FA292FAE8BBF9</h>
  </auth>
</J9Message>

Server responds with:

<J9Message len="47" cksum="123" id="2">
  <response cmd="auth">
    <r>ok</r>
  </response>
</J9Message>

Client sends:

<J9Message len="20" cksum="123" id="3">
  <getconfigts/>
</J9Message>

Server responds with:

<J9Message len="87" cksum="123" id="3">
  <response cmd="getconfigts">
    <ts>2009-01-01T00:00:00-7:00</ts>
  </response>
</J9Message>

Command Payloads

hello

Initiates authentication handshaking. This should be the 1st command send by the client and notifies the server that it should begin the authentication handshake. The server will respond with a randomly generated list of bytes. These bytes will be used in a hashing algorithm to send back a response to the server without sending the user's password or password hash.

Client sends:

<hello/>

Server sends back:

<response cmd="hello">
  <t1>ED073BE23D668645AD16C00C359378F7</t1>   
<response>

t1: A random authentication list of bytes from the server formatted in as a hexadecimal string. Each consecutive two characters represent the value of one byte.

The client should take the following steps:

  1. Calculate the MD5 hash of the user entered password.
  2. Create another random list of bytes named t2. The recommended length is between 20 and 40 bytes long. Any length will work, however longer lengths are more secure.
  3. Calculate the MD5 hash of the following contiguous bytes: t2 + password hash + t1
  4. Send the auth command to the server and include t2 and the user name.

The server will then compute the same hash to determine if they match. If they do match then the user entered password is known to be correct.

auth

Authenticate a user. This command should be sent after the response to the hello command is sent by the server. By using this approach we can eliminate the need to transmit the password or the password's hash.

Client sends:

<auth>
  <u>Admin</u>
  <t2>AB9C428629C3A...</t2>
  <h>AB9C428629C3A...</h>
</auth>

u: user name
t2: A random authentication token from the client in hex. The recommended length is between 20 and 40 bytes long. Any length will work, however longer lengths are more secure. Overly long values will slow down network performance.
h: resulting MD5 hash in hex of: t2 + password + t1

Server sends back one of:

<response cmd="auth"><r>ok</r></response>
<response cmd="auth"><r>invalid</r></response>
<response cmd="auth"><r>disabled</r></response>

r: The authentication result.

ok: Successful.
invalid: invalid username or password.
disabled: the account is disabled.

getconfigts

Gets the date/time when the configuration was last changed.

Client sends:

<getconfigts/>

Server sends back::

<response cmd="getconfigts">
  <ts>2009-01-01T00:00:00-7:00</ts>
</response>

ts: The timestamp result.

getdeviceconfig

Gets the configuration for all devices or for a specified device.

Client sends:

<getdeviceconfig>
  <dn>elkm1</dn>
</getdeviceconfig>

dn: The OPTIONAL name of the device. If no dn element is present then the configuration for all the devices will be returned.

Server sends back:

<response cmd="getdeviceconfig">
  <Config>...</Config>
</response>

getdevicestate

Gets the current state of all devices or of a specified device.

Client sends:

<getdevicestate>
  <dn>elkm1</dn>
</getdevicestate>

dn: The OPTIONAL name of the device. If no dn element is present then the state for all the devices will be returned.

Server sends back:

<response cmd="getdevicestate">
  <States>...</States>
</response>

getproperty

Get a device's property's value.

Client sends:

<getproperty>
  <dn>elkm1</dn>
  <pn>LightLevel</pn>
  <ix>2</ix>
</getproperty>

dn: Device Name
pn: Property Name
ix: If the property is an array element then this is the property index. If the property is not an array element then the ix xml element should not be included

Server sends back:

<response cmd="setproperty">
  <t>...</t>
  <v>...</v>
</response>


t: The datatype of the value. One of: string, number, boolean, datetime, bytearray.
v: The formatted representation of the value. See the setproperty variable for value formatting examples.

setproperty

Set a device's property value.

Client sends:

<setproperty>
  <dn>elkm1</dn>
  <pn>LightLevel</pn>
  <ix>2</ix>
  <t>number</t>
  <v>55</v>
</setproperty>

dn: Device Name
pn: Property Name
ix: If the property is an array element then this is the property index. If the property is not an array element then the ix xml element will not be present.
t: The datatype of the value. One of: string, number, boolean, datetime, bytearray.
v: The formatted representation of the value.

Examples:

String: <t>string</t><v>Hello</v>
Number: <t>number</t><v>12</v>
Boolean: <t>boolean</t><v>true</v>
DateTime: <t>datetime</t><v>2009-07-10T12:29:44-07:00</v>
ByteArray: <t>bytearray</t><v>SGVsbG8gV29ybGQ=</v>

Server sends back:

<response cmd="setproperty"/>

runscript

Run a script.

Client sends:

<runscript>
  <s>elkm1.TurnOnLight(2);</s>
</runscript>

s: The script to run.

Server sends back:

<response cmd="runscript">
  <v>...</v>
  <t>...</t>
</response>

v: The return value.
t: The type of the return value. string, int32, bool, datetime, byte[]

nop

No Operation. This can be used as a heartbeat to check the connection state. The server will send this out every 30 to 60 seconds and the client application must respond, or the server will assume the connection has been lost. The client can also send this command, and the server will respond.

Client sends:

<nop/>

Server sends back:

<response cmd="nop"/>

disconnect

Indicates that the connection should be closed.

Client sends:

<disconnect/>

The server does not respond, and closes the connection.

Device Property Value Change Notifications

When device property changes are detected by the master service, a notification is sent. Multiple notifications can be included in the payload and can be sent at any time.

Server sends:

<dpvcs>
  <dpvc>
    <dn>vars</dn>
    <pn>IsHome</pn>
    <ppt>boolean</ppt>
    <ppv>true</ppv>
  </dpvc>
  <dpvc>
    <dn>weather</dn>
    <pn>Highs</pn>
    <pi>1</pi>
    <ppt>number</ppt>
    <ppv>75</ppv>
  </dpvc>
  <dpvc>
    <dn>weather</dn>
    <pn>Lows</pn>
    <pi>1</pi>
    <ppt>number</ppt>
    <ppv>62</ppv>
  </dpvc>
</dpvcs>

dn: Device name.
pn: Property name.
pi: If the property is an array element then this is the property index. If the property is not an array element then this xml element will not be present.
ppt: The datatype of the value. One of :string, number, boolean, datetime, bytearray.
ppv: The formatted representation of the value. See the setproperty variable for value formatting examples.
Privacy Policy | Conditions Of Use

Copyright ©2014 Codecore Technologies, All rights reserved.