From 81faba3b85ed705de51fa4a553fe84f20eb904a9 Mon Sep 17 00:00:00 2001 From: "Matthew A. Miller" Date: Mon, 7 Apr 2014 13:55:58 -0600 Subject: [PATCH] XEP-0325: < see revision history > --- xep-0325.xml | 1005 +++++++++++++++++++++++++++++--------------------- 1 file changed, 594 insertions(+), 411 deletions(-) diff --git a/xep-0325.xml b/xep-0325.xml index 7568a483..193d933d 100644 --- a/xep-0325.xml +++ b/xep-0325.xml @@ -1,5 +1,4 @@ - %ents; @@ -37,6 +36,66 @@ peter.waher@jabber.org http://www.linkedin.com/in/peterwaher + + 0.3 + 2014-04-07 + pw + +

Response codes have been removed and replaced by XMPP compliant IQ error stanzas. The table below shows how old status codes map to XMPP IQ error elements.

+

The getFormResponse element has been removed.

+

The setResponse is now only used when configuration is successful.

+

The parameter subelement to setResponse has been reintroduced. Examples are provided in XEP-0324.

+

The element paramError has been introduced, and can be used to provide error information that are linked to control parameters.

+

Added anchors to all second level subsections.

+

The section 'Reading current control states' has been updated to include two methods: One simple method only using control forms, and a second, using Sensor Data (XEP-0323).

+

Harmonization of data types between XEP-0323 and XEP-0325.

+

The attribute writable used to correlate fields in XEP-0323 with control parameters is described.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Obsolete CodeError TypeError ElementNamespaceDescription
InsufficientPrivilegescancelforbiddenurn:ietf:params:xml:ns:xmpp-stanzasIf the caller lacks privileges to perform the action.
NotFoundcancelitem-not-foundurn:ietf:params:xml:ns:xmpp-stanzasIf an item, parameter or data source could not be found.
OtherError, FormErrormodifybad-requesturn:ietf:params:xml:ns:xmpp-stanzasIf the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.
NotImplementedcancelfeature-not-implementedurn:ietf:params:xml:ns:xmpp-stanzasIf an action has not been implemented in the device.
Lockedwaitconflicturn:ietf:params:xml:ns:xmpp-stanzasIf an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time.
+ + 0.2 2014-03-10 @@ -312,7 +371,7 @@ an handles multiple nodes behind it, which node(s) to control is defined using node elements. If not a concentrator, the use of node elements is not necessary, and control commands are sent directly to the device itself.

- +

Following is an example of a control command sent using a message stanza: @@ -350,9 +409,14 @@ from='digital.output@clayster.com' to='master@clayster.com/amr' id='1'> - + ]]> +

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

@@ -377,14 +441,18 @@ from='analog.output@clayster.com' to='master@clayster.com/amr' id='2'> - - Invalid parameter type. - + + + Invalid parameter type. + ]]> +

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

- +

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

@@ -567,7 +635,7 @@

- +

A client can get a control form containing available control parameters of the device. This is done using the getForm command, @@ -586,44 +654,42 @@ from='dimmer@clayster.com' to='master@clayster.com/amr' id='3'> - - - Dimmer - - - - - - - 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 - - - Time in milliseconds used to fade the light to the desired level. - 300 - - - - - - - Dimmer output, in percent. - 100 - - - - - - - If the dimmer is turned on or off. - true - - - - + + Dimmer + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + Time in milliseconds used to fade the light to the desired level. + 300 + + + + + + + Dimmer output, in percent. + 100 + + + + + + + If the dimmer is turned on or off. + true + + + ]]>

@@ -653,8 +719,7 @@

- A device can reject a control form request. It does this returning an error iq stanza, and detailing the error in the result - attribute of the getFormResponse element, as is shown in the following example: + A device can reject a control form request. It does this returning an error iq stanza, as is shown in the following example:

- + + + Access denied. + ]]> @@ -706,7 +774,7 @@ from='dimmer@clayster.com' to='master@clayster.com/amr' id='5'> - + ]]>

@@ -716,9 +784,8 @@

- A device can reject a control form submission. It does this returning an error iq stanza, and detailing the error in the result - attribute of the setResponse element. If there are errors in the form, details are listed using error elements in the response, - as is shown in the following example: + 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:

- - Invalid parameter value. - + + + Invalid parameter value. + ]]> - +

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. @@ -822,9 +890,10 @@ from='concentrator@clayster.com' to='master@clayster.com/amr' id='7'> - - Invalid parameter type. - + + + Invalid parameter type. + ]]> @@ -833,7 +902,7 @@ 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:

- + - - - DigitalOutput1, DigitalOutput2, ... - - - - - 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 - - - If the digital output is high (checked) or low (uncheckd). - true - - - - + + DigitalOutput1, DigitalOutput2, ... + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + If the digital output is high (checked) or low (uncheckd). + true + + + ]]>

