mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-05 00:45:05 -05:00
1959 lines
90 KiB
XML
1959 lines
90 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Internet of Things - Control</title>
|
|
<abstract>This specification describes how to control devices or actuators in an XMPP-based sensor network.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0325</number>
|
|
<status>Experimental</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XEP-0001</spec>
|
|
<spec>XEP-0004</spec>
|
|
<spec>XEP-0030</spec>
|
|
<spec>XEP-0122</spec>
|
|
<spec>XEP-0137</spec>
|
|
<spec>XEP-0141</spec>
|
|
<spec>XEP-0323</spec>
|
|
<spec>XEP-0324</spec>
|
|
<spec>XEP-0331</spec>
|
|
<spec>XEP-0336</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>sensor-network-control</shortname>
|
|
<author>
|
|
<firstname>Peter</firstname>
|
|
<surname>Waher</surname>
|
|
<email>peter.waher@clayster.com</email>
|
|
<jid>peter.waher@jabber.org</jid>
|
|
<uri>http://www.linkedin.com/in/peterwaher</uri>
|
|
</author>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2014-04-07</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<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>
|
|
<table caption='XMPP Errors when rejecting a readout request'>
|
|
<tr>
|
|
<th>Obsolete Code</th>
|
|
<th>Error Type</th>
|
|
<th>Error Element</th>
|
|
<th>Namespace</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>InsufficientPrivileges</td>
|
|
<td>cancel</td>
|
|
<td>forbidden</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If the caller lacks privileges to perform the action.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>NotFound</td>
|
|
<td>cancel</td>
|
|
<td>item-not-found</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an item, parameter or data source could not be found.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OtherError, FormError</td>
|
|
<td>modify</td>
|
|
<td>bad-request</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>NotImplemented</td>
|
|
<td>cancel</td>
|
|
<td>feature-not-implemented</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an action has not been implemented in the device.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Locked</td>
|
|
<td>wait</td>
|
|
<td>conflict</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time.</td>
|
|
</tr>
|
|
</table>
|
|
</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>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2013-03-27</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<p>First draft.</p>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<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>
|
|
<table caption='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>
|
|
<section1 topic='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>
|
|
<section1 topic='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 <<link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability.html</link>>
|
|
</note>.
|
|
</p>
|
|
<p>
|
|
If the device is a concentrator, as defined in <link url='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.
|
|
</p>
|
|
<section2 topic='Control commands' anchor='controlcommands'>
|
|
<section3 topic='Sending a control command using a message stanza'>
|
|
<p>
|
|
Following is an example of a control command sent using a message stanza:
|
|
</p>
|
|
<example caption='Message stanza for setting a value'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='digital.output@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<boolean name='Output' value='true'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
<p>
|
|
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:
|
|
</p>
|
|
</section3>
|
|
<section3 topic='Sending a control command using an IQ stanza'>
|
|
<p>
|
|
Following is an example of a control command sent using an iq stanza:
|
|
</p>
|
|
<example caption='IQ stanza for setting a value'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='digital.output@clayster.com'
|
|
id='1'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<boolean name='Output' value='true'/>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='digital.output@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='1'>
|
|
<setResponse xmlns='urn:xmpp:iot:control'/>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
<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;.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section3>
|
|
<section3 topic='Control failure response'>
|
|
<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.
|
|
Following is an example of a control command sent using an iq stanza, where the receiver reports an error back to the caller:
|
|
</p>
|
|
<example caption='Control failure response'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='analog.output@clayster.com'
|
|
id='2'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<boolean name='Output' value='true'/>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='analog.output@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='2'>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
Here, the <strong>paramError</strong> element is used in the IQ Error response, to provide error information related to a specific control parameter.
|
|
</p>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='Setting control parameters' anchor='set'>
|
|
<p>
|
|
The following sub-sections illustrate how to set parameters of different types in a device.
|
|
</p>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single boolean-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='digital.output@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<boolean name='Output' value='true'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single 32-bit integer-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='analog.output@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<int name='Output' value='50000'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single 64-bit integer-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='megaprecision.analog.output@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<long name='Output' value='500000000000000'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single string-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='text.display@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<string name='Row1' value='Temperature: 21.4 °C'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single double-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='analog.output2@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<double name='4-20mA' value='8.192'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a single date-valued control parameter'>
|
|
<p>
|
|
Setting date-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context.
|
|
The following example shows how a date value can be set in a device.
|
|
</p>
|
|
<example caption='Setting a single date-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='alarm@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<date name='TariffStartDate' value='2013-05-01'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a single time-valued control parameter'>
|
|
<p>
|
|
Setting time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context.
|
|
The following example shows how a time value can be set in a device.
|
|
</p>
|
|
<example caption='Setting a single time-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='alarm@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<time name='Alarm Time' value='08:00:00'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a single date & time-valued control parameter'>
|
|
<p>
|
|
Setting date & time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context.
|
|
The following example shows how a date & time value can be set in a device.
|
|
</p>
|
|
<example caption='Setting a single date & time-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='alarm@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<dateTime name='Alarm Time' value='2013-04-02T08:00:00'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a single duration-valued control parameter'>
|
|
<p>
|
|
Setting duration-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context.
|
|
The following example shows how a duration value can be set in a device.
|
|
</p>
|
|
<example caption='Setting a single duration-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='alarm@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<duration name='Alarm Duration' value='PT3M30S'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting a single color-valued control parameter'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='spotlight@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<color name='Color' value='3399FF'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Setting multiple control parameters at once'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='dimmer@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<int name='FadeTimeMilliseconds' value='500'/>
|
|
<int name='OutputPercent' value='10'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
<p>
|
|
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 <link url='#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 <link url='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>
|
|
<section2 topic='Control forms' anchor='forms'>
|
|
<section3 topic='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,
|
|
as is shown in the following example:
|
|
</p>
|
|
<example caption='Getting a control form'>
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='master@clayster.com/amr'
|
|
to='dimmer@clayster.com'
|
|
id='3'>
|
|
<getForm xmlns='urn:xmpp:iot:control' xml:lang='en'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='dimmer@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='3'>
|
|
<x type='form'
|
|
xmlns='jabber:x:data'
|
|
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
|
xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
|
|
xmlns:xdd:='urn:xmpp:xdata:dynamic'>
|
|
<title>Dimmer</title>
|
|
<xdl:page label='Output'>
|
|
<xdl:fieldref var='FaceTimeMilliseconds'/>
|
|
<xdl:fieldref var='OutputPercent'/>
|
|
<xdl:fieldref var='MainSwitch'/>
|
|
</xdl:page>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='FadeTimeMilliseconds' type='text-single' label='Fade Time (ms):'>
|
|
<desc>Time in milliseconds used to fade the light to the desired level.</desc>
|
|
<value>300</value>
|
|
<xdv:validate datatype='xs:int'>
|
|
<xdv:range min='0' max='4095'/>
|
|
</xdv:validate>
|
|
<xdd:notSame/>
|
|
</field>
|
|
<field var='OutputPercent' type='text-single' label='Output (%):'>
|
|
<desc>Dimmer output, in percent.</desc>
|
|
<value>100</value>
|
|
<xdv:validate datatype='xs:int'>
|
|
<xdv:range min='0' max='100'/>
|
|
</xdv:validate>
|
|
<xdd:notSame/>
|
|
</field>
|
|
<field var='MainSwitch' type='boolean' label='Main switch'>
|
|
<desc>If the dimmer is turned on or off.</desc>
|
|
<value>true</value>
|
|
<xdd:notSame/>
|
|
</field>
|
|
</x>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
<strong>IMPORTANT:</strong> The device MUST mark all control parameters in the form as <strong>notSame</strong>, as defined in
|
|
<note>
|
|
XEP-0336: Dynamic Data Forms <<link url='http://xmpp.org/extensions/xep-0336.html'>http://xmpp.org/extensions/xep-0336.html</link>>
|
|
</note>. If an end user would open the control form and press OK (submitting the form) without having entered a value, no value
|
|
would be written, and no action taken. If only a few parameter would be edited, only those parameters would be sent to the device
|
|
and only the corresponding actions taken.
|
|
</p>
|
|
<p>
|
|
All parameters in the form MUST also have validation rules defined according to <link url='http://xmpp.org/extensions/xep-0122.html'>XEP-0122</link>,
|
|
specifically validation data types and ranges where appropriate. This to give type information to the client, which the client later can use to send
|
|
typed control commands directly, without the need to get and send data forms to the device to control it.
|
|
</p>
|
|
<p>
|
|
Also, the device SHOULD group control parameters that should be written together using pages and sections, as described in
|
|
<link url='http://xmpp.org/extensions/xep-0141.html'>XEP-0141</link>. Parameters
|
|
MUST also be ordered in a way so that when set in that order using the typed commands, the corresponding control actions can be successfully executed.
|
|
</p>
|
|
<p>
|
|
<strong>Note:</strong> There's a difference between node parameters, as described in XEP-0326
|
|
<link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>,
|
|
and control parameters as described in this document. For more information about this, please see
|
|
<link url='#nodeparamsvscontrolparams'>Difference between node parameters and node control parameters</link>.
|
|
</p>
|
|
</section3>
|
|
<section3 topic='Getting a control form, Failure'>
|
|
<p>
|
|
A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza, as is shown in the following example:
|
|
</p>
|
|
<example caption='Getting a control form, Failure'>
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='master@clayster.com/amr'
|
|
to='dimmer@clayster.com'
|
|
id='4'>
|
|
<getForm xmlns='urn:xmpp:iot:control' xml:lang='en'/>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='dimmer@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='4'>
|
|
<error type='cancel'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang='en'>Access denied.</text>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a (partial) control form'>
|
|
<p>
|
|
Control actions can be requested by submitting a full or partial control form back to the device. Control parameters not edited MUST not be included
|
|
in the form, and the device in turn MUST ONLY invoke control actions corresponding to the parameters returned in the form.
|
|
</p>
|
|
<p>
|
|
The following example shows how control actions can be requested submitting a control parameters form to the device:
|
|
</p>
|
|
<example caption='Setting a (partial) control form'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='dimmer@clayster.com'
|
|
id='5'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<x type='submit' xmlns='jabber:x:data'>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='FadeTimeMilliseconds' type='text-single'>
|
|
<value>500</value>
|
|
</field>
|
|
<field var='OutputPercent' type='text-single'>
|
|
<value>10</value>
|
|
</field>
|
|
</x>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='dimmer@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='5'>
|
|
<setResponse xmlns='urn:xmpp:iot:control' />
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
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>
|
|
<section3 topic='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>
|
|
<example caption='Setting a (partial) control form, Failure'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='dimmer@clayster.com'
|
|
id='6'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<x type='submit' xmlns='jabber:x:data'>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='FadeTimeMilliseconds' type='text-single'>
|
|
<value>500</value>
|
|
</field>
|
|
<field var='OutputPercent' type='text-single'>
|
|
<value>200</value>
|
|
</field>
|
|
</x>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='dimmer@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='6'>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<paramError xmlns='urn:xmpp:iot:control' var='OutputPercent'>Invalid parameter value.</error>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='Controlling devices behind a concentrator' anchor='concentrator'>
|
|
<p>
|
|
Controlling devices behind a concentrator can be done by specifying what device(s) to control using <strong>node</strong> elements within the
|
|
command elements sent to the concentrator. The following sub-sections show examples of how this is done.
|
|
</p>
|
|
<section3 topic='Sending a control command to a node behind a concentrator'>
|
|
<p>
|
|
To send a control message to a specific node behind a concentrator, the <strong>node</strong> element can be used to identify the node,
|
|
as is shown in the following example:
|
|
</p>
|
|
<example caption='Sending a control command to a node behind a concentrator'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<boolean name='Output' value='false'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Sending a control command to multiple nodes'>
|
|
<![CDATA[
|
|
<message from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'>
|
|
<set xmlns='urn:xmpp:iot:control'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
<boolean name='Output' value='false'/>
|
|
</set>
|
|
</message>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Sending a control command to multiple nodes, Failure'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'
|
|
id='7'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
<node nodeId='AnalogOutput1'/>
|
|
<node nodeId='AnalogOutput2'/>
|
|
<node nodeId='AnalogOutput3'/>
|
|
<node nodeId='AnalogOutput4'/>
|
|
<boolean name='Output' value='true'/>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='concentrator@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='7'>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='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>
|
|
<example caption='Getting a control form from multiple nodes'>
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'
|
|
id='8'>
|
|
<getForm xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
</getForm>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='concentrator@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='8'>
|
|
<x type='form'
|
|
xmlns='jabber:x:data'
|
|
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
|
xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
|
|
xmlns:xdd:='urn:xmpp:xdata:dynamic'>
|
|
<title>DigitalOutput1, DigitalOutput2, ...</title>
|
|
<xdl:page label='Output'>
|
|
<xdl:fieldref var='Output'/>
|
|
</xdl:page>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='Output' type='boolean' label='Output'>
|
|
<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>
|
|
<section3 topic='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>
|
|
<example caption='Getting a control form from multiple nodes, Failure'>
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'
|
|
id='9'>
|
|
<getForm xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
</getForm>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='concentrator@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='9'>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang='en'>Cannot merge control forms from different nodes.</text>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a (partial) control form to multiple nodes'>
|
|
<p>
|
|
You set a control form to multiple nodes controlled by a concentrator by adding <strong>node</strong> elements to the <string>set</string>
|
|
command sent to the concentrator, as is shown in the following example:
|
|
</p>
|
|
<example caption='Setting a (partial) control form to multiple nodes'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'
|
|
id='10'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
<x type='submit' xmlns='jabber:x:data'>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='Output' type='boolean'>
|
|
<value>true</value>
|
|
</field>
|
|
</x>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='concentrator@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='10'>
|
|
<setResponse xmlns='urn:xmpp:iot:control' />
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
<section3 topic='Setting a (partial) control form to multiple nodes, Failure'>
|
|
<p>
|
|
A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza. The following example shows the device rejecting a
|
|
control form submission because one of the control parameters, even though it exists on all nodes, is not of the same type on all nodes.
|
|
</p>
|
|
<example caption='Setting a (partial) control form to multiple nodes'>
|
|
<![CDATA[
|
|
<iq type='set'
|
|
from='master@clayster.com/amr'
|
|
to='concentrator@clayster.com'
|
|
id='11'>
|
|
<set xmlns='urn:xmpp:iot:control' xml:lang='en'>
|
|
<node nodeId='DigitalOutput1'/>
|
|
<node nodeId='DigitalOutput2'/>
|
|
<node nodeId='DigitalOutput3'/>
|
|
<node nodeId='DigitalOutput4'/>
|
|
<node nodeId='AnalogOutput1'/>
|
|
<node nodeId='AnalogOutput2'/>
|
|
<node nodeId='AnalogOutput3'/>
|
|
<node nodeId='AnalogOutput4'/>
|
|
<x type='submit' xmlns='jabber:x:data'>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='Output' type='boolean'>
|
|
<value>true</value>
|
|
</field>
|
|
</x>
|
|
</set>
|
|
</iq>
|
|
|
|
<iq type='error'
|
|
from='concentrator@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='11'>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid type.</error>
|
|
</error>
|
|
</iq>]]>
|
|
</example>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Determining Support' anchor='support'>
|
|
<p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:control" in response to &xep0030; information requests.</p>
|
|
<example caption="Service discovery information request">
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='device@clayster.com/device'
|
|
to='provisioning@clayster.com'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>]]>
|
|
</example>
|
|
<example caption="Service discovery information response">
|
|
<![CDATA[
|
|
<iq type='result'
|
|
from='provisioning@clayster.com'
|
|
to='device@clayster.com/device'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='urn:xmpp:iot:control'/>
|
|
...
|
|
</query>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined
|
|
in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
|
<section2 topic='IQ Error Stanzas' anchor='errors'>
|
|
<p>
|
|
Depending on the reason for rejecting a control request, different XMPP errors can be returned, according to the description in the following table. The table also
|
|
lists recommended error type for each error. Error stanzas may also include <strong>paramError</strong> child elements to provide additional textual error information that
|
|
corresponds to a particular control parameter provided in the request. Any custom error message not related to control parameters is returned in a <strong>text</strong>
|
|
element.
|
|
</p>
|
|
<table caption='XMPP Errors when rejecting a readout request'>
|
|
<tr>
|
|
<th>Error Type</th>
|
|
<th>Error Element</th>
|
|
<th>Namespace</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td>forbidden</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If the caller lacks privileges to perform the action.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td>item-not-found</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an item, parameter or data source could not be found.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>modify</td>
|
|
<td>bad-request</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td>feature-not-implemented</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an action has not been implemented in the device.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>wait</td>
|
|
<td>conflict</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
<td>If an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time.</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
<section2 topic='Reading current control states' anchor='currentstates'>
|
|
<section3 topic='Using Control Forms'>
|
|
<p>
|
|
The simplest way to read the current control states of a device, is to request the control form of the device. The control form should contain the current
|
|
values for all avilable control parameters. However, since current states might not be available at the time of the request, the states might be delivered
|
|
asynchronously, using messages defined in &xep0336;.
|
|
</p>
|
|
<p>
|
|
Using this method has the advantage that a small actuator device does not need to implement other XEPs to support readout of current control states. If the device
|
|
contains all current states readily accessible, there's no need of asynchronous updates making readout simple and straightforward.
|
|
</p>
|
|
</section3>
|
|
<section3 topic='Using XEP-0323 (Sensor Data)'>
|
|
<p>
|
|
A second option is to use &xep0323; to deliver current control states. Since this XEP contains mechanisms allowing for asynchronous readout of control parameter
|
|
states. This makes readout of such parameters simpler. However, there's a need to map values between the two XEPs.
|
|
</p>
|
|
<p>
|
|
If a client wants to know the current status of control parameters using this method, it performs a readout of <strong>Momentary</strong> and <strong>Status</strong> values
|
|
from the device, and from the returned set of values take the current control parameter value according to the following rules, ordered by priority:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
If there's a field marked as momentary value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible
|
|
field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of
|
|
the control parameter.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
If there's a field marked as status value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible
|
|
field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of
|
|
the control parameter.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
To simplify mapping, a <strong>writable</strong> attribute can be used to inform the client if a field name corresponds to a control parameter or not. If the
|
|
attribute is available, it tells the client if it corresponds to a control parameter or not. If not available, no such deduction can be made.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Even though getting the the control form could provide the client with a quicker and easier way of retrieving control parameter values, the form is not
|
|
guaranteed to contain correct current values, as described above.
|
|
</p>
|
|
<p>
|
|
The following table shows how corresponding field values should be converted to the corresponding control parameter value based on field type (x-axis) and
|
|
control parameter type (y-axis). An empty cell means conversion has no meaning and types are not compatible.
|
|
</p>
|
|
<table caption='Conversion of Field Value to Control Parameter Value based on types'>
|
|
<tr>
|
|
<th>325 \ 323</th>
|
|
<th>boolean</th>
|
|
<th>date</th>
|
|
<th>dateTime</th>
|
|
<th>duration</th>
|
|
<th>enum</th>
|
|
<th>int</th>
|
|
<th>long</th>
|
|
<th>numeric</th>
|
|
<th>string</th>
|
|
<th>time</th>
|
|
</tr>
|
|
<tr>
|
|
<th>boolean</th>
|
|
<td>x</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>!=0</td>
|
|
<td>!=0</td>
|
|
<td>!=0</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>color</th>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>RRGGBB or RRGGBBAA</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>date</th>
|
|
<td> </td>
|
|
<td>x</td>
|
|
<td>Date part</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>(1)</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>dateTime</th>
|
|
<td> </td>
|
|
<td>x</td>
|
|
<td>x</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>(2)</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>double</th>
|
|
<td>Z2</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>x</td>
|
|
<td>x</td>
|
|
<td>x</td>
|
|
<td>(3)</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>duration</th>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>x</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>(4)</td>
|
|
<td>x</td>
|
|
</tr>
|
|
<tr>
|
|
<th>int</th>
|
|
<td>Z2</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>Ordinal</td>
|
|
<td>x</td>
|
|
<td>Thunk</td>
|
|
<td>Thunk</td>
|
|
<td>(5)</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>long</th>
|
|
<td>Z2</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>Ordinal</td>
|
|
<td>x</td>
|
|
<td>x</td>
|
|
<td>Thunk</td>
|
|
<td>(5)</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<th>string</th>
|
|
<td>xs:boolean</td>
|
|
<td>xs:date</td>
|
|
<td>xs:dateTime</td>
|
|
<td>xs:duration</td>
|
|
<td>x</td>
|
|
<td>xs:int</td>
|
|
<td>xs:long</td>
|
|
<td>(6)</td>
|
|
<td>x</td>
|
|
<td>xs:time</td>
|
|
</tr>
|
|
<tr>
|
|
<th>time</th>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>Time part</td>
|
|
<td>(7)</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>(8)</td>
|
|
<td>x</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
The following table lists notes with details on how to do conversion, if in doubt.
|
|
</p>
|
|
<table caption="Conversion rules">
|
|
<tr>
|
|
<th>Note</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>(1)</td>
|
|
<td>
|
|
The client should try to convert the string to a date value, first according to the format specified by the XML data type xs:date, and if not possible
|
|
by RFC 822.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(2)</td>
|
|
<td>
|
|
The client should try to convert the string to a date & time value, first according to the format specified by the XML data type xs:dateTime, and if not possible
|
|
by RFC 822.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(3)</td>
|
|
<td>
|
|
The client should try to convert the string to a double-precision floating-point value, first according to the format specified by the XML data type xs:double,
|
|
and if not possible using system-local string to floating-point conversion using local decimal and throusand separator settings.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(4)</td>
|
|
<td>
|
|
The client should try to convert the string to a duration value, first according to the format specified by the XML data type xs:duration,
|
|
and if not possible using the XML data type xs:time.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(5)</td>
|
|
<td>The client should try to convert the string to an integer value according to the corresponding XML data type formats xs:int and xs:long.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(6)</td>
|
|
<td>
|
|
The numeric field value consists of three parts: Numeric value, number of decimals and optional unit. If no unit is provided, only the numeric value should
|
|
be converted to a string (compatible with the XML data type xs:double), using exactly the number of decimals provided in the field. If a unit is provided
|
|
(non-empty string) it must not be appended to the value, if the value is to be used for control output. For presentation purposes however, a space could be
|
|
appended to the number and the unit appended after the space.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(7)</td>
|
|
<td>
|
|
A duration field value contains a xs:duration value. The xs:duration has a larger domain than xs:time, and contains all xs:time values, but xs:time does
|
|
not contain all possible xs:duration values. So, conversion of an xs:duration value to an xs:time value should be performed only if a duration lies
|
|
between 00:00:00 and 23:59:59.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>(8)</td>
|
|
<td>
|
|
The client should try to convert the string to a time value according to the format specified by the XML data type xs:time.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>x</td>
|
|
<td>Use the canonical conversion method.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Z2</td>
|
|
<td>true = 1, false = 0.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>!=0</td>
|
|
<td>Nonzero = true, Zero = false.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RRGGBB</td>
|
|
<td>A string of six hexadecimal characters, the first two the red component of the color, the next two the green component and the last two the blue component.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RRGGBBAA</td>
|
|
<td>A string of eight hexadecimal characters, the first two the red component of the color, the next two the green component, the following two the blue component and the last two the alpha channel.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Date part</td>
|
|
<td>Only the date part of the xs:dateTime value should be used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Time part</td>
|
|
<td>Only the time part of the xs:dateTime value should be used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Ordinal</td>
|
|
<td>Each enumeration value may in the implementation correspond to an ordinal number.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Thunk</td>
|
|
<td>The value is thunked down to lower precision in the canonical way.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>xs:boolean</td>
|
|
<td>Conversion to a string should follow the rules specified for the XML datatype xs:boolean.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>xs:dateTime</td>
|
|
<td>Conversion to a string should follow the rules specified for the XML datatype xs:dateTime.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>xs:duration</td>
|
|
<td>Conversion to a string should follow the rules specified for the XML datatype xs:duration.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<strong>Note:</strong> the namespace prefix <strong>xs</strong> is here supposed to be linked with the XML Schema namespace
|
|
<link url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</link>.
|
|
</p>
|
|
</section3>
|
|
<section3 topic='Harmonization with XEP-0323 (Sensor Data)' anchor='harmonization'>
|
|
<p>
|
|
When representing control parameters as momentary field values, it is important to note the similarities and differences between XEP-0323 (Sensor Data) and XEP-0325 (this document):
|
|
</p>
|
|
<p>
|
|
The <strong>enum</strong> field value data type is not available in XEP-0325 (this document). Instead enumeration valued parameters are represented as <strong>string</strong> control
|
|
parameters, while the control form explicitly lists available options for the parameter. Options are not available in XEP-0323, since it would not be practical to list all options
|
|
every time the corresponding parameter was read out. Instead, the <strong>enum</strong> element contains a data type attribute, that can be used to identify the type of the enumeration.
|
|
</p>
|
|
<p>
|
|
The <strong>numeric</strong> field value data type is not available in XEP-0325 (this document). The reason is that a controller is not assumed to understand unit conversion. Any
|
|
floating-point valued control parameters are represented by <strong>double</strong> control parameters, which lack a unit attribute. They are assumed to have the same unit as
|
|
the corresponding <strong>numeric</strong> field value. On the other hand, floating point valued control parameters without units, are reported using the <strong>numeric</strong>
|
|
field element, but leaving the unit blank.
|
|
</p>
|
|
<p>
|
|
Control pameters of type <strong>color</strong> have no corresponding field value data type. The color value must be represented in another way, and is implementation specific.
|
|
Possibilities include representing the color as a string, using a specific pattern (for instance RRGGBBAA), or report it using multiple fields, one for each component for instance.
|
|
</p>
|
|
<p>
|
|
The <strong>boolean</strong>, <strong>date</strong>, <strong>dateTime</strong>, <strong>duration</strong>, <strong>int</strong>, <strong>long</strong>, <strong>string</strong>
|
|
and <strong>time</strong> field value data types correspond to control parameters having the same types and same element names.
|
|
</p>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='Difference between node parameters and node control parameters' anchor='nodeparamsvscontrolparams'>
|
|
<p>
|
|
A node defined in a concentrator, as defined by <link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>, supporting control has
|
|
two sets of parameters that are different: First a set of node parameters and then a set of control parameters.
|
|
</p>
|
|
<p>
|
|
Node parameters are defined by the node type in the concentrator, as described in <link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>,
|
|
and they are typically used by the concentrator to define the node and how to communicate or interact with the underlying device. The important part here is to know
|
|
that the node parameters are maintained by the concentrator, not the underlying device.
|
|
</p>
|
|
<p>
|
|
Control parameters however, are parameters that reside on the underlying device. When set, they change the actual state or behaviour of the underlying device.
|
|
The connection to the device however, controlled by the concentrator, remains unchanged by such a control parameter update.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Grouping control parameters' anchor='parametergroups'>
|
|
<p>
|
|
Many control actions available in a device can be controlled using only one control parameter. If a device only publishes such control parameters, the order
|
|
of control parameters is not that important.
|
|
</p>
|
|
<p>
|
|
However, there are many control actions that require the client to set multiple control parameters at the same time, for the device to have a complete understanding
|
|
what the client wants to do.
|
|
</p>
|
|
<p>
|
|
<link url='http://xmpp.org/extensions/xep-0141.html'>XEP-0141</link> defines a way to group parameters in a data form by including the concept of pages and sections.
|
|
Even though these pages and sections are used for layout purposes, it should be used by devices to mark parameters that should be used together to perform control actions.
|
|
</p>
|
|
<p>
|
|
The following set of rules should be adhered to, by devices as well as clients, to minimize confusion and resulting errors:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
Control parameters should be listed in control forms in the order the device expects the client to write them back.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Clients should set control parameters in the order they are listed in the corresponding control forms.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Control actions that require multiple control parameters should report these together, grouped by pages or sections within pages,
|
|
to make clear that the parameters belong together.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
For control actions requiring multiple control parameters, devices should strive to publish default values for all parameters involved.
|
|
These default values should then be used by the device if a client happens to write only a subset of the control parameters required for
|
|
a control action. The default value could be the current state of the parameter.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Note however, that one cannot always make the assumption that parameters on the same page or same section in a control form belong to the same control action.
|
|
For instance, a PLC with 16 digital outputs might publish a control form containing a single page with 16 check boxes on (boolean parameters), that can be
|
|
controlled individually.
|
|
</p>
|
|
<p>
|
|
To solve the problem of grouping parameters together, so a client can know which parameters belong together, a new element is defined that can be used in
|
|
data forms: <strong>parameterGroup</strong>. It is optional, but can be added to control parameters in forms, as a way to tell the client that parameters
|
|
having the same <strong>parameterGroup</strong> belong together and should be written together.
|
|
</p>
|
|
<p>
|
|
<strong>Note:</strong> If used, the server must not include a parameter in more than one parameter group at a time. The form may contain multiple group, but each
|
|
parameter must only have at most one <strong>parameterGroup</strong> element.
|
|
</p>
|
|
<p>
|
|
The following example illustrates the use of the <strong>parameterGroup</strong> element to group parameters together.
|
|
</p>
|
|
<example caption='Grouping control parameters'>
|
|
<![CDATA[
|
|
<iq type='get'
|
|
from='master@clayster.com/amr'
|
|
to='spotlight@clayster.com'
|
|
id='12'>
|
|
<getForm xmlns='urn:xmpp:iot:control' xml:lang='en'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='spotlight@clayster.com'
|
|
to='master@clayster.com/amr'
|
|
id='12'>
|
|
<x type='form'
|
|
xmlns='jabber:x:data'
|
|
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
|
xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
|
|
xmlns:xdd:='urn:xmpp:xdata:dynamic'>
|
|
<title>Spotlight</title>
|
|
<xdl:page label='Output'>
|
|
<xdl:fieldref var='MainSwitch'/>
|
|
</xdl:page>
|
|
<xdl:page label='Direction'>
|
|
<xdl:fieldref var='HorizontalAngle'/>
|
|
<xdl:fieldref var='ElevationAngle'/>
|
|
</xdl:page>
|
|
<field var='xdd session' type='hidden'>
|
|
<value>325ED0F3-9A9A-45A4-9634-4E0D41C5EA06</value>
|
|
</field>
|
|
<field var='MainSwitch' type='boolean' label='Main switch'>
|
|
<desc>If the spotlight is turned on or off.</desc>
|
|
<value>true</value>
|
|
<xdd:notSame/>
|
|
</field>
|
|
<field var='HorizontalAngle' type='text-single' label='Horizontal angle:'>
|
|
<desc>Horizontal angle of the spotlight.</desc>
|
|
<value>0</value>
|
|
<xdv:validate datatype='xs:double'>
|
|
<xdv:range min='-180' max='180'/>
|
|
</xdv:validate>
|
|
<xdd:notSame/>
|
|
<parameterGroup xmlns='urn:xmpp:iot:control' name='direction'/>
|
|
</field>
|
|
<field var='ElevationAngle' type='text-single' label='Elevation angle:'>
|
|
<desc>Elevation angle of the spotlight.</desc>
|
|
<value>0</value>
|
|
<xdv:validate datatype='xs:double'>
|
|
<xdv:range min='-90' max='90'/>
|
|
</xdv:validate>
|
|
<xdd:notSame/>
|
|
<parameterGroup xmlns='urn:xmpp:iot:control' name='direction'/>
|
|
</field>
|
|
</x>
|
|
</iq>]]>
|
|
</example>
|
|
<p>
|
|
The above example informs the client that the two parameters HorizontalAngle and ElevationAngle should be written together to control a control action
|
|
(named direction).
|
|
</p>
|
|
<p>
|
|
For more information about common control actions and their parameters, see <link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability.html</link>,
|
|
which defines a set of interoperable interfaces and their abilities.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Node commands vs. control parameters' anchor='commandsvsparameters'>
|
|
<p>
|
|
Nodes behind a concentrator, as defined in <link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>, have an additional means of
|
|
publishing control interfaces: Node Commands.
|
|
</p>
|
|
<p>
|
|
However, there are many differences between Node Commands and Control Parameters, as shown in the following list:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
Node Commands are defined by the node type in the concentrator, and not by the device itself.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Node Commands may do many different things, not only performing control actions.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Parametrized Node Commands require the client to always get a parameter data form, and write back values. There's no way to send simple
|
|
control messages using Node Commands.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Node Commands can be partitioned, grouped and sorted separately.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Each Parametrized Node Command has a separate parameter form, which makes grouping of parameters normal.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Node Commands are only available for nodes controlled by a concentrator.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If implementing a device with many complex control actions (like an advanced PLC), consideration should be made to divide the device into logical groups and
|
|
implement the concentrators interface as well. Then the more complex control actions could be implemented as Node Commands instead of control actions
|
|
as defined in this document, and implementing the simpler more intuitive control actions as described in this document.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Tokens' anchor='tokens'>
|
|
<p>
|
|
If control interaction is performed in a context of delegated trust, as defined in the Sensor Network Provisioning XEP-0324 &xep0324;,
|
|
tokens should always be included in all calls. This to allow devices to check privileges with provisioning servers.
|
|
</p>
|
|
<p>
|
|
The <strong>set</strong> and <strong>getForm</strong> commands support the following token attributes:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<strong>serviceToken</strong>
|
|
</li>
|
|
<li>
|
|
<strong>deviceToken</strong>
|
|
</li>
|
|
<li>
|
|
<strong>userToken</strong>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
For more information about provisioning, see <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link>.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Controlling devices in large subsystems' anchor='largesubsystems'>
|
|
<p>
|
|
Most examples in this document have been simplified examples where a few devices containing a few control parameters have been used. However, in many cases large subsystems with
|
|
very many actuators containing many different control actions have to be controlled, as is documented in
|
|
<link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>.
|
|
In such cases, a node may have to be specified using two or perhaps even three ID's: a <strong>sourceId</strong> identifying the data source controlling the device, a possible
|
|
<strong>cacheType</strong> narrowing down the search to a specific kind of node, and the common <strong>nodeId</strong>. For more information about this, see
|
|
<link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>.
|
|
</p>
|
|
<p>
|
|
<strong>Note:</strong> For cases where the <strong>nodeId</strong> is sufficient to uniquely identify the node, it is sufficient to provide this attribute in the request.
|
|
If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding <strong>nodeId</strong> as requested.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
|
<section2 topic='Time Zones' anchor='timezones'>
|
|
<p>
|
|
All timestamps and dateTime values use the XML data type xs:dateTime to specify values. These values include a date, an optional time and an optional time zone.
|
|
</p>
|
|
<p>
|
|
<strong>Note:</strong> If time zone is not available, it is supposed to be undefined. The client reading the sensor that reports fields without time zone information
|
|
should assume the sensor has the same time zone as the client, if not explicitly configured otherwise on the client side.
|
|
</p>
|
|
<p>
|
|
If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='xml:lang' anchor='lang'>
|
|
<p>
|
|
Control commands sent using IQ stanzas instead of messages, should consider using the <strong>xml:lang</strong> attribute to specify the desired language
|
|
used (if possible) when returning information back to the caller, like error messages, localized control forms, etc.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>
|
|
Controlling devices in a large sensor network is a hackers wet dream. Therefore, consideration of how network security is implemented should not be underestimated.
|
|
The following sections provide some general items that should be considered.
|
|
</p>
|
|
<section2 topic='Encryption & Authentication' anchor='encauth'>
|
|
<p>
|
|
Consider to always use an encrypted connection with any XMPP Server used in the network. Also, make sure the server is properly authenticated and any server
|
|
certificate properly validated.
|
|
</p>
|
|
<p>
|
|
Control commands should only be accepted by trusted parties. A minimum is to make sure only authenticated and validated clients (friends) can perform control actions
|
|
on the device.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Provisioning' anchor='provisioning'>
|
|
<p>
|
|
Consider using provisioning servers to allow for detailed control of who can do what in a sensor network. Implementing proper provisioning support decreases
|
|
the risk for adverse effects, not only from intentional hacking, but also from unintentional errors.
|
|
</p>
|
|
<p>
|
|
If using delegated trust, make sure the provisioning servers are properly authenticated and validated before trusting them.
|
|
</p>
|
|
<p>
|
|
More information about provisioning can be found in <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link>.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>
|
|
The <link url="#schema">protocol schema</link> needs to be added to the list of <link url="http://xmpp.org/resources/schemas/">XMPP protocol schemas</link>.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<code>
|
|
<![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:iot:control'
|
|
xmlns='urn:xmpp:iot:control'
|
|
xmlns:sn='urn:xmpp:iot:sensordata'
|
|
xmlns:xd="jabber:x:data"
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate"
|
|
xmlns:xdl="http://jabber.org/protocol/xdata-layout"
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:import namespace='urn:xmpp:iot:sensordata'/>
|
|
<xs:import namespace='jabber:x:data'/>
|
|
<xs:import namespace='http://jabber.org/protocol/xdata-validate'/>
|
|
<xs:import namespace='http://jabber.org/protocol/xdata-layout'/>
|
|
|
|
<xs:element name='set'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' maxOccurs='unbounded'>
|
|
<xs:element name='node' type='NodeReference'/>
|
|
<xs:element name='boolean' type='BooleanParameter'/>
|
|
<xs:element name='color' type='ColorParameter'/>
|
|
<xs:element name='date' type='DateParameter'/>
|
|
<xs:element name='dateTime' type='DateTimeParameter'/>
|
|
<xs:element name='double' type='DoubleParameter'/>
|
|
<xs:element name='duration' type='DurationParameter'/>
|
|
<xs:element name='int' type='IntParameter'/>
|
|
<xs:element name='long' type='LongParameter'/>
|
|
<xs:element name='string' type='StringParameter'/>
|
|
<xs:element name='time' type='TimeParameter'/>
|
|
<xs:element ref='xd:x'/>
|
|
</xs:choice>
|
|
<xs:attributeGroup ref='tokens'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='setResponse'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' maxOccurs='unbounded'>
|
|
<xs:element name='node' type='NodeReference'/>
|
|
<xs:element name='parameter' type='Parameter'/>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='paramError' type='ParameterError'/>
|
|
|
|
<xs:element name='getForm'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
|
|
<xs:element name='node' type='NodeReference'/>
|
|
</xs:sequence>
|
|
<xs:attributeGroup ref='tokens'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='parameterGroup'>
|
|
<xs:complexType>
|
|
<xs:attribute name='name' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:attributeGroup name='nodeReference'>
|
|
<xs:attribute name='nodeId' type='xs:string' use='required'/>
|
|
<xs:attribute name='sourceId' type='xs:string' use='optional'/>
|
|
<xs:attribute name='cacheType' type='xs:string' use='optional'/>
|
|
</xs:attributeGroup>
|
|
|
|
<xs:attributeGroup name='tokens'>
|
|
<xs:attribute name='serviceToken' type='xs:string' use='optional'/>
|
|
<xs:attribute name='deviceToken' type='xs:string' use='optional'/>
|
|
<xs:attribute name='userToken' type='xs:string' use='optional'/>
|
|
</xs:attributeGroup>
|
|
|
|
<xs:complexType name='Parameter'>
|
|
<xs:attribute name='name' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='BooleanParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:boolean' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='ColorParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='Color' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='DateParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:date' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='DateTimeParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:dateTime' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='DoubleParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:double' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='DurationParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:duration' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='IntParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:int' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='LongParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:long' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='StringParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='TimeParameter'>
|
|
<xs:complexContent>
|
|
<xs:extension base='Parameter'>
|
|
<xs:attribute name='value' type='xs:time' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='ParameterError'>
|
|
<xs:simpleContent>
|
|
<xs:extension base='xs:string'>
|
|
<xs:attribute name='var' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='NodeReference'>
|
|
<xs:attributeGroup ref='nodeReference'/>
|
|
</xs:complexType>
|
|
|
|
<xs:simpleType name='Color'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:pattern value='^([0-9a-fA-F]{6})|([0-9a-fA-F]{8})$'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>]]>
|
|
</code>
|
|
</section1>
|
|
<section1 topic='For more information' anchor='moreinfo'>
|
|
<p>
|
|
For more information, please see the following resources:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
The <link url='http://wiki.xmpp.org/web/Tech_pages/SensorNetworks'>Sensor Network section of the XMPP Wiki</link> contains further information about the
|
|
use of the sensor network XEPs, links to implementations, discussions, etc.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The XEP's and related projects are also available on <link url='https://github.com/joachimlindborg/'>github</link>, thanks to Joachim Lindborg.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
A presentation giving an overview of all extensions related to Internet of Things can be found here:
|
|
<link url='http://prezi.com/esosntqhewhs/iot-xmpp/'>http://prezi.com/esosntqhewhs/iot-xmpp/</link>.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Joachim Lindborg and Tina Beckman for all valuable feedback.</p>
|
|
</section1>
|
|
</xep>
|