XEP-xxxx: Sensor Networks - Concentrators

Abstract:This specification describes how to manage and get information from concentrators of devices over XMPP networks.
Author:Peter Waher
Copyright:© 1999 - 2013 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:ProtoXEP
Type:Standards Track
Version:0.0.1
Last Updated:2013-03-20

WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Table of Contents


1. Introduction
    1.1. Relations to other extensions
       1.1.1. XEP-0060
       1.1.2. XEP-0248
       1.1.3. XEP-0050
2. Glossary
3. Use Cases
    3.1. Capabilities
       3.1.1. Get Capabilities
    3.2. Data Sources
       3.2.1. Get All Data Sources
       3.2.2. Get Root Data Sources
       3.2.3. Get Child Data Sources
       3.2.4. Subscribe to data source changes
       3.2.5. Unsubscribe from data source events
       3.2.6. Get changes since given timestamp before subscribing
    3.3. Nodes
       3.3.1. Contains Node
       3.3.2. Contains Nodes
       3.3.3. Get Node
       3.3.4. Get Nodes
       3.3.5. Get Node with parameters
       3.3.6. Get Nodes with parameters
       3.3.7. Get All Nodes
       3.3.8. Get All Nodes with Parameters
       3.3.9. Get All Nodes derived from
       3.3.10. Get All Nodes derived from, with Parameters
       3.3.11. Get Node Inheritance
       3.3.12. Get Root Nodes
       3.3.13. Get Root Nodes with Parameters
       3.3.14. Get Child Nodes
       3.3.15. Get Child Nodes with Parameters
       3.3.16. Get Indices of Data Source
       3.3.17. Get Nodes from index
       3.3.18. Get Nodes from index with Parameters
       3.3.19. Get Nodes from indices
       3.3.20. Get Nodes from indices with Parameters
       3.3.21. Get All Index Values
       3.3.22. Get Node Ancestors
       3.3.23. Move Node Up
       3.3.24. Move Node Down
       3.3.25. Move Nodes Up
       3.3.26. Move Nodes Down
    3.4. Node Parameters
       3.4.1. Get Node Parameters for editing
       3.4.2. Set Node Parameters after editing
       3.4.3. Set Node Parameters after editing, Failure
       3.4.4. Get Common Node Parameters for editing
       3.4.5. Set Common Node Parameters after editing
       3.4.6. Set Common Node Parameters after editing, Failure
       3.4.7. Get Node Status
    3.5. Creating and Destroying Nodes
       3.5.1. Get Addable Node Types
       3.5.2. Get Parameters for New Node
       3.5.3. Create New Node
       3.5.4. Create New Node, Failure
       3.5.5. Destroy Node
       3.5.6. Destroy Node, Failure
    3.6. Node Commands
       3.6.1. Get Node Commands
       3.6.2. Execute Simple Node Command
       3.6.3. Get Node Command Parameters
       3.6.4. Execute Parameterized Node Command
       3.6.5. Execute Node Command, Failure
       3.6.6. Get Common Commands for Nodes
       3.6.7. Execute Simple Command on multiple nodes
       3.6.8. Get Common Command Parameters from command on multiple nodes
       3.6.9. Execute Common Parameterized Command on multiple nodes
       3.6.10. Execute Parameterized Command on Multiple Nodes, Failure
       3.6.11. Execute Command on Multiple Nodes, Partial Failure
    3.7. Data Source Events
       3.7.1. Node added event
       3.7.2. Node removed
       3.7.3. Node updated
       3.7.4. Node status changed
       3.7.5. Node moved up
       3.7.6. Node moved down
    3.8. Field Databases
       3.8.1. Get All Databases
       3.8.2. Get Database Readout Parameters
       3.8.3. Start Database Readout
       3.8.4. Start Database Readout, Failure
       3.8.5. Cancelling a database read-out
4. Implementation Notes
    4.1. Node Information
    4.2. Parameter Types
    4.3. Response Codes
    4.4. Unimplemented commands
    4.5. Command attributes
    4.6. Node States
    4.7. Required Data Sources
5. Internationalization Considerations
    5.1. Localization
    5.2. Time Zones
    5.3. Interoperability
6. Security Considerations
    6.1. Access rights
    6.2. Integration with provisioning servers
       6.2.1. Restricting access to data source per contact
       6.2.2. Restricting access to node properties per contact
       6.2.3. Restricting access to node commands per contact
7. IANA Considerations
8. XMPP Registrar Considerations
9. XML Schema
10. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

Concentrators are devices in sensor networks, concentrating the management of a sub set of devices to one point. They can be small (for example: PLC:s managing a small set of sensors and actuators), medium-sized (for example: mid-level concentrators, controlling branches of the network, islands, perhaps using separate communication protocols), large (for example: entire sub-systems, perhaps managed by a separate child/partner organization) to massive (for example: The entire top-level system, smart-grid, IoT network).

Even though this XEP is generally written and can be used by other implementations not based on sensor networks, much of the requirements used to define this specification comes from requirements used in sensor networks and Internet of Things applications and infrastructure.

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:

1.1 Relations to other extensions

Even though there are technologies available in forms of XEPs that solve parts of the above mentioned problem, they do not provide sufficient support. The following paragraphs will take the time to list why different technologies are not applicable.

1.1.1 XEP-0060

This XEP defines tree structures for nodes in different data sources. Publish-Subscribe [1] defines a model where a tree structure of nodes is published and users can browse this tree structure. Furthermore, it allows the possibility to publish items on these nodes as well as syndicalization of this information.

This XEP also defines data sources (in a tree structure). These data sources contain nodes. PubSub Collection Nodes [2] defines a structure called a node collection, a structure that allows the creation of collections containing loosely coupled nodes.

Even though this document defines tree structures of data, it is not however based on XEP-0060. There are multiple reasons for this:

1.1.2 XEP-0248

XEP-0248 defines the concept of node collections and syndicalization of information from nodes in these collections. But XEP-0248 is not used in this specification. There are multiple reasons:

1.1.3 XEP-0050

Ad-Hoc Commands [3] defines how ad-hoc commands can be implemented and how clients can use such commands to interact with underlying logic. But XEP-0050 is not used in this specification. There are multiple reasons:

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:

Table 1: Sensor Network XEPs

XEP Description
XEP-0000-ColorParameter Defines extensions for how color parameters can be handled, based on Data Forms [4]
XEP-0000-DynamicForms Defines extensions for how dynamic forms can be created, based on Data Forms [5], Data Forms Validation [6], Publishing Stream Initiation Requests [7] and Data Forms Layout [8].
exi Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered in all sensor network implementations where memory and packet size is an issue.
xep-0000-SN-BatteryPoweredSensors Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-Concentrators This specification. Defines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-Control Defines how to control actuators and other devices in sensor networks.
xep-0000-SN-Discovery 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.
xep-0000-SN-Events Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-Interoperability Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-Multicast Defines how sensor data can be multicast in efficient ways.
sensor-network-provisioning Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSub Defines how efficient publication of sensor data can be made in sensor networks.
sensor-data Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs.

2. Glossary

The following table lists common terms and corresponding descriptions.

Actuator
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
Computed Value
A value that is computed instead of measured.
Concentrator
Device managing a set of devices which it publishes on the XMPP network.
Data Source
A Data source contains a collection of nodes. Three types of data sources exist: Singular, Flat and Tree. Singular data sources only include one object. Flat data sources contain a list of objects and Tree data sources contain nodes formed as a tree graph with one root element.
Field
One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. Fields should be unique within the triple (Node ID, Field Name, Timestamp).
Field Name
Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
Field Type
What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
Historical Value
A value stored in memory from a previous timestamp.
Identification Value
A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
Localization information
Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.
Meter
A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
Momentary Value
A momentary value represents a value measured at the time of the read-out.
Node
Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gateways, etc., are often depicted as nodes and links between sensors (friendships) are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). Each Node has a Node ID. Nodes belong to a data source, and all nodes have a Node Type. Some nodes have a parent node, and some nodes have child nodes. Nodes with the same parent nodes a called sibling nodes.
Node ID
An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted ID scheme.
Node Type
Each node has a Node Type. The Node Type defines the functionality of the node in the system.
Parameter
Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters on nodes/devices. Fields are not parameters, and parameters are not fields.
Peak Value
A maximum or minimum value during a given period.
Precision
In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and delivering field information in sensor networks should always retain the number of decimals in a message.
Sensor
Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
SN
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.
Status Value
A value displaying status information about something.
Timestamp
Timestamp of value, when the value was sampled or recorded.
Token
A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate access rights with the provisioning server.
Unit
Physical unit of value. Example: MWh, l/s, etc.
Value
A field value.
Value Status
Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
Value Type
Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
WSN
Wireless Sensor Network, a sensor network including wireless devices.
XMPP Client
Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.

3. Use Cases

To create a complete set of operations supported by all types of concentrators, ranging from PLCs to subsystems to entire systems is very difficult. So, the aim of this document is instead to create a very small reduced set of operations, a common denominator, that would allow for basic maintenance and interoperability of concentrators of different makes and models and of these varying ranges.

3.1 Capabilities

3.1.1 Get Capabilities

This document lists a sequence of commands. Some are very basic, while others are used for managing massive amounts of devices. When developing a small PLC, it might be difficult to motivate the implementation of the more advanced commands. They are simply not necessary for the management of the device. So, clients connecting to the concentrator need a way to learn what operations are available in the concentrator, and as a consequence what operations are not. To do this, the getCapabilities command is sent, as is shown in the following example.

Example 1. Full capabilities

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='subsystem@clayster.com'
       id='1'>
      <getCapabilities xmlns='urn:xmpp:sn:concentrators'/>
   </iq>
   
   <iq type='result'
       from='subsystem@clayster.com'
       to='client@clayster.com/client'
       id='1'>
      <getCapabilitiesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>getCapabilities</value>
          <value>getAllDataSources</value>
          <value>getRootDataSources</value>
          <value>getChildDataSources</value>
          <value>containsNode</value>
          <value>containsNodes</value>
          <value>getNode</value>
          <value>getNodes</value>
          <value>getAllNodes</value>
          <value>getNodeInheritance</value>
          <value>getRootNodes</value>
          <value>getChildNodes</value>
          <value>getIndices</value>
          <value>getNodesFromIndex</value>
          <value>getNodesFromIndices</value>
          <value>getAllIndexValues</value>
          <value>getNodeParametersForEdit</value>
          <value>setNodeParametersAfterEdit</value>
          <value>getCommonNodeParametersForEdit</value>
          <value>setCommonNodeParametersAfterEdit</value>
          <value>getAddableNodeTypes</value>
          <value>getParametersForNewNode</value>
          <value>createNewNode</value>
          <value>destroyNode</value>
          <value>getAncestors</value>
          <value>getNodeCommands</value>
          <value>getCommandParameters</value>
          <value>executeNodeCommand</value>
          <value>getCommonNodeCommands</value>
          <value>getCommonCommandParameters</value>
          <value>executeCommonNodeCommand</value>
          <value>moveNodeUp</value>
          <value>moveNodeDown</value>
          <value>moveNodesUp</value>
          <value>moveNodesDown</value>
          <value>subscribe</value>
          <value>unsubscribe</value>
          <value>getDatabases</value>
          <value>getDatabaseReadoutParameters</value>
          <value>startDatabaseReadout</value>
      </getCapabilitiesResponse>
   </iq>
                

A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows:

Example 2. Full capabilities

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='subsystem@clayster.com'
       id='63'>
      <getCapabilities xmlns='urn:xmpp:sn:concentrators'/>
   </iq>
   
   <iq type='result'
       from='subsystem@clayster.com'
       to='client@clayster.com/client'
       id='63'>
      <getCapabilitiesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>getCapabilities</value>
          <value>getAllDataSources</value>
          <value>getRootDataSources</value>
          <value>getChildDataSources</value>
          <value>containsNode</value>
          <value>containsNodes</value>
          <value>getNode</value>
          <value>getNodes</value>
          <value>getAllNodes</value>
          <value>getNodeInheritance</value>
          <value>getRootNodes</value>
          <value>getChildNodes</value>
          <value>getIndices</value>
          <value>getNodesFromIndex</value>
          <value>getNodesFromIndices</value>
          <value>getAllIndexValues</value>
          <value>getNodeParametersForEdit</value>
          <value>setNodeParametersAfterEdit</value>
          <value>getCommonNodeParametersForEdit</value>
          <value>setCommonNodeParametersAfterEdit</value>
          <value>getAddableNodeTypes</value>
          <value>getParametersForNewNode</value>
          <value>createNewNode</value>
          <value>destroyNode</value>
          <value>getAncestors</value>
          <value>getNodeCommands</value>
          <value>getCommandParameters</value>
          <value>executeNodeCommand</value>
          <value>getCommonNodeCommands</value>
          <value>getCommonCommandParameters</value>
          <value>executeCommonNodeCommand</value>
          <value>moveNodeUp</value>
          <value>moveNodeDown</value>
          <value>moveNodesUp</value>
          <value>moveNodesDown</value>
          <value>subscribe</value>
          <value>unsubscribe</value>
      </getCapabilitiesResponse>
   </iq>
                

A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems:

Example 3. No batch command capabilities

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='gateway@clayster.com'
       id='2'>
      <getCapabilities xmlns='urn:xmpp:sn:concentrators'/>
   </iq>
   
   <iq type='result'
       from='gateway@clayster.com'
       to='client@clayster.com/client'
       id='2'>
      <getCapabilitiesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>getCapabilities</value>
          <value>getAllDataSources</value>
          <value>getRootDataSources</value>
          <value>getChildDataSources</value>
          <value>containsNode</value>
          <value>getNode</value>
          <value>getNodeInheritance</value>
          <value>getRootNodes</value>
          <value>getChildNodes</value>
          <value>getNodeParametersForEdit</value>
          <value>setNodeParametersAfterEdit</value>
          <value>getAddableNodeTypes</value>
          <value>getParametersForNewNode</value>
          <value>createNewNode</value>
          <value>destroyNode</value>
          <value>getAncestors</value>
          <value>getNodeCommands</value>
          <value>getCommandParameters</value>
          <value>executeNodeCommand</value>
          <value>moveNodeUp</value>
          <value>moveNodeDown</value>
          <value>moveNodesUp</value>
          <value>moveNodesDown</value>
          <value>subscribe</value>
          <value>unsubscribe</value>
      </getCapabilitiesResponse>
   </iq>
                

