1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-10-31 15:35:07 -04:00
xeps/xep-0326.xml

6227 lines
408 KiB
XML
Raw Normal View History

2013-04-16 15:50:08 -04:00
<?xml version='1.0' encoding='UTF-8'?>
<!-- TODO: enhanced concentrator GUI XEP. (Icons, overlays, etc.) -->
<!-- TODO: Interaction with provisioning server -->
<!-- TODO: Execute command failure: Error message. -->
<!-- TODO: Execute command on nodes failures: Error messages. -->
2013-04-16 15:50:08 -04:00
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
2013-05-06 23:07:09 -04:00
<title>Internet of Things - Concentrators</title>
2013-04-16 15:50:08 -04:00
<abstract>This specification describes how to manage and get information from concentrators of devices over XMPP networks.</abstract>
&LEGALNOTICE;
2013-05-06 23:07:09 -04:00
<number>0326</number>
<status>Experimental</status>
2013-04-16 15:50:08 -04:00
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0122</spec>
<spec>XEP-0137</spec>
<spec>XEP-0141</spec>
2013-05-06 23:07:09 -04:00
<spec>XEP-0323</spec>
<spec>XEP-0324</spec>
<spec>XEP-0331</spec>
<spec>XEP-0336</spec>
2013-04-16 15:50:08 -04:00
</dependencies>
<supersedes/>
<supersededby/>
<shortname>sensor-network-concentrators</shortname>
&peterwaher;
<revision>
<version>0.3</version>
<date>2015-11-09</date>
<initials>pw</initials>
<remark>
<p>Updated contact information.</p>
<p>Updated example JIDs to example.org</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>Added the following node query events: <strong>title</strong>, <strong>status</strong>, <strong>beginSection</strong> and <strong>endSection</strong>.</p>
<p>Updated the schema to more strictly validate references to x-data forms.</p>
<p>Updated attribute names so queries and responses are consistent.</p>
<p>Updated the language.</p>
<p>Added section about how to determine support.</p>
<p>Corrected language and examples.</p>
<p>Node Query command type added.</p>
<p>Fixed links to documents with new numbers.</p>
<p>Changed namespace urn:xmpp:sn to urn:xmpp:iot</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-20</date>
<initials>pw</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
2013-04-16 15:50:08 -04:00
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
Concentrators are devices in sensor networks, concentrating the management of a sub set of devices to one point. They can be small (for example: PLC:s managing a small
set of sensors and actuators), medium-sized (for example: mid-level concentrators, controlling branches of the network, islands, perhaps using separate communication protocols),
large (for example: entire sub-systems, perhaps managed by a separate child/partner organization) to massive (for example: The entire top-level system, smart-grid, IoT network).
</p>
<p>
Even though this XEP is generally written and can be used by other implementations not based on sensor networks, much of the requirements used to define this specification
comes from requirements used in sensor networks and Internet of Things applications and infrastructure.
</p>
<p>
This specification will define the following aspects of a general concentrator profile, that can handle all different types of concentrators available in sensor network architectures:
</p>
<ul>
<li>
A concentrator works with multiple <strong>data sources</strong>. Effective management of data sources and their contents is a vital part of this XEP.
</li>
<li>The ability to work with massive quantities of entities.</li>
<li>Effective synchronization of contents between interested parties.</li>
<li>Effective ways to interact with entities controlled by the concentrator.</li>
</ul>
<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>Defines how to control actuators and other devices in Internet of Things.</td>
</tr>
<tr>
<td>XEP-0326</td>
<td>This specification. 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>
<section2 topic='Relations to other extensions'>
2013-04-16 15:50:08 -04:00
<p>
Even though there are technologies available in forms of XEPs that solve parts of the above mentioned problem, they do not provide sufficient support. The following paragraphs will
take the time to list why different technologies are not applicable.
</p>
<section3 topic='XEP-0060'>
<p>
This XEP defines tree structures for nodes in different data sources. &xep0060; defines a model where a tree structure of nodes is published and users can browse this
tree structure. Furthermore, it allows the possibility to publish items on these nodes as well as syndication of this information.
2013-04-16 15:50:08 -04:00
</p>
<p>
This XEP also defines data sources (in a tree structure). These data sources contain nodes. &xep0248; defines a structure called a node collection, a structure that
allows the creation of collections containing loosely coupled nodes.
</p>
<p>
Even though this document defines tree structures of data, it is not however based on XEP-0060. There are multiple reasons for this:
</p>
<ul>
<li>
The structures defined in this specification do not include items to publish for each node.
</li>
<li>
We want to be able to use XEP-0060 in parallel to this specification, for the purpose of publishing sensor data.
More information about this is found in <link url='xep-0000-IoT-PubSub.html'>xep-0000-IoT-PubSub.html</link>.
2013-04-16 15:50:08 -04:00
</li>
<li>
For massive systems (hundreds of thousands, or millions, of nodes behind a concentrator, its vitally important to be able to manage sets of nodes directly
(for example: Edit multiple nodes at once). Many of the operations in XEP-0060 only allow for operations of singular nodes. Furthermore, many simple operations
require multiple messages per node. This document defines way to operate of sets of nodes simultaneously, as well as ways to perform operations with a smaller
number of operations.
</li>
<li>
In this document, nodes have specific functions, controlled by a specific Node Type. Different Node Types have different parameter sets, different options, commands,
capabilities, etc. XEP-0060 does not differ between node types. There, nodes are only a structural way to sort data into a tree graph.
</li>
<li>
In this document, nodes have real-time status, like errors, warnings, etc.
</li>
</ul>
</section3>
<section3 topic='XEP-0248'>
<p>
XEP-0248 defines the concept of node collections and syndication of information from nodes in these collections. But XEP-0248 is not used in this specification.
2013-04-16 15:50:08 -04:00
There are multiple reasons:
</p>
<ul>
<li>
We want to be able to use XEP-0248 in parallel to this specification, for the purpose of publishing sensor data.
More information about this is found in <link url='xep-0000-IoT-PubSub.html'>xep-0000-IoT-PubSub.html</link>.
2013-04-16 15:50:08 -04:00
</li>
<li>
Node IDs are not necessarily unique by themselves in the system. This document defines a uniqueness concept based on a triple of data: (Data Source ID, Cache Type, Node ID). This
means that Nodes must have IDs unique within a given Cache Type, within a given data source.
</li>
<li>
We need to expand on types of events generated from a data source, to make them adhere to the particulars of nodes as defined in this specification.
</li>
<li>
Data sources own their nodes. XEP-0248 define a loosely coupled structure with references to nodes. In this document, a data source is the owner of all nodes
contained in it.
</li>
</ul>
</section3>
<section3 topic='XEP-0050'>
<p>
&xep0050; defines how ad-hoc commands can be implemented and how clients can use such commands to interact with underlying logic. But XEP-0050 is not used in this specification.
There are multiple reasons:
</p>
<ul>
<li>
We want to be able to use XEP-0050 for other types of commands, than commands defined in this specification. Generally, XEP-0050 is used to implement
system-wide commands.
</li>
<li>
Commands defined in this specification are context sensitive, i.e. they depend on the type of node and the context of the node on which the act.
</li>
<li>
It is a requirement to be able to execute commands on sets of nodes directly.
</li>
<li>
Since commands have to be context sensitive, a large concentrator system may have hundreds or thousands of different commands, making it impossible to create
context sensitive GUI's using XEP-0050.
</li>
<li>
Dialog types used for Ad-Hoc-commands are not sufficient. First, dynamic dialogs are required in the general case.
(<link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0326</link> define how to create dynamic forms.) Furthermore, the
2013-04-16 15:50:08 -04:00
wizard style type of dialogs used for more complex dialogs in ad-hoc commands, are difficult to automate.
</li>
</ul>
</section3>
</section2>
</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>Data Source</dt>
<dd>
A Data source contains a collection of nodes. Three types of data sources exist: Singular, Flat and Tree. Singular data sources only include one object.
Flat data sources contain a list of objects and Tree data sources contain nodes formed as a tree graph with one root element.
</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, gateways, 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. Nodes belong to a data source, and all nodes have a Node Type. Some nodes have a parent node, and some nodes have child nodes. Nodes with the same
parent nodes a called sibling nodes.
</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>Node Type</dt>
<dd>Each node has a Node Type. The Node Type defines the functionality of the node in the system.</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 &amp; 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>
2013-04-16 15:50:08 -04:00
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>
To create a complete set of operations supported by all types of concentrators, ranging from PLCs to subsystems to entire systems is very difficult. So, the aim
of this document is instead to create a very small reduced set of operations, a common denominator, that would allow for basic maintenance and interoperability of
concentrators of different makes and models and of these varying ranges.
</p>
<section2 topic='Capabilities'>
<section3 topic='Get Capabilities'>
<p>
This document lists a sequence of commands. Some are very basic, while others are used for managing massive amounts of devices. When developing a small PLC, it might
be difficult to motivate the implementation of the more advanced commands. They are simply not necessary for the management of the device. So, clients connecting to
the concentrator need a way to learn what operations are available in the concentrator, and as a consequence what operations are not. To do this, the
<strong>getCapabilities</strong> command is sent, as is shown in the following example.
</p>
<example caption='Full capabilities'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='subsystem@example.org'
2013-04-16 15:50:08 -04:00
id='1'>
<getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='subsystem@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='1'>
<getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>getCapabilities</value>
<value>getAllDataSources</value>
<value>getRootDataSources</value>
<value>getChildDataSources</value>
<value>containsNode</value>
<value>containsNodes</value>
<value>getNode</value>
<value>getNodes</value>
<value>getAllNodes</value>
<value>getNodeInheritance</value>
<value>getRootNodes</value>
<value>getChildNodes</value>
<value>getIndices</value>
<value>getNodesFromIndex</value>
<value>getNodesFromIndices</value>
<value>getAllIndexValues</value>
<value>getNodeParametersForEdit</value>
<value>setNodeParametersAfterEdit</value>
<value>getCommonNodeParametersForEdit</value>
<value>setCommonNodeParametersAfterEdit</value>
<value>getAddableNodeTypes</value>
<value>getParametersForNewNode</value>
<value>createNewNode</value>
<value>destroyNode</value>
<value>getAncestors</value>
<value>getNodeCommands</value>
<value>getCommandParameters</value>
<value>executeNodeCommand</value>
<value>executeNodeQuery</value>
<value>abortNodeQuery</value>
2013-04-16 15:50:08 -04:00
<value>getCommonNodeCommands</value>
<value>getCommonCommandParameters</value>
<value>executeCommonNodeCommand</value>
<value>executeCommonNodeQuery</value>
<value>abortCommonNodeQuery</value>
2013-04-16 15:50:08 -04:00
<value>moveNodeUp</value>
<value>moveNodeDown</value>
<value>moveNodesUp</value>
<value>moveNodesDown</value>
<value>subscribe</value>
<value>unsubscribe</value>
<value>getDatabases</value>
<value>getDatabaseReadoutParameters</value>
<value>startDatabaseReadout</value>
</getCapabilitiesResponse>
</iq>]]>
</example>
<p>
A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows:
</p>
<example caption='No database capabilities'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='subsystem@example.org'
2013-04-16 15:50:08 -04:00
id='63'>
<getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='subsystem@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='63'>
<getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>getCapabilities</value>
<value>getAllDataSources</value>
<value>getRootDataSources</value>
<value>getChildDataSources</value>
<value>containsNode</value>
<value>containsNodes</value>
<value>getNode</value>
<value>getNodes</value>
<value>getAllNodes</value>
<value>getNodeInheritance</value>
<value>getRootNodes</value>
<value>getChildNodes</value>
<value>getIndices</value>
<value>getNodesFromIndex</value>
<value>getNodesFromIndices</value>
<value>getAllIndexValues</value>
<value>getNodeParametersForEdit</value>
<value>setNodeParametersAfterEdit</value>
<value>getCommonNodeParametersForEdit</value>
<value>setCommonNodeParametersAfterEdit</value>
<value>getAddableNodeTypes</value>
<value>getParametersForNewNode</value>
<value>createNewNode</value>
<value>destroyNode</value>
<value>getAncestors</value>
<value>getNodeCommands</value>
<value>getCommandParameters</value>
<value>executeNodeCommand</value>
<value>executeNodeQuery</value>
<value>abortNodeQuery</value>
2013-04-16 15:50:08 -04:00
<value>getCommonNodeCommands</value>
<value>getCommonCommandParameters</value>
<value>executeCommonNodeCommand</value>
<value>executeCommonNodeQuery</value>
<value>abortCommonNodeQuery</value>
2013-04-16 15:50:08 -04:00
<value>moveNodeUp</value>
<value>moveNodeDown</value>
<value>moveNodesUp</value>
<value>moveNodesDown</value>
<value>subscribe</value>
<value>unsubscribe</value>
</getCapabilitiesResponse>
</iq>]]>
</example>
<p>
A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems:
</p>
<example caption='No batch command capabilities'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='gateway@example.org'
2013-04-16 15:50:08 -04:00
id='2'>
<getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='gateway@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='2'>
<getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>getCapabilities</value>
<value>getAllDataSources</value>
<value>getRootDataSources</value>
<value>getChildDataSources</value>
<value>containsNode</value>
<value>getNode</value>
<value>getNodeInheritance</value>
<value>getRootNodes</value>
<value>getChildNodes</value>
<value>getNodeParametersForEdit</value>
<value>setNodeParametersAfterEdit</value>
<value>getAddableNodeTypes</value>
<value>getParametersForNewNode</value>
<value>createNewNode</value>
<value>destroyNode</value>
<value>getAncestors</value>
<value>getNodeCommands</value>
<value>getCommandParameters</value>
<value>executeNodeCommand</value>
<value>executeNodeQuery</value>
<value>abortNodeQuery</value>
2013-04-16 15:50:08 -04:00
<value>moveNodeUp</value>
<value>moveNodeDown</value>
<value>moveNodesUp</value>
<value>moveNodesDown</value>
<value>subscribe</value>
<value>unsubscribe</value>
</getCapabilitiesResponse>
</iq>]]>
</example>
<p>
But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands:
</p>
<example caption='No edit capabilities'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='plc@example.org'
2013-04-16 15:50:08 -04:00
id='3'>
<getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='plc@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='3'>
<getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>getCapabilities</value>
<value>getAllDataSources</value>
<value>containsNode</value>
<value>getNode</value>
<value>getRootNodes</value>
<value>getChildNodes</value>
<value>getNodeCommands</value>
<value>getCommandParameters</value>
<value>executeNodeCommand</value>
<value>executeNodeQuery</value>
<value>abortNodeQuery</value>
2013-04-16 15:50:08 -04:00
</getCapabilitiesResponse>
</iq>]]>
</example>
<p>
So, clients who need to interact with different types of concentrators need to be aware of what commands are supported, and limit operations to those commands.
</p>
</section3>
</section2>
<section2 topic='Data Sources'>
<section3 topic='Get All Data Sources'>
<p>
This command will return a flat list of all available data sources on the concentrator. It is not structured hierarchically.
</p>
<example caption='Get All Data Sources'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='4'>
<getAllDataSources xmlns='urn:xmpp:iot:concentrators' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='4'>
<getAllDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<dataSource sourceId='Applications' name='Applications' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='Certificates' name='Certificates' hasChildren='false' lastChanged='2013-02-20T12:31:54'/>
<dataSource sourceId='Clayster.EventSink.Programmable' name='Programmable Event Log' hasChildren='false' lastChanged='2012-10-25T09:31:12'/>
2013-04-16 15:50:08 -04:00
...
</getAllDataSourcesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Root Data Sources'>
<p>
If the client is interested in the hierarchical structure of available data sources, it should request only the root sources, and then ask the client for their
corresponding child data sources. If the client wants to present the data sources to a user, presenting them in their hierarchical order may be more intuitive.
</p>
<example caption='Get Root Data Sources'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='5'>
<getRootDataSources xmlns='urn:xmpp:iot:concentrators' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='5'>
<getRootDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<dataSource sourceId='MeteringRoot' name='Metering' hasChildren='true' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='SecurityRoot' name='Security' hasChildren='true' lastChanged='2013-01-12T22:03:50'/>
<dataSource sourceId='SystemRoot' name='System' hasChildren='true' lastChanged='2012-02-20T12:34:56'/>
2013-04-16 15:50:08 -04:00
...
</getRootDataSourcesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Child Data Sources'>
<p>
Having the ID of a data source that contains child data sources, you can fetch the child sources as follows:
</p>
<example caption='Get Child Data Sources'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='6'>
<getChildDataSources xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringRoot' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='6'>
<getChildDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<dataSource sourceId='MeteringFieldImports' name='Field Imports' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringFieldProcessors' name='Field Processors' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringFieldSinks' name='Field Sinks' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringGroups' name='Groups' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringJobs' name='Jobs' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringTopology' name='Topology' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
<dataSource sourceId='MeteringUnitConversion' name='Unit Conversion' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
2013-04-16 15:50:08 -04:00
</getChildDataSourcesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Subscribe to data source events' anchor='subscribe'>
2013-04-16 15:50:08 -04:00
<p>
A client can subscribe to changes made in a data source. It does this by sending the <strong>subscribe</strong> command to the concentrator,
as is shown in the following example:
</p>
<example caption='Subscribing to data source events'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='57'>
<subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='57'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Multiple subscriptions to the same source will not result in an error, however the server will still only send one event message for each event in the data source.
</p>
<p>
<strong>Important:</strong> Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist
event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription
is removed.
</p>
<p>
<strong>Note:</strong> The <strong>parameters</strong> and <strong>messages</strong> attributes can be used to retrieve parameter and status message information
about the nodes in event messages sent from the concentrator. Note that the <strong>xml:lang</strong> may be used to select the language used in such events,
if the concentrator supports localization of strings.
</p>
<example caption='Subscribing to data source events with localized parameters'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='60'>
<subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='true' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='60'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
The <strong>subscribe</strong> command has a set of optional attributes, one for each event type available, and with the same names (<strong>nodeAdded</strong>,
<strong>nodeUpdated</strong>, <strong>nodeStatusChanged</strong>, <strong>nodeRemoved</strong>, <strong>nodeMovedUp</strong> and <strong>nodeMovedDown</strong>), that the
2013-04-16 15:50:08 -04:00
client can use to subscribe to individual events, but not to others. They have the default value of true implying that if not provided, the
default action is to subscribe to those events. The attributes <strong>parameters</strong> and <strong>messages</strong> can also be used to specify
if node parameters and node messages respectively should be available in event messages. The default value for the these later attributes is false, implying
that normal events do not include node parameter and node message information.
2013-04-16 15:50:08 -04:00
</p>
<p>
The following example shows how a client can subscribe to a set of events only:
</p>
<example caption='Subscribing to data source events, avoiding state events'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='61'>
<subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
2013-04-16 15:50:08 -04:00
nodeAdded='true' nodeUpdated='true' nodeStatusChanged='false' nodeRemoved='true' nodeMovedUp='false' nodeMovedDown='false'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='61'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
For more information on types of events sent, see the <link url='#sourceevents'>Data Source Events</link> section.
</p>
</section3>
<section3 topic='Unsubscribe from data source events'>
<p>
A client can unsubscribe to changes made in a data source it is subscribed to. It does this by sending the <strong>unsubscribe</strong> command to the concentrator,
as is shown in the following example:
</p>
<example caption='Unsubscribing from data source events'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='58'>
<unsubscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='58'>
<unsubscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
An unsubscription made to an existing data source, but where an event subscription does not exist, must not result in an error.
</p>
<p>
The <strong>unsubscribe</strong> command has a set of optional attributes, one for each event type available, and with the same names, that the
client can use to unsubscribe from individual events, but not from others. They have the default value of true implying that if not provided, the
default action is to unsubscribe from those events.
</p>
<p>
The following example shows how a client can unsubscribe from a subset of events, keeping subscriptions on the others (if subscribed to):
</p>
<example caption='Unsubscribing from state events'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='62'>
<unsubscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
2013-04-16 15:50:08 -04:00
nodeAdded='false' nodeUpdated='false' nodeStatusChanged='true' nodeRemoved='false' nodeMovedUp='false' nodeMovedDown='false'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='62'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Get changes since given timestamp before subscribing' anchor='subscribe2'>
<p>
If a client comes back online and wants to know any changes that have taken place on the concentrator since last time it was in contact with it,
it can include a <strong>getEventsSince</strong> attribute in the <strong>subscribe</strong> command sent to the concentrator. This will make the
concentrator send all event messages since the given timestamp to the client before subscribing the client to events in the given data source.
</p>
<example caption='Get changes since given timestamp before subscribing'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='59'>
<subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' getEventsSince='2013-03-21T19:24:00'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='59'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>
... Sequence of event messages sent from concentrator to client.]]>
</example>
<p>
<strong>Important:</strong> Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist
event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription
is removed.
</p>
<p>
<strong>Note:</strong> The <strong>parameters</strong> and <strong>messages</strong> attributes can be used to retrieve parameter and status message information
about the nodes in event messages sent from the concentrator.
</p>
<p>
For more information on types of events sent, see the <link url='#sourceevents'>Data Source Events</link> section.
</p>
</section3>
<section3 topic='Get changes since given timestamp before subscribing, Failure'>
<p>
If during a subscription request the concentrator is not able to fulfill the request of retrieving previous events using the <strong>getEventsSince</strong> attribute,
perhaps the attribute stretches too far back, or includes too many records, the concentrator can return an error message using a response code of <strong>NotImplemented</strong>.
In this case, the subscription must not be made.
</p>
<p>
When receiving such an error from the concentrator, the client must make a decision if it should download the data source again, or keep the data source as is, and
subscribing again without the <strong>getEventsSince</strong> attribute.
</p>
<example caption='Get changes since given timestamp before subscribing, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='73'>
<subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' getEventsSince='2001-01-01T00:00:00'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='73'>
<subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='NotImplemented'/>
</iq>]]>
</example>
</section3>
2013-04-16 15:50:08 -04:00
</section2>
<section2 topic='Nodes'>
<section3 topic='Contains Node'>
<p>
This command permits the client to check the existence of a node in the concentrator.
</p>
<example caption='Checking the existence of a node'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='7'>
<containsNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='7'>
<containsNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>true</containsNodeResponse>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Contains Nodes'>
<p>
If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead:
</p>
<example caption='Checking the existence of a multiple nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='8'>
<containsNodes xmlns='urn:xmpp:iot:concentrators'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<node sourceId='MeteringGroups' nodeId='Group1'/>
</containsNodes>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='8'>
<containsNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>true</value>
<value>true</value>
<value>false</value>
<value>true</value>
</containsNodesResponse>
</iq>]]>
</example>
<p>
The array returned will have one item for each item in the request, in the same order.
</p>
</section3>
<section3 topic='Get Node'>
<p>
This command returns basic information about a node in the concentrator.
</p>
<example caption='Get Node'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='9'>
<getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='9'>
<getNodeResponse xmlns='urn:xmpp:iot:concentrators'
2013-04-16 15:50:08 -04:00
result='OK'
nodeId='Node1'
2013-04-16 15:50:08 -04:00
nodeType='Namespace.NodeType1'
cacheType='Node'
state='WarningUnsigned'
hasChildren='false'
isReadable='true'
isControllable='true'
2013-04-16 15:50:08 -04:00
hasCommands='true'
parentId='Root'
lastChanged='2013-03-19T17:58:01'/>
</iq>]]>
</example>
<p>
For more information, see <link url='#nodeinfo'>Node Information</link>.
</p>
</section3>
<section3 topic='Get Nodes'>
<p>
This command lets the client get information from multiple nodes at once.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='10'>
<getNodes xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
</getNodes>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='10'>
<getNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
2013-04-16 15:50:08 -04:00
</getNodesResponse>
</iq>]]>
</example>
<p>
For more information, see <link url='#nodeinfo'>Node Information</link>.
</p>
</section3>
<section3 topic='Get Node with parameters'>
<p>
This command returns basic information about a node in the concentrator, as well as node parameters.
</p>
<example caption='Get Node with parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='11'>
<getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='11'>
<getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK' nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node'
state='WarningUnsigned' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</getNodeResponse>
</iq>]]>
</example>
<p>
For more information, see <link url='#nodeinfo'>Node Information</link>.
</p>
</section3>
<section3 topic='Get Nodes with parameters'>
<p>
This command lets the client get information from multiple nodes at once, including node parameters.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Nodes with parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='12'>
<getNodes xmlns='urn:xmpp:iot:concentrators' parameters='true' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
</getNodes>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='12'>
<getNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
<string id='sn' name='Serial Number' value='234567'/>
<string id='class' name='Node Class' value='Pressure'/>
<string id='meterLoc' name='Meter Location' value='P668632-6'/>
<int id='addr' name='Address' value='124'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
<string id='sn' name='Serial Number' value='345678'/>
<string id='class' name='Node Class' value='Electricity'/>
<string id='meterLoc' name='Meter Location' value='P332367-9'/>
<int id='addr' name='Address' value='125'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</getNodesResponse>
</iq>]]>
</example>
<p>
For more information, see <link url='#nodeinfo'>Node Information</link>.
</p>
</section3>
<section3 topic='Get All Nodes'>
<p>
If the device does not manage too many nodes, it could choose to implement this function. It would return all available nodes with one call.
</p>
<example caption='Get All Nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='13'>
<getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='13'>
<getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
<node nodeId='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true'/>
2013-04-16 15:50:08 -04:00
</getAllNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get All Nodes with Parameters'>
<p>
If the device does not manage too many nodes, it could choose to implement this function. It would return all available nodes with their parameters with one call.
</p>
<example caption='Get All Nodes with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='14'>
<getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='14'>
<getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
<string id='sn' name='Serial Number' value='234567'/>
<string id='class' name='Node Class' value='Pressure'/>
<string id='meterLoc' name='Meter Location' value='P668632-6'/>
<int id='addr' name='Address' value='124'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
<string id='sn' name='Serial Number' value='345678'/>
<string id='class' name='Node Class' value='Electricity'/>
<string id='meterLoc' name='Meter Location' value='P332367-9'/>
<int id='addr' name='Address' value='125'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Root'/>
<string id='type' name='Node Type' value='Root Node'/>
</node>
</getAllNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get All Nodes derived from'>
<p>
This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance.
</p>
<example caption='Get All Nodes derived from'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='15'>
<getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
</getAllNodes>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='15'>
<getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
2013-04-16 15:50:08 -04:00
</getAllNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get All Nodes derived from, with Parameters'>
<p>
This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance. It also returns node parameters
directly in the response.
</p>
<example caption='Get All Nodes derived from, with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='16'>
<getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
</getAllNodes>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='16'>
<getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
<string id='sn' name='Serial Number' value='345678'/>
<string id='class' name='Node Class' value='Electricity'/>
<string id='meterLoc' name='Meter Location' value='P332367-9'/>
<int id='addr' name='Address' value='125'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</getAllNodesResponse>
</iq>]]>
</example>
<p>
Note that the caller can list multiple classes in the request. This would return only nodes having the correct base class(es) and
implementing all interfaces.
</p>
</section3>
<section3 topic='Get Node Inheritance'>
<p>
This command assumes node types exist in a class hierarchy. It allows the caller to get a list of the node class hierarchy and implemented interfaces the
node has.
</p>
<example caption='Get node inheritance'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='17'>
<getNodeInheritance xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='17'>
<getNodeInheritanceResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<baseClasses>
<value>Namespace.BaseClass1</value>
<value>Namespace.AbstractBase</value>
</baseClasses>
</getNodeInheritanceResponse>
</iq>]]>
</example>
<p>
<strong>Note:</strong> It is assumed the client already knows the node type of the node, so the response must not contain the type of the node, only
its base classes and any implemented interfaces.
</p>
2013-04-16 15:50:08 -04:00
</section3>
<section3 topic='Get Root Nodes'>
<p>
This command returns the root node of a data source (in case the source is a tree-shaped data source) or the nodes of a data source (in case the
2013-04-16 15:50:08 -04:00
source is flat).
</p>
<example caption='Get Root Nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='18'>
<getRootNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='18'>
<getRootNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
2013-04-16 15:50:08 -04:00
</getRootNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Root Nodes with Parameters'>
<p>
This command returns the root node of a data source (in case the source is a tree-shaped data source) or the root nodes of a data source (in case the
2013-04-16 15:50:08 -04:00
source is flat), and also returns the parameters for the corresponding nodes.
</p>
<example caption='Get Root Nodes with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='19'>
<getRootNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='19'>
<getRootNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</getRootNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Child Nodes'>
<p>
This command returns the child nodes of a node in a data source.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Child Nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='20'>
<getChildNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='20'>
<getChildNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
2013-04-16 15:50:08 -04:00
</getChildNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Child Nodes with Parameters'>
<p>
This command returns the child nodes of a node in a data source, and also returns the parameters for the corresponding nodes.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Child Nodes with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='21'>
<getChildNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' parameters='true' xml:lang='en' />
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='21'>
<getChildNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
<string id='sn' name='Serial Number' value='234567'/>
<string id='class' name='Node Class' value='Pressure'/>
<string id='meterLoc' name='Meter Location' value='P668632-6'/>
<int id='addr' name='Address' value='124'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
<string id='sn' name='Serial Number' value='345678'/>
<string id='class' name='Node Class' value='Electricity'/>
<string id='meterLoc' name='Meter Location' value='P332367-9'/>
<int id='addr' name='Address' value='125'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</getChildNodesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Indices of Data Source'>
<p>
This command returns a list of available indices in a data source. Indices can be used for efficient node look-up.
</p>
<example caption='Get Indices of Data Source'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='22'>
<getIndices xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' />
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='22'>
<getIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>country</value>
<value>region</value>
<value>city</value>
<value>area</value>
<value>street</value>
<value>building</value>
<value>apartment</value>
<value>oid</value>
</getIndicesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Nodes from index'>
<p>
This command can be used to get a node or nodes from a data source using an index and an index value.
</p>
<example caption='Get Nodes from index'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='23'>
<getNodesFromIndex xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='23'>
<getNodesFromIndexResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
2013-04-16 15:50:08 -04:00
</getNodesFromIndexResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Nodes from index with Parameters'>
<p>
This command can be used to get a node or nodes from a data source using an index and an index value, and also returns the parameters for the corresponding nodes.
</p>
<example caption='Get Nodes from index with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='24'>
<getNodesFromIndex xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1'
2013-04-16 15:50:08 -04:00
parameters='true' xml:lang='en'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='24'>
<getNodesFromIndexResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Metering Topology Reference'/>
<string id='referenceId' name='Reference ID' value='Node2'/>
</node>
</getNodesFromIndexResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Nodes from indices'>
<p>
This command can be used to get nodes from a set of data source using indices and index values.
</p>
<example caption='Get Nodes from indices'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='25'>
<getNodesFromIndices xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
<indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
</getNodesFromIndices>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='25'>
<getNodesFromIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
<node nodeId='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-2'/>
2013-04-16 15:50:08 -04:00
</getNodesFromIndicesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Nodes from indices with Parameters'>
<p>
This command can be used to get nodes from a set of data source using indices and index values, and also returns the parameters for the corresponding nodes.
</p>
<example caption='Get Nodes from indices with Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='26'>
<getNodesFromIndices xmlns='urn:xmpp:iot:concentrators' parameters='true' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
<indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
</getNodesFromIndices>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='26'>
<getNodesFromIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Metering Topology Reference'/>
<string id='referenceId' name='Reference ID' value='Node2'/>
</node>
<node nodeId='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-2'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Metering Topology Reference'/>
<string id='referenceId' name='Reference ID' value='Node3'/>
</node>
</getNodesFromIndicesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get All Index Values'>
<p>
This command can be used to get a list of available index values, given a data source and an index.
</p>
<example caption='Get All Index Values'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='27'>
<getAllIndexValues xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='27'>
<getAllIndexValuesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<value>A1-1</value>
<value>A1-2</value>
...
</getAllIndexValuesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Node Ancestors'>
<p>
In a tree formed data source, all nodes except the root node has a parent node. The <strong>getAncestors</strong> command allows the client to get a list
of all ancestors (parent, grand parent, etc.) of a node, as is shown in the following example:
</p>
<example caption='Get Node Ancestors'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='42'>
<getAncestors xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Node2' parameters='false' messages='false' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='42'>
<getAncestorsResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
<node nodeId='Apartment 1-1' nodeType='Namespace.Apartment' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Building 1'/>
<node nodeId='Building 1' nodeType='Namespace.Building' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Street'/>
<node nodeId='Street' nodeType='Namespace.Street' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Area'/>
<node nodeId='Area' nodeType='Namespace.Area' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='City'/>
<node nodeId='City' nodeType='Namespace.City' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Region'/>
<node nodeId='Region' nodeType='Namespace.Region' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Country'/>
<node nodeId='Country' nodeType='Namespace.Country' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true' parentId='Root'/>
<node nodeId='Root' nodeType='Namespace.Root' state='None' hasChildren='true'
isReadable='false' isControllable='false' hasCommands='true'/>
2013-04-16 15:50:08 -04:00
</getAncestorsResponse>
</iq>]]>
</example>
<p>
Note that the concentrator returns information about the node itself in the response. The <strong>parameters</strong> and <strong>messages</strong>
attributes are used in the request to control if the concentrator should return node parameters and node status messages in the response as well.
</p>
</section3>
<section3 topic='Move Node Up'>
<p>
As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings.
To move a node upwards among its siblings is done using the command <strong>moveNodeUp</strong>, as is shown in the following example:
</p>
<example caption='Move Node Up'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='53'>
<moveNodeUp xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='53'>
<moveNodeUpResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Note that a node that is first among its siblings will maintain its position. The response to the command must still be <strong>OK</strong>.
</p>
</section3>
<section3 topic='Move Node Down'>
<p>
As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings.
To move a node downwards among its siblings is done using the command <strong>moveNodeDown</strong>, as is shown in the following example:
</p>
<example caption='Move Node Up'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='54'>
<moveNodeDown xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='54'>
<moveNodeDownResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Note that a node that is last among its siblings will maintain its position. The response to the command must still be <strong>OK</strong>.
</p>
</section3>
<section3 topic='Move Nodes Up'>
<p>
To move a set of nodes upwards among its siblings is done using the command <strong>moveNodesUp</strong>, as is shown in the following example:
</p>
<example caption='Move Nodes Up'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='55'>
<moveNodesUp xmlns='urn:xmpp:iot:concentrators'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
</moveNodesUp>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='55'>
<moveNodesUpResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Note that a node that is first among its siblings will maintain its position. The response to the command must still be <strong>OK</strong>. If an attempt is performed to move a
sequence of nodes that are together first as siblings, none of the nodes move relative to each other.
</p>
</section3>
<section3 topic='Move Nodes Down'>
<p>
To move a set of nodes downwards among its siblings is done using the command <strong>moveNodesDown</strong>, as is shown in the following example:
</p>
<example caption='Move Node Down'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='56'>
<moveNodesDown xmlns='urn:xmpp:iot:concentrators'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
<node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
</moveNodesDown>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='56'>
<moveNodesDownResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Note that a node that is last among its siblings will maintain its position. The response to the command must still be <strong>OK</strong>. If an attempt is performed to move a
sequence of nodes that are together last as siblings, none of the nodes move relative to each other.
</p>
</section3>
</section2>
<section2 topic='Node Parameters'>
<section3 topic='Get Node Parameters for editing'>
<p>
Previously described commands can return parameters for a node. But these parameters are for presentational or informational use. If the client wants to edit
the parameters of a node, another set of commands must be used. This use case shows how <strong>getNodeParametersForEdit</strong> can be used to edit available
parameters for one node.
</p>
<p>
<strong>Note:</strong> When editing parameters for a node, a different set of parameters might be returned compared to the set of parameters available in commands
mentioned above. There may be various reasons for this, among other things (but not limited to) user rights, node settings, and parameter type. User rights may restrict the number
of parameters the user can access. The node may be configured not to allow editing of certain parameters. Also, some types of parameters may only be available in
an edit mode (like long multi-line parameters) and not in a shorter presentation mode.
</p>
<example caption='Get Node Parameters for editing'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='28'>
<getNodeParametersForEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='28'>
<getNodeParametersForEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Node1</title>
<xdl:page label='Identity'>
<xdl:fieldref var='id'/>
<xdl:fieldref var='type'/>
<xdl:fieldref var='class'/>
<xdl:fieldref var='sn'/>
</xdl:page>
<xdl:page label='Location'>
<xdl:fieldref var='meterLoc'/>
<xdl:fieldref var='lat'/>
<xdl:fieldref var='long'/>
</xdl:page>
<xdl:page label='Communication'>
<xdl:fieldref var='addr'/>
</xdl:page>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='id' type='text-single' label='Node ID:'>
<desc>ID of the node.</desc>
<required/>
<value>Node1</value>
</field>
<field var='type' type='text-single' label='Node Type:'>
<desc>Type of node.</desc>
<value>Watchamacallit Temperature Sensor v1.2</value>
<xdd:readOnly/>
</field>
<field var='class' type='list-single' label='Node Class:'>
<desc>Class of node</desc>
<value>Temperature</value>
<option label='Cooling'><value>Cooling</value></option>
<option label='Electricity'><value>Electricity</value></option>
<option label='Heating'><value>Heating</value></option>
<option label='Pressure'><value>Pressure</value></option>
<option label='Temperature'><value>Temperature</value></option>
<option label='Water'><value>Water</value></option>
...
</field>
<field var='sn' type='text-single' label='Serial Number:'>
<desc>Serial number of node/device.</desc>
<value>123456</value>
</field>
<field var='meterLoc' type='text-single' label='Meter Location:'>
<desc>Meter Location.</desc>
<value>P123502-2</value>
</field>
<field var='addr' type='text-single' label='Address:'>
<xdv:validate datatype='xs:int'>
<xdv:range min='1' max='250'/>
</xdv:validate>
<desc>Bus address</desc>
<value>123</value>
</field>
<field var='lat' type='text-single' label='Latitude:'>
<xdv:validate datatype='xs:double'>
<xdv:range min='-90' max='90'/>
</xdv:validate>
<desc>Latitude of node.</desc>
<value>12.345</value>
</field>
<field var='long' type='text-single' label='Longitude:'>
<xdv:validate datatype='xs:double'>
<xdv:range min='-180' max='180'/>
</xdv:validate>
<desc>Longitude of node.</desc>
<value>123.45</value>
</field>
</x>
</getNodeParametersForEditResponse>
</iq>]]>
</example>
<p>
The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal:
</p>
<table caption='Form XEPs'>
<tr>
<th>XEP</th>
<th>Description</th>
</tr>
<tr>
<td>XEP-0004</td>
<td>Describes how basic forms are handled.</td>
</tr>
<tr>
<td>XEP-0122</td>
<td>Makes it possible to add certain client validation rules to form parameters.</td>
</tr>
<tr>
<td>XEP-0137</td>
<td>Makes it possible to publish a file upload parameter.</td>
</tr>
<tr>
<td>XEP-0141</td>
<td>Makes it possible to layout parameters into pages and sections.</td>
</tr>
<tr>
<td>XEP-0331</td>
2013-04-16 15:50:08 -04:00
<td>Defines extensions for how color parameters can be handled.</td>
</tr>
<tr>
<td>XEP-0336</td>
2013-04-16 15:50:08 -04:00
<td>Makes it possible to create dynamic forms, with server-side validation and forms that change dynamically depending on input.</td>
</tr>
</table>
<p>
Read-only parameters will be returned with the <strong>readOnly</strong> element, as defined in <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>.
2013-04-16 15:50:08 -04:00
Clients SHOULD support this extension if using this command. However, the server MUST NOT change parameters in a node that are read-only, even if clients happen
to try to set them.
</p>
</section3>
<section3 topic='Set Node Parameters after editing'>
<p>
After editing the form, the client uses the <strong>setNodeParametersAfterEdit</strong> command to set the parameters in the node. Note that it is possible to
set the same parameters (or a sub-set of the same parameters) to a different node using this command, without the need to get new form parameters. However, after the first
successful set operation, any form session used for dynamic validation during edit will not be available on the server anymore and must be ignored by the server.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Set Node Parameters after editing'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='29'>
<setNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='id' type='text-single'>
<value>Node1</value>
</field>
<field var='class' type='list-single'>
<value>Temperature</value>
</field>
<field var='sn' type='text-single'>
<value>123456</value>
</field>
<field var='meterLoc' type='text-single'>
<value>P123502-2</value>
</field>
<field var='addr' type='text-single'>
<value>123</value>
</field>
<field var='lat' type='text-single'>
<value>12.345</value>
</field>
<field var='long' type='text-single'>
<value>123.45</value>
</field>
</x>
</setNodeParametersAfterEdit>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='29'>
<setNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</setNodeParametersAfterEditResponse>
</iq>]]>
</example>
<p>
Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set
to <strong>'submit'</strong>. Note also that as the <strong>result</strong> attribute is <strong>OK</strong>, it is assumed the server has dropped any parameter form resources
related to the form, which disables any future dynamic validation of the contents of the form. The newly edited node will also be available in the response
in a <strong>node</strong> element.
</p>
</section3>
<section3 topic='Set Node Parameters after editing, Failure'>
<p>
The following example shows how the server responds when the client tries to set invalid parameters. The response contains detailed information about why,
information which the client can use to inform the user (if any) of what went wrong.
</p>
<example caption='Set Node Parameters after editing, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='30'>
<setNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node2' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='id' type='text-single'>
<value>Node1</value>
</field>
<field var='class' type='list-single'>
<value>Temperature</value>
</field>
<field var='sn' type='text-single'>
<value>123456</value>
</field>
<field var='meterLoc' type='text-single'>
<value>P123502-2</value>
</field>
<field var='addr' type='text-single'>
<value>123</value>
</field>
<field var='lat' type='text-single'>
<value>12.345</value>
</field>
<field var='long' type='text-single'>
<value>123.45</value>
</field>
</x>
</setNodeParametersAfterEdit>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='30'>
<setNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='id'>There already exists a node with this ID.</error>
</setNodeParametersAfterEditResponse>
</iq>]]>
</example>
<p>
As the <strong>result</strong> attribute is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>
2013-04-16 15:50:08 -04:00
<note>
XEP-0336: Dynamic Data Forms &lt;<link url='http://xmpp.org/extensions/xep-0336.html'>http://xmpp.org/extensions/xep-0336.html</link>&gt;
2013-04-16 15:50:08 -04:00
</note> for more information.
</p>
</section3>
<section3 topic='Get Common Node Parameters for editing'>
<p>
Advanced concentrators handling large quantities of nodes may let users edit sets of nodes at once to be practical. This is done by publishing the
<strong>getCommonNodeParametersForEdit</strong> command. It will return a form with parameters that are common for all selected nodes. Since nodes
may have different node types it is assumed that different nodes have different sets of parameters. But if this command is used, only parameters matching
in IDs, descriptions, validation rules, etc., (but not values) will be returned in a form.
</p>
<p>
<strong>Important:</strong> A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the
<strong>notSame</strong> element, according to <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>. Clients using this command MUST
support the extensions defined in <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Common Node Parameters for editing'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='31'>
<getCommonNodeParametersForEdit xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
</getCommonNodeParametersForEdit>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='31'>
<getCommonNodeParametersForEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Node1, Node2, Node3</title>
<xdl:page label='Identity'>
<xdl:fieldref var='type'/>
<xdl:fieldref var='class'/>
<xdl:fieldref var='sn'/>
</xdl:page>
<xdl:page label='Location'>
<xdl:fieldref var='meterLoc'/>
<xdl:fieldref var='lat'/>
<xdl:fieldref var='long'/>
</xdl:page>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='type' type='text-single' label='Node Type:'>
<desc>Type of node.</desc>
<value>Watchamacallit Temperature Sensor v1.2</value>
<xdd:readOnly/>
<xdd:notSame/>
</field>
<field var='class' type='list-single' label='Node Class:'>
<desc>Class of node</desc>
<value>Temperature</value>
<xdd:notSame/>
<option label='Cooling'><value>Cooling</value></option>
<option label='Electricity'><value>Electricity</value></option>
<option label='Heating'><value>Heating</value></option>
<option label='Pressure'><value>Pressure</value></option>
<option label='Temperature'><value>Temperature</value></option>
<option label='Water'><value>Water</value></option>
...
</field>
<field var='sn' type='text-single' label='Serial Number:'>
<desc>Serial number of node/device.</desc>
<value>123456</value>
<xdd:notSame/>
</field>
<field var='meterLoc' type='text-single' label='Meter Location:'>
<desc>Meter Location.</desc>
<value>P123502-2</value>
<xdd:notSame/>
</field>
<field var='addr' type='text-single' label='Address:'>
<xdv:validate datatype='xs:int'>
<xdv:range min='1' max='250'/>
</xdv:validate>
<desc>Bus address</desc>
<value>123</value>
<xdd:notSame/>
</field>
<field var='lat' type='text-single' label='Latitude:'>
<xdv:validate datatype='xs:double'>
<xdv:range min='-90' max='90'/>
</xdv:validate>
<desc>Latitude of node.</desc>
<value>12.345</value>
<xdd:notSame/>
</field>
<field var='long' type='text-single' label='Longitude:'>
<xdv:validate datatype='xs:double'>
<xdv:range min='-180' max='180'/>
</xdv:validate>
<desc>Longitude of node.</desc>
<value>123.45</value>
<xdd:notSame/>
</field>
</x>
</getCommonNodeParametersForEditResponse>
</iq>]]>
</example>
<p>
Note that parameters that are not available in all selected nodes will have been removed. Also and ID-parameter will have been removed, since they
cannot be set for a collection of nodes.
</p>
<p>
Fields marked with the <strong>notSame</strong> element only present one value, perhaps the value of the first node. However, the field should be clearly
marked in any end-user GUI (for example by graying the field), and MUST ONLY be sent back to the server in a set operation if explicitly edited by the end-user.
The parameter will be set in all selected nodes in that case. Unedited fields should be treated as if the end-user accepts the different values for the current set of nodes.
</p>
</section3>
<section3 topic='Set Common Node Parameters after editing'>
<p>
After editing the form, the client uses the <strong>setCommonNodeParametersAfterEdit</strong> command to set the parameters in the set of nodes. Note that it is possible to
set the same parameters (or a sub-set of the same parameters) to a different set of nodes using this command, without the need to get new form parameters. However, after the first
successful set operation, any form session used for dynamic validation during edit will not be available on the server any more.
</p>
<example caption='Set Common Node Parameters after editing'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='32'>
<setCommonNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='class' type='list-single'>
<value>Temperature</value>
</field>
</x>
</setCommonNodeParametersAfterEdit>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='32'>
<setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
<node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node2'/>
<string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
<string id='sn' name='Serial Number' value='234567'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P668632-6'/>
<int id='addr' name='Address' value='124'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
<node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node3'/>
<string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
<string id='sn' name='Serial Number' value='345678'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P332367-9'/>
<int id='addr' name='Address' value='125'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</node>
</setCommonNodeParametersAfterEditResponse>
</iq>]]>
</example>
<p>
Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set
to <strong>'submit'</strong>. Note also that as the <strong>result</strong> attribute is <strong>OK</strong>, it is assumed the server has dropped any parameter form resources
related to the form, which disables any future dynamic validation of the contents of the form.
</p>
<p>
<strong>Important:</strong> A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the
<strong>notSame</strong> element, according to <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>. Such parameters MUST NOT be sent back to the server
2013-04-16 15:50:08 -04:00
unless they have explicitly been edited or signed by the end-user. The value sent back to the server will be set in all nodes.
</p>
</section3>
<section3 topic='Set Common Node Parameters after editing, Failure'>
<p>
The following example shows how the server responds when the client tries to set invalid parameters to a set of nodes. The response contains detailed information about why,
information which the client can use to inform the user (if any) of what went wrong.
</p>
<example caption='Set Common Node Parameters after editing, Failure'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='33'>
<setCommonNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
</field>
<field var='id' type='text-single'>
<value>Node1</value>
</field>
<field var='class' type='list-single'>
<value>Temperature</value>
</field>
</x>
</setCommonNodeParametersAfterEdit>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='33'>
<setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='id'>Parameter not available.</error>
</setCommonNodeParametersAfterEditResponse>
</iq>]]>
</example>
<p>
As the <strong>result</strong> attribute is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
2013-04-16 15:50:08 -04:00
</p>
</section3>
<section3 topic='Get Node Messages'>
2013-04-16 15:50:08 -04:00
<p>
Each node in the concentrator has a <strong>state</strong>. This state is a dynamic run-time state, and therefore not presented as a more static property.
This state can be any of the following values, in order of increasing importance:
</p>
<table caption='Node states'>
<tr>
<th>State</th>
<th>Description</th>
</tr>
<tr>
<td>None</td>
<td>Nothing has been reported on the node.</td>
</tr>
<tr>
<td>Information</td>
<td>There are informative events reported on the node.</td>
</tr>
<tr>
<td>WarningSigned</td>
<td>There are warnings reported on the node. But these warnings have been viewed by an operator.</td>
</tr>
<tr>
<td>WarningUnsigned</td>
<td>There are new or unreviewed warnings reported on the node.</td>
</tr>
<tr>
<td>ErrorSigned</td>
<td>There are errors reported on the node. But these errors have been viewed by an operator.</td>
</tr>
<tr>
<td>ErrorUnsigned</td>
<td>There are new or unreviewed errors reported on the node.</td>
</tr>
</table>
<p>
Other types of "states" are of course possible, such as phase - installation phase, test phase, production phase, etc. - but such "states" are seen as static
and presented as parameters on the node. The purpose of the dynamic state attribute of a node, is to give a dynamic runtime state that has
the possibility to change during runtime, which operators must be aware of.
</p>
<p>
The following commands have an optional attribute <strong>messages</strong>, with which they can ask the server to return any events logged on the node, giving more details of the
current state of the node:
</p>
<ul>
<li>
<strong>getNode</strong>
</li>
<li>
<strong>getNodes</strong>
</li>
<li>
<strong>getChildNodes</strong>
</li>
<li>
<strong>getAllNodes</strong>
</li>
<li>
<strong>getRootNodes</strong>
</li>
<li>
<strong>getNodesFromIndex</strong>
</li>
<li>
<strong>getNodesFromIndices</strong>
</li>
</ul>
<example caption='Get Node Messages'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='34'>
<getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' messages='true' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='34'>
<getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'
nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
<message timestamp='2013-03-21T11:06:15' type='WarningUnsigned'
eventId='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
2013-04-16 15:50:08 -04:00
</getNodeResponse>
</iq>]]>
</example>
<p>
The <strong>messages</strong> attribute can be combined with the <strong>parameters</strong> attribute to provide both node parameters and
messages in the response.
</p>
<example caption='Get Node with parameters and messages'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='35'>
<getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true' messages='true'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='35'>
<getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'
nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
<message timestamp='2013-03-21T11:06:15' type='WarningUnsigned'
eventId='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
2013-04-16 15:50:08 -04:00
</getNodeResponse>
</iq>]]>
</example>
</section3>
</section2>
<section2 topic='Creating and Destroying Nodes'>
<section3 topic='Get Addable Node Types'>
<p>
Since nodes are context sensitive, depending on node type and tree structure, before being able to create a new node, it is important to know what types of nodes
that can be added to a given node. This is done using the <strong>getAddableNodeTypes</strong> command, as is shown in the following example:
</p>
<example caption='Get Addable Node Types'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='36'>
<getAddableNodeTypes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='36'>
<getAddableNodeTypesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<nodeType type='Namespace.Apartment' name='Apartment'/>
<nodeType type='Namespace.MeteringTopologyReference' name='Metering Topology Reference'/>
<nodeType type='Namespace.Location' name='Service Location'/>
</getAddableNodeTypesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Parameters for New Node'>
<p>
When you know what type of node you want to create, you need to get a set of parameters you need to fill in for the new node, before you can create it.
This is done using the <strong>getParametersForNewNode</strong> command, as is shown in the following example:
</p>
<example caption='Get Parameters for New Node'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='37'>
<getParametersForNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1'
type='Namespace.MeteringTopologyReference' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='37'>
<getParametersForNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Metering Topology</title>
<xdl:page label='Identity'>
<xdl:fieldref var='id'/>
<xdl:fieldref var='referenceId'/>
</xdl:page>
<field var='xdd session' type='hidden'>
<value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
</field>
<field var='id' type='text-single' label='Node ID:'>
<desc>ID of the node.</desc>
<required/>
<value/>
</field>
<field var='referenceId' type='text-single' label='Metering Node ID:'>
<desc>ID of the node in the metering topology.</desc>
<required/>
<value/>
</field>
</x>
</getParametersForNewNodeResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Create New Node'>
<p>
After editing the form, the client uses the <strong>createNewNode</strong> command to create the new node using the parameters provided in the form.
</p>
<example caption='Create New Node after editing'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='38'>
<createNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1'
type='Namespace.MeteringTopologyReference' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
</field>
<field var='id' type='text-single'>
<value>Reference to Node1</value>
</field>
<field var='referenceId' type='text-single'>
<value>Node1</value>
</field>
</x>
</createNewNode>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='38'>
<createNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<node nodeId='Reference to Node1' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false'
isReadable='true' isControllable='true' hasCommands='true' parentId='B1'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Reference to Node1'/>
<string id='type' name='Node Type' value='Metering Topology Reference'/>
<string id='referenceId' name='Reference ID' value='Node1'/>
</node>
</createNewNodeResponse>
</iq>]]>
</example>
<p>
Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set
to <strong>'submit'</strong>. Note also that as the <strong>result</strong> attribute is <strong>OK</strong>, it is assumed the server has dropped any parameter form resources
related to the form, which disables any future dynamic validation of the contents of the form. The newly created node with corresponding parameters is also returned
in the response in a <strong>node</strong> element.
</p>
</section3>
<section3 topic='Create New Node, Failure'>
<p>
The following example shows how the server responds when it cannot accept parameters provided when trying to create a node. The response will contain detailed information
about why, information which the client can use to inform the user (if any) of what went wrong.
</p>
<example caption='Create New Node, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='39'>
<createNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1'
type='Namespace.MeteringTopologyReference' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
</field>
<field var='id' type='text-single'>
<value>Node2</value>
</field>
<field var='referenceId' type='text-single'>
<value>NodeX</value>
</field>
</x>
</createNewNode>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='39'>
<createNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='id'>There already exists a node with this ID.</error>
<error var='referenceId'>Referenced node was not found.</error>
</createNewNodeResponse>
</iq>]]>
</example>
<p>
As the <strong>result</strong> attribute is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
2013-04-16 15:50:08 -04:00
</p>
</section3>
<section3 topic='Destroy Node'>
<p>
To destroy (remove) a node from the concentrator, the <strong>destroyNode</strong> command is sent, as is shown in the following example:
</p>
<example caption='Destroy Node'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='40'>
<destroyNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='40'>
<destroyNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
Since the <strong>result</strong> attribute in the response is <strong>OK</strong>, the node has been removed.
</p>
</section3>
<section3 topic='Destroy Node, Failure'>
<p>
If the <strong>result</strong> attribute in the response is other than <strong>OK</strong>, the node was not removed from the concentrator.
The <strong>result</strong> attribute contains the reason why the operation failed, as is shown in the following example:
</p>
<example caption='Destroy Node, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='41'>
<destroyNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='41'>
<destroyNodeResponse xmlns='urn:xmpp:iot:concentrators' result='InsufficientPrivileges'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
</section2>
<section2 topic='Node Commands'>
<section3 topic='Get Node Commands'>
<p>
Each node can have a context sensitive set of commands available to it. This is shown using the <strong>hasCommands</strong> attribute in the
<link url='#nodeinfo'>Node Information</link> record describing the corresponding node. If the client wants to get a list of available commands,
the <strong>getNodeCommands</strong> command is sent to the concentrator, as is shown in the following example:
</p>
<example caption='Get Node Commands'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='43'>
<getNodeCommands xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='43'>
<getNodeCommandsResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<command command='knockDoor' name='Knock on door' type='Simple'
2013-04-16 15:50:08 -04:00
confirmationString='Are you sure you want to knock on the door?'
failureString='Unable to knock on the door.'
successString='Door knocked.'/>
<command command='scheduleWakeupCall' name='Schedule wakeup call' type='Parameterized'
2013-04-16 15:50:08 -04:00
failureString='Unable to schedule the wakeup call.'
successString='Wakeup call scheduled.'/>
<command command='searchEvents' name='Search events...' type='Query'
failureString='Unable to search for events.'
successString='Search for events started...'/>
2013-04-16 15:50:08 -04:00
</getNodeCommandsResponse>
</iq>]]>
</example>
<p>
There are three types of commands available: <strong>Simple</strong>, <strong>Parameterized</strong> and <strong>Query</strong>. <strong>Simple</strong> commands
take no parameters, and are therefore simpler to execute. <strong>Parameterized</strong> commands require the client to get a set of parameters for the corresponding
command before it can be executed. <strong>Query</strong> commands also require a set of parameters to be executed, but return a response after (or during) execution
in an asynchronous fashion. Queries can also be aborted during execution. A Query with an empty parameter set is considered to be a simple query, not requiring a
parameter dialog to be shown.
</p>
<p>
For more information about command attributes, see <link url='#nodecommands'>Node Commands</link>.
2013-04-16 15:50:08 -04:00
</p>
</section3>
<section3 topic='Execute Simple Node Command'>
<p>
Executing a simple command is done by sending the <strong>executeNodeCommand</strong> command to the concentrator, as is shown in the following example:
</p>
<example caption='Execute Simple Node Command'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='44'>
<executeNodeCommand xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='knockDoor' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='44'>
<executeNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Get Node Command Parameters'>
<p>
To execute a parameterized command or a query on the node, the client first needs to get (and edit) a set of parameters for the command. Getting a set of parameters for a
2013-04-16 15:50:08 -04:00
parameterized command is done as follows:
</p>
<example caption='Get Node Command Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='45'>
<getCommandParameters xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1'
command='scheduleWakeupCall' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='45'>
<getCommandParametersResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Schedule wake-up call</title>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single' label='Time:'>
<desc>Time of the wake-up call.</desc>
<required/>
<value></value>
<xdv:validate datatype='xs:time'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='mode' type='list-single' label='Wake-up mode:'>
<desc>Type of wake-up call</desc>
<value>Soft</value>
<option label='Soft'><value>Soft</value></option>
<option label='Normal'><value>Normal</value></option>
<option label='Harass'><value>Harass</value></option>
</field>
</x>
</getCommandParametersResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Parameterized Node Command'>
<p>
Executing a parameterized command is also done by sending the <strong>executeNodeCommand</strong> command to the concentrator, but including the edited form parameters,
as is shown in the following example:
</p>
<example caption='Execute Parameterized Node Command'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='46'>
<executeNodeCommand xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1'
command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single'>
<value>04:30:00</value>
</field>
<field var='mode' type='list-single'>
<value>Harass</value>
</field>
</x>
</executeNodeCommand>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='46'>
<executeNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Execute Node Command, Failure'>
<p>
If an error occurs during the execution of a command or if the server rejects the execution of a command, the server returns a response code different from
<strong>OK</strong>. If the response code is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Execute Node Command, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='47'>
<executeNodeCommand xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1'
command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single'>
<value>04:30:00</value>
</field>
<field var='mode' type='list-single'>
<value>Harass</value>
</field>
</x>
</executeNodeCommand>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='47'>
<executeNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='mode'>You are not allowed to harass people at 04:30:00!</error>
</executeNodeCommandResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Node Query'>
<p>
Executing a Node Query also requires the client to get a set of parameters for the query. This is done in the same way as for parametrized commands,
as is shown in the following example:
</p>
<example caption='Get Node Query Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
id='74'>
<getCommandParameters xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1'
command='searchEvents' xml:lang='en'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='74'>
<getCommandParametersResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<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>Search for events</title>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='from' type='text-single' label='From:'>
<desc>From what point in time events will be fetched.</desc>
<required/>
<value>2013-04-16T12:58:00</value>
<xdv:validate datatype='xs:dateTime'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='to' type='text-single' label='To:'>
<desc>To what point in time events will be fetched.</desc>
<required/>
<value>2013-04-23T12:58:00</value>
<xdv:validate datatype='xs:dateTime'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='searchText' type='text-single' label='Search Text:'>
<desc>Only return events including this text.</desc>
<required/>
<value></value>
</field>
</x>
</getCommandParametersResponse>
</iq>]]>
</example>
<p>
Executing the query is then done by sending the <strong>executeNodeQuery</strong> command to the concentrator, but including the edited form parameters,
as is shown in the following example:
</p>
<example caption='Execute Node Query'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='75'>
<executeNodeQuery xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='searchEvents' xml:lang='en'>
<x type='submit' xmlns='jabber:x:data'>
<field var='from' type='text-single'>
<value>2013-04-16T12:58:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-04-23T12:58:00</value>
</field>
<field var='searchText' type='text-single'>
<value>Harass</value>
</field>
</x>
</executeNodeQuery>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='75'>
<executeNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='OK' queryId='Query0001'/>
</iq>
...]]>
</example>
<p>
After the successful execution of a query command, a sequence of query events will follow. These events will include a <strong>queryId</strong>
attribute to identify to which query the corresponding events correspond. See section about <link url='#queryevents'>Query Events</link>
for more information about this.
</p>
<p>
<strong>Note:</strong> Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed.
However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before
executing the command.
</p>
</section3>
<section3 topic='Execute Node Query, Failure'>
<p>
If an error occurs during the reception of a query or if the server rejects the execution of a query, the server returns a response code different from
<strong>OK</strong>. If the response code is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
</p>
<example caption='Execute Node Query, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='76'>
<executeNodeQuery xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='searchEvents' xml:lang='en'>
<x type='submit' xmlns='jabber:x:data'>
<field var='from' type='text-single'>
<value>2013-04-23T12:58:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-04-16T12:58:00</value>
</field>
<field var='searchText' type='text-single'>
<value>Harass</value>
</field>
</x>
</executeNodeQuery>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
id='76'>
<executeNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
<error var='to'>The TO timestamp needs to be later than the FROM timestamp.</error>
</executeNodeQueryResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Abort Node Query'>
<p>
One a query has been accepted and started running, the client can abort it using the <strong>abortNodeQuery</strong> command, as is shown in the
following example.
</p>
<example caption='Abort Node Query'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='77'>
<abortNodeQuery xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='searchEvents'
queryId='Query0001' xml:lang='en'/>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='77'>
<abortNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
</iq>]]>
</example>
<p>
<strong>Note:</strong> The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of
<link url='#queryevents'>query events</link> and the reception of them by a client. A client may thinkt a query is still active when asking
to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this
when receiving <strong>NotFound</strong> responses from a concentrator, that the query might already have been finished.
</p>
</section3>
2013-04-16 15:50:08 -04:00
<section3 topic='Get Common Commands for Nodes'>
<p>
Using the command <strong>getCommonNodeCommands</strong>, the client can receive commands that are common for a set of nodes,
as is shown in the following example:
</p>
<example caption='Get Common Commands for Nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='48'>
<getCommonNodeCommands xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
</getCommonNodeCommands>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='48'>
<getCommonNodeCommandsResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<command command='knockDoor' name='Knock on door' type='Simple'
2013-04-16 15:50:08 -04:00
confirmationString='Are you sure you want to knock on the door?'
failureString='Unable to knock on the door.'
successString='Door knocked.'/>
<command command='scheduleWakeupCall' name='Schedule wakeup call' type='Parameterized'
2013-04-16 15:50:08 -04:00
failureString='Unable to schedule the wakeup call.'
successString='Wakeup call scheduled.'/>
</getCommonNodeCommandsResponse>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Execute Simple Command on multiple nodes'>
<p>
Executing a simple command on multiple nodes is done by sending the <strong>executeCommonNodeCommand</strong> command to the concentrator,
as is shown in the following example:
</p>
<example caption='Execute Simple Command on multiple nodes'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='49'>
<executeCommonNodeCommand xmlns='urn:xmpp:iot:concentrators' command='knockDoor' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
</executeCommonNodeCommand>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='49'>
<executeCommonNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
</executeCommonNodeCommandResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Common Command Parameters from command on multiple nodes'>
<p>
To execute a parameterized command on a set of nodes, the client first needs to get (and edit) a set of parameters for the common command. Getting a set of parameters for a
common parameterized command is done as follows:
</p>
<example caption='Get Common Command Parameters from command on multiple nodes'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='50'>
<getCommonCommandParameters xmlns='urn:xmpp:iot:concentrators' command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
</getCommonCommandParameters>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='50'>
<getCommonCommandParametersResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Schedule wake-up call</title>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single' label='Time:'>
<desc>Time of the wake-up call.</desc>
<required/>
<value></value>
<xdv:validate datatype='xs:time'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='mode' type='list-single' label='Wake-up mode:'>
<desc>Type of wake-up call</desc>
<value>Soft</value>
<option label='Soft'><value>Soft</value></option>
<option label='Normal'><value>Normal</value></option>
<option label='Harass'><value>Harass</value></option>
</field>
</x>
</getCommonCommandParametersResponse>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section3>
<section3 topic='Execute Common Parameterized Command on multiple nodes'>
<p>
Executing a common parameterized command is also done by sending the <strong>executeCommonNodeCommand</strong> command to the concentrator, but including the edited form parameters,
as is shown in the following example:
</p>
<example caption='Execute Common Parameterized Command on multiple nodes'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='51'>
<executeCommonNodeCommand xmlns='urn:xmpp:iot:concentrators' command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single'>
<value>04:30:00</value>
</field>
<field var='mode' type='list-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeCommand>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='51'>
<executeCommonNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
<result>true</result>
</executeCommonNodeCommandResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Parameterized Command on Multiple Nodes, Failure'>
<p>
If an error occurs during the execution of a common command or if the server rejects the execution of a common command, the server returns a response code different from
<strong>OK</strong>. If the response code is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Execute Parameterized Command on Multiple Nodes, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='52'>
<executeCommonNodeCommand xmlns='urn:xmpp:iot:concentrators' command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single'>
<value>04:30:00</value>
</field>
<field var='mode' type='list-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeCommand>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='52'>
<executeCommonNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='mode'>You are not allowed to harass people at 04:30:00!</error>
</executeCommonNodeCommandResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Command on Multiple Nodes, Partial Failure'>
<p>
When executing a command, simple or parameterized, on multiple nodes, it might happen that the command fails on some nodes, but not on others, even though
any parameters are validated beforehand. Therefore, the client needs to check any <strong>result</strong> elements in the response, even though the
response code is <strong>OK</strong>.
</p>
<p>
The following example shows the execution of a parameterized command on multiple nodes that fail on some nodes but are executed on others. Note that
individual error messages can be provided as <strong>error</strong> attribute messages for each node that fails in the corresponding <strong>result</strong>
element.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Execute Command on Multiple Nodes, Partial Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='72'>
<executeCommonNodeCommand xmlns='urn:xmpp:iot:concentrators' command='scheduleWakeupCall' xml:lang='en'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='time' type='text-single'>
<value>04:30:00</value>
</field>
<field var='mode' type='list-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeCommand>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='72'>
<executeCommonNodeCommandResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<result>true</result>
<result>true</result>
<result error='Too early!'>false</result>
2013-04-16 15:50:08 -04:00
<result>true</result>
<result error='Sleeping at that time...'>false</result>
2013-04-16 15:50:08 -04:00
<result>true</result>
</executeCommonNodeCommandResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Common Query on multiple nodes'>
2013-04-16 15:50:08 -04:00
<p>
Executing a Node Query on multiple nodes also requires the client to get a set of parameters for the query common to all nodes.
This is done in the same way as for parametrized commands, as is shown in the following example:
2013-04-16 15:50:08 -04:00
</p>
<example caption='Get Common Query Parameters from query on multiple nodes'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
id='78'>
<getCommonCommandParameters xmlns='urn:xmpp:iot:concentrators' command='searchEvents' xml:lang='en'>
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
</getCommonCommandParameters>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='78'>
<getCommonCommandParametersResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<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>Schedule wake-up call</title>
<field var='xdd session' type='hidden'>
<value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
</field>
<field var='from' type='text-single' label='From:'>
<desc>From what point in time events will be fetched.</desc>
<required/>
<value>2013-04-16T12:58:00</value>
<xdv:validate datatype='xs:dateTime'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='to' type='text-single' label='To:'>
<desc>To what point in time events will be fetched.</desc>
<required/>
<value>2013-04-23T12:58:00</value>
<xdv:validate datatype='xs:dateTime'/>
<xdv:basic/>
</xdv:validate>
</field>
<field var='searchText' type='text-single' label='Search Text:'>
<desc>Only return events including this text.</desc>
<required/>
<value></value>
</field>
</x>
</getCommonCommandParametersResponse>]]>
2013-04-16 15:50:08 -04:00
</example>
<p>
Executing the query is then done by sending the <strong>executeCommonNodeQuery</strong> command to the concentrator, but including the edited form parameters,
as is shown in the following example:
</p>
<example caption='Execute Common Query on multiple nodes'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='79'>
<executeCommonNodeQuery xmlns='urn:xmpp:iot:concentrators' command='searchEvents' xml:lang='en'>
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='from' type='text-single'>
<value>2013-04-16T12:58:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-04-23T12:58:00</value>
</field>
<field var='searchText' type='text-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeQuery>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='79'>
<executeCommonNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='OK' queryId='Query0001'/>
</iq>
...]]>
2013-04-16 15:50:08 -04:00
</example>
<p>
After the successful execution of a query command, a sequence of query events will follow. These events will include a <strong>queryId</strong>
attribute to identify to which query the corresponding events correspond. They will also include node reference attributes so the receptor can
distinguish information from different nodes in the query. See section about <link url='#queryevents'>Query Events</link>
for more information about this.
</p>
<p>
<strong>Note:</strong> Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed.
However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before
executing the command.
2013-04-16 15:50:08 -04:00
</p>
</section3>
<section3 topic='Execute Common Query on multiple nodes, Failure'>
2013-04-16 15:50:08 -04:00
<p>
If an error occurs during the execution of a common query or if the server rejects the execution of a common query, the server returns a response code different from
<strong>OK</strong>. If the response code is <strong>FormError</strong>, the server maintains any parameter form resources related to the form, and features such as
dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link> for more information.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Execute Parameterized Query on multiple nodes, Failure'>
2013-04-16 15:50:08 -04:00
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='80'>
<executeCommonNodeQuery xmlns='urn:xmpp:iot:concentrators' command='searchEvents' xml:lang='en'>
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='from' type='text-single'>
<value>2013-04-23T12:58:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-04-16T12:58:00</value>
</field>
<field var='searchText' type='text-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeQuery>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
id='80'>
<executeCommonNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
<error var='to'>The TO timestamp needs to be later than the FROM timestamp.</error>
</executeCommonNodeQueryResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Execute Common Query on multiple nodes, Partial Failure'>
<p>
When executing a query on multiple nodes, it might happen that the query is rejected on some nodes, but not on others, even though
any parameters are validated beforehand. Therefore, the client needs to check any <strong>result</strong> elements in the response, even though the
response code is <strong>OK</strong>.
</p>
<p>
The following example shows the execution of a query on multiple nodes that fail on some nodes but are executed on others. Note that
individual error messages can be provided as <strong>error</strong> attribute messages for each node that fails in the corresponding <strong>result</strong>
element.
</p>
<example caption='Execute Common Query on multiple nodes, Partial Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='81'>
<executeCommonNodeQuery xmlns='urn:xmpp:iot:concentrators' command='searchEvents' xml:lang='en'>
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='from' type='text-single'>
<value>2013-04-23T12:58:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-04-16T12:58:00</value>
</field>
<field var='searchText' type='text-single'>
<value>Harass</value>
</field>
</x>
</executeCommonNodeQuery>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
id='81'>
<executeCommonNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='OK' queryId='Query0002'>
<result>true</result>
<result>true</result>
<result error='Event Database not available!'>false</result>
<result>true</result>
<result>true</result>
<result>true</result>
</executeCommonNodeQueryResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Abort Common Query on multiple nodes'>
<p>
To abort a query common to a set of nodes you use the <strong>abortCommonNodeQuery</strong> command, as is shown in the following example:
</p>
<example caption='Abort Common Query on multiple nodes'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
id='82'>
<abortCommonNodeQuery xmlns='urn:xmpp:iot:concentrators' queryId='Query0002' xml:lang='en'>
<node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
<node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
</abortCommonNodeQuery>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
id='82'>
<abortCommonNodeQueryResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
</iq>]]>
</example>
<p>
<strong>Note:</strong> The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of
<link url='#queryevents'>query events</link> and the reception of them by a client. A client may thinkt a query is still active when asking
to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this
when receiving <strong>NotFound</strong> responses from a concentrator, that the query might already have been finished. In the case of
aborting queries on multiple nodes, servers must ignore nodes where the query has already finished executing.
</p>
</section3>
</section2>
<section2 topic='Query Events' anchor='queryevents'>
<p>
Query events are sent as a response to executing queries on nodes. They are reported asynchronously from the concentrator to the client executing the query. Each
event is wrapped in a <strong>queryProgress</strong> element within a message sent from the concentrator to the client. Each such <strong>queryProgress</strong>
element can include any number of query events, and the client must process them in the order they appear in the message.
</p>
<p>
Each <strong>queryProgress</strong> element contains a <strong>queryId</strong> attribute identifying the query to which the events correspond. They also contain
<strong>sourceId</strong>, <strong>nodeId</strong> and an optional <strong>cacheType</strong> to identify from which node in a concentrator the events originated.
</p>
<p>
<strong>Note:</strong> A <strong>queryProgress</strong> element can only contain events from a single query executed on a single node. If a query is executed on
multiple nodes, events resulting from different nodes will be sent in different messages.
</p>
<p>
The following subsections describe each query event in turn.
</p>
<section3 topic='Query Started'>
<p>
This event is sent when the query is started on a node. It is sent using a <strong>queryStarted</strong> event element. This element does not take any
attributes.
</p>
<example caption='Query Started'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
<queryStarted/>
...
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='Query Done'>
<p>
This event is sent when the query is done on a node. It is sent using a <strong>queryDone</strong> event element. This element does not take any
attributes.
</p>
<example caption='Query Done'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<queryDone/>
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='Query Aborted'>
<p>
This event is sent when the query has been aborted on a node. It is sent using a <strong>queryAborted</strong> event element. This element does not take any
attributes.
</p>
<example caption='Query Aborted'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<queryAborted/>
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='New Table'>
<p>
A query result can consist of zero or more data tables. Each data table consists of a set of columns and records containing value items for the these
columns. A new table is identified by a query event named <strong>newTable</strong>. a <strong>newTable</strong> event contains a sequence of
<strong>column</strong> events each identifying a column in the table.
</p>
<example caption='New Table'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<newTable tableId='table1' tableName='Events'>
<column columnId='timestamp' header='Timestamp'>
<column columnId='message' header='Message'>
</newTable>
...
</queryProgress>
</message>]]>
</example>
<p>
For more information about column definitions, see <link url='#columndef'>Table Column definitions in query results</link>.
</p>
</section3>
<section3 topic='New Records'>
<p>
A set of records in an open table is reported using the <strong>newRecords</strong> query event.
</p>
<example caption='New Records'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<newRecords tableId='table1'>
<record>
<dateTime>2013-04-24T17:43:15</dateTime>
<string>Harassed</string>
</record>
...
</newRecords>
...
</queryProgress>
</message>]]>
</example>
<p>
For more information about records, see <link url='#recorddef'>Record Item definitions in query results</link>.
</p>
</section3>
<section3 topic='Table Done'>
<p>
This event is sent when the query is done with a table. It is sent using a <strong>tableDone</strong> event element. The query must not send any more records
to a table that has been closed using this query event.
</p>
<example caption='Table Done'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<tableDone tableId='table1'/>
...
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='New Object'>
<p>
Some queries may want to return other types of data than tables, like images, graphs, etc. These may be combined with table information or not.
A query returns such an object using the <strong>newObject</strong> query event. Each object is MIME encoded, and the MIME Type is sent in the
<strong>contentType</strong> attribute. The object itself is Base-64 encoded.
</p>
<example caption='New Object'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<newObject contentType='image/png'>...</newObject>
...
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='Query Message'>
<p>
During the processing of a query, the query might want to report a message of some kind. This is done using the <strong>queryMessage</strong>
query event.
</p>
<example caption='Query Message'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<queryMessage type='Information' level='Minor'>30 events found.</queryMessage>
...
</queryProgress>
</message>]]>
</example>
<p>
For more information about query messages, see <link url='#messagedef'>Message definitions in query results</link>.
</p>
</section3>
<section3 topic='Title'>
<p>
Enables the executing process of the query to set a custom title for the result. Note that the result only has one title.
</p>
<example caption='Title'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<title name='Current state'/>
...
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='Status'>
<p>
Permits the executing process to report the current status. This can change a lot during execution and values should not be persisted, like
query messages. Instead, they can be displayed in a status bar, just to give the end-user feedback of the status of a long-running query.
</p>
<example caption='Status'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<status message='Processing. 67% done.'/>
...
</queryProgress>
</message>]]>
</example>
</section3>
<section3 topic='Starting a section or subsection'>
<p>
Starts a new section in the query result. In large query results, sections can be used to format the result using an intuitive disposition
in a visually appealing way. Nested sections should be interepreted as sub-sections. Tables and objects started or reported within a section
belong in that section, and should be listed sequentially in the order they are reported to the client.
</p>
<example caption='Starting a section or subsection'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<beginSection header='1. Stockholm'/>
...
<beginSection header='1.1. Solna'/>
...
</queryProgress>
</message>]]>
</example>
<p>
Note that the use of sections in a query result is optional. Tables and objects received outside the scope of sections should be placed
in a default section by the client.
</p>
</section3>
<section3 topic='Closing a section or subsection'>
<p>
Closes the current section or sub-section. Tables inside closed sections can still be open and receive fields. Tables are closed using the
<strong>tableDone</strong> query event.
</p>
</section3>
<example caption='Starting a section or subsection'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<queryProgress xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' cacheType='Apartment' queryId='Query0001'>
...
<endSection/>
...
<endSection/>
...
</queryProgress>
</message>]]>
</example>
</section2>
<section2 topic='Data Source Events' anchor='sourceevents'>
<p>
Events are asynchronous messages sent from the concentrator to devices registered with the concentrator and having subscribed to events from the concentrator.
<link url='#subscribe'>Event subscription</link> can be activated using the <strong>subscribe</strong> command. You can also <link url='#subscribe2'>retrieve historical events</link>
using the <strong>subscribe</strong> command.
</p>
<p>
Each event is sent from the concentrator to each subscriber using a <strong>message</strong> stanza. Each such <strong>message</strong> stanza may contain multiple
events. The following subsections list the different types of events that can be sent. Even though these examples may list only one element in a message stanza, this
is not a limitation. Different types of events may also be mixed within the message stanza.
</p>
<p>
Event subscriptions only last for as long as the client and concentrator both maintains presence. The concentrator must not persist
event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription
is removed.
</p>
<p>
Node events may contain parameters or status messages. This depends on how the subscription was made. The <strong>parameters</strong> and <strong>messages</strong> attributes
in the <strong>subscribe</strong> command determine if node parameters and/or status messages should be sent in event messages.
</p>
<section3 topic='Node added event'>
<p>
The <strong>nodeAdded</strong> event is sent when a node has been added to a data source which the client subscribes to. The following example
shows how such an event message may look like:
</p>
<example caption='Node added event, without parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeAdded xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' nodeType='Namespace.NodeType1'
cacheType='Node' state='None' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01'/>
</message>]]>
</example>
<example caption='Node added event, with parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeAdded xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' nodeType='Namespace.NodeType1'
cacheType='Node' state='None' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01'>
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</nodeAdded>
</message>]]>
</example>
<p>
<strong>Note:</strong> Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first
removing it from the current source (sending a <strong>nodeRemoved</strong> event) and then adding it to the new data source (sending a <strong>nodeAdded</strong>
event), in that order.
</p>
<p>
If a node is added to a parent where order of nodes is important, the attributes <strong>afterNodeId</strong> and also optionally
<strong>afterNodeCacheType</strong> used to identify the node after which the new node should be inserted.
</p>
<example caption='Ordered Node added event, without parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeAdded xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node2' nodeType='Namespace.NodeType1'
cacheType='Node' state='None' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01' afterNodeId='Node1' afterNodeCacheType='Node'/>
</message>]]>
</example>
</section3>
<section3 topic='Node removed'>
<p>
The <strong>nodeRemoved</strong> event is sent when a node in a data source has been removed or destroyed. It does not include status message or parameter
information about the node, only the reference to the node. The following example shows how such an event message may look like:
</p>
<example caption='Node removed'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeRemoved xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<p>
<strong>Note:</strong> Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first
removing it from the current source (sending a <strong>nodeRemoved</strong> event) and then adding it to the new data source (sending a <strong>nodeAdded</strong>
event), in that order.
</p>
</section3>
<section3 topic='Node updated'>
<p>
The <strong>nodeUpdated</strong> event is sent when a node has been updated in a data source which the client subscribes to. The following example
shows how such an event message may look like:
</p>
<example caption='Node updated event, without parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeUpdated xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' nodeType='Namespace.NodeType1'
cacheType='Node' state='None' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<example caption='Node updated event, with parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeUpdated xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' nodeType='Namespace.NodeType1'
cacheType='Node' state='None' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true'
parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</nodeUpdated>
</message>]]>
</example>
<p>
The event has an optional attribute named <strong>oldId</strong>. It is set when the node has been renamed. It must be used, if available, to identify
what node has been updated, as the following example shows:
</p>
<example caption='Node renamed event, without parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeUpdated xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' oldId='OldNode1' nodeId='Node1'
nodeType='Namespace.NodeType1' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<example caption='Node renamed event, with parameters'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeUpdated xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' oldId='OldNode1' nodeId='Node1'
nodeType='Namespace.NodeType1' cacheType='Node' state='None' hasChildren='false' isReadable='true'
isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2013-04-16 15:50:08 -04:00
<string id='id' name='Node ID' value='Node1'/>
<string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
<string id='sn' name='Serial Number' value='123456'/>
<string id='class' name='Node Class' value='Temperature'/>
<string id='meterLoc' name='Meter Location' value='P123502-2'/>
<int id='addr' name='Address' value='123'/>
<double id='lat' name='Latitude' value='12.345'/>
<double id='long' name='Longitude' value='123.45'/>
</nodeUpdated>
</message>]]>
</example>
<p>
<strong>Note: </strong>If only the status has changed, and no other parameters have changed, the <link url='#nodeStatusChanged'>nodeStatusChanged</link>
event could be sent instead, for somewhat improved performance in this case.
</p>
</section3>
<section3 topic='Node status changed' anchor='#nodeStatusChanged'>
<p>
The <strong>nodeStatusChanged</strong> event is sent when the <link url='#nodestates'>state of the node</link> has changed, but no other parameters have been changed.
If the client has subscribed to state messages, these will also be included in the event.
</p>
<example caption='Node status changed event, without messages'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeStatusChanged xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' cacheType='Node' state='ErrorUnsigned'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<example caption='Node status changed event, with messages'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeStatusChanged xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' cacheType='Node' state='ErrorUnsigned'>
2013-04-16 15:50:08 -04:00
<message timestamp='2013-03-22T12:49:34' type='Error'>Sensor does not respond to read-out requests.</message>
</nodeStatusChanged>
</message>]]>
</example>
</section3>
<section3 topic='Node moved up'>
<p>
The <strong>nodeMovedUp</strong> event is sent when a node in a data source has been moved up among its siblings. It does not include status message or parameter
information about the node, only the reference to the node. The following example shows how such an event message may look like:
</p>
<example caption='Node moved up'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeMovedUp xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<p>
<strong>Note:</strong> If issuing a <strong>moveNodeUp</strong> command on a node that is already first among its siblings, the node is not moved and the
concentrator must not send a <strong>nodeMovedUp</strong> event. However, if the client receives such an event pointing to a node that is already first among
its siblings, it should not move the node.
</p>
</section3>
<section3 topic='Node moved down'>
<p>
The <strong>nodeMovedDown</strong> event is sent when a node in a data source has been moved down among its siblings. It does not include status message or parameter
information about the node, only the reference to the node. The following example shows how such an event message may look like:
</p>
<example caption='Node moved down'>
<![CDATA[
<message from='concentrator@example.org'
to='client@example.org/client'>
<nodeMovedDown xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
2013-04-16 15:50:08 -04:00
</message>]]>
</example>
<p>
<strong>Note:</strong> If issuing a <strong>moveNodeDown</strong> command on a node that is already last among its siblings, the node is not moved and the
concentrator must not send a <strong>nodeMovedDown</strong> event. However, if the client receives such an event pointing to a node that is already last among
its siblings, it should not move the node.
</p>
</section3>
</section2>
<section2 topic='Field Databases'>
<p>
A concentrator can often store data from sensors locally (or remotely but controlled locally). Storage is done in <strong>field databases</strong>. A concentrator with
only communicative abilities will publish zero such field databases (and support for none of the field database commands), while a pure metering database will publish
one or many field databases, but none of the nodes available in any of the different data sources are readable or writable. The nodes in this latter case only acts as
placeholders for the data that the concentrator is storing or controlling.
</p>
<p>
The following subsections lists different use cases relating to field databases and how to use them.
</p>
<section3 topic='Get All Databases'>
<p>
The client can retrieve the list of available databases on the concentrator using the <strong>getDatabases</strong> command, as is shown in the following example:
</p>
<example caption='Get All Databases'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='64'>
<getDatabases xmlns='urn:xmpp:iot:concentrators' xml:lang='en'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='64'>
<getDatabasesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
<database databaseId='LocalDB' name='Local Database'/>
<database databaseId='LocalDBTest' name='Local Test Database'/>
<database databaseId='LocalDBProduction' name='Local Production Database'/>
<database databaseId='RemoteDB' name='Remote Database'/>
2013-04-16 15:50:08 -04:00
</getDatabasesResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Get Database Readout Parameters'>
<p>
Before reading data from a database can begin, a parameter form containing database specific search parameters needs to be fetched from the server.
This is done using the <strong>getDatabaseReadoutParameters</strong> command, as is shown in the following example:
</p>
<example caption='Get Database Readout Parameters'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='65'>
<getDatabaseReadoutParameters xmlns='urn:xmpp:iot:concentrators' xml:lang='en' databaseId='LocalDB'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='65'>
<getDatabaseReadoutParametersResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2013-04-16 15:50:08 -04:00
<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'>
2013-04-16 15:50:08 -04:00
<title>Database read-out</title>
<xdl:page label='Time'>
<xdl:fieldref var='from'/>
<xdl:fieldref var='to'/>
</xdl:page>
<xdl:page label='Fields'>
<xdl:fieldref var='fields'/>
</xdl:page>
<xdl:page label='Types'>
<xdl:fieldref var='momentary'/>
<xdl:fieldref var='peak'/>
<xdl:fieldref var='status'/>
<xdl:fieldref var='computed'/>
<xdl:fieldref var='identity'/>
<xdl:fieldref var='historySecond'/>
<xdl:fieldref var='historyMinute'/>
<xdl:fieldref var='historyHour'/>
<xdl:fieldref var='historyDay'/>
<xdl:fieldref var='historyWeek'/>
<xdl:fieldref var='historyMonth'/>
<xdl:fieldref var='historyQuarter'/>
<xdl:fieldref var='historyYear'/>
<xdl:fieldref var='historyOther'/>
</xdl:page>
<xdl:page label='Status'>
<xdl:fieldref var='missing'/>
<xdl:fieldref var='automaticEstimates'/>
<xdl:fieldref var='manualEstimates'/>
<xdl:fieldref var='manualReadout'/>
<xdl:fieldref var='automaticReadout'/>
<xdl:fieldref var='timeOffset'/>
<xdl:fieldref var='warning'/>
<xdl:fieldref var='error'/>
<xdl:fieldref var='signed'/>
<xdl:fieldref var='invoiced'/>
<xdl:fieldref var='invoicedConfirmed'/>
<xdl:fieldref var='endOfSeries'/>
<xdl:fieldref var='powerFailure'/>
<xdl:fieldref var='statusLogicMode'/>
</xdl:page>
<field var='xdd session' type='hidden'>
<value>C20D4F0C-8F8A-490F-8188-53017DF2B71A</value>
</field>
<field var='from' type='text-single' label='From:'>
<required/>
<xdv:validate datatype='xs:dateTime'>
<xdv:basic/>
</xdv:validate>
<desc>Read values not older that this timestamp.</desc>
<value></value>
</field>
<field var='to' type='text-single' label='To:'>
<required/>
<xdv:validate datatype='xs:dateTime'>
<xdv:basic/>
</xdv:validate>
<desc>Read values not newer that this timestamp.</desc>
<value></value>
</field>
<field var='fields' type='text-multi' label='Fields to include: (Use * as wildcards)'>
<desc>If specified, only the following fields (include wildcards) will be read out.</desc>
<value></value>
</field>
<field var='momentary' type='boolean' label='Momentary Values'>
<desc>If checked, momentary values will be read.</desc>
<value>false</value>
</field>
<field var='peak' type='boolean' label='Peak Values'>
<desc>If checked, peak values will be read.</desc>
<value>false</value>
</field>
<field var='status' type='boolean' label='Status Values'>
<desc>If checked, status values will be read.</desc>
<value>false</value>
</field>
<field var='computed' type='boolean' label='Computed Values'>
<desc>If checked, computed values will be read.</desc>
<value>false</value>
</field>
<field var='identity' type='boolean' label='Identity Values'>
<desc>If checked, identity values will be read.</desc>
<value>false</value>
</field>
<field var='historySecond' type='boolean' label='Historical Values (second)'>
<desc>If checked, historical values (second) will be read.</desc>
<value>false</value>
</field>
<field var='historyMinute' type='boolean' label='Historical Values (minute)'>
<desc>If checked, historical values (minute) will be read.</desc>
<value>false</value>
</field>
<field var='historyHour' type='boolean' label='Historical Values (hour)'>
<desc>If checked, historical values (hour) will be read.</desc>
<value>false</value>
</field>
<field var='historyDay' type='boolean' label='Historical Values (day)'>
<desc>If checked, historical values (day) will be read.</desc>
<value>false</value>
</field>
<field var='historyWeek' type='boolean' label='Historical Values (week)'>
<desc>If checked, historical values (week) will be read.</desc>
<value>false</value>
</field>
<field var='historyMonth' type='boolean' label='Historical Values (month)'>
<desc>If checked, historical values (month) will be read.</desc>
<value>false</value>
</field>
<field var='historyQuarter' type='boolean' label='Historical Values (quarter)'>
<desc>If checked, historical values (quarter) will be read.</desc>
<value>false</value>
</field>
<field var='historyYear' type='boolean' label='Historical Values (year)'>
<desc>If checked, historical values (year) will be read.</desc>
<value>false</value>
</field>
<field var='historyOther' type='boolean' label='Historical Values (other)'>
<desc>If checked, historical values (other) will be read.</desc>
<value>false</value>
</field>
<field var='missing' type='list-single' label='Missing Values:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='automaticEstimates' type='list-single' label='Automatic Estimates:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='manualEstimates' type='list-single' label='Manual Estimates:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='manualReadout' type='list-single' label='Manual Readout:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='automaticReadout' type='list-single' label='Automatic Readout:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='timeOffset' type='list-single' label='Time Offset:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='warning' type='list-single' label='Warning:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='error' type='list-single' label='Error:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='signed' type='list-single' label='Signed:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='invoiced' type='list-single' label='Invoiced:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='invoicedConfirmed' type='list-single' label='Invoiced and Confirmed:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='endOfSeries' type='list-single' label='End of Series:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='powerFailure' type='list-single' label='Power Failure:'>
<desc>Determines how this flag should be treated during readout.</desc>
<value>Ignore</value>
<option label='Ignore'><value>Ignore this flag.</value></option>
<option label='Required'><value>Only read values with this flag set.</value></option>
<option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
</field>
<field var='statusLogicMode' type='list-single' label='Combination Logic:'>
<desc>This parameter specifies how multiple status flags are to be treated in the readout.</desc>
<value>Any</value>
<option label='Any'><value>Any of the conditions above are met.</value></option>
<option label='All'><value>All of the conditions above are met.</value></option>
</field>
</x>
</getDatabaseReadoutParametersResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Start Database Readout'>
<p>
Once the parameter form has been filled out, a database readout can be started using the <strong>startDatabaseReadout</strong> command.
Data read from the concentrator will follow the same flow of sensor data as that described in &xep0323;. The only difference is that the
read-out is started with the <strong>startDatabaseReadout</strong> command instead of the <strong>req</strong>
2013-04-16 15:50:08 -04:00
command of the sensor data namespace.
</p>
<p>
The following diagram shows the flow of messages when requesting a readout from a database:
</p>
<p>
<img src='data:image/png;base64,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
2013-04-16 15:50:08 -04:00
</p>
<p>
The following example shows a <strong>startDatabaseReadout</strong> request:
</p>
<example caption='Start Database Readout'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='66'>
<startDatabaseReadout xmlns='urn:xmpp:iot:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='1' userToken='12392748927492834'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>C20D4F0C-8F8A-490F-8188-53017DF2B71A</value>
</field>
<field var='from' type='text-single'>
<value>2013-03-22T00:00:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-03-23T00:00:00</value>
</field>
<field var='fields' type='text-multi'>
<value>Temperature</value>
<value>Pressure</value>
<value>Power</value>
</field>
<field var='momentary' type='boolean'>
<value>true</value>
</field>
<field var='peak' type='boolean'>
<value>false</value>
</field>
<field var='status' type='boolean'>
<value>false</value>
</field>
<field var='computed' type='boolean'>
<value>false</value>
</field>
<field var='identity' type='boolean'>
<value>false</value>
</field>
<field var='historySecond' type='boolean'>
<value>false</value>
</field>
<field var='historyMinute' type='boolean'>
<value>false</value>
</field>
<field var='historyHour' type='boolean'>
<value>false</value>
</field>
<field var='historyDay' type='boolean'>
<value>false</value>
</field>
<field var='historyWeek' type='boolean'>
<value>false</value>
</field>
<field var='historyMonth' type='boolean'>
<value>false</value>
</field>
<field var='historyQuarter' type='boolean'>
<value>false</value>
</field>
<field var='historyYear' type='boolean'>
<value>false</value>
</field>
<field var='historyOther' type='boolean'>
<value>false</value>
</field>
<field var='missing' type='list-single'>
<value>Ignore</value>
</field>
<field var='automaticEstimates' type='list-single'>
<value>Ignore</value>
</field>
<field var='manualEstimates' type='list-single'>
<value>Ignore</value>
</field>
<field var='manualReadout' type='list-single'>
<value>Ignore</value>
</field>
<field var='automaticReadout' type='list-single'>
<value>Ignore</value>
</field>
<field var='timeOffset' type='list-single'>
<value>Ignore</value>
</field>
<field var='warning' type='list-single'>
<value>Ignore</value>
</field>
<field var='error' type='list-single'>
<value>Ignore</value>
</field>
<field var='signed' type='list-single'>
<value>Ignore</value>
</field>
<field var='invoiced' type='list-single'>
<value>Ignore</value>
</field>
<field var='invoicedConfirmed' type='list-single'>
<value>Ignore</value>
</field>
<field var='endOfSeries' type='list-single'>
<value>Ignore</value>
</field>
<field var='powerFailure' type='list-single'>
<value>Ignore</value>
</field>
<field var='statusLogicMode' type='list-single'>
<value>Any</value>
</field>
</x>
</startDatabaseReadout>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='66'>
<startDatabaseReadoutResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>
... Readout messages follow.]]>
</example>
</section3>
<section3 topic="Start Database Readout, Failure">
<p>
The following example shows a response when the concentrator rejects the read-out request:
</p>
<example caption='Start Database Readout, Failure'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='67'>
<startDatabaseReadout xmlns='urn:xmpp:iot:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='2' userToken='12392748927492834'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
...
</x>
</startDatabaseReadout>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='67'>
<startDatabaseReadoutResponse xmlns='urn:xmpp:iot:concentrators' result='InsufficientPrivileges'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
<p>
The error might also be a result of invalid input parameters being sent:
</p>
<example caption='Start Database Readout, Failure 2'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='68'>
<startDatabaseReadout xmlns='urn:xmpp:iot:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='3' userToken='12392748927492834'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
...
<field var='from' type='text-single'>
<value>2013-03-23T00:00:00</value>
</field>
<field var='to' type='text-single'>
<value>2013-03-22T00:00:00</value>
</field>
...
</x>
</startDatabaseReadout>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='68'>
<startDatabaseReadoutResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2013-04-16 15:50:08 -04:00
<error var='to'>The To timestamp cannot be older than the From timestamp.</error>
</startDatabaseReadoutResponse>
</iq>]]>
</example>
</section3>
<section3 topic='Cancelling a database read-out'>
<p>
A client can cancel a database read-out using the <link url='http://xmpp.org/extensions/xep-0323.html#cancelreadout'>cancel</link> read-out command,
as described in <link url='http://xmpp.org/extensions/xep-0323.html'>Internet of Things - Sensor Data</link>.
2013-04-16 15:50:08 -04:00
</p>
<example caption='Cancelling a database read-out'>
<![CDATA[
<iq type='set'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='70'>
<startDatabaseReadout xmlns='urn:xmpp:iot:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='4' userToken='12392748927492834'>
2013-04-16 15:50:08 -04:00
<node sourceId='MeteringTopology' nodeId='Node1'/>
<node sourceId='MeteringTopology' nodeId='Node2'/>
<node sourceId='MeteringTopology' nodeId='Node3'/>
<x type='submit' xmlns='jabber:x:data'>
...
</x>
</startDatabaseReadout>
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='70'>
<startDatabaseReadoutResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
2013-04-16 15:50:08 -04:00
</iq>
...
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='71'>
<cancel xmlns='urn:xmpp:iot:sensordata' seqnr='4'/>
2013-04-16 15:50:08 -04:00
</iq>
<iq type='result'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='71'>
<cancelled xmlns='urn:xmpp:iot:sensordata' seqnr='4'/>
2013-04-16 15:50:08 -04:00
</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:concentrators" in response to &xep0030; information requests.</p>
<example caption="Service discovery information request">
<![CDATA[
<iq type='get'
from='device@example.org/device'
to='provisioning@example.org'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]>
</example>
<example caption="Service discovery information response">
<![CDATA[
<iq type='result'
from='provisioning@example.org'
to='device@example.org/device'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:iot:concentrators'/>
...
</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>
2013-04-16 15:50:08 -04:00
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Node Information' anchor='nodeinfo'>
<p>
Several commands return basic node information. The following table lists possible fields with corresponding descriptions.
</p>
<table caption='Basic Node Information'>
<tr>
<th>Attribute</th>
<th>Use</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>nodeId</td>
2013-04-16 15:50:08 -04:00
<td>required</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>The ID of the node in the data source.</td>
</tr>
<tr>
<td>displayName</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>If provided, a string presentable to users. If localization is supported and a correct language attribute was provided, this string will be localized.</td>
</tr>
<tr>
<td>nodeType</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>A string representing the type of the node.</td>
</tr>
<tr>
<td>localId</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>If provided, an ID for the node, but unique locally between siblings.</td>
</tr>
<tr>
<td>logId</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>If provided, an ID for the node, as it would appear or be used in system logs.</td>
</tr>
<tr>
<td>cacheType</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>Used to uniquely identify the node in sources where the ID of the node is not sufficient. Example: In a spatial ordering different nodes may represent
countries, regions, cities, areas, streets, buildings and apartments in the same source. However, the ID of each node would depend on what type of node it
represents. It might be valid to have a region, city and/or area with the same ID. So, to these circumstances, a Cache Type of Country, Region, City, Area,
Street, Building and Apartment can be used to allow for non-unique IDs within the source, as long as they are unique within the same cache type. ***</td>
</tr>
<tr>
<td>state</td>
<td>required</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>Current overall state of the node.</td>
</tr>
<tr>
<td>hasChildren</td>
<td>required</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>If the node has children or not.</td>
</tr>
<tr>
<td>childrenOrdered</td>
<td>optional</td>
<td>false</td>
<td>If the children of the node have an intrinsic order (true), or if the order is not important (false). If the order is not important, the client
can present the order as it wishes, for example sorted on Node ID or any other parameter available on the child nodes. However, if the children have an
intrinsic order, it's important for the client to refresh the child list when necessary whenever the order is unknown, such as after a nodeAdded event or
a nodeRemoved event.
</td>
</tr>
<tr>
<td>isReadable</td>
<td>optional</td>
<td>false</td>
<td>If the node can be read. (*)</td>
</tr>
<tr>
<td>isControllable</td>
2013-04-16 15:50:08 -04:00
<td>optional</td>
<td>false</td>
<td>If the node can be controlled. (**)</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>hasCommands</td>
<td>optional</td>
<td>false</td>
<td>If the node has registered commands or not.</td>
</tr>
<tr>
<td>parentId</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>The node ID of the parent node. If not available, the node is considered a root node.</td>
</tr>
<tr>
<td>parentCacheType</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>The Cache Type of the parent node.</td>
</tr>
<tr>
<td>lastChanged</td>
<td>optional</td>
<td>&nbsp;</td>
2013-04-16 15:50:08 -04:00
<td>When the node was last changed. Can be used by clients to synchronize content between the concentrator and itself.</td>
</tr>
</table>
<p>
(*) See <link url='http://xmpp.org/extensions/xep-0323.html'>Internet of Things - Sensor Data</link> for more information about how to read nodes.
2013-04-16 15:50:08 -04:00
</p>
<p>
(**) See <link url='http://xmpp.org/extensions/xep-0325.html'>Internet of Things - Control</link> for more information about how to control nodes.
2013-04-16 15:50:08 -04:00
</p>
<p>
(***) Note that <strong>cacheType</strong> is optional. In some data sources it might be necessary to include a cache type to allow for IDs that are not unique
within the source. In these cases, it concentrator must include the cacheType attribute for nodes in the corresponding data source, and clients must use the corresponding
cacheType value when referencing the node. But if such a separation of IDs within a source is not required, the concentrator may ignore the cacheType attribute.
In these instances clients may also ignore the cacheType attribute when referencing the nodes in the corresponding data source, or use the empty string as value for the
cacheType value. The server must ignore empty cacheType values for data sources not using a cache type separation mechanism.
</p>
</section2>
<section2 topic='Parameter Types'>
<p>
Nodes can report parameters of different types. The following table lists available parameter types.
</p>
<table caption='Parameter Types'>
<tr>
<th>Element Name</th>
<th>Parameter Value</th>
</tr>
<tr>
<td>boolean</td>
<td>Boolean values. Can be true or false.</td>
</tr>
<tr>
<td>color</td>
<td>Color values. They are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component.</td>
</tr>
<tr>
<td>dateTime</td>
<td>Date and time value, with possible time zone information.</td>
</tr>
<tr>
<td>double</td>
<td>double precision floating point value.</td>
</tr>
<tr>
<td>duration</td>
<td>A time duration value.</td>
</tr>
<tr>
<td>int</td>
<td>A 32-bit integer value.</td>
</tr>
<tr>
<td>long</td>
<td>A 64-bit integer value.</td>
</tr>
<tr>
<td>string</td>
<td>A string value.</td>
</tr>
<tr>
<td>time</td>
<td>A time value using a 24-hour clock.</td>
</tr>
</table>
</section2>
<section2 topic='Response Codes'>
<p>
All responses have a response code that the client is required to check. The following table lists possible response codes and their corresponding meanings.
</p>
<table caption='Response Codes'>
<tr>
<th>Response Code</th>
<th>Description</th>
</tr>
<tr>
<td>OK</td>
<td>Request is OK and accepted.</td>
</tr>
<tr>
<td>NotFound</td>
<td>Corresponding object, node, etc., was not found.</td>
</tr>
<tr>
<td>InsufficientPrivileges</td>
<td>Insufficient privileges to perform the corresponding action or execute the corresponding command. Make sure to provide sufficient credentials in the call
(user, service, device tokens) with sufficient privileges to perform the action/command.</td>
</tr>
<tr>
<td>Locked</td>
<td>The object/node is locked, and operation could not be performed or completed.</td>
</tr>
<tr>
<td>NotImplemented</td>
<td>Command is not implemented.</td>
</tr>
<tr>
<td>FormError</td>
<td>The form send to the concentrator contains errors. The response contains detailed error information.</td>
</tr>
<tr>
<td>OtherError</td>
<td>Another error occurred.</td>
</tr>
</table>
</section2>
<section2 topic='Unimplemented commands'>
<p>
It's important that the concentrator responds to unrecognized commands. This, to make sure future extensions to this document does not produce unexpected
results in concentrators implementing a previous version, or in concentrators implementing only a subset of available commands.
</p>
<p>
When a concentrator receives an element that it does not understand, it must do as follows:
</p>
<ul>
<li>If the element is received in a message stanza, the element must be ignored.</li>
<li>If the element is received in an iq-result stanza, the element must be ignored.</li>
<li>If the element is received in an iq-get or iq-set stanza, an iq-result stanza must be composed containing an element with the same name as the incoming
element, but with <strong>Response</strong> appended to it, having a response code of <strong>NotImplemented</strong>.</li>
</ul>
<p>
The following example shows how unrecognized commands must be handled by the concentrator:
</p>
<example caption='Unimplemented commands'>
<![CDATA[
<iq type='get'
from='client@example.org/client'
to='concentrator@example.org'
2013-04-16 15:50:08 -04:00
id='69'>
<holabandola xmlns='urn:xmpp:iot:concentrators' ...>
2013-04-16 15:50:08 -04:00
...
</holabandola>
</iq>
<iq type='error'
from='concentrator@example.org'
to='client@example.org/client'
2013-04-16 15:50:08 -04:00
id='69'>
<holabandolaResponse xmlns='urn:xmpp:iot:concentrators' result='NotImplemented'/>
2013-04-16 15:50:08 -04:00
</iq>]]>
</example>
</section2>
<section2 topic='Command attributes' anchor='nodecommands'>
<p>
Node commands have a set of attributes. The following table lists available attributes and what they mean.
</p>
<table caption='Command attributes'>
<tr>
<th>Attribute</th>
<th>Use</th>
<th>Description</th>
</tr>
<tr>
<td>command</td>
2013-04-16 15:50:08 -04:00
<td>required</td>
<td>ID of the command. Used to identify the command.</td>
</tr>
<tr>
<td>name</td>
<td>required</td>
<td>A string that can be presented to an end-user. Should be localized if the request contained a language preference.</td>
</tr>
<tr>
<td>type</td>
<td>required</td>
<td>If the command is 'Simple' or 'Parameterized'.</td>
</tr>
<tr>
<td>sortCategory</td>
<td>optional</td>
<td>Should be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and
lastly by Name.</td>
</tr>
<tr>
<td>sortKey</td>
<td>optional</td>
<td>
Should be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and
lastly by Name.
</td>
</tr>
<tr>
<td>confirmationString</td>
<td>optional</td>
<td>Should presented to clients (if available) before letting an end-user execute the command. A delete command might have a confirmationString saying
'Are you sure you want to delete the current item?' The confirmation string should be presented as a Yes/No[/Cancel] dialog.</td>
</tr>
<tr>
<td>failureString</td>
<td>optional</td>
<td>
Could be presented to end-users (if available) if a command fails. It provides the client with an optionally localized string giving some context to the error message.
A delete command might have a failureString saying 'Unable to delete the current item.'. The client could then add additional error information, if available,
for instance from the response code.
</td>
</tr>
<tr>
<td>successString</td>
<td>optional</td>
<td>
Could be presented to end-users (if available) if a command is successfully executed. It provides the client with an optionally localized string giving some context
to the message. A delete command might have a successString saying 'Current item successfully deleted.'.
</td>
</tr>
</table>
</section2>
<section2 topic='Node States'>
<p>
Nodes can be in different states. Even though nodes are free to publish any amount of states as parameters, there are a set of states that are so crucial to the
concept of a node state, that they are published using a separate attribute and separate events. These node states are as follows:
</p>
<table caption='Node States'>
<tr>
<th>State</th>
<th>Description</th>
</tr>
<tr>
<td>None</td>
<td>The node has nothing special to report.</td>
</tr>
<tr>
<td>Information</td>
<td>The node has informative events reported on it.</td>
</tr>
<tr>
<td>WarningSigned</td>
<td>The node has warnings reported on it. These warnings have been viewed by an operator.</td>
</tr>
<tr>
<td>WarningUnsigned</td>
<td>The node has warnings reported on it that have not been viewed by anybody.</td>
</tr>
<tr>
<td>ErrorSigned</td>
<td>The node has errors reported on it. These errors have been viewed by an operator.</td>
</tr>
<tr>
<td>ErrorUnsigned</td>
<td>The node has errors reported on it that have not been viewed by anybody.</td>
</tr>
</table>
</section2>
<section2 topic='Required Data Sources'>
<p>
The following table lists required data sources for concentrators (of sensors, actuators, meters, etc.) in sensor networks:
</p>
<table caption='Required Data Sources'>
<tr>
<th>Data Source</th>
<th>Description</th>
</tr>
<tr>
<td>MeteringTopology</td>
<td>Data Source containing the topology of metering devices, including sensors, actuators, meter, infrastructure components, etc.</td>
</tr>
</table>
<p>
More information can be found in the <note>XEP-xxxx: Interoperability <link url='#interop'>Interoperability section</link></note>.
</p>
</section2>
<section2 topic='Table Column definitions in query results' anchor='columndef'>
<p>
Table columns in query results can have the following attributes:
</p>
<table caption='Table Column attributes'>
<tr>
<th>Attribute</th>
<th>Use</th>
<th>Description</th>
</tr>
<tr>
<td>columnId</td>
<td>Required</td>
<td>ID of column</td>
</tr>
<tr>
<td>header</td>
<td>Optional</td>
<td>If provided, a localized name to be displayed instead of the column ID.</td>
</tr>
<tr>
<td>alignment</td>
<td>Optional</td>
<td>Alignment of contents in the column. If provided, the client does not need to guess alignment from the type of data reported.</td>
</tr>
<tr>
<td>nrDecimals</td>
<td>Optional</td>
<td>If floating point data is presented in the column and a fixed number of decimals is desired, this attribute is used to fix the number of decimals used.</td>
</tr>
<tr>
<td>dataSourceId</td>
<td>Optional</td>
<td>If contents of columns contains references to nodes in a data source, this attribute defines the data source ID.</td>
</tr>
<tr>
<td>cacheTypeName</td>
<td>Optional</td>
<td>If contents of columns contains references to nodes in a data source, this attribute defines the cache type.</td>
</tr>
<tr>
<td>fgColor</td>
<td>Optional</td>
<td>If presentation of this column should be done using a specific foreground color.</td>
</tr>
<tr>
<td>bgColor</td>
<td>Optional</td>
<td>If presentation of this column should be done using a specific background color.</td>
</tr>
</table>
</section2>
<section2 topic='Record Item definitions in query results' anchor='recorddef'>
<p>
Records contain arrays of items, each item correspond to a specific column with the same ordinal index. Each item is specified together with its type.
This, so receptors can integrate the result with type information if necessary. The following different type elements are available:
</p>
<table caption='Table Column attributes'>
<tr>
<th>Element</th>
<th>Contents</th>
</tr>
<tr>
<td>boolean</td>
<td>A boolean value, corresponding to the xs:boolean data type.</td>
</tr>
<tr>
<td>color</td>
<td>A color value. These are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component.</td>
</tr>
<tr>
<td>dateTime</td>
<td>A Date &amp; Time value, corresponding to the xs:dateTime data type.</td>
</tr>
<tr>
<td>double</td>
<td>A floating-point value, corresponding to the xs:double data type.</td>
</tr>
<tr>
<td>duration</td>
<td>A duration value, corresponding to the xs:duration data type.</td>
</tr>
<tr>
<td>int</td>
<td>A 32-bit integer value, corresponding to the xs:int data type.</td>
</tr>
<tr>
<td>long</td>
<td>A 64-bit value, corresponding to the xs:long data type.</td>
</tr>
<tr>
<td>string</td>
<td>A string value, corresponding to the xs:string data type.</td>
</tr>
<tr>
<td>time</td>
<td>A time value, corresponding to the xs:time data type.</td>
</tr>
<tr>
<td>base64</td>
<td>A base-64 encoded object. The object is MIME encoded, and the attribute contentType contains the MIME Type which includes information on how to decode the value.</td>
</tr>
<tr>
<td>void</td>
<td>Contains no information. This represents a NULL value.</td>
2013-04-16 15:50:08 -04:00
</tr>
</table>
</section2>
<section2 topic='Message definitions in query results' anchor='messagedef'>
2013-04-16 15:50:08 -04:00
<p>
Messages in query results contain apart from a message text, also contain some classification on what the message is using two attributes: The
<strong>type</strong> attribute gives a rough idea about the type of message and <strong>level</strong> the importance of the message.
2013-04-16 15:50:08 -04:00
</p>
<table caption='Message Types'>
2013-04-16 15:50:08 -04:00
<tr>
<th>Type</th>
2013-04-16 15:50:08 -04:00
<th>Description</th>
</tr>
<tr>
<td>Information</td>
<td>Information message</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Warning</td>
<td>Message contains a warning. The situation could turn into an error if consideration or action is not taken.</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Error</td>
<td>Message contains an error. The error message describes the error, and the error has been handled correctly by the device performing the query.</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Exception</td>
<td>Message contains an exception message. An unforseen and perhaps an unhandled event has occurred during the execution of the query.</td>
2013-04-16 15:50:08 -04:00
</tr>
</table>
<table caption='Message Levels'>
2013-04-16 15:50:08 -04:00
<tr>
<th>Level</th>
<th>Description</th>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Minor</td>
<td>Minor event. Message describes common tasks.</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Medium</td>
<td>Medium event. Message might describe a state change, something has been updated, or important information.</td>
2013-04-16 15:50:08 -04:00
</tr>
<tr>
<td>Major</td>
<td>Major event. Message might describe architectural change or vital information.</td>
2013-04-16 15:50:08 -04:00
</tr>
</table>
</section2>
<section2 topic='Single vs. batch commands'>
2013-04-16 15:50:08 -04:00
<p>
Many commands exist in single and batch versions. Large concentrators require efficient ways to manage sets of nodes simultaneously, while for small
concentrators, it is sufficient to manage nodes one at a time.
</p>
<p>
A concentrator is not required to implement both sets of commands if not desired. However, it must report which commands it supports in the
<strong>getCapabilities</strong> command. A caller can then adapt its calls based on what commands are supported.
</p>
<p>
If a caller wants to call the single item version of a command, but the concentrator only supports the batch version, it should call the batch version, but
only include the single node in the list of nodes.
</p>
<p>
On the other hand, if the caller wants to perform an operation on a set of nodes, but the concentrator only supports the single item version of the command,
it needs to manually perform the operation on each node separately, unless failing the request is an option.
2013-04-16 15:50:08 -04:00
</p>
</section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<section2 topic='Localization'>
<p>
Localization of content can be performed if clients provide <strong>xml:lang</strong> attributes in commands made to the concentrator. If omitted, the
<strong>default language</strong> will be used in responses. If provided, but the concentrator does not support localization, or the requested language,
the <strong>default language</strong> will also be used.
</p>
</section2>
<section2 topic='Time Zones'>
<p>
Concentrators of larger sub-systems spanning multiple time-zones should specify all timestamps with time-zone information, so readers can perform comparisons
of time information.
</p>
<p>
Information read from a concentrator that lacks time-zone information should be considered to lie in the same time-zone as the reader, unless not explicitly
configured with a time-zone.
</p>
</section2>
<section2 topic='Interoperability' anchor='interop'>
<p>
For concentrators to be interoperable in sensor networks, they need to adhere to rules and guidelines described in the
<link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability</link> document.
2013-04-16 15:50:08 -04:00
</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<section2 topic='Access rights'>
<p>
This document publishes a lot of commands with which to interact with a concentrator. If security and access rights is an issue, it might not be sufficient
to allow all friends access to the system. There are many ways in which to restrict access to the contents of the concentrator. Following are some examples:
</p>
<ul>
<li>
The concentrator can restrict friendships to trusted friends, and then assign access rights internally to the approved contacts.
</li>
<li>
The concentrator can use a provisioning server (see &xep0324;)
to delegate trust to a third party responsible for controlling who can get access to the concentrator (<strong>isFriend</strong> or <strong>canAccess</strong> commands),
2013-04-16 15:50:08 -04:00
and what items can be viewed (<strong>hasPrivilege</strong> or <strong>downloadPrivileges</strong> commands).
</li>
<li>
All requests to the concentrator can contain the optional attributes <strong>deviceToken</strong>, <strong>serviceToken</strong> and <strong>userToken</strong>.
Clients making requests to the concentrator can use these attributes to forward information about who originated the action (<strong>userToken</strong>),
what service is performing the action (<strong>serviceToken</strong>) or what device is performing the action (<strong>deviceToken</strong>). The concentrator
can use this information to check with provisioning servers what access rights and user privileges exist before performing the action.
</li>
</ul>
</section2>
<section2 topic='Integration with provisioning servers'>
<p>
The <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link> document describes how trust can be delegated to trusted provisioning servers
that can be used to restrict access to and privileges in a network.
</p>
<p>
If a concentrator has a trusted relationship with a provisioning server, external or internal, the provisioning server must be used to guarantee that the
concentrator only allows access according to rules defined by the provisioning server. In order to do this, it's important that clients always provide
available tokens (<strong>userToken</strong>, <strong>serviceToken</strong> and <strong>deviceToken</strong>) to the concentrator so that it can forward this
information to the provisioning server.
</p>
<p>
The following subsections show different examples of how such an integration can be performed.
</p>
<section3 topic='Restricting access to data source per contact'>
<p>
This section shows how a provisioning server can be used to restrict access to data sources to users allowed to access those data sources.
</p>
<p>
<img src='data:image/png;base64,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
</p>
<p>
Notice the following:
</p>
<ul>
<li>
The user has a <strong>userToken</strong> it received during <link url='http://xmpp.org/extensions/xep-0324.html#usertoken'>connection with the service</link>. This user token should
be included in all calls made by the user.
</li>
<li>
The service has a <strong>serviceToken</strong> it received during <link url='http://xmpp.org/extensions/xep-0324.html#servicetoken'>service registration</link>. This service token
should be aggregated by all calls made by the service.
</li>
<li>
The concentrators should cache all calls made to the provisioning server according to available <link url='http://xmpp.org/extensions/xep-0324.html#cache'>cache rules</link>.
</li>
<li>
The conversion of a Data Source ID to a Privilege ID should be performed according to rules defined in <link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability</link>.
</li>
</ul>
</section3>
<section3 topic='Restricting access to node properties per contact'>
<p>
This section shows how a provisioning server can be used to restrict access to node parameters that users allowed to access and edit.
</p>
<p>
<img src='data:image/png;base64,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
</p>
<ul>
<li>
Not that privileges for all parameters needs to be checked in every call. And if lost from the cache, a new request needs to be made to the provisioning server.
</li>
<li>
The conversion of a Parameter ID (and Page) to a Privilege ID should be performed according to rules defined in
<link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability</link>.
</li>
</ul>
</section3>
<section3 topic='Restricting access to node commands per contact'>
<p>
This section shows how a provisioning server can be used to restrict access to node commands to users allowed to access those commands.
</p>
<p>
<img src='data:image/png;base64,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
</p>
<p>
In addition to rules noted above, also notice the following:
</p>
<ul>
<li>
Not that privileges for all parameters needs to be checked in every call. And if lost from the cache, a new request needs to be made to the provisioning server.
</li>
<li>
The conversion of a Command ID to a Privilege ID should be performed according to rules defined in <link url='xep-0000-IoT-Interoperability.html'>xep-0000-IoT-Interoperability</link>.
</li>
</ul>
</section3>
</section2>
</section1>
2013-04-16 15:50:08 -04:00
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
2013-04-16 15:50:08 -04:00
<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>
2013-04-16 15:50:08 -04:00
<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:concentrators'
xmlns='urn:xmpp:iot:concentrators'
xmlns:sn='urn:xmpp:iot:sensordata'
2013-04-16 15:50:08 -04:00
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'/>
2013-04-16 15:50:08 -04:00
<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='getCapabilities' type='TokenRequest'/>
<xs:element name='getCapabilitiesResponse' type='StringArrayResponse'/>
<xs:element name='getAllDataSources' type='TokenRequest'/>
<xs:element name='getAllDataSourcesResponse' type='DataSourceArrayResponse'/>
<xs:element name='getRootDataSources' type='TokenRequest'/>
<xs:element name='getRootDataSourcesResponse' type='DataSourceArrayResponse'/>
<xs:element name='getChildDataSources' type='SourceReferenceRequest'/>
<xs:element name='getChildDataSourcesResponse' type='DataSourceArrayResponse'/>
<xs:element name='containsNode' type='NodeReferenceRequest'/>
<xs:element name='containsNodeResponse'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:boolean'>
<xs:attributeGroup ref='responseCode'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='containsNodes' type='NodeReferencesRequest'/>
<xs:element name='containsNodesResponse' type='BooleanArrayResponse'/>
<xs:element name='getNode' type='NodeReferenceParametersRequest'/>
<xs:element name='getNodeResponse'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeInformation'>
<xs:attributeGroup ref='responseCode'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='getNodes' type='NodeReferenceParametersRequest'/>
<xs:element name='getNodesResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getAllNodes' type='GetAllNodesRequest'/>
2013-04-16 15:50:08 -04:00
<xs:element name='getAllNodesResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getNodeInheritance' type='NodeReferenceRequest'/>
<xs:element name='getNodeInheritanceResponse'>
<xs:complexType>
<xs:sequence>
<xs:element name='baseClasses' type='StringArray' minOccurs='1' maxOccurs='1'/>
<xs:element name='interfaces' type='StringArray' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='getRootNodes' type='SourceReferenceParametersRequest'/>
<xs:element name='getRootNodesResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getChildNodes' type='GetChildNodesRequest'/>
2013-04-16 15:50:08 -04:00
<xs:element name='getChildNodesResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getIndices' type='SourceReferenceRequest'/>
<xs:element name='getIndicesResponse' type='StringArrayResponse'/>
<xs:element name='getNodesFromIndex' type='IndexReferenceRequest'/>
<xs:element name='getNodesFromIndexResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getNodesFromIndices' type='IndexReferencesRequest'/>
<xs:element name='getNodesFromIndicesResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getAllIndexValues'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='SourceReferenceRequest'>
<xs:attribute name='index' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='getAllIndexValuesResponse' type='StringArrayResponse'/>
<xs:element name='getNodeParametersForEdit' type='NodeReferenceRequest'/>
<xs:element name='getNodeParametersForEditResponse' type='ParameterFormResponse'/>
<xs:element name='setNodeParametersAfterEdit'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferenceRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="1" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='setNodeParametersAfterEditResponse' type='SetNodeParametersResponse'/>
<xs:element name='getCommonNodeParametersForEdit' type='NodeReferencesRequest'/>
<xs:element name='getCommonNodeParametersForEditResponse' type='ParameterFormResponse'/>
<xs:element name='setCommonNodeParametersAfterEdit'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferencesRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="1" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='setCommonNodeParametersAfterEditResponse' type='SetNodeParametersResponse'/>
<xs:element name='getAddableNodeTypes' type='NodeReferenceRequest'/>
<xs:element name='getAddableNodeTypesResponse'>
<xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='nodeType'>
<xs:complexType>
<xs:attribute name='type' type='xs:string' use='required'/>
<xs:attribute name='name' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='getParametersForNewNode' type='NodeTypeReferenceRequest'/>
<xs:element name='getParametersForNewNodeResponse' type='ParameterFormResponse'/>
<xs:element name='createNewNode'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeTypeReferenceRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="1" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='createNewNodeResponse' type='SetNodeParametersResponse'/>
<xs:element name='destroyNode' type='NodeReferenceRequest'/>
<xs:element name='destroyNodeResponse'>
<xs:complexType>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
</xs:element>
<xs:element name='getAncestors' type='NodeReferenceParametersRequest'/>
<xs:element name='getAncestorsResponse' type='NodeInformationArrayResponse'/>
<xs:element name='getNodeCommands' type='NodeReferenceRequest'/>
<xs:element name='getNodeCommandsResponse' type='CommandArray'/>
<xs:element name='getCommandParameters' type='NodeCommandReferenceRequest'/>
<xs:element name='getCommandParametersResponse' type='ParameterFormResponse'/>
<xs:element name='executeNodeCommand'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeCommandReferenceRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="0" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='executeNodeCommandResponse' type='ExecuteNodeCommandResponse'/>
<xs:element name='executeNodeQuery'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeCommandReferenceRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='executeNodeQueryResponse'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='ExecuteNodeCommandResponse'>
<xs:attribute name="queryId" type="xs:string" use="optional"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:element name='getCommonNodeCommands' type='NodeReferencesRequest'/>
<xs:element name='getCommonNodeCommandsResponse' type='CommandArray'/>
<xs:element name='getCommonCommandParameters'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferencesRequest'>
<xs:attribute name='command' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='getCommonCommandParametersResponse' type='ParameterFormResponse'/>
<xs:element name='executeCommonNodeCommand'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferencesRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="0" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
<xs:attribute name="queryId" type="xs:string" use="optional"/>
2013-04-16 15:50:08 -04:00
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='executeCommonNodeCommandResponse' type='ExecuteCommonNodeCommandResponse'/>
<xs:element name='executeCommonNodeQuery'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferencesRequest'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='executeCommonNodeQueryResponse'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='ExecuteCommonNodeCommandResponse'>
<xs:attribute name="queryId" type="xs:string" use="optional"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:element name='moveNodeUp' type='NodeReferenceRequest'/>
<xs:element name='moveNodeUpResponse' type='Response'/>
<xs:element name='moveNodeDown' type='NodeReferenceRequest'/>
<xs:element name='moveNodeDownResponse' type='Response'/>
<xs:element name='moveNodesUp' type='NodeReferencesRequest'/>
<xs:element name='moveNodesUpResponse' type='Response'/>
<xs:element name='moveNodesDown' type='NodeReferencesRequest'/>
<xs:element name='moveNodesDownResponse' type='Response'/>
<xs:element name='subscribe'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='SourceReferenceRequest'>
<xs:attribute name='getEventsSince' type='xs:dateTime' use='optional'/>
<xs:attributeGroup ref='parametersAndMessages'/>
<xs:attributeGroup ref='eventTypes'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='subscribeResponse' type='Response'/>
<xs:element name='unsubscribe'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='SourceReferenceRequest'>
<xs:attributeGroup ref='eventTypes'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='unsubscribeResponse' type='Response'/>
<xs:element name='nodeAdded'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeSourceInformation'>
<xs:attribute name='afterNodeId' type='xs:string' use='optional'/>
<xs:attribute name='afterNodeCacheType' type='xs:string' use='optional'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:element name='nodeUpdated'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeSourceInformation'>
<xs:attribute name='oldId' type='xs:string' use='optional'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:element name='nodeStatusChanged'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReference'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='message' type='Message'/>
</xs:choice>
<xs:attribute name='state' type='NodeState' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:element name='nodeRemoved' type='NodeReference'/>
<xs:element name='nodeMovedUp' type='NodeReference'/>
<xs:element name='nodeMovedDown' type='NodeReference'/>
<xs:element name='getDatabases' type='TokenRequest'/>
<xs:element name='getDatabasesResponse'>
<xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='database'>
<xs:complexType>
<xs:attribute name='databaseId' type='xs:string' use='required'/>
2013-04-16 15:50:08 -04:00
<xs:attribute name='name' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
</xs:element>
<xs:element name='getDatabaseReadoutParameters' type='DatabaseReferenceRequest'/>
<xs:element name='getDatabaseReadoutParametersResponse' type='ParameterFormResponse'/>
<xs:element name='startDatabaseReadout'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='DatabaseReferenceRequest'>
<xs:sequence>
<xs:element name='node' type='NodeReference' minOccurs='1' maxOccurs='unbounded'/>
<xs:element ref='xd:x' minOccurs="1" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
<xs:attribute name="seqnr" type="xs:int" use="required"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='startDatabaseReadoutResponse' type='ExecuteNodeCommandResponse'/>
<xs:element name='queryProgress'>
<xs:complexType>
<xs:choice minOccurs='1' maxOccurs='unbounded'>
<xs:element name='queryStarted'>
<xs:complexType/>
</xs:element>
<xs:element name='queryDone'>
<xs:complexType/>
</xs:element>
<xs:element name='queryAborted'>
<xs:complexType/>
</xs:element>
<xs:element name='newTable'>
<xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='column'>
<xs:complexType>
<xs:attribute name='columnId' type='xs:string' use='required'/>
<xs:attribute name='header' type='xs:string' use='optional'/>
<xs:attribute name='dataSourceId' type='xs:string' use='optional'/>
<xs:attribute name='cacheTypeName' type='xs:string' use='optional'/>
<xs:attribute name='fgColor' type='Color' use='optional'/>
<xs:attribute name='bgColor' type='Color' use='optional'/>
<xs:attribute name='alignment' type='Alignment' use='optional'/>
<xs:attribute name='nrDecimals' type='xs:nonNegativeInteger' use='optional'/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name='tableId' type='xs:string' use='required'/>
<xs:attribute name='tableName' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='newRecords'>
<xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='record'>
<xs:complexType>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='boolean' type='xs:boolean'/>
<xs:element name='color' type='Color'/>
<xs:element name='date' type='xs:date'/>
<xs:element name='dateTime' type='xs:dateTime'/>
<xs:element name='double' type='xs:double'/>
<xs:element name='duration' type='xs:duration'/>
<xs:element name='int' type='xs:int'/>
<xs:element name='long' type='xs:long'/>
<xs:element name='string' type='xs:string'/>
<xs:element name='time' type='xs:time'/>
<xs:element name='base64'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:base64Binary'>
<xs:attribute name='contentType' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='void'>
<xs:complexType/>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name='tableId' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='tableDone'>
<xs:complexType>
<xs:attribute name='tableId' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='newObject'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:base64Binary'>
<xs:attribute name='contentType' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='queryMessage'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='type' type='EventType' use='optional' default='Information'/>
<xs:attribute name='level' type='EventLevel' use='optional' default='Minor'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='title'>
<xs:complexType>
<xs:attribute name='name' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='status'>
<xs:complexType>
<xs:attribute name='message' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='beginSection'>
<xs:complexType>
<xs:attribute name='header' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='endSection'>
<xs:complexType/>
</xs:element>
</xs:choice>
<xs:attributeGroup ref='nodeReference'/>
<xs:attribute name='queryId' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='abortNodeQuery'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferenceRequest'>
<xs:attribute name='queryId' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='abortNodeQueryResponse'>
<xs:complexType>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
</xs:element>
<xs:element name='abortCommonNodeQuery'>
<xs:complexType>
<xs:complexContent>
<xs:extension base='NodeReferencesRequest'>
<xs:attribute name='queryId' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name='abortCommonNodeQueryResponse'>
<xs:complexType>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
<xs:simpleType name='ResponseCode'>
<xs:restriction base='xs:string'>
<xs:enumeration value='OK'/>
<xs:enumeration value='NotFound'/>
<xs:enumeration value='InsufficientPrivileges'/>
<xs:enumeration value='Locked'/>
<xs:enumeration value='NotImplemented'/>
<xs:enumeration value='FormError'/>
<xs:enumeration value='OtherError'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='Color'>
<xs:restriction base='xs:string'>
<xs:pattern value='^[0-9a-fA-F]{6}$'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='NodeState'>
<xs:restriction base='xs:string'>
<xs:enumeration value='None'/>
<xs:enumeration value='Information'/>
<xs:enumeration value='WarningSigned'/>
<xs:enumeration value='WarningUnsigned'/>
<xs:enumeration value='ErrorSigned'/>
<xs:enumeration value='ErrorUnsigned'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='MessageType'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Error'/>
<xs:enumeration value='Warning'/>
<xs:enumeration value='Information'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='CommandType'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Simple'/>
<xs:enumeration value='Parameterized'/>
<xs:enumeration value='Query'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='Alignment'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Left'/>
<xs:enumeration value='Center'/>
<xs:enumeration value='Right'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='EventType'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Information'/>
<xs:enumeration value='Warning'/>
<xs:enumeration value='Error'/>
<xs:enumeration value='Exception'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name='EventLevel'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Minor'/>
<xs:enumeration value='Medium'/>
<xs:enumeration value='Major'/>
2013-04-16 15:50:08 -04:00
</xs:restriction>
</xs:simpleType>
<xs:attributeGroup name='tokens'>
<xs:attribute name='deviceToken' type='xs:string' use='optional'/>
<xs:attribute name='serviceToken' type='xs:string' use='optional'/>
<xs:attribute name='userToken' type='xs:string' use='optional'/>
</xs:attributeGroup>
<xs:attributeGroup name='sourceReference'>
<xs:attribute name='sourceId' type='xs:string' use='required'/>
</xs:attributeGroup>
<xs:attributeGroup name='nodeReference'>
<xs:attributeGroup ref='sourceReference'/>
<xs:attribute name='nodeId' type='xs:string' use='required'/>
<xs:attribute name='cacheType' type='xs:string' use='optional'/>
</xs:attributeGroup>
<xs:attributeGroup name='parametersAndMessages'>
<xs:attribute name='parameters' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='messages' type='xs:boolean' use='optional' default='false'/>
</xs:attributeGroup>
<xs:attributeGroup name='indexReference'>
<xs:attributeGroup ref='sourceReference'/>
<xs:attribute name='index' type='xs:string' use='required'/>
<xs:attribute name='indexValue' type='xs:string' use='required'/>
</xs:attributeGroup>
<xs:attributeGroup name='responseCode'>
<xs:attribute name='result' type='ResponseCode' use='required'/>
</xs:attributeGroup>
<xs:attributeGroup name='eventTypes'>
<xs:attribute name='nodeAdded' type='xs:boolean' use='optional' default='true'/>
<xs:attribute name='nodeUpdated' type='xs:boolean' use='optional' default='true'/>
<xs:attribute name='nodeStatusChanged' type='xs:boolean' use='optional' default='true'/>
<xs:attribute name='nodeRemoved' type='xs:boolean' use='optional' default='true'/>
<xs:attribute name='nodeMovedUp' type='xs:boolean' use='optional' default='true'/>
<xs:attribute name='nodeMovedDown' type='xs:boolean' use='optional' default='true'/>
</xs:attributeGroup>
<xs:attributeGroup name='databaseReference'>
<xs:attribute name='databaseId' type='xs:string' use='required'/>
</xs:attributeGroup>
<xs:attributeGroup name='readoutReference'>
<xs:attribute name='seqnr' type='xs:int' use='required'/>
</xs:attributeGroup>
<xs:complexType name='Response'>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='TokenRequest'>
<xs:attributeGroup ref='tokens'/>
</xs:complexType>
<xs:complexType name='SourceReferenceRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:attributeGroup ref='sourceReference'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='DataSource'>
<xs:attribute name='sourceId' type='xs:string' use='required'/>
2013-04-16 15:50:08 -04:00
<xs:attribute name='name' type='xs:string' use='required'/>
<xs:attribute name='hasChildren' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='lastChanged' type='xs:dateTime' use='optional'/>
</xs:complexType>
<xs:complexType name='DataSourceArrayResponse'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='dataSource' type='DataSource'/>
</xs:sequence>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='NodeReferenceRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:attributeGroup ref='nodeReference'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='NodeReference'>
<xs:attributeGroup ref='nodeReference'/>
</xs:complexType>
<xs:complexType name='NodeReferencesRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='node' type='NodeReference'/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='NodeReferenceParametersRequest'>
<xs:complexContent>
<xs:extension base='NodeReferenceRequest'>
<xs:attributeGroup ref='parametersAndMessages'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='SourceReferenceParametersRequest'>
<xs:complexContent>
<xs:extension base='SourceReferenceRequest'>
<xs:attributeGroup ref='parametersAndMessages'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='GetAllNodesRequest'>
<xs:complexContent>
<xs:extension base='SourceReferenceParametersRequest'>
2013-04-16 15:50:08 -04:00
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='onlyIfDerivedFrom' type='xs:string'/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='GetChildNodesRequest'>
<xs:complexContent>
<xs:extension base='NodeReferenceParametersRequest'>
2013-04-16 15:50:08 -04:00
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='sortOrder' type='SortOrder'/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='SortOrder'>
<xs:attribute name='parameterName' type='xs:string' use='required'/>
<xs:attribute name='ascending' type='xs:boolean' use='optional' default='true'/>
</xs:complexType>
2013-04-16 15:50:08 -04:00
<xs:complexType name='NodeInformation'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='boolean' type='BooleanParameter'/>
<xs:element name='color' type='ColorParameter'/>
<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 name='message' type='Message'/>
</xs:choice>
<xs:attribute name='nodeId' type='xs:string' use='required'/>
2013-04-16 15:50:08 -04:00
<xs:attribute name='displayName' type='xs:string' use='optional'/>
<xs:attribute name='nodeType' type='xs:string' use='optional'/>
<xs:attribute name='localId' type='xs:string' use='optional'/>
<xs:attribute name='logId' type='xs:string' use='optional'/>
<xs:attribute name='cacheType' type='xs:string' use='optional'/>
<xs:attribute name='state' type='NodeState' use='required'/>
<xs:attribute name='hasChildren' type='xs:boolean' use='required'/>
<xs:attribute name='childrenOrdered' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='isReadable' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='isControllable' type='xs:boolean' use='optional' default='false'/>
2013-04-16 15:50:08 -04:00
<xs:attribute name='hasCommands' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='parentId' type='xs:string' use='optional'/>
<xs:attribute name='parentCacheType' type='xs:string' use='optional'/>
<xs:attribute name='lastChanged' type='xs:dateTime' use='optional'/>
</xs:complexType>
<xs:complexType name='NodeSourceInformation'>
<xs:complexContent>
<xs:extension base='NodeInformation'>
<xs:attributeGroup ref='sourceReference'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='Parameter' abstract='true'>
<xs:attribute name='id' type='xs:string' use='required'/>
<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='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='Message'>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='timestamp' type='xs:dateTime' use='required'/>
<xs:attribute name='type' type='MessageType' use='required'/>
<xs:attribute name='eventId' type='xs:string' use='optional'/>
2013-04-16 15:50:08 -04:00
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name='NodeInformationArrayResponse'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='node' type='NodeInformation'/>
</xs:sequence>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='StringArray'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='value' type='xs:string'/>
</xs:sequence>
</xs:complexType>
<xs:complexType name='StringArrayResponse'>
<xs:complexContent>
<xs:extension base='StringArray'>
<xs:attributeGroup ref='responseCode'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='BooleanArrayResponse'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='value' type='xs:boolean'/>
</xs:sequence>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='IndexReferenceRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:attributeGroup ref='indexReference'/>
<xs:attributeGroup ref='parametersAndMessages'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='IndexReference'>
<xs:attributeGroup ref='indexReference'/>
</xs:complexType>
<xs:complexType name='IndexReferencesRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='indexRef' type='IndexReference'/>
</xs:sequence>
<xs:attributeGroup ref='parametersAndMessages'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='SetNodeParametersResponse'>
<xs:choice minOccurs='1' maxOccurs='1'>
<xs:element name='error' type='ParameterError' minOccurs='1' maxOccurs='unbounded'/>
<xs:element name='node' type='NodeInformation' minOccurs='1' maxOccurs='unbounded'/>
</xs:choice>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='ParameterFormResponse'>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="1" maxOccurs="1"/>
2013-04-16 15:50:08 -04:00
</xs:sequence>
<xs:attributeGroup ref="responseCode"/>
</xs:complexType>
<xs:complexType name='NodeTypeReferenceRequest'>
<xs:complexContent>
<xs:extension base='NodeReferenceRequest'>
<xs:attribute name='type' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='Command'>
<xs:attribute name='command' type='xs:string' use='required'/>
2013-04-16 15:50:08 -04:00
<xs:attribute name='name' type='xs:string' use='required'/>
<xs:attribute name='type' type='CommandType' use='required'/>
<xs:attribute name='sortCategory' type='xs:string' use='optional'/>
<xs:attribute name='sortKey' type='xs:string' use='optional'/>
<xs:attribute name='confirmationString' type='xs:string' use='optional'/>
<xs:attribute name='failureString' type='xs:string' use='optional'/>
<xs:attribute name='successString' type='xs:string' use='optional'/>
</xs:complexType>
<xs:complexType name='CommandArray'>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='command' type='Command'/>
</xs:sequence>
</xs:complexType>
<xs:complexType name='NodeCommandReferenceRequest'>
<xs:complexContent>
<xs:extension base='NodeReferenceRequest'>
<xs:attribute name='command' type='xs:string' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name='ExecuteNodeCommandResponse'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='error' type='ParameterError'/>
</xs:choice>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
<xs:complexType name='ExecuteCommonNodeCommandResponse'>
<xs:complexContent>
<xs:extension base='ExecuteNodeCommandResponse'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='result'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:boolean'>
<xs:attribute name='error' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
2013-04-16 15:50:08 -04:00
</xs:choice>
</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='ReadoutReference'>
<xs:attributeGroup ref='databaseReference'/>
<xs:attributeGroup ref='readoutReference'/>
</xs:complexType>
<xs:complexType name='DatabaseReferenceRequest'>
<xs:complexContent>
<xs:extension base='TokenRequest'>
<xs:attributeGroup ref='databaseReference'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</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>
2013-04-16 15:50:08 -04:00
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Klaudiusz Staniek for all valuable feedback.</p>
2013-04-16 15:50:08 -04:00
</section1>
2013-05-06 23:07:09 -04:00
</xep>