@@ -880,9 +947,8 @@

- A device can reject a control form request. It does this returning an error iq stanza, and detailing the error in the result - attribute of the getFormResponse element. The following example shows the device rejecting a control form request, because it does not support - the handling of common parameters between multiple nodes: + 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:

- + + + Cannot merge control forms from different nodes. + ]]> @@ -937,15 +1006,14 @@ from='concentrator@clayster.com' to='master@clayster.com/amr' id='10'> - + ]]>

- A device can reject a control form submission. It does this returning an error iq stanza, and detailing the error in the result - attribute of the setResponse element. 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. + 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.

- - - Invalid type - + + + Invalid type. + ]]> @@ -1015,250 +1084,390 @@

- -

- 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 &xep0323;, 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. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
numericstringbooleandateTimetimeSpanenum
boolean!=0N/AxN/AN/AN/A
colorN/ARRGGBB or RRGGBBAAN/AN/AN/AN/A
dateN/A(1)N/ADate partN/AN/A
dateTimeN/A(2)N/AxN/AN/A
doublex(3)Z2N/AN/AN/A
durationN/A(4)N/AN/AxN/A
intx(5)Z2N/AN/AN/A
longx(5)Z2N/AN/AN/A
string(6)xxs:booleanxs:dateTimexs:durationx
timeN/A(7)N/ATime part(8)N/A
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +

+ Depending on the reason for rejecting a control request, different XMPP errors can be returned, according to the description in the following table. The table also + lists recommended error type for each error. Error stanzas may also include paramError child elements to provide additional textual error information that + corresponds to a particular control parameter provided in the request. Any custom error message not related to control parameters is returned in a text + element. +

+
NoteDescription
(1) - The client should try to convert the string to a date value, first according to the format specified by the XML data type xs:date, and if not possible - by RFC 822. -
(2) - The client should try to convert the string to a date & time value, first according to the format specified by the XML data type xs:dateTime, and if not possible - by RFC 822. -
(3) - The client should try to convert the string to a double-precision floating-point value, first according to the format specified by the XML data type xs:double, - and if not possible using system-local string to floating-point conversion using local decimal and throusand separator settings. -
(4) - The client should try to convert the string to a duration value, first according to the format specified by the XML data type xs:duration, - and if not possible using the XML data type xs:time. -
(5)The client should try to convert the string to an integer value according to the corresponding XML data type formats xs:int and xs:long.
(6) - The numeric field value consists of three parts: Numeric value, number of decimals and optional unit. If no unit is provided, only the numeric value should - be converted to a string (compatible with the XML data type xs:double), using exactly the number of decimals provided in the field. If a unit is provided - (non-empty string) it must not be appended to the value, if the value is to be used for control output. For presentation purposes however, a space could be - appended to the number and the unit appended after the space. -
(7) - The client should try to convert the string to a time value according to the format specified by the XML data type xs:time. -
(8) - A timeSpan field value contains a xs:duration value. The xs:duration has a larger domain than xs:time, and contains all xs:time values, but xs:time does - not contain all possible xs:duration values. So, conversion of an xs:duration value to an xs:time value should be performed only if a duration lies - between 00:00:00 and 23:59:59. -
xUse the canonical conversion method.
Z2true = 1, false = 0.
N/ANot applicable. Conversion has no meaning. Value types are not compatible.
!=0Nonzero = true, Zero = false.
RRGGBBA string of six hexadecimal characters, the first two the red component of the color, the next two the green component and the last two the blue component.
- - + + + + - - - - - - - - - - - - - - - - - - - -
RRGGBBAAA string of eight hexadecimal characters, the first two the red component of the color, the next two the green component, the following two the blue component and the last two the alpha channel.Error TypeError ElementNamespaceDescription
Date partOnly the date part of the xs:dateTime value should be used.
Time partOnly the time part of the xs:dateTime value should be used.
xs:booleanConversion to a string should follow the rules specified for the XML datatype xs:boolean.
xs:dateTimeConversion to a string should follow the rules specified for the XML datatype xs:dateTime.
xs:durationConversion to a string should follow the rules specified for the XML datatype xs:duration.
-

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