But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands:

Example 4. No edit capabilities

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='plc@clayster.com'
       id='3'>
      <getCapabilities xmlns='urn:xmpp:sn:concentrators'/>
   </iq>
   
   <iq type='result'
       from='plc@clayster.com'
       to='client@clayster.com/client'
       id='3'>
      <getCapabilitiesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>getCapabilities</value>
          <value>getAllDataSources</value>
          <value>containsNode</value>
          <value>getNode</value>
          <value>getRootNodes</value>
          <value>getChildNodes</value>
          <value>getNodeCommands</value>
          <value>getCommandParameters</value>
          <value>executeNodeCommand</value>
      </getCapabilitiesResponse>
   </iq>
                

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.

3.2 Data Sources

3.2.1 Get All Data Sources

This command will return a flat list of all available data sources on the concentrator. It is not structured hierarchically.

Example 5. Get All Data Sources

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='4'>
      <getAllDataSources xmlns='urn:xmpp:sn:concentrators' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='4'>
      <getAllDataSourcesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <dataSource id='Applications' name='Applications' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='Certificates' name='Certificates' hasChildren='false' lastChanged='2013-02-20T12:31:54'/>
          <dataSource id='Clayster.EventSink.Programmable' name='Programmable Event Log' hasChildren='false' lastChanged='2012-10-25T09:31:12'/>
          ...
      </getAllDataSourcesResponse>
   </iq>
                

3.2.2 Get Root Data Sources

If the client is interested in the hierarchical structure of available data sources, it should request only the root sources, and then ask the client for their corresponding child data sources. If the client wants to present the data sources to a user, presenting them in their hierarchical order may be more intuitive.

Example 6. Get Root Data Sources

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='5'>
      <getRootDataSources xmlns='urn:xmpp:sn:concentrators' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='5'>
      <getRootDataSourcesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <dataSource id='MeteringRoot' name='Metering' hasChildren='true' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='SecurityRoot' name='Security' hasChildren='true' lastChanged='2013-01-12T22:03:50'/>
          <dataSource id='SystemRoot' name='System' hasChildren='true' lastChanged='2012-02-20T12:34:56'/>
          ...
      </getRootDataSourcesResponse>
   </iq>
                

3.2.3 Get Child Data Sources

Having the ID of a data source that contains child data sources, you can fetch the child sources as follows:

Example 7. Get Child Data Sources

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='6'>
      <getChildDataSources xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringRoot' xml:lang='en' lastChanged='2013-03-19T17:58:01'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='6'>
      <getChildDataSourcesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <dataSource id='MeteringFieldImports' name='Field Imports' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringFieldProcessors' name='Field Processors' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringFieldSinks' name='Field Sinks' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringGroups' name='Groups' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringJobs' name='Jobs' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringTopology' name='Topology' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
          <dataSource id='MeteringUnitConversion' name='Unit Conversion' hasChildren='false' lastChanged='2013-03-19T17:58:01'/>
      </getChildDataSourcesResponse>
   </iq>
                

3.2.4 Subscribe to data source changes

A client can subscribe to changes made in a data source. It does this by sending the subscribe command to the concentrator, as is shown in the following example:

Example 8. Subscribing to data source events

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='57'>
      <subscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='57'>
      <subscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

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.

Important: Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription is removed.

Note: The parameters and messages attributes can be used to retrieve parameter and status message information about the nodes in event messages sent from the concentrator. Note that the xml:lang may be used to select the language used in such events, if the concentrator supports localization of strings.

Example 9. Subscribing to data source events with localized parameters

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='60'>
      <subscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' messages='true' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='60'>
      <subscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

The subscribe command has a set of optional attributes, one for each event type available, and with the same names, that the client can use to subscribe to individual events, but not to others. They have the default value of true implying that if not provided, the default action is to subscribe to those events.

The following example shows how a client can subscribe to a set of events only:

Example 10. Subscribing to data source events, avoiding state events

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='61'>
      <subscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
                 nodeAdded='true' nodeUpdated='true' nodeStatusChanged='false' nodeRemoved='true' nodeMovedUp='false' nodeMovedDown='false'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='61'>
      <subscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

For more information on types of events sent, see the Data Source Events section.

3.2.5 Unsubscribe from data source events

A client can unsubscribe to changes made in a data source it is subscribed to. It does this by sending the unsubscribe command to the concentrator, as is shown in the following example:

Example 11. Unsubscribing from data source events

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='58'>
      <unsubscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='58'>
      <unsubscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

An unsubscription made to an existing data source, but where an event subscription does not exist, must not result in an error.

The unsubscribe command has a set of optional attributes, one for each event type available, and with the same names, that the client can use to unsubscribe from individual events, but not from others. They have the default value of true implying that if not provided, the default action is to unsubscribe from those events.

The following example shows how a client can unsubscribe from a subset of events, keeping subscriptions on the others (if subscribed to):

Example 12. Unsubscribing from state events

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='62'>
      <unsubscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' messages='false' xml:lang='en'
                 nodeAdded='false' nodeUpdated='false' nodeStatusChanged='true' nodeRemoved='false' nodeMovedUp='false' nodeMovedDown='false'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='62'>
      <subscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

3.2.6 Get changes since given timestamp before subscribing

If a client comes back online and wants to know any changes that have taken place on the concentrator since last time it was in contact with it, it can include a getEventsSince attribute in the subscribe command sent to the concentrator. This will make the concentrator send all event messages since the given timestamp to the client before subscribing the client to events in the given data source.

Example 13. Get changes since given timestamp before subscribing

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='59'>
      <subscribe xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' getEventsSince='2013-03-21T19:24:00'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='59'>
      <subscribeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
   
   ... Sequence of event messages sent from concentrator to client.
                

Important: Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription is removed.

Note: The parameters and messages attributes can be used to retrieve parameter and status message information about the nodes in event messages sent from the concentrator.

For more information on types of events sent, see the Data Source Events section.

3.3 Nodes

3.3.1 Contains Node

This command permits the client to check the existence of a node in the concentrator.

Example 14. Checking the existence of a node

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='7'>
      <containsNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='7'>
      <containsNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>true</containsNodeResponse>
   </iq>
                

3.3.2 Contains Nodes

If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead:

Example 15. Checking the existence of a multiple nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='8'>
      <containsNodes xmlns='urn:xmpp:sn:concentrators'>
         <node sourceId='MeteringTopology' nodeId='Node1'/>
         <node sourceId='MeteringTopology' nodeId='Node2'/>
         <node sourceId='MeteringTopology' nodeId='Node3'/>
         <node sourceId='MeteringGroups' nodeId='Group1'/>
      </containsNodes>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='8'>
      <containsNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
         <value>true</value>
         <value>true</value>
         <value>false</value>
         <value>true</value>
      </containsNodesResponse>
   </iq>
                

The array returned will have one item for each item in the request, in the same order.

3.3.3 Get Node

This command returns basic information about a node in the concentrator.

Example 16. Get Node

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='9'>
      <getNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='9'>
      <getNodeResponse xmlns='urn:xmpp:sn:concentrators' 
                       result='OK'
                       id='Node1' 
                       nodeType='Namespace.NodeType1' 
                       cacheType='Node' 
                       state='WarningUnsigned' 
                       hasChildren='false'
                       isReadable='true' 
                       isConfigurable='true' 
                       hasCommands='true' 
                       parentId='Root' 
                       lastChanged='2013-03-19T17:58:01'/>
   </iq>
                

For more information, see Node Information.

3.3.4 Get Nodes

This commands lets the client get information from multiple nodes at once.

Example 17. Get Nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='10'>
      <getNodes xmlns='urn:xmpp:sn:concentrators'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
      </getNodes>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='10'>
      <getNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
      </getNodesResponse>
   </iq>
                

For more information, see Node Information.

3.3.5 Get Node with parameters

This command returns basic information about a node in the concentrator, as well as node parameters.

Example 18. Get Node with parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='11'>
      <getNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='11'>
      <getNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' 
                       hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <string id='id' name='Node ID' value='Node1'/>
          <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
          <string id='sn' name='Serial Number' value='123456'/>
          <string id='class' name='Node Class' value='Temperature'/>
          <string id='meterLoc' name='Meter Location' value='P123502-2'/>
          <int id='addr' name='Address' value='123'/>
          <double id='lat' name='Latitude' value='12.345'/>
          <double id='long' name='Longitude' value='123.45'/>
      </getNodeResponse>
   </iq>
                

For more information, see Node Information.

3.3.6 Get Nodes with parameters

This commands lets the client get information from multiple nodes at once, including node parameters.

Example 19. Get Nodes with parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='12'>
      <getNodes xmlns='urn:xmpp:sn:concentrators' parameters='true' xml:lang='true'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
      </getNodes>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='12'>
      <getNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='234567'/>
              <string id='class' name='Node Class' value='Pressure'/>
              <string id='meterLoc' name='Meter Location' value='P668632-6'/>
              <int id='addr' name='Address' value='124'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' isReadable='true' 
                isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
              <string id='sn' name='Serial Number' value='345678'/>
              <string id='class' name='Node Class' value='Electricity'/>
              <string id='meterLoc' name='Meter Location' value='P332367-9'/>
              <int id='addr' name='Address' value='125'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </getNodesResponse>
   </iq>
                

For more information, see Node Information.

3.3.7 Get All Nodes

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.

Example 20. Get All Nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='13'>
      <getAllNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='13'>
      <getAllNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
          <node id='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true'/>
      </getAllNodesResponse>
   </iq>
                

3.3.8 Get All Nodes with Parameters

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.

Example 21. Get All Nodes with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='14'>
      <getAllNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='14'>
      <getAllNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='234567'/>
              <string id='class' name='Node Class' value='Pressure'/>
              <string id='meterLoc' name='Meter Location' value='P668632-6'/>
              <int id='addr' name='Address' value='124'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
              <string id='sn' name='Serial Number' value='345678'/>
              <string id='class' name='Node Class' value='Electricity'/>
              <string id='meterLoc' name='Meter Location' value='P332367-9'/>
              <int id='addr' name='Address' value='125'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Root' nodeType='Namespace.Root' cacheType='Node' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true'>
              <string id='id' name='Node ID' value='Root'/>
              <string id='type' name='Node Type' value='Root Node'/>
          </node>
      </getAllNodesResponse>
   </iq>
                

3.3.9 Get All Nodes derived from

This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance.

Example 22. Get All Nodes derived from

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='15'>
      <getAllNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology'>
          <onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
      </getAllNodes>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='15'>
      <getAllNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
      </getAllNodesResponse>
   </iq>
                

3.3.10 Get All Nodes derived from, with Parameters

This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance. It also returns node parameters directly in the response.

Example 23. Get All Nodes derived from, with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='16'>
      <getAllNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'>
          <onlyIfDerivedFrom>Namespace.BaseClass1</onlyIfDerivedFrom>
      </getAllNodes>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='16'>
      <getAllNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
              <string id='sn' name='Serial Number' value='345678'/>
              <string id='class' name='Node Class' value='Electricity'/>
              <string id='meterLoc' name='Meter Location' value='P332367-9'/>
              <int id='addr' name='Address' value='125'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </getAllNodesResponse>
   </iq>
                

Note that the caller can list multiple classes in the request. This would return only nodes having the correct base class(es) and implementing all interfaces.

3.3.11 Get Node Inheritance

This command assumes node types exist in a class hierarchy. It allows the caller to get a list of the node class hierarchy and implemented interfaces the node has.

Example 24. Get node inheritance

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='17'>
      <getNodeInheritance xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='17'>
      <getNodeInheritanceResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <baseClasses>
              <value>Namespace.BaseClass1</value>
              <value>Namespace.AbstractBase</value>
          </baseClasses>
      </getNodeInheritanceResponse>
   </iq>
                

3.3.12 Get Root Nodes

This commands 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 source is flat).

Example 25. Get Root Nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='18'>
      <getRootNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' />
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='18'>
      <getRootNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
      </getRootNodesResponse>
   </iq>
                

3.3.13 Get Root Nodes with Parameters

This commands 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 source is flat), and also returns the parameters for the corresponding nodes.

Example 26. Get Root Nodes with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='19'>
      <getRootNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' parameters='true' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='19'>
      <getRootNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </getRootNodesResponse>
   </iq>
                

3.3.14 Get Child Nodes

This commands returns the child nodes of a node in a data source.

Example 27. Get Child Nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='20'>
      <getChildNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' />
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='20'>
      <getChildNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'/>
      </getChildNodesResponse>
   </iq>
                

3.3.15 Get Child Nodes with Parameters

This commands returns the child nodes of a node in a data source, and also returns the parameters for the corresponding nodes.

Example 28. Get Child Nodes with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='21'>
      <getChildNodes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' parameters='true' xml:lang='en' />
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='21'>
      <getChildNodesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='234567'/>
              <string id='class' name='Node Class' value='Pressure'/>
              <string id='meterLoc' name='Meter Location' value='P668632-6'/>
              <int id='addr' name='Address' value='124'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
              <string id='sn' name='Serial Number' value='345678'/>
              <string id='class' name='Node Class' value='Electricity'/>
              <string id='meterLoc' name='Meter Location' value='P332367-9'/>
              <int id='addr' name='Address' value='125'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </getChildNodesResponse>
   </iq>
                

