The following sub-sections illustrate how to set parameters of different types in a device.

Controlling devices behind a concentrator can be done by specifying what device(s) to control using node elements within the command elements sent to the concentrator. The following sub-sections show examples of how this is done.

If a client wants to know the current status of control parameters, it must perform a readout of Momentary and Status values from the device, according to XEP-xxxx: Sensor Data <sensor-data.html> , and from the returned set of values take the current control parameter value according to the following rules, ordered by priority:

• If there's a field marked as momentary value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of the control parameter.

• If there's a field marked as status value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of the control parameter.

Even though getting the the control form could provide the client with a quicker and easier way of retrieving control parameter values, the form is not guaranteed to contain correct current values. In some cases, retrieving current values might take time and only be retrieved using an asynchronous read-out process described in this section.

The following table shows how corresponding field values should be converted to the corresponding control parameter value based on field type (x-axis) and control parameter type (y-axis). N/A means conversion has no meaning and types are not compatible.

The following table lists notes with details on how to do conversion, if in doubt.

Note: the namespace prefix xs is here supposed to be linked with the XML Schema namespace http://www.w3.org/2001/XMLSchema.

A node defined in a concentrator, as defined by xep-0000-SN-Concentrators.html, supporting control has two sets of parameters that are different: First a set of node parameters and then a set of control parameters.

Node parameters are defined by the node type in the concentrator, as described in xep-0000-SN-Concentrators.html, and they are typically used by the concentrator to define the node and how to communicate or interact with the underlying device. The important part here is to know that the node parameters are maintained by the concentrator, not the underlying device.

Control parameters however, are parameters that reside on the underlying device. When set, they change the actual state or behaviour of the underlying device. The connection to the device however, controlled by the concentrator, remains unchanged by such a control parameter update.

Many control actions avilable in a device can be controlled using only one control parameter. If a device only publishes such control parameters, the order of control paramters is not that important.

However, there are many control actions that require the client to set multiple control parameters at the same time, for the device to have a complete understanding what the client wants to do.

XEP-0141 defines a way to group parameters in a data form by including the concept of pages and sections. Even though these pages and sections are used for layout purposes, it should be used by devices to mark parameters that should be used together to perform control actions.

The following set of rules should be adhered to, by devices as well as clients, to minimize confusion and resulting errors:

• Control parameters should be listed in control forms in the order the device expects the client to write them back.

• Clients should set control parameters in the order they are listed in the corresponding control forms.

• Control actions that require multiple control parameters should report these together, grouped by pages or sections within pages, to make clear that the parameters belong together.

• For control actions requiring multiple control parameters, devices should strive to publish default values for all parameters involved. These default values should then be used by the device if a client happens to write only a subset of the control parameters required for a control action. The default value could be the current state of the parameter.

Note however, that one cannot always make the assumption that parameters on the same page or same section in a control form belong to the same control action. For instance, a PLC with 16 digital outputs might publish a control form containing a single page with 16 check boxes on (boolean parameters), that can be controlled individually.

To solve the problem of grouping parameters together, so a client can know which parameters belong together, a new element is defined that can be used in data forms: parameterGroup. It is optional, but can be added to control parameters in forms, as a way to tell the client that parameters having the same parameterGroup belong together and should be written together. The following example illustrates this.

The above example informs the client that the two parameters HorizontalAngle and ElevationAngle should be written together to control a control action (named direction).

For more information about common control actions and their parameters, see xep-0000-SN-Interoperability.html, which defines a set of interoperable interfaces and their abilities.

Nodes behind a concentrator, as defined in xep-0000-SN-Concentrators.html, have an additional means of publishing control interfaces: Node Commands.

However, there are many differences between Node Commands and Control Parameters, as shown in the following list:

• Node Commands are defined by the node type in the concentrator, and not by the device itself.

• Node Commands may do many different things, not only performing control actions.

• Parametrized Node Commands require the client to always get a parameter data form, and write back values. There's no way to send simple control messages using Node Commands.

• Node Commands can be partitioned, grouped and sorted separately.

• Each Parametrized Node Command has a separate parameter form, which makes grouping of parameters normal.

• Node Commands are only available for nodes controlled by a concentrator.

If implementing a device with many complex control actions (like an advanced PLC), consideration should be made to divide the device into logical groups and implement the concentrators interface as well. Then the more complex control actions could be implemented as Node Commands instead of control actions as defined in this document, and implementing the simpler more intuitive control actions as described in this document.

If control interaction is performed in a context of delegated trust, as defined in the Sensor Network Provisioning XEP XEP-xxxx: Sensor Networks - Provisioning <sensor-network-provisioning.html> , tokens should always be included in all calls. This to allow devices to check privileges with provisioning servers.

The set and getForm commands support the following token attributes:

• serviceToken
• deviceToken
• userToken

For more information about provisioning, see sensor-network-provisioning.html.

Most examples in this document have been simplified examples where a few devices containing a few control parameters have been used. However, in many cases large subsystems with very many actuators containing many different control actions have to be controlled, as is documented in xep-0000-SN-Concentrators.html. In such cases, a node may have to be specified using two or perhaps even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to a specific kind of node, and the common nodeId. For more information about this, see xep-0000-SN-Concentrators.html.

Note: For cases where the nodeId is sufficient to uniquelly identify the node, it is sufficient to provide this attribute in the request. If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested.

All timestamps and dateTime values use the XML data type xs:dateTime to specify values. These values include a date, an optional time and an optional time zone.

Note: If time zone is not available, it is supposed to be undefined. The client reading the sensor that reports fields without time zone information should assume the sensor has the same time zone as the client, if not explicitly configured otherwise on the client side.

If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible.

Control commands sent using IQ stanzas instead of messages, should consider using the xml:lang attribute to specify the desired language used (if possible) when returning information back to the caller, like error messages, localized control forms, etc.

Consider to always use an encrypted connection with any XMPP Server used in the network. Also, make sure the server is properly authenticated and any server certificate properly validated.

Control commands should only be accepted by trusted parties. A minimum is to make sure only authenticated and validated clients (friends) can perform control actions on the device.

Consider using provisioning servers to allow for detailed control of who can do what in a sensor network. Implementing proper provisioning support decreases the risk for adverse effects, not only from intentional hacking, but also from unintentional errors.

If using delegated trust, make sure the provisioning servers are properly authenticated and validated before trusting them.

More information about provisioning can be found in sensor-network-provisioning.html.