Device API - Controls

XML
Commands can be sent from the server any time the device/gateway performs a POST or GET. All commands begin with an XML header followed by an <s2h> tag (server-to-hub). The <s2h> tag contains the version number of the API, currently "2", sequence number of the message generated by the server, and a status indicator for the last device-to-server message received by the server.

Within the <s2h> tag may be a command XML block containing a "type" attribute describing the action to take, a command identifier for acknowledgments, and the identifier for the device that is to execute the command.

Like a measurement, each individual parameter within the command XML block contains a name and a value as well as an optional index attribute to indicate which actuation point is being controlled. The name may translate to the name of a function to execute, or a variable to set for example. The value of the <param> tag may be the argument to the function, or the value of the variable to set. The exact parameters used are dependent upon the capabilities of the device and how those capabilities are exposed, defined by registering the device type with the Internet of Things Platform.

Multiple parameters may be included in a single command and must execute atomically, resulting in a single result code back to the server. Every command received by the device/gateway MUST return a result code back to the cloud. If a response is not received, the server will continue attempting to deliver the command, which may result in duplicate commands received at the device. Devices / proxies must be able to appropriately deal with duplicate commands.

The type attribute describes an action to take, typically either set or delete. 'Get' is not needed because the devices should always upload and mirror their most up-to-date parameters at the cloud. The table below describes the accepted 'type' values.

Examples
The examples below are meant to demonstrate the structure of the XML. The actual parameter names you use in your device will, again, be device-dependent and based on how you register your device with the ESP.

Boolean Commands
Turn outlets 0 and 3 OFF, and outlets 1 and 2 ON, a multi-outlet power strip that is connected through a gateway:
Command:
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="123" status="ACK">
  <command deviceId="B0C8ADFFFE000001" type="set" cmdId="1">
    <param name="outletStatus" index="0">0</param>
    <param name="outletStatus" index="1">1</param>
    <param name="outletStatus" index="2">1</param>
    <param name="outletStatus" index="3">0</param>
  </command>
</h2s>

Response
The gateway (with ID 0123456ABCDEF) would respond back to the server on behalf of the device after the command executes successfully:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF">
  <response cmdId="1" result="0" />
</h2s>

Please see the Result Codes for accepted result codes.

Physically Identify a Device
Identify a particular device by buzzing its speaker or blinking its LEDs for 5 seconds. In this example, the device hosting the Internet connection is the same one receiving the command:
Command:
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="124" status="ACK">
  <command deviceId="0123456ABCDEF" type="set" cmdId="2">
    <param name="identifyDevice">5</param>
  </command>
</h2s>

Response:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF">
  <response cmdId="2" result="0" />
</h2s>

Delete a Device at a Proxy
Command:
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="125" status="ACK">
  <command deviceId="0123456ABCDEF" type="delete" cmdId="3">
    <param name="deviceId" index="0">B0C8ADFFFE000001</param>
  </command>
</h2s>

Response:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF";>
  <response cmdId="3" result="0" />
</h2s>

Discover New Devices
Command:
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="126" status="ACK">
  <command deviceId="0123456ABCDEF" type="discover" cmdId="4" />
</h2s>

Response:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF">
  <response cmdId="4" result="0" />
</h2s>

Newly discovered devices will make themselves known to the server by uploading measurements.

Dim a Light to 55% in Outlet 2
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="126" status="ACK">
  <command deviceId="B0C8ADFFFE000001" type="set" cmdId="5">
    <param name="dimmer" index="2">55</param>
  </command>
</h2s>

Response:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF">
  <response cmdId="5" result="0" />
</h2s>

Send Text to a Display
Command:
<?xml version="1.0" encoding="utf-8" ?>
<s2h ver="2" seq="127" status="ACK">
  <command deviceId="0123456ABCDEF" type="set" cmdId="6">
    <param name="text">Hello World</param>
  </command>
</h2s>

Response:
<?xml version="1.0" encoding="UTF-8"?>
<h2s ver="2" hubId="0123456ABCDEF">
  <response cmdId="6" result="0" />
</h2s>