3.3.16 Get Indices of Data Source

This command returns a list of available indices in a data source. Indices can be used for efficient node look-up.

Example 29. Get Child Nodes with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='22'>
      <getIndices xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' />
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='22'>
      <getIndicesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>country</value>
          <value>region</value>
          <value>city</value>
          <value>area</value>
          <value>street</value>
          <value>building</value>
          <value>apartment</value>
          <value>oid</value>
      </getIndicesResponse>
   </iq>
                

3.3.17 Get Nodes from index

This command can be used to get a node or nodes from a data source using an index and an index value.

Example 30. Get Nodes from index

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='23'>
      <getNodesFromIndex xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1' />
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='23'>
      <getNodesFromIndexResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-1'/>
      </getNodesFromIndexResponse>
   </iq>
                

3.3.18 Get Nodes from index with Parameters

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.

Example 31. Get Nodes from index with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='24'>
      <getNodesFromIndex xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' index='apartment' indexValue='A1-1' 
                         parameters='true' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='24'>
      <getNodesFromIndexResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-1'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Metering Topology Reference'/>
              <string id='referenceId' name='Reference ID' value='Node2'/>
          </node>
      </getNodesFromIndexResponse>
   </iq>
                

3.3.19 Get Nodes from indices

This command can be used to get nodes from a set of data source using indices and index values.

Example 32. Get Nodes from indices

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='25'>
      <getNodesFromIndices xmlns='urn:xmpp:sn:concentrators'>
          <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
          <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
      </getNodesFromIndices>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='25'>
      <getNodesFromIndicesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-1'/>
          <node id='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-2'/>
      </getNodesFromIndicesResponse>
   </iq>
                

3.3.20 Get Nodes from indices with Parameters

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.

Example 33. Get Nodes from indices with Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='26'>
      <getNodesFromIndices xmlns='urn:xmpp:sn:concentrators' parameters='true' xml:lang='en'>
          <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-1'/>
          <indexRef sourceId='MeteringGroups' index='apartment' indexValue='A1-2'/>
      </getNodesFromIndices>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='26'>
      <getNodesFromIndicesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-1'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Metering Topology Reference'/>
              <string id='referenceId' name='Reference ID' value='Node2'/>
          </node>
          <node id='Node3' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-2'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Metering Topology Reference'/>
              <string id='referenceId' name='Reference ID' value='Node3'/>
          </node>
      </getNodesFromIndicesResponse>
   </iq>
                

3.3.21 Get All Index Values

This command can be used to get a list of available index values, given a data source and an index.

Example 34. Get All Index Values

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='27'>
      <getAllIndexValues xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' index='apartment'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='27'>
      <getAllIndexValuesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <value>A1-1</value>
          <value>A1-2</value>
          ...
      </getAllIndexValuesResponse>
   </iq>
                

3.3.22 Get Node Ancestors

In a tree formed data source, all nodes except the root node has a parent node. The getAncestors command allows the client to get a list of all ancestors (parent, grand parent, etc.) of a node, as is shown in the following example:

Example 35. Get Node Ancestors

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='42'>
      <getAncestors xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Node2' parameters='false' messages='false' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='42'>
      <getAncestorsResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node2' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Apartment 1-1'/>
          <node id='Apartment 1-1' nodeType='Namespace.Apartment' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Building 1'/>
          <node id='Building 1' nodeType='Namespace.Building' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Street'/>
          <node id='Street' nodeType='Namespace.Street' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Area'/>
          <node id='Area' nodeType='Namespace.Area' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='City'/>
          <node id='City' nodeType='Namespace.City' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Region'/>
          <node id='Region' nodeType='Namespace.Region' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Country'/>
          <node id='Country' nodeType='Namespace.Country' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true' parentId='Root'/>
          <node id='Root' nodeType='Namespace.Root' state='None' hasChildren='true' 
                isReadable='false' isConfigurable='false' hasCommands='true'/>
      </getAncestorsResponse>
   </iq>
                

Note that the concentrator returns information about the node itself in the response. The parameters and messages attributes are used in the request to control if the concentrator should return node parameters and node status messages in the response as well.

3.3.23 Move Node Up

As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings. To move a node upwards among its siblings is done using the command moveNodeUp, as is shown in the following example:

Example 36. Move Node Up

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='53'>
      <moveNodeUp xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='53'>
      <moveNodeUpResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

Note that a node that is first among its siblings will maintain its position. The response to the command must still be OK.

3.3.24 Move Node Down

As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings. To move a node downwards among its siblings is done using the command moveNodeDown, as is shown in the following example:

Example 37. Move Node Up

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='54'>
      <moveNodeDown xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringFieldProcessors' nodeId='LogicalOperator'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='54'>
      <moveNodeDownResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

Note that a node that is last among its siblings will maintain its position. The response to the command must still be OK.

3.3.25 Move Nodes Up

To move a set of nodes upwards among its siblings is done using the command moveNodesUp, as is shown in the following example:

Example 38. Move Nodes Up

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='55'>
      <moveNodesUp xmlns='urn:xmpp:sn:concentrators'>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
      </moveNodesUp>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='55'>
      <moveNodesUpResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

Note that a node that is first among its siblings will maintain its position. The response to the command must still be OK. If an attempt is performed to move a sequence of nodes that are together first as siblings, none of the nodes move relative to each other.

3.3.26 Move Nodes Down

To move a set of nodes downwards among its siblings is done using the command moveNodesDown, as is shown in the following example:

Example 39. Move Node Up

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='56'>
      <moveNodesDown xmlns='urn:xmpp:sn:concentrators'>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator3'/>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator4'/>
          <node sourceId='MeteringFieldProcessors' nodeId='LogicalOperator5'/>
      </moveNodesDown>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='56'>
      <moveNodesDownResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

Note that a node that is last among its siblings will maintain its position. The response to the command must still be OK. If an attempt is performed to move a sequence of nodes that are together last as siblings, none of the nodes move relative to each other.

3.4 Node Parameters

3.4.1 Get Node Parameters for editing

Previously described commands can return parameters for a node. But these parameters are for presentational or informational use. If the client wants to edit the parameters of a node, another set of commands must be used. This use case shows how getNodeParametersForEdit can be used to edit available parameters for one node.

Note: When editing parameters for a node, a different set of parameters might be returned compared to the set of parameters available in commands mentioned above. There may be various reasons for this, among other things (but not limited to) user rights, node settings, and parameter type. User rights may restrict the number of parameters the user can access. The node may be configured not to allow editing of certain parameters. Also, some types of parameters may only be available in an edit mode (like long multi-line parameters) and not in a shorter presentation mode.

Example 40. Get Node Parameters for editing

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='28'>
      <getNodeParametersForEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='28'>
      <getNodeParametersForEditResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Node1</title>
              <xdl:page label='Identity'>
                  <xdl:fieldref var='id'/>
                  <xdl:fieldref var='type'/>
                  <xdl:fieldref var='class'/>
                  <xdl:fieldref var='sn'/>
              </xdl:page>
              <xdl:page label='Location'>
                  <xdl:fieldref var='meterLoc'/>
                  <xdl:fieldref var='lat'/>
                  <xdl:fieldref var='long'/>
              </xdl:page>
              <xdl:page label='Communication'>
                  <xdl:fieldref var='addr'/>
              </xdl:page>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='id' type='text-single' label='Node ID:'>
                  <desc>ID of the node.</desc>
                  <required/>
                  <value>Node1</value>
              </field>
              <field var='type' type='text-single' label='Node Type:'>
                  <desc>Type of node.</desc>
                  <value>Watchamacallit Temperature Sensor v1.2</value>
                  <xdd:readOnly/>
              </field>
              <field var='class' type='list-single' label='Node Class:'>
                  <desc>Class of node</desc>
                  <value>Temperature</value>
                  <option label='Cooling'><value>Cooling</value></option>
                  <option label='Electricity'><value>Electricity</value></option>
                  <option label='Heating'><value>Heating</value></option>
                  <option label='Pressure'><value>Pressure</value></option>
                  <option label='Temperature'><value>Temperature</value></option>
                  <option label='Water'><value>Water</value></option>
                  ...
              </field>
              <field var='sn' type='text-single' label='Serial Number:'>
                  <desc>Serial number of node/device.</desc>
                  <value>123456</value>
              </field>
              <field var='meterLoc' type='text-single' label='Meter Location:'>
                  <desc>Meter Location.</desc>
                  <value>P123502-2</value>
              </field>
              <field var='addr' type='text-single' label='Address:'>
                  <xdv:validate datatype='xs:int'>
                      <xdv:range min='1' max='250'/>
                  </xdv:validate>
                  <desc>Bus address</desc>
                  <value>123</value>
              </field>
              <field var='lat' type='text-single' label='Latitude:'>
                  <xdv:validate datatype='xs:double'>
                      <xdv:range min='-90' max='90'/>
                  </xdv:validate>
                  <desc>Latitude of node.</desc>
                  <value>12.345</value>
              </field>
              <field var='long' type='text-single' label='Longitude:'>
                  <xdv:validate datatype='xs:double'>
                      <xdv:range min='-180' max='180'/>
                  </xdv:validate>
                  <desc>Longitude of node.</desc>
                  <value>123.45</value>
              </field>
          </x>
      </getNodeParametersForEditResponse>
   </iq>
                

The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal:

Table 2: Form XEPs

XEP Description
XEP-0004 Describes how basic forms are handled.
XEP-0122 Makes it possible to add certain client validation rules to form parameters.
XEP-0137 Makes it possible to publish a file upload parameter.
XEP-0141 Makes it possible to layout parameters into pages and sections.
XEP-0000-ColorParameter Defines extensions for how color parameters can be handled.
xep-0000-DynamicForms Makes it possible to create dynamic forms, with server-side validation and forms that change dynamically depending on input.

Read-only parameters will be returned with the readOnly element, as defined in xep-0000-DynamicForms. Clients SHOULD support this extension if using this command. However, the server MUST NOT change parameters in a node that are read-only, even if clients happen to try to set them.

3.4.2 Set Node Parameters after editing

After editing the form, the client uses the setNodeParametersAfterEdit command to set the parameters in the node. Note that it is possible to set the same parameters (or a sub-set of the same parameters) to a different node using this command, without the need to get new form parameters. However, after the first successful set operation, any form session used for dynamic validation during edit will not be available on the server any more.

Example 41. Set Node Parameters after editing

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='29'>
      <setNodeParametersAfterEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='id' type='text-single'>
                  <value>Node1</value>
              </field>
              <field var='class' type='list-single'>
                  <value>Temperature</value>
              </field>
              <field var='sn' type='text-single'>
                  <value>123456</value>
              </field>
              <field var='meterLoc' type='text-single'>
                  <value>P123502-2</value>
              </field>
              <field var='addr' type='text-single'>
                  <value>123</value>
              </field>
              <field var='lat' type='text-single'>
                  <value>12.345</value>
              </field>
              <field var='long' type='text-single'>
                  <value>123.45</value>
              </field>
          </x>
      </setNodeParametersAfterEdit>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='29'>
      <setNodeParametersAfterEditResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </setNodeParametersAfterEditResponse>
   </iq>
                

Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources related to the form, which disables any future dynamic validation of the contents of the form. The newly edited node will also be available in the response in a node element.

3.4.3 Set Node Parameters after editing, Failure

The following example shows how the server responds when the client tries to set invalid parameters. The response contains detailed information about why, information which the client can use to inform the user (if any) of what went wrong.

Example 42. Set Node Parameters after editing, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='30'>
      <setNodeParametersAfterEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node2' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='id' type='text-single'>
                  <value>Node1</value>
              </field>
              <field var='class' type='list-single'>
                  <value>Temperature</value>
              </field>
              <field var='sn' type='text-single'>
                  <value>123456</value>
              </field>
              <field var='meterLoc' type='text-single'>
                  <value>P123502-2</value>
              </field>
              <field var='addr' type='text-single'>
                  <value>123</value>
              </field>
              <field var='lat' type='text-single'>
                  <value>12.345</value>
              </field>
              <field var='long' type='text-single'>
                  <value>123.45</value>
              </field>
          </x>
      </setNodeParametersAfterEdit>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='30'>
      <setNodeParametersAfterEditResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='id'>There already exists a node with this ID.</error>
      </setNodeParametersAfterEditResponse>
   </iq>
                

As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms [9] for more information.

3.4.4 Get Common Node Parameters for editing

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 getCommonNodeParametersForEdit command. It will return a form with parameters that are common for all selected nodes. Since nodes may have different node types it is assumed that different nodes have different sets of parameters. But if this command is used, only parameters matching in IDs, descriptions, validation rules, etc., (but not values) will be returned in a form.

Important: A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the notSame element, according to xep-0000-DynamicForms. Clients using this command MUST support the extensions defined in xep-0000-DynamicForms.