- + cancel + forbidden + urn:ietf:params:xml:ns:xmpp-stanzas + If the caller lacks privileges to perform the action. + + + cancel + item-not-found + urn:ietf:params:xml:ns:xmpp-stanzas + If an item, parameter or data source could not be found. + + + modify + bad-request + urn:ietf:params:xml:ns:xmpp-stanzas + If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range. + + + cancel + feature-not-implemented + urn:ietf:params:xml:ns:xmpp-stanzas + If an action has not been implemented in the device. + + + wait + conflict + urn:ietf:params:xml:ns:xmpp-stanzas + If an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time. + + + + + +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
325 \ 323booleandatedateTimedurationenumintlongnumericstringtime
booleanx    !=0!=0!=0  
color        RRGGBB or RRGGBBAA 
date xDate part     (1) 
dateTime xx     (2) 
doubleZ2    xxx(3) 
duration   x    (4)x
intZ2   OrdinalxThunkThunk(5) 
longZ2   OrdinalxxThunk(5) 
stringxs:booleanxs:datexs:dateTimexs:durationxxs:intxs:long(6)xxs:time
time  Time part(7)    (8)x
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NoteDescription
(1) + The client should try to convert the string to a date value, first according to the format specified by the XML data type xs:date, and if not possible + by RFC 822. +
(2) + The client should try to convert the string to a date & time value, first according to the format specified by the XML data type xs:dateTime, and if not possible + by RFC 822. +
(3) + The client should try to convert the string to a double-precision floating-point value, first according to the format specified by the XML data type xs:double, + and if not possible using system-local string to floating-point conversion using local decimal and throusand separator settings. +
(4) + The client should try to convert the string to a duration value, first according to the format specified by the XML data type xs:duration, + and if not possible using the XML data type xs:time. +
(5)The client should try to convert the string to an integer value according to the corresponding XML data type formats xs:int and xs:long.
(6) + The numeric field value consists of three parts: Numeric value, number of decimals and optional unit. If no unit is provided, only the numeric value should + be converted to a string (compatible with the XML data type xs:double), using exactly the number of decimals provided in the field. If a unit is provided + (non-empty string) it must not be appended to the value, if the value is to be used for control output. For presentation purposes however, a space could be + appended to the number and the unit appended after the space. +
(7) + A duration field value contains a xs:duration value. The xs:duration has a larger domain than xs:time, and contains all xs:time values, but xs:time does + not contain all possible xs:duration values. So, conversion of an xs:duration value to an xs:time value should be performed only if a duration lies + between 00:00:00 and 23:59:59. +
(8) + The client should try to convert the string to a time value according to the format specified by the XML data type xs:time. +
xUse the canonical conversion method.
Z2true = 1, false = 0.
!=0Nonzero = true, Zero = false.
RRGGBBA string of six hexadecimal characters, the first two the red component of the color, the next two the green component and the last two the blue component.
RRGGBBAAA string of eight hexadecimal characters, the first two the red component of the color, the next two the green component, the following two the blue component and the last two the alpha channel.
Date partOnly the date part of the xs:dateTime value should be used.
Time partOnly the time part of the xs:dateTime value should be used.
OrdinalEach enumeration value may in the implementation correspond to an ordinal number.
ThunkThe value is thunked down to lower precision in the canonical way.
xs:booleanConversion to a string should follow the rules specified for the XML datatype xs:boolean.
xs:dateTimeConversion to a string should follow the rules specified for the XML datatype xs:dateTime.
xs:durationConversion to a string should follow the rules specified for the XML datatype xs:duration.
+

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

+ +

A node defined in a concentrator, as defined by Internet of Things - Concentrators, supporting control has @@ -1345,48 +1554,46 @@ from='spotlight@clayster.com' to='master@clayster.com/amr' id='12'> - - - Spotlight - - - - - - - - - 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 - - - If the spotlight is turned on or off. - true - - - - Horizontal angle of the spotlight. - 0 - - - - - - - - Elevation angle of the spotlight. - 0 - - - - - - - - + + Spotlight + + + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + If the spotlight is turned on or off. + true + + + + Horizontal angle of the spotlight. + 0 + + + + + + + + Elevation angle of the spotlight. + 0 + + + + + + + ]]>

@@ -1398,7 +1605,7 @@ which defines a set of interoperable interfaces and their abilities.

- +

Nodes behind a concentrator, as defined in Internet of Things - Concentrators, have an additional means of publishing control interfaces: Node Commands. @@ -1445,7 +1652,7 @@ 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-0324 &xep0324;, tokens should always be included in all calls. This to allow devices to check privileges with provisioning servers. @@ -1468,7 +1675,7 @@ For more information about provisioning, see Internet of Things - Provisioning.

- +

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 @@ -1484,7 +1691,7 @@ - +

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.

@@ -1496,7 +1703,7 @@ 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. @@ -1508,7 +1715,7 @@ Controlling devices in a large sensor network is a hackers wet dream. Therefore, consideration of how network security is implemented should not be underestimated. The following sections provide some general items that should be considered.

- +

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. @@ -1518,7 +1725,7 @@ 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. @@ -1582,12 +1789,13 @@ - + - + + @@ -1597,15 +1805,6 @@ - - - - - - - - - @@ -1624,11 +1823,7 @@ - - - - - + @@ -1730,18 +1925,6 @@ - - - - - - - - - - - - ]]>