Following is an example of a control command sent using a message stanza:

Note that any response is supressed when sending a message stanza, regardless if the desired control command could be executed or not. The following example shows how the same control command could be issued using an IQ stanza instead:

Following is an example of a control command sent using an iq stanza:

Note: An empty setResponse element means that the control command was executed as provided in the request. Sometimes, the device can restrict the command to a subset of nodes and/or parameters. In such cases, the setResponse element will contain what nodes and/or parameters were finally used to perform the command. For examples of this, see &xep0324;.

In the following use cases, often a message stanza will be used to illustrate the point. However, the same operation could equally well be used using an iq stanza instead.

By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed. Following is an example of a control command sent using an iq stanza, where the receiver reports an error back to the caller:

Here, the paramError element is used in the IQ Error response, to provide error information related to a specific control parameter.

Setting single boolean-valued control parameters is a common use case, for instance when controlling digital outputs. The following example shows how a boolean value can be set in a device.

Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. The following example shows how a 32-bit integer value can be set in a device.

Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. Even though 32-bit integers may cover most control needs, it might in some cases be limiting. Therefore, a 64-bit control parameters can be created. The following example shows how a 64-bit integer value can be set in a device.

Setting single string-valued control parameters is a common use case, for instance when controlling text displays. The following example shows how a string value can be set in a device.

Setting single double-valued control parameters can be an alternative form of controlling analog outputs for instance. The following example shows how a double value can be set in a device.

Setting date-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. The following example shows how a date value can be set in a device.

Setting time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. The following example shows how a time value can be set in a device.

Setting date & time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. The following example shows how a date & time value can be set in a device.

Setting duration-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. The following example shows how a duration value can be set in a device.

Setting single color values in a device can occur in instances where color or lighting is important. Sometimes color is set using enumerations (string-valued or integer-valued parameters), and sometimes as a color property. The following example shows how a color value can be set in a device.

Often, setting a single control parameter is not sufficient for a control action. In these cases, setting multiple control parameters at once is necessary. The set command makes this easy however, since it allows for any number of control parameters to be set at once, as the following example shows:

Sometimes the order of control parameters are important in the device, and sometimes the parameters form part of a whole. It depends on the context of the device. In the above example, the order is important. When the OutputPercent control parameter is set, it will start to fade in or out to the desired setting (10%), using the fade time set previously. If the FadeTimeMilliseconds control parameter would have been set after the OutputPercent parameter, the fading would have been started using the previous setting, which might be unknown.

The order of control parameters to use depends on the device. The Control Form lists available control parameters of the device in the order they are expected to be sent to the device. The XEP xep-0000-IoT-Interoperability details what control parameters must be available for different interfaces, and if the order of control parameters is important.

A client can get a control form containing available control parameters of the device. This is done using the getForm command, as is shown in the following example:

IMPORTANT: The device MUST mark all control parameters in the form as notSame, as defined in XEP-0336: Dynamic Data Forms <http://xmpp.org/extensions/xep-0336.html> . If an end user would open the control form and press OK (submitting the form) without having entered a value, no value would be written, and no action taken. If only a few parameter would be edited, only those parameters would be sent to the device and only the corresponding actions taken.

All parameters in the form MUST also have validation rules defined according to XEP-0122, specifically validation data types and ranges where appropriate. This to give type information to the client, which the client later can use to send typed control commands directly, without the need to get and send data forms to the device to control it.

Also, the device SHOULD group control parameters that should be written together using pages and sections, as described in XEP-0141. Parameters MUST also be ordered in a way so that when set in that order using the typed commands, the corresponding control actions can be successfully executed.

Note: There's a difference between node parameters, as described in XEP-0326 Internet of Things - Concentrators, and control parameters as described in this document. For more information about this, please see Difference between node parameters and node control parameters.

A device can reject a control form request. It does this returning an error iq stanza, as is shown in the following example:

Control actions can be requested by submitting a full or partial control form back to the device. Control parameters not edited MUST not be included in the form, and the device in turn MUST ONLY invoke control actions corresponding to the parameters returned in the form.