Example 43. Get Common Node Parameters for editing

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='31'>
      <getCommonNodeParametersForEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' xml:lang='en'>
         <node sourceId='MeteringTopology' nodeId='Node1'/>
         <node sourceId='MeteringTopology' nodeId='Node2'/>
         <node sourceId='MeteringTopology' nodeId='Node3'/>
      </getCommonNodeParametersForEdit>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='31'>
      <getCommonNodeParametersForEditResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Node1, Node2, Node3</title>
              <xdl:page label='Identity'>
                  <xdl:fieldref var='type'/>
                  <xdl:fieldref var='class'/>
                  <xdl:fieldref var='sn'/>
              </xdl:page>
              <xdl:page label='Location'>
                  <xdl:fieldref var='meterLoc'/>
                  <xdl:fieldref var='lat'/>
                  <xdl:fieldref var='long'/>
              </xdl:page>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='type' type='text-single' label='Node Type:'>
                  <desc>Type of node.</desc>
                  <value>Watchamacallit Temperature Sensor v1.2</value>
                  <xdd:readOnly/>
                  <xdd:notSame/>
              </field>
              <field var='class' type='list-single' label='Node Class:'>
                  <desc>Class of node</desc>
                  <value>Temperature</value>
                  <xdd:notSame/>
                  <option label='Cooling'><value>Cooling</value></option>
                  <option label='Electricity'><value>Electricity</value></option>
                  <option label='Heating'><value>Heating</value></option>
                  <option label='Pressure'><value>Pressure</value></option>
                  <option label='Temperature'><value>Temperature</value></option>
                  <option label='Water'><value>Water</value></option>
                  ...
              </field>
              <field var='sn' type='text-single' label='Serial Number:'>
                  <desc>Serial number of node/device.</desc>
                  <value>123456</value>
                  <xdd:notSame/>
              </field>
              <field var='meterLoc' type='text-single' label='Meter Location:'>
                  <desc>Meter Location.</desc>
                  <value>P123502-2</value>
                  <xdd:notSame/>
              </field>
              <field var='addr' type='text-single' label='Address:'>
                  <xdv:validate datatype='xs:int'>
                      <xdv:range min='1' max='250'/>
                  </xdv:validate>
                  <desc>Bus address</desc>
                  <value>123</value>
                  <xdd:notSame/>
              </field>
              <field var='lat' type='text-single' label='Latitude:'>
                  <xdv:validate datatype='xs:double'>
                      <xdv:range min='-90' max='90'/>
                  </xdv:validate>
                  <desc>Latitude of node.</desc>
                  <value>12.345</value>
                  <xdd:notSame/>
              </field>
              <field var='long' type='text-single' label='Longitude:'>
                  <xdv:validate datatype='xs:double'>
                      <xdv:range min='-180' max='180'/>
                  </xdv:validate>
                  <desc>Longitude of node.</desc>
                  <value>123.45</value>
                  <xdd:notSame/>
              </field>
          </x>
      </getCommonNodeParametersForEditResponse>
   </iq>
                

Note that parameters that are not available in all selected nodes will have been removed. Also and ID-parameter will have been removed, since they cannot be set for a collection of nodes.

Fields marked with the notSame element only present one value, perhaps the value of the first node. However, the field should be clearly marked in any end-user GUI (for example by graying the field), and MUST ONLY be sent back to the server in a set operation if explicitly edited by the end-user. The parameter will be set in all selected nodes in that case. Unedited fields should be treated as if the end-user accepts the different values for the current set of nodes.

3.4.5 Set Common Node Parameters after editing

After editing the form, the client uses the setCommonNodeParametersAfterEdit command to set the parameters in the set of nodes. Note that it is possible to set the same parameters (or a sub-set of the same parameters) to a different set of nodes using this command, without the need to get new form parameters. However, after the first successful set operation, any form session used for dynamic validation during edit will not be available on the server any more.

Example 44. Set Common Node Parameters after editing

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='32'>
      <setCommonNodeParametersAfterEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='class' type='list-single'>
                  <value>Temperature</value>
              </field>
          </x>
      </setCommonNodeParametersAfterEdit>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='32'>
      <setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <node id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node1'/>
              <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='123456'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P123502-2'/>
              <int id='addr' name='Address' value='123'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node2' nodeType='Namespace.NodeType2' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node2'/>
              <string id='type' name='Node Type' value='Watchamacallit Pressure Sensor v1.2'/>
              <string id='sn' name='Serial Number' value='234567'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P668632-6'/>
              <int id='addr' name='Address' value='124'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
          <node id='Node3' nodeType='Namespace.NodeType3' cacheType='Node' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root'>
              <string id='id' name='Node ID' value='Node3'/>
              <string id='type' name='Node Type' value='Watchamacallit Electricity Meter v1.2'/>
              <string id='sn' name='Serial Number' value='345678'/>
              <string id='class' name='Node Class' value='Temperature'/>
              <string id='meterLoc' name='Meter Location' value='P332367-9'/>
              <int id='addr' name='Address' value='125'/>
              <double id='lat' name='Latitude' value='12.345'/>
              <double id='long' name='Longitude' value='123.45'/>
          </node>
      </setCommonNodeParametersAfterEditResponse>
   </iq>
                

Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources related to the form, which disables any future dynamic validation of the contents of the form.

Important: A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the notSame element, according to xep-0000-DynamicForms. Such parameters MUST NOT be sent back to the server 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.

3.4.6 Set Common Node Parameters after editing, Failure

The following example shows how the server responds when the client tries to set invalid parameters to a set of nodes. The response contains detailed information about why, information which the client can use to inform the user (if any) of what went wrong.

Example 45. Set Node Parameters after editing, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='33'>
      <setCommonNodeParametersAfterEdit xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' xml:lang='en'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
              </field>
              <field var='id' type='text-single'>
                  <value>Node1</value>
              </field>
              <field var='class' type='list-single'>
                  <value>Temperature</value>
              </field>
          </x>
      </setCommonNodeParametersAfterEdit>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='33'>
      <setCommonNodeParametersAfterEditResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='id'>Parameter not available.</error>
      </setCommonNodeParametersAfterEditResponse>
   </iq>
                

As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms xep-0000-DynamicForms.html for more information.

3.4.7 Get Node Status

Each node in the concentrator has a state. This state is a dynamic run-time state, and therefore not presented as a more static property. This state can be any of the following values, in order of increasing importance:

Table 3: Node states

State Description
None Nothing has been reported on the node.
Information There are informative events reported on the node.
WarningSigned There are warnings reported on the node. But these warnings have been viewed by an operator.
WarningUnsigned There are new or unreviewed warnings reported on the node.
ErrorSigned There are errors reported on the node. But these errors have been viewed by an operator.
ErrorUnsigned There are new or unreviewed errors reported on the node.

Other types of "states" are of course possible, such as phase - installation phase, test phase, production phase, etc. - but such "states" are seen as static and presented as parameters on the node. The purpose of the dynamic state attribute of a node, is to give a dynamic runtime state that has the possibility to change during runtime, which operators must be aware of.

The following commands have an optional attribute messages, with which they can ask the server to return any events logged on the node, giving more details of the current state of the node:

Example 46. Get Node Status

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='34'>
      <getNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' messages='true' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='34'>
      <getNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK' 
                       id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false'
                       isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <message timestamp='2013-03-21T11:06:15' type='WarningUnsigned' id='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
      </getNodeResponse>                       
   </iq>
                

The messages attribute can be combined with the parameters attribute to provide both node parameters and messages in the response.

Example 47. Get Node with parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='35'>
      <getNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' nodeId='Node1' xml:lang='en' parameters='true' messages='true'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='35'>
      <getNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK' 
                       id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='WarningUnsigned' hasChildren='false' 
                       isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <string id='id' name='Node ID' value='Node1'/>
          <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
          <string id='sn' name='Serial Number' value='123456'/>
          <string id='class' name='Node Class' value='Temperature'/>
          <string id='meterLoc' name='Meter Location' value='P123502-2'/>
          <int id='addr' name='Address' value='123'/>
          <double id='lat' name='Latitude' value='12.345'/>
          <double id='long' name='Longitude' value='123.45'/>
          <message timestamp='2013-03-21T11:06:15' type='WarningUnsigned' id='ClockWarning'>Internal clock is offset more than 7 seconds.</message>
      </getNodeResponse>
   </iq>
                

3.5 Creating and Destroying Nodes

3.5.1 Get Addable Node Types

Since nodes are context sensitive, depending on node type and tree structure, before being able to create a new node, it is important to know what types of nodes that can be added to a given node. This is done using the getAddableNodeTypes command, as is shown in the following example:

Example 48. Get Addable Node Types

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='36'>
      <getAddableNodeTypes xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='36'>
      <getAddableNodeTypesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <nodeType type='Namespace.Apartment' name='Apartment'/>
          <nodeType type='Namespace.MeteringTopologyReference' name='Metering Topology Reference'/>
          <nodeType type='Namespace.Location' name='Service Location'/>
      </getAddableNodeTypesResponse>
   </iq>
                

3.5.2 Get Parameters for New Node

When you know what type of node you want to create, you need to get a set of parameters you need to fill in for the new node, before you can create it. This is done using the getParametersForNewNode command, as is shown in the following example:

Example 49. Get Parameters for New Node

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='37'>
      <getParametersForNewNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' type='Namespace.MeteringTopologyReference' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='37'>
      <getParametersForNewNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Metering Topology</title>
              <xdl:page label='Identity'>
                  <xdl:fieldref var='id'/>
                  <xdl:fieldref var='referenceId'/>
              </xdl:page>
              <field var='xdd session' type='hidden'>
                  <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
              </field>
              <field var='id' type='text-single' label='Node ID:'>
                  <desc>ID of the node.</desc>
                  <required/>
                  <value/>
              </field>
              <field var='referenceId' type='text-single' label='Metering Node ID:'>
                  <desc>ID of the node in the metering topology.</desc>
                  <required/>
                  <value/>
              </field>
          </x>
      </getParametersForNewNodeResponse>
   </iq>
                

3.5.3 Create New Node

After editing the form, the client uses the createNewNode command to create the new node using the parameters provided in the form.

Example 50. Create New Node after editing

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='38'>
      <createNewNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' type='Namespace.MeteringTopologyReference' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
              </field>
              <field var='id' type='text-single'>
                  <value>Reference to Node1</value>
              </field>
              <field var='referenceId' type='text-single'>
                  <value>Node1</value>
              </field>
          </x>
      </createNewNode>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='38'>
      <createNewNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <node id='Reference to Node1' nodeType='Namespace.MeteringTopologyReference' state='None' hasChildren='false' 
                isReadable='true' isConfigurable='true' hasCommands='true' parentId='B1'>
              <string id='id' name='Node ID' value='Reference to Node1'/>
              <string id='type' name='Node Type' value='Metering Topology Reference'/>
              <string id='referenceId' name='Reference ID' value='Node1'/>
          </node>
      </createNewNodeResponse>
   </iq>
                

Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources related to the form, which disables any future dynamic validation of the contents of the form. The newly created node with corresponding parameters is also returned in the response in a node element.

3.5.4 Create New Node, Failure

The following example shows how the server responds when it cannot accept parameters provided when trying to create a node. The response will contain detailed information about why, information which the client can use to inform the user (if any) of what went wrong.

Example 51. Create New Node, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='39'>
      <createNewNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' type='Namespace.MeteringTopologyReference' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D</value>
              </field>
              <field var='id' type='text-single'>
                  <value>Node2</value>
              </field>
              <field var='referenceId' type='text-single'>
                  <value>NodeX</value>
              </field>
          </x>
      </createNewNode>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='39'>
      <createNewNodeResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='id'>There already exists a node with this ID.</error>
          <error var='referenceId'>Referenced node was not found.</error>
      </createNewNodeResponse>
   </iq>
                

As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms xep-0000-DynamicForms.html for more information.

3.5.5 Destroy Node

To destroy (remove) a node from the concentrator, the destroyNode command is sent, as is shown in the following example:

Example 52. Destroy Node

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='40'>
      <destroyNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='40'>
      <destroyNodeResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

Since the result attribute in the response is OK, the node has been removed.

3.5.6 Destroy Node, Failure

If the result attribute in the response is other than OK, the node was not removed from the concentrator. The result attribute contains the reason why the operation failed, as is shown in the following example:

Example 53. Destroy Node, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='41'>
      <destroyNode xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='B1' xml:lang='en'/>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='41'>
      <destroyNodeResponse xmlns='urn:xmpp:sn:concentrators' result='InsufficientPrivileges'/>
   </iq>
                

3.6 Node Commands

3.6.1 Get Node Commands

Each node can have a context sensitive set of commands available to it. This is shown using the hasCommands attribute in the Node Information record describing the corresponding node. If the client wants to get a list of available commands, the getNodeCommands command is sent to the concentrator, as is shown in the following example:

Example 54. Get Node Commands

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='43'>
      <getNodeCommands xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='43'>
      <getNodeCommandsResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <command id='knockDoor' name='Knock on door' type='Simple' 
                   confirmationString='Are you sure you want to knock on the door?'
                   failureString='Unable to knock on the door.'
                   successString='Door knocked.'/>
          <command id='scheduleWakeupCall' name='Schedule wakeup call' type='Parameterized' 
                   failureString='Unable to schedule the wakeup call.'
                   successString='Wakeup call scheduled.'/>
      </getNodeCommandsResponse>
   </iq>
                

There are two types of commands available: Simple and Parameterized. Simple commands take no parameters, and are therefore simpler to execute. Parameterized commands require the client to get a set of parameters for the corresponding command before it can be executed. For more information about command attributes, see Node Commands.

3.6.2 Execute Simple Node Command

Executing a simple command is done by sending the executeNodeCommand command to the concentrator, as is shown in the following example:

Example 55. Execute Simple Node Command

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='44'>
      <executeNodeCommand xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='knockDoor'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='44'>
      <executeNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

3.6.3 Get Node Command Parameters

To execute a parameterized command on the node, the client first needs to get (and edit) a set of parameters for the command. Getting a set of parameters for a parameterized command is done as follows:

Example 56. Get Node Command Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='45'>
      <getCommandParameters xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='scheduleWakeupCall'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='45'>
      <getCommandParametersResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Schedule wake-up call</title>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single' label='Time:'>
                  <desc>Time of the wake-up call.</desc>
                  <required/>
                  <value></value>
                  <xdv:validate datatype='xs:time'/>
                      <xdv:basic/>
                  </xdv:validate>
              </field>
              <field var='mode' type='list-single' label='Wake-up mode:'>
                  <desc>Type of wake-up call</desc>
                  <value>Soft</value>
                  <option label='Soft'><value>Soft</value></option>
                  <option label='Normal'><value>Normal</value></option>
                  <option label='Harass'><value>Harass</value></option>
              </field>
          </x>
      </getCommandParametersResponse>
   </iq>
                

