XEP-0326 v0.2: Namespace in dynamic form examples has been changed to urn:xmpp:xdata...
[xmpp:xmpp.git] / extensions / xep-0326.xml
1 <?xml version='1.0' encoding='UTF-8'?>
2 <!-- TODO: enhanced concentrator GUI XEP. (Icons, overlays, etc.) -->
3 <!-- TODO: Interaction with provisioning server -->
4 <!-- TODO: Execute command failure: Error message. -->
5 <!-- TODO: Execute command on nodes failures: Error messages. -->
6 <!DOCTYPE xep SYSTEM 'xep.dtd' [
7     <!ENTITY % ents SYSTEM 'xep.ent'>
8     %ents;
9 ]>
10 <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
11 <xep>
12     <header>
13         <title>Internet of Things - Concentrators</title>
14         <abstract>This specification describes how to manage and get information from concentrators of devices over XMPP networks.</abstract>
15                 &LEGALNOTICE;
16         <number>0326</number>
17         <status>Experimental</status>
18         <type>Standards Track</type>
19         <sig>Standards</sig>
20         <approver>Council</approver>
21         <dependencies>
22             <spec>XMPP Core</spec>
23             <spec>XEP-0001</spec>
24             <spec>XEP-0004</spec>
25             <spec>XEP-0030</spec>
26             <spec>XEP-0122</spec>
27             <spec>XEP-0137</spec>
28             <spec>XEP-0141</spec>
29             <spec>XEP-0323</spec>
30             <spec>XEP-0324</spec>
31             <spec>XEP-0331</spec>
32             <spec>XEP-0336</spec>
33         </dependencies>
34         <supersedes/>
35         <supersededby/>
36         <shortname>sensor-network-concentrators</shortname>
37         <author>
38             <firstname>Peter</firstname>
39             <surname>Waher</surname>
40             <email>peter.waher@clayster.com</email>
41             <jid>peter.waher@jabber.org</jid>
42             <uri>http://www.linkedin.com/in/peterwaher</uri>
43         </author>
44                 <revision>
45                         <version>0.2</version>
46                         <date>2014-03-10</date>
47                         <initials>pw</initials>
48                         <remark>
49                                 <p>Namespace in dynamic form examples has been changed to urn:xmpp:xdata:dynamic.</p>
50         <p>Added the following node query events: <strong>title</strong>, <strong>status</strong>, <strong>beginSection</strong> and <strong>endSection</strong>.</p>
51         <p>Updated the schema to more strictly validate references to x-data forms.</p>
52         <p>Updated attribute names so queries and responses are consistent.</p>
53         <p>Updated the language.</p>
54         <p>Added section about how to determine support.</p>
55         <p>Corrected language and examples.</p>
56         <p>Node Query command type added.</p>
57         <p>Fixed links to documents with new numbers.</p>
58         <p>Changed namespace urn:xmpp:sn to urn:xmpp:iot</p>
59       </remark>
60     </revision>
61     <revision>
62         <version>0.1</version>
63         <date>2013-05-06</date>
64         <initials>psa</initials>
65         <remark>
66             <p>Initial published version approved by the XMPP Council.</p>
67         </remark>
68     </revision>
69     <revision>
70         <version>0.0.1</version>
71         <date>2013-03-20</date>
72         <initials>pw</initials>
73         <remark>
74             <p>First draft.</p>
75         </remark>
76     </revision>
77     </header>
78     <section1 topic='Introduction' anchor='intro'>
79         <p>
80             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
81             set of sensors and actuators), medium-sized (for example: mid-level concentrators, controlling branches of the network, islands, perhaps using separate communication protocols),
82             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).
83         </p>
84         <p>
85             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
86             comes from requirements used in sensor networks and Internet of Things applications and infrastructure.
87         </p>
88         <p>
89             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:
90         </p>
91         <ul>
92             <li>
93                 A concentrator works with multiple <strong>data sources</strong>. Effective management of data sources and their contents is a vital part of this XEP.
94             </li>
95             <li>The ability to work with massive quantities of entities.</li>
96             <li>Effective synchronization of contents between interested parties.</li>
97             <li>Effective ways to interact with entities controlled by the concentrator.</li>
98         </ul>
99
100                 <p>
101                         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:
102                 </p>
103
104                 <table caption='Sensor Network XEPs'>
105                         <tr>
106                                 <th>XEP</th>
107                                 <th>Description</th>
108                         </tr>
109                         <tr>
110                                 <td>xep-0000-IoT-BatteryPoweredSensors</td>
111                                 <td>Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.</td>
112                         </tr>
113                         <tr>
114                                 <td>xep-0000-IoT-Discovery</td>
115                                 <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>
116                         </tr>
117                         <tr>
118                                 <td>xep-0000-IoT-Events</td>
119                                 <td>Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured.</td>
120                         </tr>
121                         <tr>
122                                 <td>xep-0000-IoT-Interoperability</td>
123                                 <td>Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.</td>
124                         </tr>
125                         <tr>
126                                 <td>xep-0000-IoT-Multicast</td>
127                                 <td>Defines how sensor data can be multicast in efficient ways.</td>
128                         </tr>
129                         <tr>
130                                 <td>xep-0000-IoT-PubSub</td>
131                                 <td>Defines how efficient publication of sensor data can be made in sensor networks.</td>
132                         </tr>
133                         <tr>
134                                 <td>xep-0000-IoT-Chat</td>
135                                 <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>
136                         </tr>
137                         <tr>
138                                 <td>XEP-0322</td>
139                                 <td>
140                                         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
141                                         in all sensor network implementations where memory and packet size is an issue.
142                                 </td>
143                         </tr>
144                         <tr>
145                                 <td>XEP-0323</td>
146                                 <td>
147                                         Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks.
148                                         It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs.
149                                 </td>
150                         </tr>
151                         <tr>
152                                 <td>XEP-0324</td>
153                                 <td>Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.</td>
154                         </tr>
155                         <tr>
156                                 <td>XEP-0325</td>
157                                 <td>Defines how to control actuators and other devices in Internet of Things.</td>
158                         </tr>
159                         <tr>
160                                 <td>XEP-0326</td>
161                                 <td>This specification. Defines how to handle architectures containing concentrators or servers handling multiple sensors.</td>
162                         </tr>
163                         <tr>
164                                 <td>XEP-0331</td>
165                                 <td>Defines extensions for how color parameters can be handled, based on &xep0004;</td>
166                         </tr>
167                         <tr>
168                                 <td>XEP-0336</td>
169                                 <td>Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.</td>
170                         </tr>
171                 </table>
172
173                 <section2 topic='Relations to other extensions'>
174             <p>
175                 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
176                 take the time to list why different technologies are not applicable.
177             </p>
178             <section3 topic='XEP-0060'>
179                 <p>
180                     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
181                     tree structure. Furthermore, it allows the possibility to publish items on these nodes as well as syndication of this information.
182                 </p>
183                 <p>
184                     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
185                     allows the creation of collections containing loosely coupled nodes.
186                 </p>
187                 <p>
188                     Even though this document defines tree structures of data, it is not however based on XEP-0060. There are multiple reasons for this:
189                 </p>
190                 <ul>
191                     <li>
192                         The structures defined in this specification do not include items to publish for each node.
193                     </li>
194                     <li>
195                         We want to be able to use XEP-0060 in parallel to this specification, for the purpose of publishing sensor data.
196                         More information about this is found in <link url='xep-0000-IoT-PubSub.html'>xep-0000-IoT-PubSub.html</link>.
197                     </li>
198                     <li>
199                         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
200                         (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
201                         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
202                         number of operations.
203                     </li>
204                     <li>
205                         In this document, nodes have specific functions, controlled by a specific Node Type. Different Node Types have different parameter sets, different options, commands,
206                         capabilities, etc. XEP-0060 does not differ between node types. There, nodes are only a structural way to sort data into a tree graph.
207                     </li>
208                     <li>
209                         In this document, nodes have real-time status, like errors, warnings, etc.
210                     </li>
211                 </ul>
212             </section3>
213             <section3 topic='XEP-0248'>
214                 <p>
215                     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.
216                     There are multiple reasons:
217                 </p>
218                 <ul>
219                     <li>
220                         We want to be able to use XEP-0248 in parallel to this specification, for the purpose of publishing sensor data.
221                         More information about this is found in <link url='xep-0000-IoT-PubSub.html'>xep-0000-IoT-PubSub.html</link>.
222                     </li>
223                     <li>
224                         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
225                         means that Nodes must have IDs unique within a given Cache Type, within a given data source.
226                     </li>
227                     <li>
228                         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.
229                     </li>
230                     <li>
231                         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
232                         contained in it.
233                     </li>
234                 </ul>
235             </section3>
236             <section3 topic='XEP-0050'>
237                 <p>
238                     &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.
239                     There are multiple reasons:
240                 </p>
241                 <ul>
242                     <li>
243                         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
244                         system-wide commands.
245                     </li>
246                     <li>
247                         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.
248                     </li>
249                     <li>
250                         It is a requirement to be able to execute commands on sets of nodes directly.
251                     </li>
252                     <li>
253                         Since commands have to be context sensitive, a large concentrator system may have hundreds or thousands of different commands, making it impossible to create
254                         context sensitive GUI's using XEP-0050.
255                     </li>
256                     <li>
257                         Dialog types used for Ad-Hoc-commands are not sufficient. First, dynamic dialogs are required in the general case.
258                         (<link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0326</link> define how to create dynamic forms.) Furthermore, the
259                         wizard style type of dialogs used for more complex dialogs in ad-hoc commands, are difficult to automate.
260                     </li>
261                 </ul>
262             </section3>
263         </section2>
264     </section1>
265     <section1 topic='Glossary' anchor='glossary'>
266         <p>The following table lists common terms and corresponding descriptions.</p>
267         <dl>
268             <di>
269                 <dt>Actuator</dt>
270                 <dd>Device containing at least one configurable property or output that can and should be controlled by some other entity or device.</dd>
271             </di>
272             <di>
273                 <dt>Computed Value</dt>
274                 <dd>A value that is computed instead of measured.</dd>
275             </di>
276             <di>
277                 <dt>Concentrator</dt>
278                 <dd>Device managing a set of devices which it publishes on the XMPP network.</dd>
279             </di>
280             <di>
281                 <dt>Data Source</dt>
282                 <dd>
283                     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.
284                     Flat data sources contain a list of objects and Tree data sources contain nodes formed as a tree graph with one root element.
285                 </dd>
286             </di>
287             <di>
288                 <dt>Field</dt>
289                 <dd>
290                     One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc.
291                     Fields should be unique within the triple (Node ID, Field Name, Timestamp).
292                 </dd>
293             </di>
294             <di>
295                 <dt>Field Name</dt>
296                 <dd>Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.</dd>
297             </di>
298             <di>
299                 <dt>Field Type</dt>
300                 <dd>What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.</dd>
301             </di>
302             <di>
303                 <dt>Historical Value</dt>
304                 <dd>A value stored in memory from a previous timestamp.</dd>
305             </di>
306             <di>
307                 <dt>Identification Value</dt>
308                 <dd>A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)</dd>
309             </di>
310             <di>
311                 <dt>Localization information</dt>
312                 <dd>Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.</dd>
313             </di>
314             <di>
315                 <dt>Meter</dt>
316                 <dd>A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.</dd>
317             </di>
318             <di>
319                 <dt>Momentary Value</dt>
320                 <dd>A momentary value represents a value measured at the time of the read-out.</dd>
321             </di>
322             <di>
323                 <dt>Node</dt>
324                 <dd>
325                     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)
326                     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.).
327                     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
328                     parent nodes a called sibling nodes.
329                 </dd>
330             </di>
331             <di>
332                 <dt>Node ID</dt>
333                 <dd>
334                     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
335                     ID scheme.
336                 </dd>
337             </di>
338             <di>
339                 <dt>Node Type</dt>
340                 <dd>Each node has a Node Type. The Node Type defines the functionality of the node in the system.</dd>
341             </di>
342             <di>
343                 <dt>Parameter</dt>
344                 <dd>
345                     Readable and/or writable property on a node/device. The XEP-0326 &xep0326; deals with reading and writing parameters
346                     on nodes/devices. Fields are not parameters, and parameters are not fields.
347                 </dd>
348             </di>
349             <di>
350                 <dt>Peak Value</dt>
351                 <dd>A maximum or minimum value during a given period.</dd>
352             </di>
353             <di>
354                 <dt>Precision</dt>
355                 <dd>
356                     In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision
357                     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
358                     delivering field information in sensor networks should always retain the number of decimals in a message.
359                 </dd>
360             </di>
361             <di>
362                 <dt>Sensor</dt>
363                 <dd>
364                     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.
365                     Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
366                 </dd>
367             </di>
368             <di>
369                 <dt>SN</dt>
370                 <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>
371             </di>
372             <di>
373                 <dt>Status Value</dt>
374                 <dd>A value displaying status information about something.</dd>
375             </di>
376             <di>
377                 <dt>Timestamp</dt>
378                 <dd>Timestamp of value, when the value was sampled or recorded.</dd>
379             </di>
380             <di>
381                 <dt>Token</dt>
382                 <dd>
383                     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
384                     access rights with the provisioning server.
385                 </dd>
386             </di>
387             <di>
388                 <dt>Unit</dt>
389                 <dd>Physical unit of value. Example: MWh, l/s, etc.</dd>
390             </di>
391             <di>
392                 <dt>Value</dt>
393                 <dd>A field value.</dd>
394             </di>
395             <di>
396                 <dt>Value Status</dt>
397                 <dd>Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.</dd>
398             </di>
399             <di>
400                 <dt>Value Type</dt>
401                 <dd>Can be numeric, string, boolean, Date &amp; Time, Time Span or Enumeration.</dd>
402             </di>
403             <di>
404                 <dt>WSN</dt>
405                 <dd>Wireless Sensor Network, a sensor network including wireless devices.</dd>
406             </di>
407             <di>
408                 <dt>XMPP Client</dt>
409                 <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>
410             </di>
411         </dl>
412     </section1>
413     <section1 topic='Use Cases' anchor='usecases'>
414         <p>
415             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
416             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
417             concentrators of different makes and models and of these varying ranges.
418         </p>
419         <section2 topic='Capabilities'>
420             <section3 topic='Get Capabilities'>
421                 <p>
422                     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
423                     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
424                     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
425                     <strong>getCapabilities</strong> command is sent, as is shown in the following example.
426                 </p>
427                 <example caption='Full capabilities'>
428                     <![CDATA[
429    <iq type='get'
430        from='client@clayster.com/client'
431        to='subsystem@clayster.com'
432        id='1'>
433       <getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
434    </iq>
435    
436    <iq type='result'
437        from='subsystem@clayster.com'
438        to='client@clayster.com/client'
439        id='1'>
440       <getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
441           <value>getCapabilities</value>
442           <value>getAllDataSources</value>
443           <value>getRootDataSources</value>
444           <value>getChildDataSources</value>
445           <value>containsNode</value>
446           <value>containsNodes</value>
447           <value>getNode</value>
448           <value>getNodes</value>
449           <value>getAllNodes</value>
450           <value>getNodeInheritance</value>
451           <value>getRootNodes</value>
452           <value>getChildNodes</value>
453           <value>getIndices</value>
454           <value>getNodesFromIndex</value>
455           <value>getNodesFromIndices</value>
456           <value>getAllIndexValues</value>
457           <value>getNodeParametersForEdit</value>
458           <value>setNodeParametersAfterEdit</value>
459           <value>getCommonNodeParametersForEdit</value>
460           <value>setCommonNodeParametersAfterEdit</value>
461           <value>getAddableNodeTypes</value>
462           <value>getParametersForNewNode</value>
463           <value>createNewNode</value>
464           <value>destroyNode</value>
465           <value>getAncestors</value>
466           <value>getNodeCommands</value>
467           <value>getCommandParameters</value>
468           <value>executeNodeCommand</value>
469           <value>executeNodeQuery</value>
470           <value>abortNodeQuery</value>
471           <value>getCommonNodeCommands</value>
472           <value>getCommonCommandParameters</value>
473           <value>executeCommonNodeCommand</value>
474           <value>executeCommonNodeQuery</value>
475           <value>abortCommonNodeQuery</value>
476           <value>moveNodeUp</value>
477           <value>moveNodeDown</value>
478           <value>moveNodesUp</value>
479           <value>moveNodesDown</value>
480           <value>subscribe</value>
481           <value>unsubscribe</value>
482           <value>getDatabases</value>
483           <value>getDatabaseReadoutParameters</value>
484           <value>startDatabaseReadout</value>
485       </getCapabilitiesResponse>
486    </iq>]]>
487                 </example>
488                 <p>
489                     A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows:
490                 </p>
491                 <example caption='No database capabilities'>
492                     <![CDATA[
493    <iq type='get'
494        from='client@clayster.com/client'
495        to='subsystem@clayster.com'
496        id='63'>
497       <getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
498    </iq>
499    
500    <iq type='result'
501        from='subsystem@clayster.com'
502        to='client@clayster.com/client'
503        id='63'>
504       <getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
505           <value>getCapabilities</value>
506           <value>getAllDataSources</value>
507           <value>getRootDataSources</value>
508           <value>getChildDataSources</value>
509           <value>containsNode</value>
510           <value>containsNodes</value>
511           <value>getNode</value>
512           <value>getNodes</value>
513           <value>getAllNodes</value>
514           <value>getNodeInheritance</value>
515           <value>getRootNodes</value>
516           <value>getChildNodes</value>
517           <value>getIndices</value>
518           <value>getNodesFromIndex</value>
519           <value>getNodesFromIndices</value>
520           <value>getAllIndexValues</value>
521           <value>getNodeParametersForEdit</value>
522           <value>setNodeParametersAfterEdit</value>
523           <value>getCommonNodeParametersForEdit</value>
524           <value>setCommonNodeParametersAfterEdit</value>
525           <value>getAddableNodeTypes</value>
526           <value>getParametersForNewNode</value>
527           <value>createNewNode</value>
528           <value>destroyNode</value>
529           <value>getAncestors</value>
530           <value>getNodeCommands</value>
531           <value>getCommandParameters</value>
532           <value>executeNodeCommand</value>
533           <value>executeNodeQuery</value>
534           <value>abortNodeQuery</value>
535           <value>getCommonNodeCommands</value>
536           <value>getCommonCommandParameters</value>
537           <value>executeCommonNodeCommand</value>
538           <value>executeCommonNodeQuery</value>
539           <value>abortCommonNodeQuery</value>
540           <value>moveNodeUp</value>
541           <value>moveNodeDown</value>
542           <value>moveNodesUp</value>
543           <value>moveNodesDown</value>
544           <value>subscribe</value>
545           <value>unsubscribe</value>
546       </getCapabilitiesResponse>
547    </iq>]]>
548                 </example>
549                 <p>
550                     A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems:
551                 </p>
552                 <example caption='No batch command capabilities'>
553                     <![CDATA[
554    <iq type='get'
555        from='client@clayster.com/client'
556        to='gateway@clayster.com'
557        id='2'>
558       <getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
559    </iq>
560    
561    <iq type='result'
562        from='gateway@clayster.com'
563        to='client@clayster.com/client'
564        id='2'>
565       <getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
566           <value>getCapabilities</value>
567           <value>getAllDataSources</value>
568           <value>getRootDataSources</value>
569           <value>getChildDataSources</value>
570           <value>containsNode</value>
571           <value>getNode</value>
572           <value>getNodeInheritance</value>
573           <value>getRootNodes</value>
574           <value>getChildNodes</value>
575           <value>getNodeParametersForEdit</value>
576           <value>setNodeParametersAfterEdit</value>
577           <value>getAddableNodeTypes</value>
578           <value>getParametersForNewNode</value>
579           <value>createNewNode</value>
580           <value>destroyNode</value>
581           <value>getAncestors</value>
582           <value>getNodeCommands</value>
583           <value>getCommandParameters</value>
584           <value>executeNodeCommand</value>
585           <value>executeNodeQuery</value>
586           <value>abortNodeQuery</value>
587           <value>moveNodeUp</value>
588           <value>moveNodeDown</value>
589           <value>moveNodesUp</value>
590           <value>moveNodesDown</value>
591           <value>subscribe</value>
592           <value>unsubscribe</value>
593       </getCapabilitiesResponse>
594    </iq>]]>
595                 </example>
596                 <p>
597                     But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands:
598                 </p>
599                 <example caption='No edit capabilities'>
600                     <![CDATA[
601    <iq type='get'
602        from='client@clayster.com/client'
603        to='plc@clayster.com'
604        id='3'>
605       <getCapabilities xmlns='urn:xmpp:iot:concentrators'/>
606    </iq>
607    
608    <iq type='result'
609        from='plc@clayster.com'
610        to='client@clayster.com/client'
611        id='3'>
612       <getCapabilitiesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
613           <value>getCapabilities</value>
614           <value>getAllDataSources</value>
615           <value>containsNode</value>
616           <value>getNode</value>
617           <value>getRootNodes</value>
618           <value>getChildNodes</value>
619           <value>getNodeCommands</value>
620           <value>getCommandParameters</value>
621           <value>executeNodeCommand</value>
622           <value>executeNodeQuery</value>
623           <value>abortNodeQuery</value>
624       </getCapabilitiesResponse>
625    </iq>]]>
626                 </example>
627                 <p>
628                     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.
629                 </p>
630             </section3>
631         </section2>
632         <section2 topic='Data Sources'>
633             <section3 topic='Get All Data Sources'>
634                 <p>
635                     This command will return a flat list of all available data sources on the concentrator. It is not structured hierarchically.
636                 </p>
637                 <example caption='Get All Data Sources'>
638                     <![CDATA[
639    <iq type='get'
640        from='client@clayster.com/client'
641        to='concentrator@clayster.com'
642        id='4'>
643       <getAllDataSources xmlns='urn:xmpp:iot:concentrators' xml:lang='en'/>
644    </iq>
645    
646    <iq type='result'
647        from='concentrator@clayster.com'
648        to='client@clayster.com/client'
649        id='4'>
650       <getAllDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
651           <dataSource sourceId='Applications' name='Applications' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
652           <dataSource sourceId='Certificates' name='Certificates' hasChildren='false' lastChanged='2013-02-20T12:31:54'/>
653           <dataSource sourceId='Clayster.EventSink.Programmable' name='Programmable Event Log' hasChildren='false' lastChanged='2012-10-25T09:31:12'/>
654           ...
655       </getAllDataSourcesResponse>
656    </iq>]]>
657                 </example>
658             </section3>
659             <section3 topic='Get Root Data Sources'>
660                 <p>
661                     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
662                     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.
663                 </p>
664                 <example caption='Get Root Data Sources'>
665                     <![CDATA[
666    <iq type='get'
667        from='client@clayster.com/client'
668        to='concentrator@clayster.com'
669        id='5'>
670       <getRootDataSources xmlns='urn:xmpp:iot:concentrators' xml:lang='en'/>
671    </iq>
672    
673    <iq type='result'
674        from='concentrator@clayster.com'
675        to='client@clayster.com/client'
676        id='5'>
677       <getRootDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
678           <dataSource sourceId='MeteringRoot' name='Metering' hasChildren='true' lastChanged='2013-03-19T17:58:01'/>
679           <dataSource sourceId='SecurityRoot' name='Security' hasChildren='true' lastChanged='2013-01-12T22:03:50'/>
680           <dataSource sourceId='SystemRoot' name='System' hasChildren='true' lastChanged='2012-02-20T12:34:56'/>
681           ...
682       </getRootDataSourcesResponse>
683    </iq>]]>
684                 </example>
685             </section3>
686             <section3 topic='Get Child Data Sources'>
687                 <p>
688                     Having the ID of a data source that contains child data sources, you can fetch the child sources as follows:
689                 </p>
690                 <example caption='Get Child Data Sources'>
691                     <![CDATA[
692    <iq type='get'
693        from='client@clayster.com/client'
694        to='concentrator@clayster.com'
695        id='6'>
696       <getChildDataSources xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringRoot' xml:lang='en'/>
697    </iq>
698    
699    <iq type='result'
700        from='concentrator@clayster.com'
701        to='client@clayster.com/client'
702        id='6'>
703       <getChildDataSourcesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
704           <dataSource sourceId='MeteringFieldImports' name='Field Imports' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
705           <dataSource sourceId='MeteringFieldProcessors' name='Field Processors' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
706           <dataSource sourceId='MeteringFieldSinks' name='Field Sinks' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
707           <dataSource sourceId='MeteringGroups' name='Groups' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
708           <dataSource sourceId='MeteringJobs' name='Jobs' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
709           <dataSource sourceId='MeteringTopology' name='Topology' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
710           <dataSource sourceId='MeteringUnitConversion' name='Unit Conversion' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
711       </getChildDataSourcesResponse>
712    </iq>]]>
713                 </example>
714             </section3>
715             <section3 topic='Subscribe to data source events' anchor='subscribe'>
716                 <p>
717                     A client can subscribe to changes made in a data source. It does this by sending the <strong>subscribe</strong> command to the concentrator,
718                     as is shown in the following example:
719                 </p>
720                 <example caption='Subscribing to data source events'>
721                     <![CDATA[
722    <iq type='set'
723        from='client@clayster.com/client'
724        to='concentrator@clayster.com'
725        id='57'>
726       <subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology'/>
727    </iq>
728    
729    <iq type='result'
730        from='concentrator@clayster.com'
731        to='client@clayster.com/client'
732        id='57'>
733       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
734    </iq>]]>
735                 </example>
736                 <p>
737                     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.
738                 </p>
739                 <p>
740                     <strong>Important:</strong> Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist
741                     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
742                     is removed.
743                 </p>
744                 <p>
745                     <strong>Note:</strong> The <strong>parameters</strong> and <strong>messages</strong> attributes can be used to retrieve parameter and status message information
746                     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, 
747                     if the concentrator supports localization of strings.
748                 </p>
749                 <example caption='Subscribing to data source events with localized parameters'>
750                     <![CDATA[
751    <iq type='set'
752        from='client@clayster.com/client'
753        to='concentrator@clayster.com'
754        id='60'>
755       <subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='true' xml:lang='en'/>
756    </iq>
757    
758    <iq type='result'
759        from='concentrator@clayster.com'
760        to='client@clayster.com/client'
761        id='60'>
762       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
763    </iq>]]>
764                 </example>
765                 <p>
766                     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>, 
767                     <strong>nodeUpdated</strong>, <strong>nodeStatusChanged</strong>, <strong>nodeRemoved</strong>, <strong>nodeMovedUp</strong> and <strong>nodeMovedDown</strong>), that the
768                     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
769                     default action is to subscribe to those events. The attributes <strong>parameters</strong> and <strong>messages</strong> can also be used to specify
770                     if node parameters and node messages respectively should be available in event messages. The default value for the these later attributes is false, implying
771                     that normal events do not include node parameter and node message information.
772                 </p>
773                 <p>
774                     The following example shows how a client can subscribe to a set of events only:
775                 </p>
776                 <example caption='Subscribing to data source events, avoiding state events'>
777                     <![CDATA[
778    <iq type='set'
779        from='client@clayster.com/client'
780        to='concentrator@clayster.com'
781        id='61'>
782       <subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
783                  nodeAdded='true' nodeUpdated='true' nodeStatusChanged='false' nodeRemoved='true' nodeMovedUp='false' nodeMovedDown='false'/>
784    </iq>
785    
786    <iq type='result'
787        from='concentrator@clayster.com'
788        to='client@clayster.com/client'
789        id='61'>
790       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
791    </iq>]]>
792                 </example>
793                 <p>
794                     For more information on types of events sent, see the <link url='#sourceevents'>Data Source Events</link> section.
795                 </p>
796             </section3>
797             <section3 topic='Unsubscribe from data source events'>
798                 <p>
799                     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,
800                     as is shown in the following example:
801                 </p>
802                 <example caption='Unsubscribing from data source events'>
803                     <![CDATA[
804    <iq type='set'
805        from='client@clayster.com/client'
806        to='concentrator@clayster.com'
807        id='58'>
808       <unsubscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology'/>
809    </iq>
810    
811    <iq type='result'
812        from='concentrator@clayster.com'
813        to='client@clayster.com/client'
814        id='58'>
815       <unsubscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
816    </iq>]]>
817                 </example>
818                 <p>
819                     An unsubscription made to an existing data source, but where an event subscription does not exist, must not result in an error.
820                 </p>
821                 <p>
822                     The <strong>unsubscribe</strong> command has a set of optional attributes, one for each event type available, and with the same names, that the
823                     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
824                     default action is to unsubscribe from those events.
825                 </p>
826                 <p>
827                     The following example shows how a client can unsubscribe from a subset of events, keeping subscriptions on the others (if subscribed to):
828                 </p>
829                 <example caption='Unsubscribing from state events'>
830                     <![CDATA[
831    <iq type='set'
832        from='client@clayster.com/client'
833        to='concentrator@clayster.com'
834        id='62'>
835       <unsubscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
836                  nodeAdded='false' nodeUpdated='false' nodeStatusChanged='true' nodeRemoved='false' nodeMovedUp='false' nodeMovedDown='false'/>
837    </iq>
838    
839    <iq type='result'
840        from='concentrator@clayster.com'
841        to='client@clayster.com/client'
842        id='62'>
843       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
844    </iq>]]>
845                 </example>
846             </section3>
847             <section3 topic='Get changes since given timestamp before subscribing' anchor='subscribe2'>
848                 <p>
849                     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,
850                     it can include a <strong>getEventsSince</strong> attribute in the <strong>subscribe</strong> command sent to the concentrator. This will make the
851                     concentrator send all event messages since the given timestamp to the client before subscribing the client to events in the given data source.
852                 </p>
853                 <example caption='Get changes since given timestamp before subscribing'>
854                     <![CDATA[
855    <iq type='set'
856        from='client@clayster.com/client'
857        to='concentrator@clayster.com'
858        id='59'>
859       <subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' getEventsSince='2013-03-21T19:24:00'/>
860    </iq>
861    
862    <iq type='result'
863        from='concentrator@clayster.com'
864        to='client@clayster.com/client'
865        id='59'>
866       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
867    </iq>
868    
869    ... Sequence of event messages sent from concentrator to client.]]>
870                 </example>
871                 <p>
872                     <strong>Important:</strong> Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist
873                     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
874                     is removed.
875                 </p>
876                 <p>
877                     <strong>Note:</strong> The <strong>parameters</strong> and <strong>messages</strong> attributes can be used to retrieve parameter and status message information
878                     about the nodes in event messages sent from the concentrator.
879                 </p>
880                 <p>
881                     For more information on types of events sent, see the <link url='#sourceevents'>Data Source Events</link> section.
882                 </p>
883             </section3>
884             <section3 topic='Get changes since given timestamp before subscribing, Failure'>
885                 <p>
886                     If during a subscription request the concentrator is not able to fulfill the request of retrieving previous events using the <strong>getEventsSince</strong> attribute,
887                     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>.
888                     In this case, the subscription must not be made.
889                 </p>
890                 <p>
891                     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
892                     subscribing again without the <strong>getEventsSince</strong> attribute.
893                 </p>
894                 <example caption='Get changes since given timestamp before subscribing, Failure'>
895                     <![CDATA[
896    <iq type='set'
897        from='client@clayster.com/client'
898        to='concentrator@clayster.com'
899        id='73'>
900       <subscribe xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' getEventsSince='2001-01-01T00:00:00'/>
901    </iq>
902    
903    <iq type='result'
904        from='concentrator@clayster.com'
905        to='client@clayster.com/client'
906        id='73'>
907       <subscribeResponse xmlns='urn:xmpp:iot:concentrators' result='NotImplemented'/>
908    </iq>]]>
909                 </example>
910             </section3>
911         </section2>
912         <section2 topic='Nodes'>
913             <section3 topic='Contains Node'>
914                 <p>
915                     This command permits the client to check the existence of a node in the concentrator.
916                 </p>
917                 <example caption='Checking the existence of a node'>
918                     <![CDATA[
919    <iq type='get'
920        from='client@clayster.com/client'
921        to='concentrator@clayster.com'
922        id='7'>
923       <containsNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
924    </iq>
925    
926    <iq type='result'
927        from='concentrator@clayster.com'
928        to='client@clayster.com/client'
929        id='7'>
930       <containsNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>true</containsNodeResponse>
931    </iq>]]>
932                 </example>
933             </section3>
934             <section3 topic='Contains Nodes'>
935                 <p>
936                     If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead:
937                 </p>
938                 <example caption='Checking the existence of a multiple nodes'>
939                     <![CDATA[
940    <iq type='get'
941        from='client@clayster.com/client'
942        to='concentrator@clayster.com'
943        id='8'>
944       <containsNodes xmlns='urn:xmpp:iot:concentrators'>
945          <node sourceId='MeteringTopology' nodeId='Node1'/>
946          <node sourceId='MeteringTopology' nodeId='Node2'/>
947          <node sourceId='MeteringTopology' nodeId='Node3'/>
948          <node sourceId='MeteringGroups' nodeId='Group1'/>
949       </containsNodes>
950    </iq>
951    
952    <iq type='result'
953        from='concentrator@clayster.com'
954        to='client@clayster.com/client'
955        id='8'>
956       <containsNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
957          <value>true</value>
958          <value>true</value>
959          <value>false</value>
960          <value>true</value>
961       </containsNodesResponse>
962    </iq>]]>
963                 </example>
964                 <p>
965                     The array returned will have one item for each item in the request, in the same order.
966                 </p>
967             </section3>
968             <section3 topic='Get Node'>
969                 <p>
970                     This command returns basic information about a node in the concentrator.
971                 </p>
972                 <example caption='Get Node'>
973                     <![CDATA[
974    <iq type='get'
975        from='client@clayster.com/client'
976        to='concentrator@clayster.com'
977        id='9'>
978       <getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
979    </iq>
980    
981    <iq type='result'
982        from='concentrator@clayster.com'
983        to='client@clayster.com/client'
984        id='9'>
985       <getNodeResponse xmlns='urn:xmpp:iot:concentrators' 
986                        result='OK'
987                        nodeId='Node1' 
988                        nodeType='Namespace.NodeType1' 
989                        cacheType='Node' 
990                        state='WarningUnsigned' 
991                        hasChildren='false'
992                        isReadable='true' 
993                        isControllable='true' 
994                        hasCommands='true' 
995                        parentId='Root' 
996                        lastChanged='2013-03-19T17:58:01'/>
997    </iq>]]>
998                 </example>
999                 <p>
1000                     For more information, see <link url='#nodeinfo'>Node Information</link>.
1001                 </p>
1002             </section3>
1003             <section3 topic='Get Nodes'>
1004                 <p>
1005                     This command lets the client get information from multiple nodes at once.
1006                 </p>
1007                 <example caption='Get Nodes'>
1008                     <![CDATA[
1009    <iq type='get'
1010        from='client@clayster.com/client'
1011        to='concentrator@clayster.com'
1012        id='10'>
1013       <getNodes xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
1014           <node sourceId='MeteringTopology' nodeId='Node1'/>
1015           <node sourceId='MeteringTopology' nodeId='Node2'/>
1016           <node sourceId='MeteringTopology' nodeId='Node3'/>
1017       </getNodes>
1018    </iq>
1019    
1020    <iq type='result'
1021        from='concentrator@clayster.com'
1022        to='client@clayster.com/client'
1023        id='10'>
1024       <getNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1025           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true' 
1026                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
1027           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
1028                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
1029           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
1030                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
1031       </getNodesResponse>
1032    </iq>]]>
1033                 </example>
1034                 <p>
1035                     For more information, see <link url='#nodeinfo'>Node Information</link>.
1036                 </p>
1037             </section3>
1038             <section3 topic='Get Node with parameters'>
1039                 <p>
1040                     This command returns basic information about a node in the concentrator, as well as node parameters.
1041                 </p>
1042                 <example caption='Get Node with parameters'>
1043                     <![CDATA[
1044    <iq type='get'
1045        from='client@clayster.com/client'
1046        to='concentrator@clayster.com'
1047        id='11'>
1048       <getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true'/>
1049    </iq>
1050    
1051    <iq type='result'
1052        from='concentrator@clayster.com'
1053        to='client@clayster.com/client'
1054        id='11'>
1055       <getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK' nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' 
1056                        state='WarningUnsigned' hasChildren='false' isReadable='true' isControllable='true' hasCommands='true' 
1057                        parentId='Root' lastChanged='2013-03-19T17:58:01'>
1058           <string id='id' name='Node ID' value='Node1'/>
1059           <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1060           <string id='sn' name='Serial Number' value='123456'/>
1061           <string id='class' name='Node Class' value='Temperature'/>
1062           <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1063           <int id='addr' name='Address' value='123'/>
1064           <double id='lat' name='Latitude' value='12.345'/>
1065           <double id='long' name='Longitude' value='123.45'/>
1066       </getNodeResponse>
1067    </iq>]]>
1068                 </example>
1069                 <p>
1070                     For more information, see <link url='#nodeinfo'>Node Information</link>.
1071                 </p>
1072             </section3>
1073             <section3 topic='Get Nodes with parameters'>
1074                 <p>
1075                     This command lets the client get information from multiple nodes at once, including node parameters.
1076                 </p>
1077                 <example caption='Get Nodes with parameters'>
1078                     <![CDATA[
1079    <iq type='get'
1080        from='client@clayster.com/client'
1081        to='concentrator@clayster.com'
1082        id='12'>
1083       <getNodes xmlns='urn:xmpp:iot:concentrators' parameters='true' xml:lang='en'>
1084           <node sourceId='MeteringTopology' nodeId='Node1'/>
1085           <node sourceId='MeteringTopology' nodeId='Node2'/>
1086           <node sourceId='MeteringTopology' nodeId='Node3'/>
1087       </getNodes>
1088    </iq>
1089    
1090    <iq type='result'
1091        from='concentrator@clayster.com'
1092        to='client@clayster.com/client'
1093        id='12'>
1094       <getNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1095           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true' 
1096                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
1097               <string id='id' name='Node ID' value='Node1'/>
1098               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1099               <string id='sn' name='Serial Number' value='123456'/>
1100               <string id='class' name='Node Class' value='Temperature'/>
1101               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1102               <int id='addr' name='Address' value='123'/>
1103               <double id='lat' name='Latitude' value='12.345'/>
1104               <double id='long' name='Longitude' value='123.45'/>
1105           </node>
1106           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
1107                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
1108               <string id='id' name='Node ID' value='Node2'/>
1109               <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
1110               <string id='sn' name='Serial Number' value='234567'/>
1111               <string id='class' name='Node Class' value='Pressure'/>
1112               <string id='meterLoc' name='Meter Location' value='P668632-6'/>
1113               <int id='addr' name='Address' value='124'/>
1114               <double id='lat' name='Latitude' value='12.345'/>
1115               <double id='long' name='Longitude' value='123.45'/>
1116           </node>
1117           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
1118                 isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
1119               <string id='id' name='Node ID' value='Node3'/>
1120               <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
1121               <string id='sn' name='Serial Number' value='345678'/>
1122               <string id='class' name='Node Class' value='Electricity'/>
1123               <string id='meterLoc' name='Meter Location' value='P332367-9'/>
1124               <int id='addr' name='Address' value='125'/>
1125               <double id='lat' name='Latitude' value='12.345'/>
1126               <double id='long' name='Longitude' value='123.45'/>
1127           </node>
1128       </getNodesResponse>
1129    </iq>]]>
1130                 </example>
1131                 <p>
1132                     For more information, see <link url='#nodeinfo'>Node Information</link>.
1133                 </p>
1134             </section3>
1135             <section3 topic='Get All Nodes'>
1136                 <p>
1137                     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.
1138                 </p>
1139                 <example caption='Get All Nodes'>
1140                     <![CDATA[
1141    <iq type='get'
1142        from='client@clayster.com/client'
1143        to='concentrator@clayster.com'
1144        id='13'>
1145       <getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'/>
1146    </iq>
1147    
1148    <iq type='result'
1149        from='concentrator@clayster.com'
1150        to='client@clayster.com/client'
1151        id='13'>
1152       <getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1153           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1154                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1155           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
1156                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1157           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1158                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1159           <node nodeId='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true' 
1160                 isReadable='false' isControllable='false' hasCommands='true'/>
1161       </getAllNodesResponse>
1162    </iq>]]>
1163                 </example>
1164             </section3>
1165             <section3 topic='Get All Nodes with Parameters'>
1166                 <p>
1167                     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.
1168                 </p>
1169                 <example caption='Get All Nodes with Parameters'>
1170                     <![CDATA[
1171    <iq type='get'
1172        from='client@clayster.com/client'
1173        to='concentrator@clayster.com'
1174        id='14'>
1175       <getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
1176    </iq>
1177    
1178    <iq type='result'
1179        from='concentrator@clayster.com'
1180        to='client@clayster.com/client'
1181        id='14'>
1182       <getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1183           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1184                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1185               <string id='id' name='Node ID' value='Node1'/>
1186               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1187               <string id='sn' name='Serial Number' value='123456'/>
1188               <string id='class' name='Node Class' value='Temperature'/>
1189               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1190               <int id='addr' name='Address' value='123'/>
1191               <double id='lat' name='Latitude' value='12.345'/>
1192               <double id='long' name='Longitude' value='123.45'/>
1193           </node>
1194           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
1195                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1196               <string id='id' name='Node ID' value='Node2'/>
1197               <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
1198               <string id='sn' name='Serial Number' value='234567'/>
1199               <string id='class' name='Node Class' value='Pressure'/>
1200               <string id='meterLoc' name='Meter Location' value='P668632-6'/>
1201               <int id='addr' name='Address' value='124'/>
1202               <double id='lat' name='Latitude' value='12.345'/>
1203               <double id='long' name='Longitude' value='123.45'/>
1204           </node>
1205           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1206                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1207               <string id='id' name='Node ID' value='Node3'/>
1208               <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
1209               <string id='sn' name='Serial Number' value='345678'/>
1210               <string id='class' name='Node Class' value='Electricity'/>
1211               <string id='meterLoc' name='Meter Location' value='P332367-9'/>
1212               <int id='addr' name='Address' value='125'/>
1213               <double id='lat' name='Latitude' value='12.345'/>
1214               <double id='long' name='Longitude' value='123.45'/>
1215           </node>
1216           <node nodeId='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true' 
1217                 isReadable='false' isControllable='false' hasCommands='true'>
1218               <string id='id' name='Node ID' value='Root'/>
1219               <string id='type' name='Node Type' value='Root Node'/>
1220           </node>
1221       </getAllNodesResponse>
1222    </iq>]]>
1223                 </example>
1224             </section3>
1225             <section3 topic='Get All Nodes derived from'>
1226                 <p>
1227                     This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance.
1228                 </p>
1229                 <example caption='Get All Nodes derived from'>
1230                     <![CDATA[
1231    <iq type='get'
1232        from='client@clayster.com/client'
1233        to='concentrator@clayster.com'
1234        id='15'>
1235       <getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'>
1236           <onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
1237       </getAllNodes>
1238    </iq>
1239    
1240    <iq type='result'
1241        from='concentrator@clayster.com'
1242        to='client@clayster.com/client'
1243        id='15'>
1244       <getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1245           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1246                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1247           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1248                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1249       </getAllNodesResponse>
1250    </iq>]]>
1251                 </example>
1252             </section3>
1253             <section3 topic='Get All Nodes derived from, with Parameters'>
1254                 <p>
1255                     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
1256                     directly in the response.
1257                 </p>
1258                 <example caption='Get All Nodes derived from, with Parameters'>
1259                     <![CDATA[
1260    <iq type='get'
1261        from='client@clayster.com/client'
1262        to='concentrator@clayster.com'
1263        id='16'>
1264       <getAllNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'>
1265           <onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
1266       </getAllNodes>
1267    </iq>
1268    
1269    <iq type='result'
1270        from='concentrator@clayster.com'
1271        to='client@clayster.com/client'
1272        id='16'>
1273       <getAllNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1274           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1275                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1276               <string id='id' name='Node ID' value='Node1'/>
1277               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1278               <string id='sn' name='Serial Number' value='123456'/>
1279               <string id='class' name='Node Class' value='Temperature'/>
1280               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1281               <int id='addr' name='Address' value='123'/>
1282               <double id='lat' name='Latitude' value='12.345'/>
1283               <double id='long' name='Longitude' value='123.45'/>
1284           </node>
1285           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1286                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1287               <string id='id' name='Node ID' value='Node3'/>
1288               <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
1289               <string id='sn' name='Serial Number' value='345678'/>
1290               <string id='class' name='Node Class' value='Electricity'/>
1291               <string id='meterLoc' name='Meter Location' value='P332367-9'/>
1292               <int id='addr' name='Address' value='125'/>
1293               <double id='lat' name='Latitude' value='12.345'/>
1294               <double id='long' name='Longitude' value='123.45'/>
1295           </node>
1296       </getAllNodesResponse>
1297    </iq>]]>
1298                 </example>
1299                 <p>
1300                     Note that the caller can list multiple classes in the request. This would return only nodes having the correct base class(es) and
1301                     implementing all interfaces.
1302                 </p>
1303             </section3>
1304             <section3 topic='Get Node Inheritance'>
1305                 <p>
1306                     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
1307                     node has.
1308                 </p>
1309                 <example caption='Get node inheritance'>
1310                     <![CDATA[
1311    <iq type='get'
1312        from='client@clayster.com/client'
1313        to='concentrator@clayster.com'
1314        id='17'>
1315       <getNodeInheritance xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
1316    </iq>
1317    
1318    <iq type='result'
1319        from='concentrator@clayster.com'
1320        to='client@clayster.com/client'
1321        id='17'>
1322       <getNodeInheritanceResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1323           <baseClasses>
1324               <value>Namespace.BaseClass1</value>
1325               <value>Namespace.AbstractBase</value>
1326           </baseClasses>
1327       </getNodeInheritanceResponse>
1328    </iq>]]>
1329                 </example>
1330                 <p>
1331                     <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
1332                     its base classes and any implemented interfaces.
1333                 </p>
1334             </section3>
1335             <section3 topic='Get Root Nodes'>
1336                 <p>
1337                     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
1338                     source is flat).
1339                 </p>
1340                 <example caption='Get Root Nodes'>
1341                     <![CDATA[
1342    <iq type='get'
1343        from='client@clayster.com/client'
1344        to='concentrator@clayster.com'
1345        id='18'>
1346       <getRootNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'/>
1347    </iq>
1348    
1349    <iq type='result'
1350        from='concentrator@clayster.com'
1351        to='client@clayster.com/client'
1352        id='18'>
1353       <getRootNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1354           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1355                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1356       </getRootNodesResponse>
1357    </iq>]]>
1358                 </example>
1359             </section3>
1360             <section3 topic='Get Root Nodes with Parameters'>
1361                 <p>
1362                     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
1363                     source is flat), and also returns the parameters for the corresponding nodes.
1364                 </p>
1365                 <example caption='Get Root Nodes with Parameters'>
1366                     <![CDATA[
1367    <iq type='get'
1368        from='client@clayster.com/client'
1369        to='concentrator@clayster.com'
1370        id='19'>
1371       <getRootNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
1372    </iq>
1373    
1374    <iq type='result'
1375        from='concentrator@clayster.com'
1376        to='client@clayster.com/client'
1377        id='19'>
1378       <getRootNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1379           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1380                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1381               <string id='id' name='Node ID' value='Node1'/>
1382               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1383               <string id='sn' name='Serial Number' value='123456'/>
1384               <string id='class' name='Node Class' value='Temperature'/>
1385               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1386               <int id='addr' name='Address' value='123'/>
1387               <double id='lat' name='Latitude' value='12.345'/>
1388               <double id='long' name='Longitude' value='123.45'/>
1389           </node>
1390       </getRootNodesResponse>
1391    </iq>]]>
1392                 </example>
1393             </section3>
1394             <section3 topic='Get Child Nodes'>
1395                 <p>
1396                     This command returns the child nodes of a node in a data source.
1397                 </p>
1398                 <example caption='Get Child Nodes'>
1399                     <![CDATA[
1400    <iq type='get'
1401        from='client@clayster.com/client'
1402        to='concentrator@clayster.com'
1403        id='20'>
1404       <getChildNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
1405    </iq>
1406    
1407    <iq type='result'
1408        from='concentrator@clayster.com'
1409        to='client@clayster.com/client'
1410        id='20'>
1411       <getChildNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1412           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
1413                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1414           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1415                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'/>
1416       </getChildNodesResponse>
1417    </iq>]]>
1418                 </example>
1419             </section3>
1420             <section3 topic='Get Child Nodes with Parameters'>
1421                 <p>
1422                     This command returns the child nodes of a node in a data source, and also returns the parameters for the corresponding nodes.
1423                 </p>
1424                 <example caption='Get Child Nodes with Parameters'>
1425                     <![CDATA[
1426    <iq type='get'
1427        from='client@clayster.com/client'
1428        to='concentrator@clayster.com'
1429        id='21'>
1430       <getChildNodes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' parameters='true' xml:lang='en' />
1431    </iq>
1432    
1433    <iq type='result'
1434        from='concentrator@clayster.com'
1435        to='client@clayster.com/client'
1436        id='21'>
1437       <getChildNodesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1438           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
1439                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1440               <string id='id' name='Node ID' value='Node2'/>
1441               <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
1442               <string id='sn' name='Serial Number' value='234567'/>
1443               <string id='class' name='Node Class' value='Pressure'/>
1444               <string id='meterLoc' name='Meter Location' value='P668632-6'/>
1445               <int id='addr' name='Address' value='124'/>
1446               <double id='lat' name='Latitude' value='12.345'/>
1447               <double id='long' name='Longitude' value='123.45'/>
1448           </node>
1449           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
1450                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1451               <string id='id' name='Node ID' value='Node3'/>
1452               <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
1453               <string id='sn' name='Serial Number' value='345678'/>
1454               <string id='class' name='Node Class' value='Electricity'/>
1455               <string id='meterLoc' name='Meter Location' value='P332367-9'/>
1456               <int id='addr' name='Address' value='125'/>
1457               <double id='lat' name='Latitude' value='12.345'/>
1458               <double id='long' name='Longitude' value='123.45'/>
1459           </node>
1460       </getChildNodesResponse>
1461    </iq>]]>
1462                 </example>
1463             </section3>
1464             <section3 topic='Get Indices of Data Source'>
1465                 <p>
1466                     This command returns a list of available indices in a data source. Indices can be used for efficient node look-up.
1467                 </p>
1468                 <example caption='Get Indices of Data Source'>
1469                     <![CDATA[
1470    <iq type='get'
1471        from='client@clayster.com/client'
1472        to='concentrator@clayster.com'
1473        id='22'>
1474       <getIndices xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' />
1475    </iq>
1476    
1477    <iq type='result'
1478        from='concentrator@clayster.com'
1479        to='client@clayster.com/client'
1480        id='22'>
1481       <getIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1482           <value>country</value>
1483           <value>region</value>
1484           <value>city</value>
1485           <value>area</value>
1486           <value>street</value>
1487           <value>building</value>
1488           <value>apartment</value>
1489           <value>oid</value>
1490       </getIndicesResponse>
1491    </iq>]]>
1492                 </example>
1493             </section3>
1494             <section3 topic='Get Nodes from index'>
1495                 <p>
1496                     This command can be used to get a node or nodes from a data source using an index and an index value.
1497                 </p>
1498                 <example caption='Get Nodes from index'>
1499                     <![CDATA[
1500    <iq type='get'
1501        from='client@clayster.com/client'
1502        to='concentrator@clayster.com'
1503        id='23'>
1504       <getNodesFromIndex xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1' xml:lang='en'/>
1505    </iq>
1506    
1507    <iq type='result'
1508        from='concentrator@clayster.com'
1509        to='client@clayster.com/client'
1510        id='23'>
1511       <getNodesFromIndexResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1512           <node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1513                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
1514       </getNodesFromIndexResponse>
1515    </iq>]]>
1516                 </example>
1517             </section3>
1518             <section3 topic='Get Nodes from index with Parameters'>
1519                 <p>
1520                     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.
1521                 </p>
1522                 <example caption='Get Nodes from index with Parameters'>
1523                     <![CDATA[
1524    <iq type='get'
1525        from='client@clayster.com/client'
1526        to='concentrator@clayster.com'
1527        id='24'>
1528       <getNodesFromIndex xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1' 
1529                          parameters='true' xml:lang='en'/>
1530    </iq>
1531    
1532    <iq type='result'
1533        from='concentrator@clayster.com'
1534        to='client@clayster.com/client'
1535        id='24'>
1536       <getNodesFromIndexResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1537           <node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1538                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'>
1539               <string id='id' name='Node ID' value='Node2'/>
1540               <string id='type' name='Node Type' value='Metering Topology Reference'/>
1541               <string id='referenceId' name='Reference ID' value='Node2'/>
1542           </node>
1543       </getNodesFromIndexResponse>
1544    </iq>]]>
1545                 </example>
1546             </section3>
1547             <section3 topic='Get Nodes from indices'>
1548                 <p>
1549                     This command can be used to get nodes from a set of data source using indices and index values.
1550                 </p>
1551                 <example caption='Get Nodes from indices'>
1552                     <![CDATA[
1553    <iq type='get'
1554        from='client@clayster.com/client'
1555        to='concentrator@clayster.com'
1556        id='25'>
1557       <getNodesFromIndices xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
1558           <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
1559           <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
1560       </getNodesFromIndices>
1561    </iq>
1562    
1563    <iq type='result'
1564        from='concentrator@clayster.com'
1565        to='client@clayster.com/client'
1566        id='25'>
1567       <getNodesFromIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1568           <node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1569                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
1570           <node nodeId='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1571                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-2'/>
1572       </getNodesFromIndicesResponse>
1573    </iq>]]>
1574                 </example>
1575             </section3>
1576             <section3 topic='Get Nodes from indices with Parameters'>
1577                 <p>
1578                     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.
1579                 </p>
1580                 <example caption='Get Nodes from indices with Parameters'>
1581                     <![CDATA[
1582    <iq type='get'
1583        from='client@clayster.com/client'
1584        to='concentrator@clayster.com'
1585        id='26'>
1586       <getNodesFromIndices xmlns='urn:xmpp:iot:concentrators' parameters='true' xml:lang='en'>
1587           <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
1588           <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
1589       </getNodesFromIndices>
1590    </iq>
1591    
1592    <iq type='result'
1593        from='concentrator@clayster.com'
1594        to='client@clayster.com/client'
1595        id='26'>
1596       <getNodesFromIndicesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1597           <node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1598                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'>
1599               <string id='id' name='Node ID' value='Node2'/>
1600               <string id='type' name='Node Type' value='Metering Topology Reference'/>
1601               <string id='referenceId' name='Reference ID' value='Node2'/>
1602           </node>
1603           <node nodeId='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1604                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-2'>
1605               <string id='id' name='Node ID' value='Node3'/>
1606               <string id='type' name='Node Type' value='Metering Topology Reference'/>
1607               <string id='referenceId' name='Reference ID' value='Node3'/>
1608           </node>
1609       </getNodesFromIndicesResponse>
1610    </iq>]]>
1611                 </example>
1612             </section3>
1613             <section3 topic='Get All Index Values'>
1614                 <p>
1615                     This command can be used to get a list of available index values, given a data source and an index.
1616                 </p>
1617                 <example caption='Get All Index Values'>
1618                     <![CDATA[
1619    <iq type='get'
1620        from='client@clayster.com/client'
1621        to='concentrator@clayster.com'
1622        id='27'>
1623       <getAllIndexValues xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' index='apartment'/>
1624    </iq>
1625    
1626    <iq type='result'
1627        from='concentrator@clayster.com'
1628        to='client@clayster.com/client'
1629        id='27'>
1630       <getAllIndexValuesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1631           <value>A1-1</value>
1632           <value>A1-2</value>
1633           ...
1634       </getAllIndexValuesResponse>
1635    </iq>]]>
1636                 </example>
1637             </section3>
1638             <section3 topic='Get Node Ancestors'>
1639                 <p>
1640                     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
1641                     of all ancestors (parent, grand parent, etc.) of a node, as is shown in the following example:
1642                 </p>
1643                 <example caption='Get Node Ancestors'>
1644                     <![CDATA[
1645    <iq type='get'
1646        from='client@clayster.com/client'
1647        to='concentrator@clayster.com'
1648        id='42'>
1649       <getAncestors xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='Node2' parameters='false' messages='false' xml:lang='en'/>
1650    </iq>
1651    
1652    <iq type='result'
1653        from='concentrator@clayster.com'
1654        to='client@clayster.com/client'
1655        id='42'>
1656       <getAncestorsResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1657           <node nodeId='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
1658                 isReadable='true' isControllable='true' hasCommands='true' parentId='Apartment 1-1'/>
1659           <node nodeId='Apartment 1-1' nodeType='Namespace.Apartment' state='None' hasChildren='true' 
1660                 isReadable='false' isControllable='false' hasCommands='true' parentId='Building 1'/>
1661           <node nodeId='Building 1' nodeType='Namespace.Building' state='None' hasChildren='true' 
1662                 isReadable='false' isControllable='false' hasCommands='true' parentId='Street'/>
1663           <node nodeId='Street' nodeType='Namespace.Street' state='None' hasChildren='true' 
1664                 isReadable='false' isControllable='false' hasCommands='true' parentId='Area'/>
1665           <node nodeId='Area' nodeType='Namespace.Area' state='None' hasChildren='true' 
1666                 isReadable='false' isControllable='false' hasCommands='true' parentId='City'/>
1667           <node nodeId='City' nodeType='Namespace.City' state='None' hasChildren='true' 
1668                 isReadable='false' isControllable='false' hasCommands='true' parentId='Region'/>
1669           <node nodeId='Region' nodeType='Namespace.Region' state='None' hasChildren='true' 
1670                 isReadable='false' isControllable='false' hasCommands='true' parentId='Country'/>
1671           <node nodeId='Country' nodeType='Namespace.Country' state='None' hasChildren='true' 
1672                 isReadable='false' isControllable='false' hasCommands='true' parentId='Root'/>
1673           <node nodeId='Root' nodeType='Namespace.Root' state='None' hasChildren='true' 
1674                 isReadable='false' isControllable='false' hasCommands='true'/>
1675       </getAncestorsResponse>
1676    </iq>]]>
1677                 </example>
1678                 <p>
1679                     Note that the concentrator returns information about the node itself in the response. The <strong>parameters</strong> and <strong>messages</strong>
1680                     attributes are used in the request to control if the concentrator should return node parameters and node status messages in the response as well.
1681                 </p>
1682             </section3>
1683             <section3 topic='Move Node Up'>
1684                 <p>
1685                     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.
1686                     To move a node upwards among its siblings is done using the command <strong>moveNodeUp</strong>, as is shown in the following example:
1687                 </p>
1688                 <example caption='Move Node Up'>
1689                     <![CDATA[
1690    <iq type='set'
1691        from='client@clayster.com/client'
1692        to='concentrator@clayster.com'
1693        id='53'>
1694       <moveNodeUp xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
1695    </iq>
1696    
1697    <iq type='result'
1698        from='concentrator@clayster.com'
1699        to='client@clayster.com/client'
1700        id='53'>
1701       <moveNodeUpResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
1702    </iq>]]>
1703                 </example>
1704                 <p>
1705                     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>.
1706                 </p>
1707             </section3>
1708             <section3 topic='Move Node Down'>
1709                 <p>
1710                     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.
1711                     To move a node downwards among its siblings is done using the command <strong>moveNodeDown</strong>, as is shown in the following example:
1712                 </p>
1713                 <example caption='Move Node Up'>
1714                     <![CDATA[
1715    <iq type='set'
1716        from='client@clayster.com/client'
1717        to='concentrator@clayster.com'
1718        id='54'>
1719       <moveNodeDown xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
1720    </iq>
1721    
1722    <iq type='result'
1723        from='concentrator@clayster.com'
1724        to='client@clayster.com/client'
1725        id='54'>
1726       <moveNodeDownResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
1727    </iq>]]>
1728                 </example>
1729                 <p>
1730                     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>.
1731                 </p>
1732             </section3>
1733             <section3 topic='Move Nodes Up'>
1734                 <p>
1735                     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:
1736                 </p>
1737                 <example caption='Move Nodes Up'>
1738                     <![CDATA[
1739    <iq type='set'
1740        from='client@clayster.com/client'
1741        to='concentrator@clayster.com'
1742        id='55'>
1743       <moveNodesUp xmlns='urn:xmpp:iot:concentrators'>
1744           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
1745           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
1746           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
1747       </moveNodesUp>
1748    </iq>
1749    
1750    <iq type='result'
1751        from='concentrator@clayster.com'
1752        to='client@clayster.com/client'
1753        id='55'>
1754       <moveNodesUpResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
1755    </iq>]]>
1756                 </example>
1757                 <p>
1758                     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
1759                     sequence of nodes that are together first as siblings, none of the nodes move relative to each other.
1760                 </p>
1761             </section3>
1762             <section3 topic='Move Nodes Down'>
1763                 <p>
1764                     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:
1765                 </p>
1766                 <example caption='Move Node Down'>
1767                     <![CDATA[
1768    <iq type='set'
1769        from='client@clayster.com/client'
1770        to='concentrator@clayster.com'
1771        id='56'>
1772       <moveNodesDown xmlns='urn:xmpp:iot:concentrators'>
1773           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
1774           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
1775           <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
1776       </moveNodesDown>
1777    </iq>
1778    
1779    <iq type='result'
1780        from='concentrator@clayster.com'
1781        to='client@clayster.com/client'
1782        id='56'>
1783       <moveNodesDownResponse xmlns='urn:xmpp:iot:concentrators' result='OK'/>
1784    </iq>]]>
1785                 </example>
1786                 <p>
1787                     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
1788                     sequence of nodes that are together last as siblings, none of the nodes move relative to each other.
1789                 </p>
1790             </section3>
1791         </section2>
1792         <section2 topic='Node Parameters'>
1793             <section3 topic='Get Node Parameters for editing'>
1794                 <p>
1795                     Previously described commands can return parameters for a node. But these parameters are for presentational or informational use. If the client wants to edit
1796                     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
1797                     parameters for one node.
1798                 </p>
1799                 <p>
1800                     <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
1801                     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
1802                     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
1803                     an edit mode (like long multi-line parameters) and not in a shorter presentation mode.
1804                 </p>
1805                 <example caption='Get Node Parameters for editing'>
1806                     <![CDATA[
1807    <iq type='get'
1808        from='client@clayster.com/client'
1809        to='concentrator@clayster.com'
1810        id='28'>
1811       <getNodeParametersForEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
1812    </iq>
1813    
1814    <iq type='result'
1815        from='concentrator@clayster.com'
1816        to='client@clayster.com/client'
1817        id='28'>
1818       <getNodeParametersForEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1819           <x type='form' 
1820              xmlns='jabber:x:data' 
1821              xmlns:xdv='http://jabber.org/protocol/xdata-validate'
1822              xmlns:xdl='http://jabber.org/protocol/xdata-layout'
1823              xmlns:xdd='urn:xmpp:xdata:dynamic'>
1824               <title>Node1</title>
1825               <xdl:page label='Identity'>
1826                   <xdl:fieldref var='id'/>
1827                   <xdl:fieldref var='type'/>
1828                   <xdl:fieldref var='class'/>
1829                   <xdl:fieldref var='sn'/>
1830               </xdl:page>
1831               <xdl:page label='Location'>
1832                   <xdl:fieldref var='meterLoc'/>
1833                   <xdl:fieldref var='lat'/>
1834                   <xdl:fieldref var='long'/>
1835               </xdl:page>
1836               <xdl:page label='Communication'>
1837                   <xdl:fieldref var='addr'/>
1838               </xdl:page>
1839               <field var='xdd session' type='hidden'>
1840                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
1841               </field>
1842               <field var='id' type='text-single' label='Node ID:'>
1843                   <desc>ID of the node.</desc>
1844                   <required/>
1845                   <value>Node1</value>
1846               </field>
1847               <field var='type' type='text-single' label='Node Type:'>
1848                   <desc>Type of node.</desc>
1849                   <value>Watchamacallit Temperature Sensor v1.2</value>
1850                   <xdd:readOnly/>
1851               </field>
1852               <field var='class' type='list-single' label='Node Class:'>
1853                   <desc>Class of node</desc>
1854                   <value>Temperature</value>
1855                   <option label='Cooling'><value>Cooling</value></option>
1856                   <option label='Electricity'><value>Electricity</value></option>
1857                   <option label='Heating'><value>Heating</value></option>
1858                   <option label='Pressure'><value>Pressure</value></option>
1859                   <option label='Temperature'><value>Temperature</value></option>
1860                   <option label='Water'><value>Water</value></option>
1861                   ...
1862               </field>
1863               <field var='sn' type='text-single' label='Serial Number:'>
1864                   <desc>Serial number of node/device.</desc>
1865                   <value>123456</value>
1866               </field>
1867               <field var='meterLoc' type='text-single' label='Meter Location:'>
1868                   <desc>Meter Location.</desc>
1869                   <value>P123502-2</value>
1870               </field>
1871               <field var='addr' type='text-single' label='Address:'>
1872                   <xdv:validate datatype='xs:int'>
1873                       <xdv:range min='1' max='250'/>
1874                   </xdv:validate>
1875                   <desc>Bus address</desc>
1876                   <value>123</value>
1877               </field>
1878               <field var='lat' type='text-single' label='Latitude:'>
1879                   <xdv:validate datatype='xs:double'>
1880                       <xdv:range min='-90' max='90'/>
1881                   </xdv:validate>
1882                   <desc>Latitude of node.</desc>
1883                   <value>12.345</value>
1884               </field>
1885               <field var='long' type='text-single' label='Longitude:'>
1886                   <xdv:validate datatype='xs:double'>
1887                       <xdv:range min='-180' max='180'/>
1888                   </xdv:validate>
1889                   <desc>Longitude of node.</desc>
1890                   <value>123.45</value>
1891               </field>
1892           </x>
1893       </getNodeParametersForEditResponse>
1894    </iq>]]>
1895                 </example>
1896                 <p>
1897                     The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal:
1898                 </p>
1899                 <table caption='Form XEPs'>
1900                     <tr>
1901                         <th>XEP</th>
1902                         <th>Description</th>
1903                     </tr>
1904                     <tr>
1905                         <td>XEP-0004</td>
1906                         <td>Describes how basic forms are handled.</td>
1907                     </tr>
1908                     <tr>
1909                         <td>XEP-0122</td>
1910                         <td>Makes it possible to add certain client validation rules to form parameters.</td>
1911                     </tr>
1912                     <tr>
1913                         <td>XEP-0137</td>
1914                         <td>Makes it possible to publish a file upload parameter.</td>
1915                     </tr>
1916                     <tr>
1917                         <td>XEP-0141</td>
1918                         <td>Makes it possible to layout parameters into pages and sections.</td>
1919                     </tr>
1920                     <tr>
1921                         <td>XEP-0331</td>
1922                         <td>Defines extensions for how color parameters can be handled.</td>
1923                     </tr>
1924                     <tr>
1925                         <td>XEP-0336</td>
1926                         <td>Makes it possible to create dynamic forms, with server-side validation and forms that change dynamically depending on input.</td>
1927                     </tr>
1928                 </table>
1929                 <p>
1930                     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>.
1931                     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
1932                     to try to set them.
1933                 </p>
1934             </section3>
1935             <section3 topic='Set Node Parameters after editing'>
1936                 <p>
1937                     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
1938                     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
1939                     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.
1940                 </p>
1941                 <example caption='Set Node Parameters after editing'>
1942                     <![CDATA[
1943    <iq type='set'
1944        from='client@clayster.com/client'
1945        to='concentrator@clayster.com'
1946        id='29'>
1947       <setNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'>
1948           <x type='submit' xmlns='jabber:x:data'>
1949               <field var='xdd session' type='hidden'>
1950                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
1951               </field>
1952               <field var='id' type='text-single'>
1953                   <value>Node1</value>
1954               </field>
1955               <field var='class' type='list-single'>
1956                   <value>Temperature</value>
1957               </field>
1958               <field var='sn' type='text-single'>
1959                   <value>123456</value>
1960               </field>
1961               <field var='meterLoc' type='text-single'>
1962                   <value>P123502-2</value>
1963               </field>
1964               <field var='addr' type='text-single'>
1965                   <value>123</value>
1966               </field>
1967               <field var='lat' type='text-single'>
1968                   <value>12.345</value>
1969               </field>
1970               <field var='long' type='text-single'>
1971                   <value>123.45</value>
1972               </field>
1973           </x>
1974       </setNodeParametersAfterEdit>
1975    </iq>
1976    
1977    <iq type='result'
1978        from='concentrator@clayster.com'
1979        to='client@clayster.com/client'
1980        id='29'>
1981       <setNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
1982           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
1983                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
1984               <string id='id' name='Node ID' value='Node1'/>
1985               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
1986               <string id='sn' name='Serial Number' value='123456'/>
1987               <string id='class' name='Node Class' value='Temperature'/>
1988               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
1989               <int id='addr' name='Address' value='123'/>
1990               <double id='lat' name='Latitude' value='12.345'/>
1991               <double id='long' name='Longitude' value='123.45'/>
1992           </node>
1993       </setNodeParametersAfterEditResponse>
1994    </iq>]]>
1995                 </example>
1996                 <p>
1997                     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
1998                     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
1999                     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
2000                     in a <strong>node</strong> element.
2001                 </p>
2002             </section3>
2003             <section3 topic='Set Node Parameters after editing, Failure'>
2004                 <p>
2005                     The following example shows how the server responds when the client tries to set invalid parameters. The response contains detailed information about why,
2006                     information which the client can use to inform the user (if any) of what went wrong.
2007                 </p>
2008                 <example caption='Set Node Parameters after editing, Failure'>
2009                     <![CDATA[
2010    <iq type='set'
2011        from='client@clayster.com/client'
2012        to='concentrator@clayster.com'
2013        id='30'>
2014       <setNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node2' xml:lang='en'>
2015           <x type='submit' xmlns='jabber:x:data'>
2016               <field var='xdd session' type='hidden'>
2017                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
2018               </field>
2019               <field var='id' type='text-single'>
2020                   <value>Node1</value>
2021               </field>
2022               <field var='class' type='list-single'>
2023                   <value>Temperature</value>
2024               </field>
2025               <field var='sn' type='text-single'>
2026                   <value>123456</value>
2027               </field>
2028               <field var='meterLoc' type='text-single'>
2029                   <value>P123502-2</value>
2030               </field>
2031               <field var='addr' type='text-single'>
2032                   <value>123</value>
2033               </field>
2034               <field var='lat' type='text-single'>
2035                   <value>12.345</value>
2036               </field>
2037               <field var='long' type='text-single'>
2038                   <value>123.45</value>
2039               </field>
2040           </x>
2041       </setNodeParametersAfterEdit>
2042    </iq>
2043    
2044    <iq type='error'
2045        from='concentrator@clayster.com'
2046        to='client@clayster.com/client'
2047        id='30'>
2048       <setNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2049           <error var='id'>There already exists a node with this ID.</error>
2050       </setNodeParametersAfterEditResponse>
2051    </iq>]]>
2052                 </example>
2053                 <p>
2054                     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
2055                     dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
2056                     explicitly cancelled or a form session time-out has occurred. See <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>
2057                     <note>
2058                         XEP-0336: Dynamic Data Forms &lt;<link url='http://xmpp.org/extensions/xep-0336.html'>http://xmpp.org/extensions/xep-0336.html</link>&gt;
2059                     </note> for more information.
2060                 </p>
2061             </section3>
2062             <section3 topic='Get Common Node Parameters for editing'>
2063                 <p>
2064                     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
2065                     <strong>getCommonNodeParametersForEdit</strong> command. It will return a form with parameters that are common for all selected nodes. Since nodes
2066                     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
2067                     in IDs, descriptions, validation rules, etc., (but not values) will be returned in a form.
2068                 </p>
2069                 <p>
2070                     <strong>Important:</strong> A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the 
2071                     <strong>notSame</strong> element, according to <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>. Clients using this command MUST 
2072                     support the extensions defined in <link url='http://xmpp.org/extensions/xep-0336.html'>XEP-0336</link>.
2073                 </p>
2074                 <example caption='Get Common Node Parameters for editing'>
2075                     <![CDATA[
2076    <iq type='get'
2077        from='client@clayster.com/client'
2078        to='concentrator@clayster.com'
2079        id='31'>
2080       <getCommonNodeParametersForEdit xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2081          <node sourceId='MeteringTopology' nodeId='Node1'/>
2082          <node sourceId='MeteringTopology' nodeId='Node2'/>
2083          <node sourceId='MeteringTopology' nodeId='Node3'/>
2084       </getCommonNodeParametersForEdit>
2085    </iq>
2086    
2087    <iq type='result'
2088        from='concentrator@clayster.com'
2089        to='client@clayster.com/client'
2090        id='31'>
2091       <getCommonNodeParametersForEditResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2092           <x type='form' 
2093              xmlns='jabber:x:data' 
2094              xmlns:xdv='http://jabber.org/protocol/xdata-validate'
2095              xmlns:xdl='http://jabber.org/protocol/xdata-layout'
2096              xmlns:xdd='urn:xmpp:xdata:dynamic'>
2097               <title>Node1, Node2, Node3</title>
2098               <xdl:page label='Identity'>
2099                   <xdl:fieldref var='type'/>
2100                   <xdl:fieldref var='class'/>
2101                   <xdl:fieldref var='sn'/>
2102               </xdl:page>
2103               <xdl:page label='Location'>
2104                   <xdl:fieldref var='meterLoc'/>
2105                   <xdl:fieldref var='lat'/>
2106                   <xdl:fieldref var='long'/>
2107               </xdl:page>
2108               <field var='xdd session' type='hidden'>
2109                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
2110               </field>
2111               <field var='type' type='text-single' label='Node Type:'>
2112                   <desc>Type of node.</desc>
2113                   <value>Watchamacallit Temperature Sensor v1.2</value>
2114                   <xdd:readOnly/>
2115                   <xdd:notSame/>
2116               </field>
2117               <field var='class' type='list-single' label='Node Class:'>
2118                   <desc>Class of node</desc>
2119                   <value>Temperature</value>
2120                   <xdd:notSame/>
2121                   <option label='Cooling'><value>Cooling</value></option>
2122                   <option label='Electricity'><value>Electricity</value></option>
2123                   <option label='Heating'><value>Heating</value></option>
2124                   <option label='Pressure'><value>Pressure</value></option>
2125                   <option label='Temperature'><value>Temperature</value></option>
2126                   <option label='Water'><value>Water</value></option>
2127                   ...
2128               </field>
2129               <field var='sn' type='text-single' label='Serial Number:'>
2130                   <desc>Serial number of node/device.</desc>
2131                   <value>123456</value>
2132                   <xdd:notSame/>
2133               </field>
2134               <field var='meterLoc' type='text-single' label='Meter Location:'>
2135                   <desc>Meter Location.</desc>
2136                   <value>P123502-2</value>
2137                   <xdd:notSame/>
2138               </field>
2139               <field var='addr' type='text-single' label='Address:'>
2140                   <xdv:validate datatype='xs:int'>
2141                       <xdv:range min='1' max='250'/>
2142                   </xdv:validate>
2143                   <desc>Bus address</desc>
2144                   <value>123</value>
2145                   <xdd:notSame/>
2146               </field>
2147               <field var='lat' type='text-single' label='Latitude:'>
2148                   <xdv:validate datatype='xs:double'>
2149                       <xdv:range min='-90' max='90'/>
2150                   </xdv:validate>
2151                   <desc>Latitude of node.</desc>
2152                   <value>12.345</value>
2153                   <xdd:notSame/>
2154               </field>
2155               <field var='long' type='text-single' label='Longitude:'>
2156                   <xdv:validate datatype='xs:double'>
2157                       <xdv:range min='-180' max='180'/>
2158                   </xdv:validate>
2159                   <desc>Longitude of node.</desc>
2160                   <value>123.45</value>
2161                   <xdd:notSame/>
2162               </field>
2163           </x>
2164       </getCommonNodeParametersForEditResponse>
2165    </iq>]]>
2166                 </example>
2167                 <p>
2168                     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
2169                     cannot be set for a collection of nodes.
2170                 </p>
2171                 <p>
2172                     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
2173                     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.
2174                     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.
2175                 </p>
2176             </section3>
2177             <section3 topic='Set Common Node Parameters after editing'>
2178                 <p>
2179                     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
2180                     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
2181                     successful set operation, any form session used for dynamic validation during edit will not be available on the server any more.
2182                 </p>
2183                 <example caption='Set Common Node Parameters after editing'>
2184                     <![CDATA[
2185    <iq type='set'
2186        from='client@clayster.com/client'
2187        to='concentrator@clayster.com'
2188        id='32'>
2189       <setCommonNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' xml:lang='en'>
2190           <node sourceId='MeteringTopology' nodeId='Node1'/>
2191           <node sourceId='MeteringTopology' nodeId='Node2'/>
2192           <node sourceId='MeteringTopology' nodeId='Node3'/>
2193           <x type='submit' xmlns='jabber:x:data'>
2194               <field var='xdd session' type='hidden'>
2195                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
2196               </field>
2197               <field var='class' type='list-single'>
2198                   <value>Temperature</value>
2199               </field>
2200           </x>
2201       </setCommonNodeParametersAfterEdit>
2202    </iq>
2203    
2204    <iq type='error'
2205        from='concentrator@clayster.com'
2206        to='client@clayster.com/client'
2207        id='32'>
2208       <setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2209           <node nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
2210                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2211               <string id='id' name='Node ID' value='Node1'/>
2212               <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
2213               <string id='sn' name='Serial Number' value='123456'/>
2214               <string id='class' name='Node Class' value='Temperature'/>
2215               <string id='meterLoc' name='Meter Location' value='P123502-2'/>
2216               <int id='addr' name='Address' value='123'/>
2217               <double id='lat' name='Latitude' value='12.345'/>
2218               <double id='long' name='Longitude' value='123.45'/>
2219           </node>
2220           <node nodeId='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
2221                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2222               <string id='id' name='Node ID' value='Node2'/>
2223               <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
2224               <string id='sn' name='Serial Number' value='234567'/>
2225               <string id='class' name='Node Class' value='Temperature'/>
2226               <string id='meterLoc' name='Meter Location' value='P668632-6'/>
2227               <int id='addr' name='Address' value='124'/>
2228               <double id='lat' name='Latitude' value='12.345'/>
2229               <double id='long' name='Longitude' value='123.45'/>
2230           </node>
2231           <node nodeId='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
2232                 isReadable='true' isControllable='true' hasCommands='true' parentId='Root'>
2233               <string id='id' name='Node ID' value='Node3'/>
2234               <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
2235               <string id='sn' name='Serial Number' value='345678'/>
2236               <string id='class' name='Node Class' value='Temperature'/>
2237               <string id='meterLoc' name='Meter Location' value='P332367-9'/>
2238               <int id='addr' name='Address' value='125'/>
2239               <double id='lat' name='Latitude' value='12.345'/>
2240               <double id='long' name='Longitude' value='123.45'/>
2241           </node>
2242       </setCommonNodeParametersAfterEditResponse>
2243    </iq>]]>
2244                 </example>
2245                 <p>
2246                     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
2247                     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
2248                     related to the form, which disables any future dynamic validation of the contents of the form.
2249                 </p>
2250                 <p>
2251                     <strong>Important:</strong> A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the
2252                     <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 
2253                     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.
2254                 </p>
2255             </section3>
2256             <section3 topic='Set Common Node Parameters after editing, Failure'>
2257                 <p>
2258                     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,
2259                     information which the client can use to inform the user (if any) of what went wrong.
2260                 </p>
2261                 <example caption='Set Common Node Parameters after editing, Failure'>
2262                     <![CDATA[
2263    <iq type='set'
2264        from='client@clayster.com/client'
2265        to='concentrator@clayster.com'
2266        id='33'>
2267       <setCommonNodeParametersAfterEdit xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' xml:lang='en'>
2268           <node sourceId='MeteringTopology' nodeId='Node1'/>
2269           <node sourceId='MeteringTopology' nodeId='Node2'/>
2270           <node sourceId='MeteringTopology' nodeId='Node3'/>
2271           <x type='submit' xmlns='jabber:x:data'>
2272               <field var='xdd session' type='hidden'>
2273                   <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
2274               </field>
2275               <field var='id' type='text-single'>
2276                   <value>Node1</value>
2277               </field>
2278               <field var='class' type='list-single'>
2279                   <value>Temperature</value>
2280               </field>
2281           </x>
2282       </setCommonNodeParametersAfterEdit>
2283    </iq>
2284    
2285    <iq type='error'
2286        from='concentrator@clayster.com'
2287        to='client@clayster.com/client'
2288        id='33'>
2289       <setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2290           <error var='id'>Parameter not available.</error>
2291       </setCommonNodeParametersAfterEditResponse>
2292    </iq>]]>
2293                 </example>
2294                 <p>
2295                     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
2296                     dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been
2297                     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.
2298                 </p>
2299             </section3>
2300             <section3 topic='Get Node Messages'>
2301                 <p>
2302                     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.
2303                     This state can be any of the following values, in order of increasing importance:
2304                 </p>
2305                 <table caption='Node states'>
2306                     <tr>
2307                         <th>State</th>
2308                         <th>Description</th>
2309                     </tr>
2310                     <tr>
2311                         <td>None</td>
2312                         <td>Nothing has been reported on the node.</td>
2313                     </tr>
2314                     <tr>
2315                         <td>Information</td>
2316                         <td>There are informative events reported on the node.</td>
2317                     </tr>
2318                     <tr>
2319                         <td>WarningSigned</td>
2320                         <td>There are warnings reported on the node. But these warnings have been viewed by an operator.</td>
2321                     </tr>
2322                     <tr>
2323                         <td>WarningUnsigned</td>
2324                         <td>There are new or unreviewed warnings reported on the node.</td>
2325                     </tr>
2326                     <tr>
2327                         <td>ErrorSigned</td>
2328                         <td>There are errors reported on the node. But these errors have been viewed by an operator.</td>
2329                     </tr>
2330                     <tr>
2331                         <td>ErrorUnsigned</td>
2332                         <td>There are new or unreviewed errors reported on the node.</td>
2333                     </tr>
2334                 </table>
2335                 <p>
2336                     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
2337                     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
2338                     the possibility to change during runtime, which operators must be aware of.
2339                 </p>
2340                 <p>
2341                     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
2342                     current state of the node:
2343                 </p>
2344                 <ul>
2345                     <li>
2346                         <strong>getNode</strong>
2347                     </li>
2348                     <li>
2349                         <strong>getNodes</strong>
2350                     </li>
2351                     <li>
2352                         <strong>getChildNodes</strong>
2353                     </li>
2354                     <li>
2355                         <strong>getAllNodes</strong>
2356                     </li>
2357                     <li>
2358                         <strong>getRootNodes</strong>
2359                     </li>
2360                     <li>
2361                         <strong>getNodesFromIndex</strong>
2362                     </li>
2363                     <li>
2364                         <strong>getNodesFromIndices</strong>
2365                     </li>
2366                 </ul>
2367                 <example caption='Get Node Messages'>
2368                     <![CDATA[
2369    <iq type='get'
2370        from='client@clayster.com/client'
2371        to='concentrator@clayster.com'
2372        id='34'>
2373       <getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' messages='true' xml:lang='en'/>
2374    </iq>
2375    
2376    <iq type='result'
2377        from='concentrator@clayster.com'
2378        to='client@clayster.com/client'
2379        id='34'>
2380       <getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK' 
2381                        nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
2382                        isReadable='true' isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2383           <message timestamp='2013-03-21T11:06:15' type='WarningUnsigned' 
2384                    eventId='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
2385       </getNodeResponse>                       
2386    </iq>]]>
2387                 </example>
2388                 <p>
2389                     The <strong>messages</strong> attribute can be combined with the <strong>parameters</strong> attribute to provide both node parameters and
2390                     messages in the response.
2391                 </p>
2392                 <example caption='Get Node with parameters and messages'>
2393                     <![CDATA[
2394    <iq type='get'
2395        from='client@clayster.com/client'
2396        to='concentrator@clayster.com'
2397        id='35'>
2398       <getNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true' messages='true'/>
2399    </iq>
2400    
2401    <iq type='result'
2402        from='concentrator@clayster.com'
2403        to='client@clayster.com/client'
2404        id='35'>
2405       <getNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK' 
2406                        nodeId='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
2407                        isReadable='true' isControllable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
2408           <string id='id' name='Node ID' value='Node1'/>
2409           <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
2410           <string id='sn' name='Serial Number' value='123456'/>
2411           <string id='class' name='Node Class' value='Temperature'/>
2412           <string id='meterLoc' name='Meter Location' value='P123502-2'/>
2413           <int id='addr' name='Address' value='123'/>
2414           <double id='lat' name='Latitude' value='12.345'/>
2415           <double id='long' name='Longitude' value='123.45'/>
2416           <message timestamp='2013-03-21T11:06:15' type='WarningUnsigned' 
2417                    eventId='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
2418       </getNodeResponse>
2419    </iq>]]>
2420                 </example>
2421             </section3>
2422         </section2>
2423         <section2 topic='Creating and Destroying Nodes'>
2424             <section3 topic='Get Addable Node Types'>
2425                 <p>
2426                     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
2427                     that can be added to a given node. This is done using the <strong>getAddableNodeTypes</strong> command, as is shown in the following example:
2428                 </p>
2429                 <example caption='Get Addable Node Types'>
2430                     <![CDATA[
2431    <iq type='get'
2432        from='client@clayster.com/client'
2433        to='concentrator@clayster.com'
2434        id='36'>
2435       <getAddableNodeTypes xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
2436    </iq>
2437    
2438    <iq type='result'
2439        from='concentrator@clayster.com'
2440        to='client@clayster.com/client'
2441        id='36'>
2442       <getAddableNodeTypesResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2443           <nodeType type='Namespace.Apartment' name='Apartment'/>
2444           <nodeType type='Namespace.MeteringTopologyReference' name='Metering Topology Reference'/>
2445           <nodeType type='Namespace.Location' name='Service Location'/>
2446       </getAddableNodeTypesResponse>
2447    </iq>]]>
2448                 </example>
2449             </section3>
2450             <section3 topic='Get Parameters for New Node'>
2451                 <p>
2452                     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.
2453                     This is done using the <strong>getParametersForNewNode</strong> command, as is shown in the following example:
2454                 </p>
2455                 <example caption='Get Parameters for New Node'>
2456                     <![CDATA[
2457    <iq type='get'
2458        from='client@clayster.com/client'
2459        to='concentrator@clayster.com'
2460        id='37'>
2461       <getParametersForNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' 
2462                                type='Namespace.MeteringTopologyReference' xml:lang='en'/>
2463    </iq>
2464    
2465    <iq type='result'
2466        from='concentrator@clayster.com'
2467        to='client@clayster.com/client'
2468        id='37'>
2469       <getParametersForNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2470           <x type='form' 
2471              xmlns='jabber:x:data' 
2472              xmlns:xdv='http://jabber.org/protocol/xdata-validate'
2473              xmlns:xdl='http://jabber.org/protocol/xdata-layout'
2474              xmlns:xdd='urn:xmpp:xdata:dynamic'>
2475               <title>Metering Topology</title>
2476               <xdl:page label='Identity'>
2477                   <xdl:fieldref var='id'/>
2478                   <xdl:fieldref var='referenceId'/>
2479               </xdl:page>
2480               <field var='xdd session' type='hidden'>
2481                   <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
2482               </field>
2483               <field var='id' type='text-single' label='Node ID:'>
2484                   <desc>ID of the node.</desc>
2485                   <required/>
2486                   <value/>
2487               </field>
2488               <field var='referenceId' type='text-single' label='Metering Node ID:'>
2489                   <desc>ID of the node in the metering topology.</desc>
2490                   <required/>
2491                   <value/>
2492               </field>
2493           </x>
2494       </getParametersForNewNodeResponse>
2495    </iq>]]>
2496                 </example>
2497             </section3>
2498             <section3 topic='Create New Node'>
2499                 <p>
2500                     After editing the form, the client uses the <strong>createNewNode</strong> command to create the new node using the parameters provided in the form.
2501                 </p>
2502                 <example caption='Create New Node after editing'>
2503                     <![CDATA[
2504    <iq type='set'
2505        from='client@clayster.com/client'
2506        to='concentrator@clayster.com'
2507        id='38'>
2508       <createNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' 
2509                      type='Namespace.MeteringTopologyReference' xml:lang='en'>
2510           <x type='submit' xmlns='jabber:x:data'>
2511               <field var='xdd session' type='hidden'>
2512                   <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
2513               </field>
2514               <field var='id' type='text-single'>
2515                   <value>Reference to Node1</value>
2516               </field>
2517               <field var='referenceId' type='text-single'>
2518                   <value>Node1</value>
2519               </field>
2520           </x>
2521       </createNewNode>
2522    </iq>
2523    
2524    <iq type='result'
2525        from='concentrator@clayster.com'
2526        to='client@clayster.com/client'
2527        id='38'>
2528       <createNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='OK'>
2529           <node nodeId='Reference to Node1' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
2530                 isReadable='true' isControllable='true' hasCommands='true' parentId='B1'>
2531               <string id='id' name='Node ID' value='Reference to Node1'/>
2532               <string id='type' name='Node Type' value='Metering Topology Reference'/>
2533               <string id='referenceId' name='Reference ID' value='Node1'/>
2534           </node>
2535       </createNewNodeResponse>
2536    </iq>]]>
2537                 </example>
2538                 <p>
2539                     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
2540                     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
2541                     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
2542                     in the response in a <strong>node</strong> element.
2543                 </p>
2544             </section3>
2545             <section3 topic='Create New Node, Failure'>
2546                 <p>
2547                     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
2548                     about why, information which the client can use to inform the user (if any) of what went wrong.
2549                 </p>
2550                 <example caption='Create New Node, Failure'>
2551                     <![CDATA[
2552    <iq type='set'
2553        from='client@clayster.com/client'
2554        to='concentrator@clayster.com'
2555        id='39'>
2556       <createNewNode xmlns='urn:xmpp:iot:concentrators' sourceId='MeteringGroups' nodeId='B1' 
2557                      type='Namespace.MeteringTopologyReference' xml:lang='en'>
2558           <x type='submit' xmlns='jabber:x:data'>
2559               <field var='xdd session' type='hidden'>
2560                   <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
2561               </field>
2562               <field var='id' type='text-single'>
2563                   <value>Node2</value>
2564               </field>
2565               <field var='referenceId' type='text-single'>
2566                   <value>NodeX</value>
2567               </field>
2568           </x>
2569       </createNewNode>
2570    </iq>
2571    
2572    <iq type='error'
2573        from='concentrator@clayster.com'
2574        to='client@clayster.com/client'
2575        id='39'>
2576       <createNewNodeResponse xmlns='urn:xmpp:iot:concentrators' result='FormError'>
2577           <error var='id'>There already exists a node with this ID.</error>
2578           <error var='referenceId'>Referenced node was not found.</error>