The following example shows how control actions can be requested submitting a control parameters form to the device:

In this example, the FadeTimeMilliseconds and OutputPercent control parameters are sent, while the MainSwitch control parameter is left as is. Fading is therefore parformed only if the dimmer is switched on.

A device can reject a control form submission. It does this returning an error iq stanza. If there are errors in the form, details are listed using paramError elements in the response, as is shown in the following example:

To send a control message to a specific node behind a concentrator, the node element can be used to identify the node, as is shown in the following example:

The client can send the same control command to multiple nodes behind a concentrator by simply adding more node elements in the request, as is shown in the following example:

By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed. When sending a control command to multiple nodes at a time the device must validate all parameters against all nodes before taking any control action. If validation fails, an error message is returned and no control action is taken. The following example shows an example of an erroneous control message made to multiple nodes on a device:

A client can get a control form containing available control parameters common between a set of nodes controlled by the concentrator. This is done adding a sequence of node elements to a getForm command sent to the concentrator, as is shown in the following example:

Note that only parameters that are common between the nodes defined in the request must be returned. However, all parameters must have the notSame flag set, regardless of current output status.

A device can reject a control form request. It does this returning an error iq stanza. The following example shows the device rejecting a control form request, because it does not support the handling of common parameters between multiple nodes:

You set a control form to multiple nodes controlled by a concentrator by adding node elements to the set command sent to the concentrator, as is shown in the following example:

A device can reject a control form submission. It does this returning an error iq stanza. The following example shows the device rejecting a control form submission because one of the control parameters, even though it exists on all nodes, is not of the same type on all nodes.

The simplest way to read the current control states of a device, is to request the control form of the device. The control form should contain the current values for all avilable control parameters. However, since current states might not be available at the time of the request, the states might be delivered asynchronously, using messages defined in &xep0336;.

Using this method has the advantage that a small actuator device does not need to implement other XEPs to support readout of current control states. If the device contains all current states readily accessible, there's no need of asynchronous updates making readout simple and straightforward.

A second option is to use &xep0323; to deliver current control states. Since this XEP contains mechanisms allowing for asynchronous readout of control parameter states. This makes readout of such parameters simpler. However, there's a need to map values between the two XEPs.

If a client wants to know the current status of control parameters using this method, it performs a readout of Momentary and Status values from the device, and from the returned set of values take the current control parameter value according to the following rules, ordered by priority:

• 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.

• To simplify mapping, a writable attribute can be used to inform the client if a field name corresponds to a control parameter or not. If the attribute is available, it tells the client if it corresponds to a control parameter or not. If not available, no such deduction can be made.

Even though getting the the control form could provide the client with a quicker and easier way of retrieving control parameter values, the form is not guaranteed to contain correct current values, as described above.

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

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.

When representing control parameters as momentary field values, it is important to note the similarities and differences between XEP-0323 (Sensor Data) and XEP-0325 (this document):

The enum field value data type is not available in XEP-0325 (this document). Instead enumeration valued parameters are represented as string control parameters, while the control form explicitly lists available options for the parameter. Options are not available in XEP-0323, since it would not be practical to list all options every time the corresponding parameter was read out. Instead, the enum element contains a data type attribute, that can be used to identify the type of the enumeration.

The numeric field value data type is not available in XEP-0325 (this document). The reason is that a controller is not assumed to understand unit conversion. Any floating-point valued control parameters are represented by double control parameters, which lack a unit attribute. They are assumed to have the same unit as the corresponding numeric field value. On the other hand, floating point valued control parameters without units, are reported using the numeric field element, but leaving the unit blank.

Control pameters of type color have no corresponding field value data type. The color value must be represented in another way, and is implementation specific. Possibilities include representing the color as a string, using a specific pattern (for instance RRGGBBAA), or report it using multiple fields, one for each component for instance.

The boolean, date, dateTime, duration, int, long, string and time field value data types correspond to control parameters having the same types and same element names.