3.6.4 Execute Parameterized Node Command

Executing a parameterized command is also done by sending the executeNodeCommand command to the concentrator, but including the edited form parameters, as is shown in the following example:

Example 57. Execute Parameterized Node Command

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='46'>
      <executeNodeCommand xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='scheduleWakeupCall' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single'>
                  <value>04:30:00</value>
              </field>
              <field var='mode' type='list-single'>
                  <value>Harass</value>
              </field>
          </x>
      </executeNodeCommand>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='46'>
      <executeNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
                

3.6.5 Execute Node Command, Failure

If an error occurs during the execution of a command or if the server rejects the execution of a command, the server returns a response code different from OK. If the response code is FormError, the server maintains any parameter form resources related to the form, and features such as dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms xep-0000-DynamicForms.html for more information.

Example 58. Execute Node Command, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='47'>
      <executeNodeCommand xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringGroups' nodeId='Apartment 1-1' command='scheduleWakeupCall' xml:lang='en'>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single'>
                  <value>04:30:00</value>
              </field>
              <field var='mode' type='list-single'>
                  <value>Harass</value>
              </field>
          </x>
      </executeNodeCommand>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='47'>
      <executeNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='mode'>You are not allowed to harass people at 04:30:00!</error>
      </executeNodeCommandResponse>
   </iq>
                

3.6.6 Get Common Commands for Nodes

Using the command getCommonNodeCommands, the client can receive commands that are common for a set of nodes, as is shown in the following example:

Example 59. Get Common Commands for Nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='48'>
      <getCommonNodeCommands xmlns='urn:xmpp:sn:concentrators' xml:lang='en'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
      </getCommonNodeCommands>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='48'>
      <getNodeCommandsResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <command id='knockDoor' name='Knock on door' type='Simple' 
                   confirmationString='Are you sure you want to knock on the door?'
                   failureString='Unable to knock on the door.'
                   successString='Door knocked.'/>
          <command id='scheduleWakeupCall' name='Schedule wakeup call' type='Parameterized' 
                   failureString='Unable to schedule the wakeup call.'
                   successString='Wakeup call scheduled.'/>
      </getNodeCommandsResponse>
   </iq>
                

3.6.7 Execute Simple Command on multiple nodes

Executing a simple command on multiple nodes is done by sending the executeCommonNodeCommand command to the concentrator, as is shown in the following example:

Example 60. Execute Simple Command on multiple nodes

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='49'>
      <executeCommonNodeCommand xmlns='urn:xmpp:sn:concentrators' command='knockDoor'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
      </executeCommonNodeCommand>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='49'>
      <executeCommonNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
      </executeCommonNodeCommandResponse>
   </iq>
                

3.6.8 Get Common Command Parameters from command on multiple nodes

To execute a parameterized command on a set of nodes, the client first needs to get (and edit) a set of parameters for the common command. Getting a set of parameters for a common parameterized command is done as follows:

Example 61. Get Common Command Parameters from command on multiple nodes

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='50'>
      <getCommonCommandParameters xmlns='urn:xmpp:sn:concentrators' command='scheduleWakeupCall'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
      </getCommonCommandParameters>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='50'>
      <getCommonCommandParametersResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Schedule wake-up call</title>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single' label='Time:'>
                  <desc>Time of the wake-up call.</desc>
                  <required/>
                  <value></value>
                  <xdv:validate datatype='xs:time'/>
                      <xdv:basic/>
                  </xdv:validate>
              </field>
              <field var='mode' type='list-single' label='Wake-up mode:'>
                  <desc>Type of wake-up call</desc>
                  <value>Soft</value>
                  <option label='Soft'><value>Soft</value></option>
                  <option label='Normal'><value>Normal</value></option>
                  <option label='Harass'><value>Harass</value></option>
              </field>
          </x>
      </getCommandParametersResponse>
   </iq>
                

3.6.9 Execute Common Parameterized Command on multiple nodes

Executing a common parameterized command is also done by sending the executeCommonNodeCommand command to the concentrator, but including the edited form parameters, as is shown in the following example:

Example 62. Execute Common Parameterized Command on multiple nodes

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='51'>
      <executeCommonNodeCommand xmlns='urn:xmpp:sn:concentrators' command='scheduleWakeupCall' xml:lang='en'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single'>
                  <value>04:30:00</value>
              </field>
              <field var='mode' type='list-single'>
                  <value>Harass</value>
              </field>
          </x>
      </executeCommonNodeCommand>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='51'>
      <executeCommonNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
          <result>true</result>
      </executeCommonNodeCommandResponse>
   </iq>
                

3.6.10 Execute Parameterized Command on Multiple Nodes, Failure

If an error occurs during the execution of a common command or if the server rejects the execution of a common command, the server returns a response code different from OK. If the response code is FormError, the server maintains any parameter form resources related to the form, and features such as dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms xep-0000-DynamicForms.html for more information.

Example 63. Execute Parameterized Command on Multiple Nodes, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='52'>
      <executeCommonNodeCommand xmlns='urn:xmpp:sn:concentrators' command='scheduleWakeupCall' xml:lang='en'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single'>
                  <value>04:30:00</value>
              </field>
              <field var='mode' type='list-single'>
                  <value>Harass</value>
              </field>
          </x>
      </executeCommonNodeCommand>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='52'>
      <executeCommonNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='mode'>You are not allowed to harass people at 04:30:00!</error>
      </executeCommonNodeCommandResponse>
   </iq>
                

3.6.11 Execute Command on Multiple Nodes, Partial Failure

When executing a command, simple or parameterized, on multiple nodes, it might happen that the command fails on some nodes, but not on others, even though any parameters are validated beforehand. Therefore, the client needs to check any result elements in the response, even though the response code is OK.

The following example shows the execution of a parameterized command on multiple nodes that fail on some nodes but are executed on others.

Example 64. Execute Command on Multiple Nodes, Partial Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='72'>
      <executeCommonNodeCommand xmlns='urn:xmpp:sn:concentrators' command='scheduleWakeupCall' xml:lang='en'>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-1'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-2'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-3'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-4'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-5'/>
          <node sourceId='MeteringGroups' nodeId='Apartment 1-6'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>E14E330F-8496-46F0-8F40-178808AB13A7</value>
              </field>
              <field var='time' type='text-single'>
                  <value>04:30:00</value>
              </field>
              <field var='mode' type='list-single'>
                  <value>Harass</value>
              </field>
          </x>
      </executeCommonNodeCommand>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='72'>
      <executeCommonNodeCommandResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <result>true</result>
          <result>true</result>
          <result>false</result>
          <result>true</result>
          <result>false</result>
          <result>true</result>
      </executeCommonNodeCommandResponse>
   </iq>
                

3.7 Data Source Events

Events are asynchronous messages sent from the concentrator to devices registered with the concentrator and having subscribed to events from the concentrator. Event subscription can be activated using the subscribe command. You can also retrieve historical events using the subscribe command.

Each event is sent from the concentrator to each subscriber using a message stanza. Each such message stanza may contain multiple events. The following subsections list the different types of events that can be sent. Even though these examples may list only one element in a message stanza, this is not a limitation. Different types of events may also be mixed within the message stanza.

Event subscriptions only last for as long as the client and concentrator both maintains presence. The concentrator must not persist event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription is removed.

Node events may contain parameters or status messages. This depends on how the subscription was made. The parameters and messages attributes in the subscribe command determine if node parameters and/or status messages should be sent in event messages.

3.7.1 Node added event

The nodeAdded event is sent when a node has been added to a data source which the client subscribes to. The following example shows how such an event message may look like:

Example 65. Node added event, without parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeAdded xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
   </message>
                

Example 66. Node added event, with parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeAdded xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <string id='id' name='Node ID' value='Node1'/>
          <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
          <string id='sn' name='Serial Number' value='123456'/>
          <string id='class' name='Node Class' value='Temperature'/>
          <string id='meterLoc' name='Meter Location' value='P123502-2'/>
          <int id='addr' name='Address' value='123'/>
          <double id='lat' name='Latitude' value='12.345'/>
          <double id='long' name='Longitude' value='123.45'/>
      </nodeAdded>
   </message>
                

Note: Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first removing it from the current source (sending a nodeRemoved event) and then adding it to the new data source (sending a nodeAdded event), in that order.

3.7.2 Node removed

The nodeRemoved event is sent when a node in a data source has been removed or destroyed. It does not include status message or parameter information about the node, only the reference to the node. The following example shows how such an event message may look like:

Example 67. Node removed

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeRemoved xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1'/>
   </message>
                

Note: Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first removing it from the current source (sending a nodeRemoved event) and then adding it to the new data source (sending a nodeAdded event), in that order.

3.7.3 Node updated

The nodeUpdated event is sent when a node has been updated in a data source which the client subscribes to. The following example shows how such an event message may look like:

Example 68. Node updated event, without parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeUpdated xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
   </message>
                

Example 69. Node updated event, with parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeUpdated xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <string id='id' name='Node ID' value='Node1'/>
          <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
          <string id='sn' name='Serial Number' value='123456'/>
          <string id='class' name='Node Class' value='Temperature'/>
          <string id='meterLoc' name='Meter Location' value='P123502-2'/>
          <int id='addr' name='Address' value='123'/>
          <double id='lat' name='Latitude' value='12.345'/>
          <double id='long' name='Longitude' value='123.45'/>
      </nodeUpdated>
   </message>
                

The event has an optional attribute named oldId. It is set when the node has been renamed. It must be used, if available, to identify what node has been updated, as the following example shows:

Example 70. Node renamed event, without parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeUpdated xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' oldId='OldNode1' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'/>
   </message>
                

Example 71. Node renamed event, with parameters

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeUpdated xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' oldId='OldNode1' id='Node1' nodeType='Namespace.NodeType1' cacheType='Node' state='None' 
                 hasChildren='false' isReadable='true' isConfigurable='true' hasCommands='true' parentId='Root' lastChanged='2013-03-19T17:58:01'>
          <string id='id' name='Node ID' value='Node1'/>
          <string id='type' name='Node Type' value='Watchamacallit Temperature Sensor v1.2'/>
          <string id='sn' name='Serial Number' value='123456'/>
          <string id='class' name='Node Class' value='Temperature'/>
          <string id='meterLoc' name='Meter Location' value='P123502-2'/>
          <int id='addr' name='Address' value='123'/>
          <double id='lat' name='Latitude' value='12.345'/>
          <double id='long' name='Longitude' value='123.45'/>
      </nodeUpdated>
   </message>
                

Note: If only the status has changed, and no other parameters have changed, the nodeStatusChanged event could be sent instead, for somewhat improved performance in this case.

3.7.4 Node status changed

The nodeStatusChanged event is sent when the state of the node has changed, but no other parameters have been changed. If the client has subscribed to state messages, these will also be included in the event.

Example 72. Node status changed event, without messages

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeStatusChanged xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' cacheType='Node' state='ErrorUnsigned'/>
   </message>
                

Example 73. Node status changed event, with messages

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeStatusChanged xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1' cacheType='Node' state='ErrorUnsigned'>
          <message timestamp='2013-03-22T12:49:34' type='Error'>Sensor does not respond to read-out requests.</message>
      </nodeStatusChanged>
   </message>
                

3.7.5 Node moved up

The nodeMovedUp event is sent when a node in a data source has been moved up among its siblings. It does not include status message or parameter information about the node, only the reference to the node. The following example shows how such an event message may look like:

Example 74. Node moved up

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeMovedUp xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1'/>
   </message>
                

Note: If issuing a moveNodeUp command on a node that is already first among its siblings, the node is not moved and the concentrator must not send a nodeMovedUp event. However, if the client receives such an event pointing to a node that is already first among its siblings, it should not move the node.

3.7.6 Node moved down

The nodeMovedDown event is sent when a node in a data source has been moved down among its siblings. It does not include status message or parameter information about the node, only the reference to the node. The following example shows how such an event message may look like:

Example 75. Node moved down

                    
   <message from='concentrator@clayster.com'
            to='client@clayster.com/client'>
      <nodeMovedDown xmlns='urn:xmpp:sn:concentrators' sourceId='MeteringTopology' id='Node1'/>
   </message>
                

Note: If issuing a moveNodeDown command on a node that is already last among its siblings, the node is not moved and the concentrator must not send a nodeMovedDown event. However, if the client receives such an event pointing to a node that is already last among its siblings, it should not move the node.

3.8 Field Databases

A concentrator can often store data from sensors locally (or remotely but controlled locally). Storage is done in field databases. A concentrator with only communicative abilities will publish zero such field databases (and support for none of the field database commands), while a pure metering database will publish one or many field databases, but none of the nodes available in any of the different data sources are readable or writable. The nodes in this latter case only acts as placeholders for the data that the concentrator is storing or controlling.

The following subsections lists different use cases relating to field databases and how to use them.

3.8.1 Get All Databases

The client can retrieve the list of available databases on the concentrator using the getDatabases command, as is shown in the following example:

Example 76. Get All Databases

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='64'>
      <getDatabases xmlns='urn:xmpp:sn:concentrators' xml:lang='en'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='64'>
      <getDatabasesResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <database id='LocalDB' name='Local Database'/>
          <database id='LocalDBTest' name='Local Test Database'/>
          <database id='LocalDBProduction' name='Local Production Database'/>
          <database id='RemoteDB' name='Remote Database'/>
      </getDatabasesResponse>
   </iq>
                

3.8.2 Get Database Readout Parameters

Before reading data from a database can begin, a parameter form containing database specific search parameters needs to be fetched from the server. This is done using the getDatabaseReadoutParameters command, as is shown in the following example:

