<p>Response codes have been removed and replaced by XMPP compliant IQ error stanzas. The table below shows how old status codes map to XMPP IQ error elements.</p>
<p>The <strong>getFormResponse</strong> element has been removed.</p>
<p>The <strong>setResponse</strong> is now only used when configuration is successful.</p>
<p>The <strong>parameter</strong> subelement to <strong>setResponse</strong> has been reintroduced. Examples are provided in XEP-0324.</p>
<p>The element <strong>paramError</strong> has been introduced, and can be used to provide error information that are linked to control parameters.</p>
<p>Added anchors to all second level subsections.</p>
<p>The section 'Reading current control states' has been updated to include two methods: One simple method only using control forms, and a second, using Sensor Data (XEP-0323).</p>
<p>Harmonization of data types between XEP-0323 and XEP-0325.</p>
<p>The attribute <strong>writable</strong> used to correlate fields in XEP-0323 with control parameters is described.</p>
</remark>
</revision>
<revision>
<version>0.2</version>
<date>2014-03-10</date>
<initials>pw</initials>
<remark>
<p>Namespace in dynamic form examples has been changed to urn:xmpp:xdata:dynamic.</p>
<p>Corrected the namespace used for parameterGroup elements in the examples of the document.</p>
<p>Added support for color values with alpha channel.</p>
<p>Updated the schema to more strictly validate references to x-data forms.</p>
<p>Schema was updated to reflect the correct relationship between the x-data subelement in a set operation.</p>
<p>Fixed links to documents with new numbers.</p>
<p>Changed namespace urn:xmpp:sn to urn:xmpp:iot</p>
<p>Schema was corrected: The parameter sub-element in the setResponse element was removed.</p>
</remark>
</revision>
<revision>
<version>0.1</version>
<date>2013-05-06</date>
<initials>psa</initials>
<remark>
<p>Initial published version approved by the XMPP Council.</p>
Actuators are devices in sensor networks that can be controlled through the network and act with the outside world. In sensor networks and Internet of Things applications,
actuators make it possible to automate real-world processes. This document defines a mechanism whereby actuators can be controlled in XMPP-based sensor networks, making it
possible to integrate sensors and actuators of different brands, makes and models into larger Internet of Things applications.
</p>
<p>
Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power).
Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily with millions of devices in peer-to-peer networks.
</p>
<p>
Sensor networks contains many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table:
</p>
<tablecaption='Sensor Network XEPs'>
<tr>
<th>XEP</th>
<th>Description</th>
</tr>
<tr>
<td>xep-0000-IoT-BatteryPoweredSensors</td>
<td>Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.</td>
</tr>
<tr>
<td>xep-0000-IoT-Discovery</td>
<td>Defines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.</td>
</tr>
<tr>
<td>xep-0000-IoT-Events</td>
<td>Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured.</td>
</tr>
<tr>
<td>xep-0000-IoT-Interoperability</td>
<td>Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.</td>
</tr>
<tr>
<td>xep-0000-IoT-Multicast</td>
<td>Defines how sensor data can be multicast in efficient ways.</td>
</tr>
<tr>
<td>xep-0000-IoT-PubSub</td>
<td>Defines how efficient publication of sensor data can be made in sensor networks.</td>
</tr>
<tr>
<td>xep-0000-IoT-Chat</td>
<td>Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.</td>
</tr>
<tr>
<td>XEP-0322</td>
<td>
Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered
in all sensor network implementations where memory and packet size is an issue.
</td>
</tr>
<tr>
<td>XEP-0323</td>
<td>
Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks.
It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs.
</td>
</tr>
<tr>
<td>XEP-0324</td>
<td>Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.</td>
</tr>
<tr>
<td>XEP-0325</td>
<td>This specification. Defines how to control actuators and other devices in Internet of Things.</td>
</tr>
<tr>
<td>XEP-0326</td>
<td>Defines how to handle architectures containing concentrators or servers handling multiple sensors.</td>
</tr>
<tr>
<td>XEP-0331</td>
<td>Defines extensions for how color parameters can be handled, based on &xep0004;</td>
</tr>
<tr>
<td>XEP-0336</td>
<td>Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.</td>
</tr>
</table>
</section1>
<section1topic='Glossary'anchor='glossary'>
<p>The following table lists common terms and corresponding descriptions.</p>
<dl>
<di>
<dt>Actuator</dt>
<dd>Device containing at least one configurable property or output that can and should be controlled by some other entity or device.</dd>
</di>
<di>
<dt>Computed Value</dt>
<dd>A value that is computed instead of measured.</dd>
</di>
<di>
<dt>Concentrator</dt>
<dd>Device managing a set of devices which it publishes on the XMPP network.</dd>
</di>
<di>
<dt>Field</dt>
<dd>
One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc.
Fields should be unique within the triple (Node ID, Field Name, Timestamp).
</dd>
</di>
<di>
<dt>Field Name</dt>
<dd>Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.</dd>
</di>
<di>
<dt>Field Type</dt>
<dd>What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.</dd>
</di>
<di>
<dt>Historical Value</dt>
<dd>A value stored in memory from a previous timestamp.</dd>
</di>
<di>
<dt>Identification Value</dt>
<dd>A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)</dd>
</di>
<di>
<dt>Localization information</dt>
<dd>Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.</dd>
</di>
<di>
<dt>Meter</dt>
<dd>A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.</dd>
</di>
<di>
<dt>Momentary Value</dt>
<dd>A momentary value represents a value measured at the time of the read-out.</dd>
</di>
<di>
<dt>Node</dt>
<dd>
Graphs contain nodes and edges between nodes. In Internet of Things, sensors, actuators, meters, devices, gatewats, etc., are often depicted as nodes whereas links between sensors (friendships)
are depicted as edges. In abstract terms, it's easier to talk about a Node, rather than list different possible node types (sensors, actuators, meters, devices, gateways, etc.).
Each Node has a Node ID.
</dd>
</di>
<di>
<dt>Node ID</dt>
<dd>
An ID uniquely identifying a node within its corresponding context. If a globally unique ID is desired, an architecture should be used using a universally accepted
ID scheme.
</dd>
</di>
<di>
<dt>Parameter</dt>
<dd>
Readable and/or writable property on a node/device. The XEP-0326 &xep0326; deals with reading and writing parameters
on nodes/devices. Fields are not parameters, and parameters are not fields.
</dd>
</di>
<di>
<dt>Peak Value</dt>
<dd>A maximum or minimum value during a given period.</dd>
</di>
<di>
<dt>Precision</dt>
<dd>
In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision
determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and
delivering field information in sensor networks should always retain the number of decimals in a message.
</dd>
</di>
<di>
<dt>Sensor</dt>
<dd>
Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc.
Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
</dd>
</di>
<di>
<dt>SN</dt>
<dd>Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.</dd>
</di>
<di>
<dt>Status Value</dt>
<dd>A value displaying status information about something.</dd>
</di>
<di>
<dt>Timestamp</dt>
<dd>Timestamp of value, when the value was sampled or recorded.</dd>
</di>
<di>
<dt>Token</dt>
<dd>
A client, device or user can get a token from a provisioning server. These tokens can be included in requests to other entities in the network, so these entities can validate
access rights with the provisioning server.
</dd>
</di>
<di>
<dt>Unit</dt>
<dd>Physical unit of value. Example: MWh, l/s, etc.</dd>
</di>
<di>
<dt>Value</dt>
<dd>A field value.</dd>
</di>
<di>
<dt>Value Status</dt>
<dd>Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.</dd>
</di>
<di>
<dt>Value Type</dt>
<dd>Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.</dd>
</di>
<di>
<dt>WSN</dt>
<dd>Wireless Sensor Network, a sensor network including wireless devices.</dd>
</di>
<di>
<dt>XMPP Client</dt>
<dd>Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.</dd>
</di>
</dl>
</section1>
<section1topic='Use Cases'anchor='usecases'>
<p>
Control in sensor networks is about setting output values. To make the implementation simple, it is assumed that control of a device can be made using a single message.
If only a simple set operation is requested, a <message> stanza can be sent. If an acknowledgement (ACK) of the operation (or Not-acknowledgement NACK) of the operation
is desired, an <iq> stanza can be used instead.
</p>
<p>
To set control parameters in a device, the <strong>set</strong> command is sent to the device. The set command allows for two different ways of setting control parameters:
</p>
<ul>
<li>Using strongly typed parameters. This way performs best in EXI compression and automation.</li>
<li>Using a weakly typed data form. This might be better for manually setting control parameters, since it allows the device to give the user a better user interface explaining
available control parameters.</li>
</ul>
<p>
What type of control parameters there are available in different types of devices is described in
<note>
XEP-xxxx: Internet of Things - Interoperability <<linkurl='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability.html</link>>
</note>.
</p>
<p>
If the device is a concentrator, as defined in <linkurl='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>,
an handles multiple nodes behind it, which node(s) to control is defined using <strong>node</strong> elements. If not a concentrator,
the use of <strong>node</strong> elements is not necessary, and control commands are sent directly to the device itself.
Note that any response is supressed when sending a message stanza, regardless if the desired control command could be executed or not. The following example shows how the same
control command could be issued using an IQ stanza instead:
<strong>Note:</strong> An empty <strong>setResponse</strong> element means that the control command was executed as provided in the request. Sometimes, the device
can restrict the command to a subset of nodes and/or parameters. In such cases, the <strong>setResponse</strong> element will contain what nodes and/or parameters
were finally used to perform the command. For examples of this, see &xep0324;.
In the following use cases, often a message stanza will be used to illustrate the point. However, the same operation could equally well be used using an iq stanza instead.
By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed.
Following is an example of a control command sent using an iq stanza, where the receiver reports an error back to the caller:
<section2topic='Setting control parameters'anchor='set'>
<p>
The following sub-sections illustrate how to set parameters of different types in a device.
</p>
<section3topic='Setting a single boolean-valued control parameter'>
<p>
Setting single boolean-valued control parameters is a common use case, for instance when controlling digital outputs. The following example shows how a boolean value
can be set in a device.
</p>
<examplecaption='Setting a single boolean-valued control parameter'>
<section3topic='Setting a single 32-bit integer-valued control parameter'>
<p>
Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. The following example shows how a 32-bit integer value
can be set in a device.
</p>
<examplecaption='Setting a single 32-bit integer-valued control parameter'>
<section3topic='Setting a single 64-bit integer-valued control parameter'>
<p>
Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. Even though 32-bit integers may cover most control needs,
it might in some cases be limiting. Therefore, a 64-bit control parameters can be created. The following example shows how a 64-bit integer value
can be set in a device.
</p>
<examplecaption='Setting a single 64-bit integer-valued control parameter'>
<section3topic='Setting a single string-valued control parameter'>
<p>
Setting single string-valued control parameters is a common use case, for instance when controlling text displays. The following example shows how a string value
can be set in a device.
</p>
<examplecaption='Setting a single string-valued control parameter'>
<section3topic='Setting a single double-valued control parameter'>
<p>
Setting single double-valued control parameters can be an alternative form of controlling analog outputs for instance. The following example shows how a double value
can be set in a device.
</p>
<examplecaption='Setting a single double-valued control parameter'>
<section3topic='Setting a single color-valued control parameter'>
<p>
Setting single color values in a device can occur in instances where color or lighting is important. Sometimes color is set using enumerations (string-valued
or integer-valued parameters), and sometimes as a color property. The following example shows how a color value can be set in a device.
</p>
<examplecaption='Setting a single color-valued control parameter'>
<section3topic='Setting multiple control parameters at once'>
<p>
Often, setting a single control parameter is not sufficient for a control action. In these cases, setting multiple control parameters at once is necessary.
The <strong>set</strong> command makes this easy however, since it allows for any number of control parameters to be set at once, as the following example shows:
</p>
<examplecaption='Setting multiple control parameters at once'>
Sometimes the order of control parameters are important in the device, and sometimes the parameters form part of a whole. It depends on the context of the device.
In the above example, the order is important. When the OutputPercent control parameter is set, it will start to fade in or out to the desired setting (10%), using the
fade time set previously. If the FadeTimeMilliseconds control parameter would have been set after the OutputPercent parameter, the fading would have been started using
the previous setting, which might be unknown.
</p>
<p>
The order of control parameters to use depends on the device. The <linkurl='#controlform'>Control Form</link> lists available control parameters of the device in the
order they are expected to be sent to the device. The XEP <linkurl='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability</link> details what control parameters
must be available for different interfaces, and if the order of control parameters is important.
</p>
</section3>
</section2>
<section2topic='Control forms'anchor='forms'>
<section3topic='Getting a control form'anchor='controlform'>
<p>
A client can get a control form containing available control parameters of the device. This is done using the <strong>getForm</strong> command,
In this example, the FadeTimeMilliseconds and OutputPercent control parameters are sent, while the MainSwitch control parameter is left as is. Fading is therefore
parformed only if the dimmer is switched on.
</p>
</section3>
<section3topic='Setting a (partial) control form, Failure'>
<p>
A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza. If there are errors in the form, details are listed
using <strong>paramError</strong> elements in the response, as is shown in the following example:
</p>
<examplecaption='Setting a (partial) control form, Failure'>
<section3topic='Sending a control command to multiple nodes'>
<p>
The client can send the same control command to multiple nodes behind a concentrator by simply adding more <strong>node</strong> elements in the request,
as is shown in the following example:
</p>
<examplecaption='Sending a control command to multiple nodes'>
<section3topic='Sending a control command to multiple nodes, Failure'>
<p>
By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed.
When sending a control command to multiple nodes at a time the device must validate all parameters against all nodes before taking any control action. If
validation fails, an error message is returned and no control action is taken. The following example shows an example of an erroneous control message made to
multiple nodes on a device:
</p>
<examplecaption='Sending a control command to multiple nodes, Failure'>
<section3topic='Getting a control form from multiple nodes'>
<p>
A client can get a control form containing available control parameters common between a set of nodes controlled by the concentrator. This is done
adding a sequence of <strong>node</strong> elements to a <strong>getForm</strong> command sent to the concentrator, as is shown in the following example:
</p>
<examplecaption='Getting a control form from multiple nodes'>
<desc>If the digital output is high (checked) or low (uncheckd).</desc>
<value>true</value>
<xdd:notSame/>
</field>
</x>
</iq>]]>
</example>
<p>
Note that only parameters that are common between the nodes defined in the request must be returned. However, all parameters must have the
<strong>notSame</strong> flag set, regardless of current output status.
</p>
</section3>
<section3topic='Getting a control form from multiple nodes, Failure'>
<p>
A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza. The following example shows the device rejecting
a control form request, because it does not support the handling of common parameters between multiple nodes:
</p>
<examplecaption='Getting a control form from multiple nodes, Failure'>