Example 77. Get Database Readout Parameters

                    
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='65'>
      <getDatabaseReadoutParameters xmlns='urn:xmpp:sn:concentrators' xml:lang='en' databaseId='LocalDB'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='65'>
      <getDatabaseReadoutParametersResponse xmlns='urn:xmpp:sn:concentrators' result='OK'>
          <x type='form' 
             xmlns='jabber:x:data' 
             xmlns:xdv='http://jabber.org/protocol/xdata-validate'
             xmlns:xdl:='http://jabber.org/protocol/xdata-layout'
             xmlns:xdd:='http://jabber.org/protocol/xdata-dynamic'>
              <title>Database read-out</title>
              <xdl:page label='Time'>
                  <xdl:fieldref var='from'/>
                  <xdl:fieldref var='to'/>
              </xdl:page>
              <xdl:page label='Fields'>
                  <xdl:fieldref var='fields'/>
              </xdl:page>
              <xdl:page label='Types'>
                  <xdl:fieldref var='momentary'/>
                  <xdl:fieldref var='peak'/>
                  <xdl:fieldref var='status'/>
                  <xdl:fieldref var='computed'/>
                  <xdl:fieldref var='identity'/>
                  <xdl:fieldref var='historySecond'/>
                  <xdl:fieldref var='historyMinute'/>
                  <xdl:fieldref var='historyHour'/>
                  <xdl:fieldref var='historyDay'/>
                  <xdl:fieldref var='historyWeek'/>
                  <xdl:fieldref var='historyMonth'/>
                  <xdl:fieldref var='historyQuarter'/>
                  <xdl:fieldref var='historyYear'/>
                  <xdl:fieldref var='historyOther'/>
              </xdl:page>
              <xdl:page label='Status'>
                  <xdl:fieldref var='missing'/>
                  <xdl:fieldref var='automaticEstimates'/>
                  <xdl:fieldref var='manualEstimates'/>
                  <xdl:fieldref var='manualReadout'/>
                  <xdl:fieldref var='automaticReadout'/>
                  <xdl:fieldref var='timeOffset'/>
                  <xdl:fieldref var='warning'/>
                  <xdl:fieldref var='error'/>
                  <xdl:fieldref var='signed'/>
                  <xdl:fieldref var='invoiced'/>
                  <xdl:fieldref var='invoicedConfirmed'/>
                  <xdl:fieldref var='endOfSeries'/>
                  <xdl:fieldref var='powerFailure'/>
                  <xdl:fieldref var='statusLogicMode'/>
              </xdl:page>
              <field var='xdd session' type='hidden'>
                  <value>C20D4F0C-8F8A-490F-8188-53017DF2B71A</value>
              </field>
              <field var='from' type='text-single' label='From:'>
                  <required/>
                  <xdv:validate datatype='xs:dateTime'>
                      <xdv:basic/>
                  </xdv:validate>
                  <desc>Read values not older that this timestamp.</desc>
                  <value></value>
              </field>
              <field var='to' type='text-single' label='To:'>
                  <required/>
                  <xdv:validate datatype='xs:dateTime'>
                      <xdv:basic/>
                  </xdv:validate>
                  <desc>Read values not newer that this timestamp.</desc>
                  <value></value>
              </field>
              <field var='fields' type='text-multi' label='Fields to include: (Use * as wildcards)'>
                  <desc>If specified, only the following fields (include wildcards) will be read out.</desc>
                  <value></value>
              </field>
              <field var='momentary' type='boolean' label='Momentary Values'>
                  <desc>If checked, momentary values will be read.</desc>
                  <value>false</value>
              </field>
              <field var='peak' type='boolean' label='Peak Values'>
                  <desc>If checked, peak values will be read.</desc>
                  <value>false</value>
              </field>
              <field var='status' type='boolean' label='Status Values'>
                  <desc>If checked, status values will be read.</desc>
                  <value>false</value>
              </field>
              <field var='computed' type='boolean' label='Computed Values'>
                  <desc>If checked, computed values will be read.</desc>
                  <value>false</value>
              </field>
              <field var='identity' type='boolean' label='Identity Values'>
                  <desc>If checked, identity values will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historySecond' type='boolean' label='Historical Values (second)'>
                  <desc>If checked, historical values (second) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyMinute' type='boolean' label='Historical Values (minute)'>
                  <desc>If checked, historical values (minute) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyHour' type='boolean' label='Historical Values (hour)'>
                  <desc>If checked, historical values (hour) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyDay' type='boolean' label='Historical Values (day)'>
                  <desc>If checked, historical values (day) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyWeek' type='boolean' label='Historical Values (week)'>
                  <desc>If checked, historical values (week) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyMonth' type='boolean' label='Historical Values (month)'>
                  <desc>If checked, historical values (month) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyQuarter' type='boolean' label='Historical Values (quarter)'>
                  <desc>If checked, historical values (quarter) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyYear' type='boolean' label='Historical Values (year)'>
                  <desc>If checked, historical values (year) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='historyOther' type='boolean' label='Historical Values (other)'>
                  <desc>If checked, historical values (other) will be read.</desc>
                  <value>false</value>
              </field>
              <field var='missing' type='list-single' label='Missing Values:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='automaticEstimates' type='list-single' label='Automatic Estimates:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='manualEstimates' type='list-single' label='Manual Estimates:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='manualReadout' type='list-single' label='Manual Readout:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='automaticReadout' type='list-single' label='Automatic Readout:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='timeOffset' type='list-single' label='Time Offset:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='warning' type='list-single' label='Warning:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='error' type='list-single' label='Error:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='signed' type='list-single' label='Signed:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='invoiced' type='list-single' label='Invoiced:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='invoicedConfirmed' type='list-single' label='Invoiced and Confirmed:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='endOfSeries' type='list-single' label='End of Series:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='powerFailure' type='list-single' label='Power Failure:'>
                  <desc>Determines how this flag should be treated during readout.</desc>
                  <value>Ignore</value>
                  <option label='Ignore'><value>Ignore this flag.</value></option>
                  <option label='Required'><value>Only read values with this flag set.</value></option>
                  <option label='Prohibit'><value>Only read values with this flag cleared.</value></option>
              </field>
              <field var='statusLogicMode' type='list-single' label='Combination Logic:'>
                  <desc>This parameter specifies how multiple status flags are to be treated in the readout.</desc>
                  <value>Any</value>
                  <option label='Any'><value>Any of the conditions above are met.</value></option>
                  <option label='All'><value>All of the conditions above are met.</value></option>
              </field>
          </x>
      </getDatabaseReadoutParametersResponse>
   </iq>
                

3.8.3 Start Database Readout

Once the parameter form has been filled out, a database readout can be started using the startDatabaseReadout command. Data read from the concentrator will follow the same flow of sensor data as that described in sensor-data [10]. The only difference is that the read-out is started with the startDatabaseReadout command instead of the req command of the sensor data namespace.

The following diagram shows the flow of messages when requesting a readout from a database:

The following example shows a startDatabaseReadout request:

Example 78. Start Database Readout

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='66'>
      <startDatabaseReadout xmlns='urn:xmpp:sn:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='1'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              <field var='xdd session' type='hidden'>
                  <value>C20D4F0C-8F8A-490F-8188-53017DF2B71A</value>
              </field>
              <field var='from' type='text-single'>
                  <value>2013-03-22T00:00:00</value>
              </field>
              <field var='to' type='text-single'>
                  <value>2013-03-23T00:00:00</value>
              </field>
              <field var='fields' type='text-multi'>
                  <value>Temperature</value>
                  <value>Pressure</value>
                  <value>Power</value>
              </field>
              <field var='momentary' type='boolean'>
                  <value>true</value>
              </field>
              <field var='peak' type='boolean'>
                  <value>false</value>
              </field>
              <field var='status' type='boolean'>
                  <value>false</value>
              </field>
              <field var='computed' type='boolean'>
                  <value>false</value>
              </field>
              <field var='identity' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historySecond' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyMinute' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyHour' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyDay' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyWeek' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyMonth' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyQuarter' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyYear' type='boolean'>
                  <value>false</value>
              </field>
              <field var='historyOther' type='boolean'>
                  <value>false</value>
              </field>
              <field var='missing' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='automaticEstimates' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='manualEstimates' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='manualReadout' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='automaticReadout' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='timeOffset' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='warning' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='error' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='signed' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='invoiced' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='invoicedConfirmed' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='endOfSeries' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='powerFailure' type='list-single'>
                  <value>Ignore</value>
              </field>
              <field var='statusLogicMode' type='list-single'>
                  <value>Any</value>
              </field>
          </x>
      </startDatabaseReadout>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='66'>
      <startDatabaseReadoutResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
   
   ... Readout messages follow.
                

3.8.4 Start Database Readout, Failure

The following example shows a response when the concentrator rejects the read-out request:

Example 79. Start Database Readout, Failure

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='67'>
      <startDatabaseReadout xmlns='urn:xmpp:sn:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='2' userToken='12392748927492834'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              ...
          </x>
      </startDatabaseReadout>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='67'>
      <startDatabaseReadoutResponse xmlns='urn:xmpp:sn:concentrators' result='InsufficientPrivileges'/>
   </iq>
                

The error might also be a result of invalid input parameters being sent:

Example 80. Start Database Readout, Failure 2

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='68'>
      <startDatabaseReadout xmlns='urn:xmpp:sn:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='3' userToken='12392748927492834'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              ...
              <field var='from' type='text-single'>
                  <value>2013-03-23T00:00:00</value>
              </field>
              <field var='to' type='text-single'>
                  <value>2013-03-22T00:00:00</value>
              </field>
              ...
          </x>
      </startDatabaseReadout>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='68'>
      <startDatabaseReadoutResponse xmlns='urn:xmpp:sn:concentrators' result='FormError'>
          <error var='to'>The To timestamp cannot be older than the From timestamp.</error>
      </startDatabaseReadoutResponse>
   </iq>
                

3.8.5 Cancelling a database read-out

A client can cancel a database read-out using the cancel read-out command, as described in sensor-data.

Example 81. Cancelling a database read-out

                    
   <iq type='set'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='70'>
      <startDatabaseReadout xmlns='urn:xmpp:sn:concentrators' xml:lang='en' databaseId='LocalDB' seqnr='4' userToken='12392748927492834'>
          <node sourceId='MeteringTopology' nodeId='Node1'/>
          <node sourceId='MeteringTopology' nodeId='Node2'/>
          <node sourceId='MeteringTopology' nodeId='Node3'/>
          <x type='submit' xmlns='jabber:x:data'>
              ...
          </x>
      </startDatabaseReadout>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='70'>
      <startDatabaseReadoutResponse xmlns='urn:xmpp:sn:concentrators' result='OK'/>
   </iq>
   
   ...
   
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='71'>
      <cancel xmlns='urn:xmpp:sn' seqnr='4'/>
   </iq>
   
   <iq type='result'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='71'>
      <cancelled xmlns='urn:xmpp:sn' seqnr='4'/>
   </iq>
                

4. Implementation Notes

4.1 Node Information

Several commands return basic node information. The following table lists possible fields with corresponding descriptions.

Table 4: Basic Node Information

Attribute Use Default Description
id required   The ID of the node in the data source.
displayName optional   If provided, a string presentable to users. If localization is supported and a correct language attribute was provided, this string will be localized.
nodeType optional   A string representing the type of the node.
localId optional   If provided, an ID for the node, but unique locally between siblings.
logId optional   If provided, an ID for the node, as it would appear or be used in system logs.
cacheType optional   Used to uniquely identify the node in sources where the ID of the node is not sufficient. Example: In a spatial ordering different nodes may represent countries, regions, cities, areas, streets, buildings and apartments in the same source. However, the ID of each node would depend on what type of node it represents. It might be valid to have a region, city and/or area with the same ID. So, to these circumstances, a Cache Type of Country, Region, City, Area, Street, Building and Apartment can be used to allow for non-unique IDs within the source, as long as they are unique within the same cache type. ***
state required   Current overall state of the node.
hasChildren required   If the node has children or not.
childrenOrdered optional false If the children of the node have an intrinsic order (true), or if the order is not important (false). If the order is not important, the client can present the order as it wishes, for example sorted on Node ID or any other parameter available on the child nodes. However, if the children have an intrinsic order, it's important for the client to refresh the child list when necessary whenever the order is unknown, such as after a nodeAdded event or a nodeRemoved event.
isReadable optional false If the node can be read. (*)
isConfigurable optional false If the node can be configured. (**)
hasCommands optional false If the node has registered commands or not.
parentId optional   The node ID of the parent node. If not available, the node is considered a root node.
parentCacheType optional   The Cache Type of the parent node.
lastChanged optional   When the node was last changed. Can be used by clients to synchronize content between the concentrator and itself.

(*) See sensor-data for more information about how to read nodes.

(**) See xep-0000-SN-Control for more information about how to configure nodes.

(***) Note that cacheType is optional. In some data sources it might be necessary to include a cache type to allow for IDs that are not unique within the source. In these cases, it concentrator must include the cacheType attribute for nodes in the corresponding data source, and clients must use the corresponding cacheType value when referencing the node. But if such a separation of IDs within a source is not required, the concentrator may ignore the cacheType attribute. In these instances clients may also ignore the cacheType attribute when referencing the nodes in the corresponding data source, or use the empty string as value for the cacheType value. The server must ignore empty cacheType values for data sources not using a cache type separation mechanism.

4.2 Parameter Types

Nodes can report parameters of different types. The following table lists available parameter types.

Table 5: Parameter Types

Element Name Parameter Value
boolean Boolean values. Can be true or false.
color Color values. They are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component.
dateTime Date and time value, with possible time zone information.
double double precision floating point value.
duration A time duration value.
int A 32-bit integer value.
long A 64-bit integer value.
string A string value.
time A time value using a 24-hour clock.

4.3 Response Codes

All responses have a response code that the client is required to check. The following table lists possible response codes and their corresponding meanings.

Table 6: Response Codes

Response Code Description
OK Request is OK and accepted.
NotFound Corresponding object, node, etc., was not found.
InsufficientPrivileges Insufficient privileges to perform the corresponding action or execute the corresponding command. Make sure to provide sufficient credentials in the call (user, service, device tokens) with sufficient privileges to perform the action/command.
Locked The object/node is locked, and operation could not be performed or completed.
NotImplemented Command is not implemented.
FormError The form send to the concentrator contains errors. The response contains detailed error information.
OtherError Another error occurred.

4.4 Unimplemented commands

It's important that the concentrator responds to unrecognized commands. This, to make sure future extensions to this document does not produce unexpected results in concentrators implementing a previous version, or in concentrators implementing only a subset of available commands.

When a concentrator receives an element that it does not understand, it must do as follows:

The following example shows how unrecognized commands must be handled by the concentrator:

Example 82. Unimplemented commands

                
   <iq type='get'
       from='client@clayster.com/client'
       to='concentrator@clayster.com'
       id='69'>
      <holabandola xmlns='urn:xmpp:sn:concentrators' ...>
          ...
      </holabandola>
   </iq>
   
   <iq type='error'
       from='concentrator@clayster.com'
       to='client@clayster.com/client'
       id='69'>
      <holabandolaResponse xmlns='urn:xmpp:sn:concentrators' result='NotImplemented'/>
   </iq>
            

4.5 Command attributes

Node commands have a set of attributes. The following table lists available attributes and what they mean.

Table 7: Command attributes

Attribute Use Description
id required ID of the command. Used to identify the command.
name required A string that can be presented to an end-user. Should be localized if the request contained a language preference.
type required If the command is 'Simple' or 'Parameterized'.
sortCategory optional Should be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and lastly by Name.
sortKey optional Should be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and lastly by Name.
confirmationString optional Should presented to clients (if available) before letting an end-user execute the command. A delete command might have a confirmationString saying 'Are you sure you want to delete the current item?' The confirmation string should be presented as a Yes/No[/Cancel] dialog.
failureString optional Could be presented to end-users (if available) if a command fails. It provides the client with an optionally localized string giving some context to the error message. A delete command might have a failureString saying 'Unable to delete the current item.'. The client could then add additional error information, if available, for instance from the response code.
successString optional Could be presented to end-users (if available) if a command is successfully executed. It provides the client with an optionally localized string giving some context to the message. A delete command might have a successString saying 'Current item successfully deleted.'.

4.6 Node States

Nodes can be in different states. Even though nodes are free to publish any amount of states as parameters, there are a set of states that are so crucial to the concept of a node state, that they are published using a separate attribute and separate events. These node states are as follows:

Table 8: Node States

State Description
None The node has nothing special to report.
Information The node has informative events reported on it.
WarningSigned The node has warnings reported on it. These warnings have been viewed by an operator.
WarningUnsigned The node has warnings reported on it that have not been viewed by anybody.
ErrorSigned The node has errors reported on it. These errors have been viewed by an operator.
ErrorUnsigned The node has errors reported on it that have not been viewed by anybody.

4.7 Required Data Sources

The following table lists required data sources for concentrators (of sensors, actuators, meters, etc.) in sensor networks:

Table 9: Required Data Sources

Data Source Description
MeteringTopology Data Source containing the topology of metering devices, including sensors, actuators, meter, infrastructure components, etc.

More information can be found in the [11].

5. Internationalization Considerations

5.1 Localization

Localization of content can be performed if clients provide xml:lang attributes in commands made to the concentrator. If omitted, the default language will be used in responses. If provided, but the concentrator does not support localization, or the requested language, the default language will also be used.

5.2 Time Zones

Concentrators of larger sub-systems spanning multiple time-zones should specify all timestamps with time-zone information, so readers can perform comparisons of time information.

Information read from a concentrator that lacks time-zone information should be considered to lie in the same time-zone as the reader, unless not explicitly configured with a time-zone.

5.3 Interoperability

For concentrators to be interoperable in sensor networks, they need to adhere to rules and guidelines described in the xep-0000-SN-Interoperability document.

6. Security Considerations

6.1 Access rights

This document publishes a lot of commands with which to interact with a concentrator. If security and access rights is an issue, it might not be sufficient to allow all friends access to the system. There are many ways in which to restrict access to the contents of the concentrator. Following are some examples:

6.2 Integration with provisioning servers

The sensor-network-provisioning document describes how trust can be delegated to trusted provisioning servers that can be used to restrict access to and privileges in a network.

If a concentrator has a trusted relationship with a provisioning server, external or internal, the provisioning server must be used to guarantee that the concetrator only allows access according to rules defiend by the provisioning server. In order to do this, it's important that clients always provide available tokens (userToken, serviceToken and deviceToken) to the concentrator so that it can forward this information to the provisioning server.

The following subsections show different examples of how such an integration can be performed.

6.2.1 Restricting access to data source per contact

This section shows how a provisioning server can be used to restrict access to data sources to users allowed to access those data sources.

Notice the following:

6.2.2 Restricting access to node properties per contact

This section shows how a provisioning server can be used to restrict access to node parameters that users allowed to access and edit.

6.2.3 Restricting access to node commands per contact

This section shows how a provisioning server can be used to restrict access to node commands to users allowed to access those commands.

In addition to rules noted above, also notice the following:

7. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [13].

8. XMPP Registrar Considerations

REQUIRED.

9. XML Schema

            
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:sn:concentrators'
    xmlns='urn:xmpp:sn:concentrators'
    xmlns:sn='urn:xmpp:sn'
    xmlns:xd="jabber:x:data"
    xmlns:xdv="http://jabber.org/protocol/xdata-validate"
    xmlns:xdl="http://jabber.org/protocol/xdata-layout"
    elementFormDefault='qualified'>
 
    <xs:import namespace='urn:xmpp:sn'/>
    <xs:import namespace='jabber:x:data'/>
    <xs:import namespace='http://jabber.org/protocol/xdata-validate'/>
    <xs:import namespace='http://jabber.org/protocol/xdata-layout'/>
 
    <xs:element name='getCapabilities' type='TokenRequest'/>
    <xs:element name='getCapabilitiesResponse' type='StringArrayResponse'/>
 
    <xs:element name='getAllDataSources' type='TokenRequest'/>
    <xs:element name='getAllDataSourcesResponse' type='DataSourceArrayResponse'/>
 
    <xs:element name='getRootDataSources' type='TokenRequest'/>
    <xs:element name='getRootDataSourcesResponse' type='DataSourceArrayResponse'/>
 
    <xs:element name='getChildDataSources' type='SourceReferenceRequest'/>
    <xs:element name='getChildDataSourcesResponse' type='DataSourceArrayResponse'/>
 
    <xs:element name='containsNode' type='NodeReferenceRequest'/>
    <xs:element name='containsNodeResponse'>
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base='xs:boolean'>
                    <xs:attributeGroup ref='responseCode'/>
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='containsNodes' type='NodeReferencesRequest'/>
    <xs:element name='containsNodesResponse' type='BooleanArrayResponse'/>
 
    <xs:element name='getNode' type='NodeReferenceParametersRequest'/>
    <xs:element name='getNodeResponse'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeInformation'>
                    <xs:attributeGroup ref='responseCode'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='getNodes' type='NodeReferenceParametersRequest'/>
    <xs:element name='getNodesResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getAllNodes' type='SourceReferenceParametersRequest'/>
    <xs:element name='getAllNodesResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getNodeInheritance' type='NodeReferenceRequest'/>
    <xs:element name='getNodeInheritanceResponse'>
        <xs:complexType>
            <xs:sequence>
                <xs:element name='baseClasses' type='StringArray' minOccurs='1' maxOccurs='1'/>
                <xs:element name='interfaces' type='StringArray' minOccurs='0' maxOccurs='1'/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='getRootNodes' type='SourceReferenceParametersRequest'/>
    <xs:element name='getRootNodesResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getChildNodes' type='NodeReferenceParametersRequest'/>
    <xs:element name='getChildNodesResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getIndices' type='SourceReferenceRequest'/>
    <xs:element name='getIndicesResponse' type='StringArrayResponse'/>
 
    <xs:element name='getNodesFromIndex' type='IndexReferenceRequest'/>
    <xs:element name='getNodesFromIndexResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getNodesFromIndices' type='IndexReferencesRequest'/>
    <xs:element name='getNodesFromIndicesResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getAllIndexValues'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='SourceReferenceRequest'>
                    <xs:attribute name='index' type='xs:string' use='required'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='getAllIndexValuesResponse' type='StringArrayResponse'/>
 
    <xs:element name='getNodeParametersForEdit' type='NodeReferenceRequest'/>
    <xs:element name='getNodeParametersForEditResponse' type='ParameterFormResponse'/>
 
    <xs:element name='setNodeParametersAfterEdit'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeReferenceRequest'>
                    <xs:sequence>
                        <xs:any minOccurs="1" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='setNodeParametersAfterEditResponse' type='SetNodeParametersResponse'/>
 
    <xs:element name='getCommonNodeParametersForEdit' type='NodeReferencesRequest'/>
    <xs:element name='getCommonNodeParametersForEditResponse' type='ParameterFormResponse'/>
 
    <xs:element name='setCommonNodeParametersAfterEdit'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeReferencesRequest'>
                    <xs:sequence>
                        <xs:any minOccurs="1" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='setCommonNodeParametersAfterEditResponse' type='SetNodeParametersResponse'/>
 
    <xs:element name='getAddableNodeTypes' type='NodeReferenceRequest'/>
    <xs:element name='getAddableNodeTypesResponse'>
        <xs:complexType>
            <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                <xs:element name='nodeType'>
                    <xs:complexType>
                        <xs:attribute name='type' type='xs:string' use='required'/>
                        <xs:attribute name='name' type='xs:string' use='required'/>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='getParametersForNewNode' type='NodeTypeReferenceRequest'/>
    <xs:element name='getParametersForNewNodeResponse' type='ParameterFormResponse'/>
 
    <xs:element name='createNewNode'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeTypeReferenceRequest'>
                    <xs:sequence>
                        <xs:any minOccurs="1" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='createNewNodeResponse' type='SetNodeParametersResponse'/>
 
    <xs:element name='destroyNode' type='NodeReferenceRequest'/>
    <xs:element name='destroyNodeResponse'>
        <xs:complexType>
            <xs:attributeGroup ref='responseCode'/>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='getAncestors' type='NodeReferenceParametersRequest'/>
    <xs:element name='getAncestorsResponse' type='NodeInformationArrayResponse'/>
 
    <xs:element name='getNodeCommands' type='NodeReferenceRequest'/>
    <xs:element name='getNodeCommandsResponse' type='CommandArray'/>
 
    <xs:element name='getCommandParameters' type='NodeCommandReferenceRequest'/>
    <xs:element name='getCommandParametersResponse' type='ParameterFormResponse'/>
 
    <xs:element name='executeNodeCommand'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeCommandReferenceRequest'>
                    <xs:sequence>
                        <xs:any minOccurs="0" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='executeNodeCommandResponse' type='ExecuteNodeCommandResponse'/>
 
    <xs:element name='getCommonNodeCommands' type='NodeReferencesRequest'/>
    <xs:element name='getCommonNodeCommandsResponse' type='CommandArray'/>
     
    <xs:element name='getCommonCommandParameters'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeReferencesRequest'>
                    <xs:attribute name='command' type='xs:string' use='required'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='getCommonCommandParametersResponse' type='ParameterFormResponse'/>
 
    <xs:element name='executeCommonNodeCommand'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeReferencesRequest'>
                    <xs:sequence>
                        <xs:any minOccurs="0" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='executeCommonNodeCommandResponse' type='ExecuteCommonNodeCommandResponse'/>
 
    <xs:element name='moveNodeUp' type='NodeReferenceRequest'/>
    <xs:element name='moveNodeUpResponse' type='Response'/>
 
    <xs:element name='moveNodeDown' type='NodeReferenceRequest'/>
    <xs:element name='moveNodeDownResponse' type='Response'/>
 
    <xs:element name='moveNodesUp' type='NodeReferencesRequest'/>
    <xs:element name='moveNodesUpResponse' type='Response'/>
 
    <xs:element name='moveNodesDown' type='NodeReferencesRequest'/>
    <xs:element name='moveNodesDownResponse' type='Response'/>
 
    <xs:element name='subscribe'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='SourceReferenceRequest'>
                    <xs:attribute name='getEventsSince' type='xs:dateTime' use='optional'/>
                    <xs:attributeGroup ref='parametersAndMessages'/>
                    <xs:attributeGroup ref='eventTypes'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='subscribeResponse' type='Response'/>
 
    <xs:element name='unsubscribe'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='SourceReferenceRequest'>
                    <xs:attributeGroup ref='eventTypes'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='unsubscribeResponse' type='Response'/>
 
    <xs:element name='nodeAdded' type='NodeSourceInformation'/>
    <xs:element name='nodeUpdated'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeSourceInformation'>
                    <xs:attribute name='oldId' type='xs:string' use='optional'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='nodeStatusChanged'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='NodeReference'>
                    <xs:choice minOccurs='0' maxOccurs='unbounded'>
                        <xs:element name='message' type='Message'/>
                    </xs:choice>
                    <xs:attribute name='state' type='NodeState' use='required'/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='nodeRemoved' type='NodeReference'/>
    <xs:element name='nodeMovedUp' type='NodeReference'/>
    <xs:element name='nodeMovedDown' type='NodeReference'/>
 
    <xs:element name='getDatabases' type='TokenRequest'/>
    <xs:element name='getDatabasesResponse'>
        <xs:complexType>
            <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                <xs:element name='database'>
                    <xs:complexType>
                        <xs:attribute name='id' type='xs:string' use='required'/>
                        <xs:attribute name='name' type='xs:string' use='optional'/>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
            <xs:attributeGroup ref='responseCode'/>
        </xs:complexType>
    </xs:element>
 
    <xs:element name='getDatabaseReadoutParameters' type='DatabaseReferenceRequest'/>
    <xs:element name='getDatabaseReadoutParametersResponse' type='ParameterFormResponse'/>
 
    <xs:element name='startDatabaseReadout'>
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base='DatabaseReferenceRequest'>
                    <xs:sequence>
                        <xs:element name='node' type='NodeReference' minOccurs='1' maxOccurs='unbounded'/>
                        <xs:any minOccurs="1" maxOccurs="1" namespace="jabber:x:data"/>
                    </xs:sequence>
                    <xs:attribute name="seqnr" type="xs:int" use="required"/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name='startDatabaseReadoutResponse' type='ExecuteNodeCommandResponse'/>
 
    <xs:simpleType name='ResponseCode'>
        <xs:restriction base='xs:string'>
            <xs:enumeration value='OK'/>
            <xs:enumeration value='NotFound'/>
            <xs:enumeration value='InsufficientPrivileges'/>
            <xs:enumeration value='Locked'/>
            <xs:enumeration value='NotImplemented'/>
            <xs:enumeration value='FormError'/>
            <xs:enumeration value='OtherError'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:simpleType name='Color'>
        <xs:restriction base='xs:string'>
            <xs:pattern value='^[0-9a-fA-F]{6}$'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:simpleType name='NodeState'>
        <xs:restriction base='xs:string'>
            <xs:enumeration value='None'/>
            <xs:enumeration value='Information'/>
            <xs:enumeration value='WarningSigned'/>
            <xs:enumeration value='WarningUnsigned'/>
            <xs:enumeration value='ErrorSigned'/>
            <xs:enumeration value='ErrorUnsigned'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:simpleType name='MessageType'>
        <xs:restriction base='xs:string'>
            <xs:enumeration value='Error'/>
            <xs:enumeration value='Warning'/>
            <xs:enumeration value='Information'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:simpleType name='CommandType'>
        <xs:restriction base='xs:string'>
            <xs:enumeration value='Simple'/>
            <xs:enumeration value='Parameterized'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:attributeGroup name='tokens'>
        <xs:attribute name='deviceToken' type='xs:string' use='optional'/>
        <xs:attribute name='serviceToken' type='xs:string' use='optional'/>
        <xs:attribute name='userToken' type='xs:string' use='optional'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='sourceReference'>
        <xs:attribute name='sourceId' type='xs:string' use='required'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='nodeReference'>
        <xs:attributeGroup ref='sourceReference'/>
        <xs:attribute name='nodeId' type='xs:string' use='required'/>
        <xs:attribute name='cacheType' type='xs:string' use='optional'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='parametersAndMessages'>
        <xs:attribute name='parameters' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='messages' type='xs:boolean' use='optional' default='false'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='indexReference'>
        <xs:attributeGroup ref='sourceReference'/>
        <xs:attribute name='index' type='xs:string' use='required'/>
        <xs:attribute name='indexValue' type='xs:string' use='required'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='responseCode'>
        <xs:attribute name='result' type='ResponseCode' use='required'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='eventTypes'>
        <xs:attribute name='nodeAdded' type='xs:boolean' use='optional' default='true'/>
        <xs:attribute name='nodeUpdated' type='xs:boolean' use='optional' default='true'/>
        <xs:attribute name='nodeStatusChanged' type='xs:boolean' use='optional' default='true'/>
        <xs:attribute name='nodeRemoved' type='xs:boolean' use='optional' default='true'/>
        <xs:attribute name='nodeMovedUp' type='xs:boolean' use='optional' default='true'/>
        <xs:attribute name='nodeMovedDown' type='xs:boolean' use='optional' default='true'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='databaseReference'>
        <xs:attribute name='databaseId' type='xs:string' use='required'/>
    </xs:attributeGroup>
 
    <xs:attributeGroup name='readoutReference'>
        <xs:attribute name='seqnr' type='xs:int' use='required'/>
    </xs:attributeGroup>
 
    <xs:complexType name='Response'>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
 
    <xs:complexType name='TokenRequest'>
        <xs:attributeGroup ref='tokens'/>
    </xs:complexType>
  
    <xs:complexType name='SourceReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:attributeGroup ref='sourceReference'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='DataSource'>
        <xs:attribute name='id' type='xs:string' use='required'/>
        <xs:attribute name='name' type='xs:string' use='required'/>
        <xs:attribute name='hasChildren' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='lastChanged' type='xs:dateTime' use='optional'/>
    </xs:complexType>
  
    <xs:complexType name='DataSourceArrayResponse'>
        <xs:sequence minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='dataSource' type='DataSource'/>
        </xs:sequence>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
  
    <xs:complexType name='NodeReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:attributeGroup ref='nodeReference'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='NodeReference'>
        <xs:attributeGroup ref='nodeReference'/>
    </xs:complexType>
  
    <xs:complexType name='NodeReferencesRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='node' type='NodeReference'/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='NodeReferenceParametersRequest'>
        <xs:complexContent>
            <xs:extension base='NodeReferenceRequest'>
                <xs:attributeGroup ref='parametersAndMessages'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='SourceReferenceParametersRequest'>
        <xs:complexContent>
            <xs:extension base='SourceReferenceRequest'>
                <xs:attributeGroup ref='parametersAndMessages'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='GetAllNodesRequest'>
        <xs:complexContent>
            <xs:extension base='SourceReferenceRequest'>
                <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='onlyIfDerivedFrom' type='xs:string'/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='GetChildNodesRequest'>
        <xs:complexContent>
            <xs:extension base='NodeReferenceRequest'>
                <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='sortOrder' type='SortOrder'/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='SortOrder'>
        <xs:attribute name='parameterName' type='xs:string' use='required'/>
        <xs:attribute name='ascending' type='xs:boolean' use='optional' default='true'/>
    </xs:complexType>
  
    <xs:complexType name='NodeInformation'>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='boolean' type='BooleanParameter'/>
            <xs:element name='color' type='ColorParameter'/>
            <xs:element name='dateTime' type='DateTimeParameter'/>
            <xs:element name='double' type='DoubleParameter'/>
            <xs:element name='duration' type='DurationParameter'/>
            <xs:element name='int' type='IntParameter'/>
            <xs:element name='long' type='LongParameter'/>
            <xs:element name='string' type='StringParameter'/>
            <xs:element name='time' type='TimeParameter'/>
            <xs:element name='message' type='Message'/>
        </xs:choice>
        <xs:attribute name='id' type='xs:string' use='required'/>
        <xs:attribute name='displayName' type='xs:string' use='optional'/>
        <xs:attribute name='nodeType' type='xs:string' use='optional'/>
        <xs:attribute name='localId' type='xs:string' use='optional'/>
        <xs:attribute name='logId' type='xs:string' use='optional'/>
        <xs:attribute name='cacheType' type='xs:string' use='optional'/>
        <xs:attribute name='state' type='NodeState' use='required'/>
        <xs:attribute name='hasChildren' type='xs:boolean' use='required'/>
        <xs:attribute name='childrenOrdered' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='isReadable' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='isConfigurable' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='hasCommands' type='xs:boolean' use='optional' default='false'/>
        <xs:attribute name='parentId' type='xs:string' use='optional'/>
        <xs:attribute name='parentCacheType' type='xs:string' use='optional'/>
        <xs:attribute name='lastChanged' type='xs:dateTime' use='optional'/>
    </xs:complexType>
 
    <xs:complexType name='NodeSourceInformation'>
        <xs:complexContent>
            <xs:extension base='NodeInformation'>
                <xs:attributeGroup ref='sourceReference'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='Parameter' abstract='true'>
        <xs:attribute name='id' type='xs:string' use='required'/>
        <xs:attribute name='name' type='xs:string' use='required'/>
    </xs:complexType>
  
    <xs:complexType name='BooleanParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:boolean' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='ColorParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='Color' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='DateTimeParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:dateTime' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='DoubleParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:double' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='DurationParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:duration' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='IntParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:int' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='LongParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:long' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='StringParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:string' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='TimeParameter'>
        <xs:complexContent>
            <xs:extension base='Parameter'>
                <xs:attribute name='value' type='xs:time' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='Message'>
        <xs:simpleContent>
            <xs:extension base='xs:string'>
                <xs:attribute name='timestamp' type='xs:dateTime' use='required'/>
                <xs:attribute name='type' type='MessageType' use='required'/>
                <xs:attribute name='id' type='xs:string' use='optional'/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
 
    <xs:complexType name='NodeInformationArrayResponse'>
        <xs:sequence minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='node' type='NodeInformation'/>
        </xs:sequence>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
 
    <xs:complexType name='StringArray'>
        <xs:sequence minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='value' type='xs:string'/>
        </xs:sequence>
    </xs:complexType>
 
    <xs:complexType name='StringArrayResponse'>
        <xs:complexContent>
            <xs:extension base='StringArray'>
                <xs:attributeGroup ref='responseCode'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='BooleanArrayResponse'>
        <xs:sequence minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='value' type='xs:boolean'/>
        </xs:sequence>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
  
    <xs:complexType name='IndexReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:attributeGroup ref='indexReference'/>
                <xs:attributeGroup ref='parametersAndMessages'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='IndexReference'>
        <xs:attributeGroup ref='indexReference'/>
    </xs:complexType>
  
    <xs:complexType name='IndexReferencesRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:sequence minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='indexRef' type='IndexReference'/>
                </xs:sequence>
                <xs:attributeGroup ref='parametersAndMessages'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='SetNodeParametersResponse'>
        <xs:choice minOccurs='1' maxOccurs='1'>
            <xs:element name='error' type='ParameterError' minOccurs='1' maxOccurs='unbounded'/>
            <xs:element name='node' type='NodeInformation' minOccurs='1' maxOccurs='unbounded'/>
        </xs:choice>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
 
    <xs:complexType name='ParameterFormResponse'>
        <xs:sequence>
            <xs:any minOccurs="1" maxOccurs="1" namespace="jabber:x:data"/>
        </xs:sequence>
        <xs:attributeGroup ref="responseCode"/>
    </xs:complexType>
  
    <xs:complexType name='NodeTypeReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='NodeReferenceRequest'>
                <xs:attribute name='type' type='xs:string' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  
    <xs:complexType name='Command'>
        <xs:attribute name='id' type='xs:string' use='required'/>
        <xs:attribute name='name' type='xs:string' use='required'/>
        <xs:attribute name='type' type='CommandType' use='required'/>
        <xs:attribute name='sortCategory' type='xs:string' use='optional'/>
        <xs:attribute name='sortKey' type='xs:string' use='optional'/>
        <xs:attribute name='confirmationString' type='xs:string' use='optional'/>
        <xs:attribute name='failureString' type='xs:string' use='optional'/>
        <xs:attribute name='successString' type='xs:string' use='optional'/>
    </xs:complexType>
  
    <xs:complexType name='CommandArray'>
        <xs:sequence minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='command' type='Command'/>
        </xs:sequence>
    </xs:complexType>
  
    <xs:complexType name='NodeCommandReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='NodeReferenceRequest'>
                <xs:attribute name='command' type='xs:string' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='ExecuteNodeCommandResponse'>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='error' type='ParameterError'/>
        </xs:choice>
        <xs:attributeGroup ref='responseCode'/>
    </xs:complexType>
 
    <xs:complexType name='ExecuteCommonNodeCommandResponse'>
        <xs:complexContent>
            <xs:extension base='ExecuteNodeCommandResponse'>
                <xs:choice minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='result' type='xs:boolean'/>
                </xs:choice>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='ParameterError'>
        <xs:simpleContent>
            <xs:extension base='xs:string'>
                <xs:attribute name='var' type='xs:string' use='required'/>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
 
    <xs:complexType name='ReadoutReference'>
        <xs:attributeGroup ref='databaseReference'/>
        <xs:attributeGroup ref='readoutReference'/>
    </xs:complexType>
 
    <xs:complexType name='DatabaseReferenceRequest'>
        <xs:complexContent>
            <xs:extension base='TokenRequest'>
                <xs:attributeGroup ref='databaseReference'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
</xs:schema>
        

10. Acknowledgements

Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.


Appendices


Appendix A: Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2013-03-20
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, XEP-0004, XEP-0030, XEP-0122, XEP-0137, XEP-0141, sensor-data, sensor-network-provisioning, xep-0000-DynamicForms, xep-0000-ColorParameter
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
This document in other formats: XML  PDF


Appendix B: Author Information

Peter Waher

Email: peter.waher@clayster.com
JabberID: peter.waher@jabber.org
URI: http://se.linkedin.com/pub/peter-waher/1a/71b/a29/


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Appendix G: Notes

1. XEP-0060: Publish-Subscribe <http://xmpp.org/extensions/xep-0060.html>.

2. XEP-0248: PubSub Collection Nodes <http://xmpp.org/extensions/xep-0248.html>.

3. XEP-0050: Ad-Hoc Commands <http://xmpp.org/extensions/xep-0050.html>.

4. XEP-0004: Data Forms <http://xmpp.org/extensions/xep-0004.html>.

5. XEP-0004: Data Forms <http://xmpp.org/extensions/xep-0004.html>.

6. XEP-0122: Data Forms Validation <http://xmpp.org/extensions/xep-0122.html>.

7. XEP-0137: Publishing Stream Initiation Requests <http://xmpp.org/extensions/xep-0137.html>.

8. XEP-0141: Data Forms Layout <http://xmpp.org/extensions/xep-0141.html>.

9. XEP-xxxx: Dynamic Data Forms <xep-0000-DynamicForms.html>

10. XEP-xxxx: Sensor Data sensor-data

11. XEP-xxxx: Interoperability Interoperability section

12. XEP-xxxx: Provisioning sensor-network-provisioning

13. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.0.1 (2013-03-20)

First draft.

(pwa)

END