moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2025-02-16 07:10:15 -05:00
Code Issues Releases Wiki Activity

XEP-0325: < see revision history >

Browse Source
This commit is contained in:
Matthew A. Miller 2014-04-07 13:55:58 -06:00
parent 29405ffe48
commit 81faba3b85
1 changed files with 594 additions and 411 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

463
xep-0325.xml
View File

@ -1,5 +1,4 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!-- TODO: SImple readout: Only control form - no XEP-0323 -->
<!DOCTYPE xep SYSTEM 'xep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
@ -37,6 +36,66 @@
<jid>peter.waher@jabber.org</jid> <jid>peter.waher@jabber.org</jid>
<uri>http://www.linkedin.com/in/peterwaher</uri> <uri>http://www.linkedin.com/in/peterwaher</uri>
</author> </author>
<revision>
<version>0.3</version>
<date>2014-04-07</date>
<initials>pw</initials>
<remark>
<p>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.</p>
<p>The <strong>getFormResponse</strong> element has been removed.</p>
<p>The <strong>setResponse</strong> is now only used when configuration is successful.</p>
<p>The <strong>parameter</strong> subelement to <strong>setResponse</strong> has been reintroduced. Examples are provided in XEP-0324.</p>
<p>The element <strong>paramError</strong> has been introduced, and can be used to provide error information that are linked to control parameters.</p>
<p>Added anchors to all second level subsections.</p>
<p>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).</p>
<p>Harmonization of data types between XEP-0323 and XEP-0325.</p>
<p>The attribute <strong>writable</strong> used to correlate fields in XEP-0323 with control parameters is described.</p>
<table caption='XMPP Errors when rejecting a readout request'>
<tr>
<th>Obsolete Code</th>
<th>Error Type</th>
<th>Error Element</th>
<th>Namespace</th>
<th>Description</th>
</tr>
<tr>
<td>InsufficientPrivileges</td>
<td>cancel</td>
<td>forbidden</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If the caller lacks privileges to perform the action.</td>
</tr>
<tr>
<td>NotFound</td>
<td>cancel</td>
<td>item-not-found</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If an item, parameter or data source could not be found.</td>
</tr>
<tr>
<td>OtherError, FormError</td>
<td>modify</td>
<td>bad-request</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.</td>
</tr>
<tr>
<td>NotImplemented</td>
<td>cancel</td>
<td>feature-not-implemented</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If an action has not been implemented in the device.</td>
</tr>
<tr>
<td>Locked</td>
<td>wait</td>
<td>conflict</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>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.</td>
</tr>
</table>
</remark>
</revision>
<revision> <revision>
<version>0.2</version> <version>0.2</version>
<date>2014-03-10</date> <date>2014-03-10</date>
@ -312,7 +371,7 @@
an handles multiple nodes behind it, which node(s) to control is defined using <strong>node</strong> elements. If not a concentrator, an handles multiple nodes behind it, which node(s) to control is defined using <strong>node</strong> elements. If not a concentrator,
the use of <strong>node</strong> elements is not necessary, and control commands are sent directly to the device itself. the use of <strong>node</strong> elements is not necessary, and control commands are sent directly to the device itself.
</p> </p>
<section2 topic='Control commands'> <section2 topic='Control commands' anchor='controlcommands'>
<section3 topic='Sending a control command using a message stanza'> <section3 topic='Sending a control command using a message stanza'>
<p> <p>
Following is an example of a control command sent using a message stanza: Following is an example of a control command sent using a message stanza:
@ -350,9 +409,14 @@
from='digital.output@clayster.com' from='digital.output@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='1'> id='1'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/> <setResponse xmlns='urn:xmpp:iot:control'/>
</iq>]]> </iq>]]>
</example> </example>
<p>
<strong>Note:</strong> An empty <strong>setResponse</strong> 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 <strong>setResponse</strong> element will contain what nodes and/or parameters
were finally used to perform the command. For examples of this, see &xep0324;.
</p>
<p> <p>
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. 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.
</p> </p>
@ -377,14 +441,18 @@
from='analog.output@clayster.com' from='analog.output@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='2'> id='2'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OtherError'> <error type='modify'>
<error var='Output'>Invalid parameter type.</error> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</setResponse> <paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
</error>
</iq>]]> </iq>]]>
</example> </example>
<p>
Here, the <strong>paramError</strong> element is used in the IQ Error response, to provide error information related to a specific control parameter.
</p>
</section3> </section3>
</section2> </section2>
<section2 topic='Setting control parameters'> <section2 topic='Setting control parameters' anchor='set'>
<p> <p>
The following sub-sections illustrate how to set parameters of different types in a device. The following sub-sections illustrate how to set parameters of different types in a device.
</p> </p>
@ -567,7 +635,7 @@
</p> </p>
</section3> </section3>
</section2> </section2>
<section2 topic='Control forms'> <section2 topic='Control forms' anchor='forms'>
<section3 topic='Getting a control form' anchor='controlform'> <section3 topic='Getting a control form' anchor='controlform'>
<p> <p>
A client can get a control form containing available control parameters of the device. This is done using the <strong>getForm</strong> command, A client can get a control form containing available control parameters of the device. This is done using the <strong>getForm</strong> command,
@ -586,7 +654,6 @@
from='dimmer@clayster.com' from='dimmer@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='3'> id='3'>
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
<x type='form' <x type='form'
xmlns='jabber:x:data' xmlns='jabber:x:data'
xmlns:xdv='http://jabber.org/protocol/xdata-validate' xmlns:xdv='http://jabber.org/protocol/xdata-validate'
@ -623,7 +690,6 @@
<xdd:notSame/> <xdd:notSame/>
</field> </field>
</x> </x>
</getFormResponse>
</iq>]]> </iq>]]>
</example> </example>
<p> <p>
@ -653,8 +719,7 @@
</section3> </section3>
<section3 topic='Getting a control form, Failure'> <section3 topic='Getting a control form, Failure'>
<p> <p>
A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza, and detailing the error in the <strong>result</strong> A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza, as is shown in the following example:
attribute of the <strong>getFormResponse</strong> element, as is shown in the following example:
</p> </p>
<example caption='Getting a control form, Failure'> <example caption='Getting a control form, Failure'>
<![CDATA[ <![CDATA[
@ -669,7 +734,10 @@
from='dimmer@clayster.com' from='dimmer@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='4'> id='4'>
<getFormResponse xmlns='urn:xmpp:iot:control' result='InsufficientPrivileges'/> <error type='cancel'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang='en'>Access denied.</text>
</error>
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
@ -706,7 +774,7 @@
from='dimmer@clayster.com' from='dimmer@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='5'> id='5'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/> <setResponse xmlns='urn:xmpp:iot:control' />
</iq>]]> </iq>]]>
</example> </example>
<p> <p>
@ -716,9 +784,8 @@
</section3> </section3>
<section3 topic='Setting a (partial) control form, Failure'> <section3 topic='Setting a (partial) control form, Failure'>
<p> <p>
A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza, and detailing the error in the <strong>result</strong> A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza. If there are errors in the form, details are listed
attribute of the <strong>setResponse</strong> element. If there are errors in the form, details are listed using <strong>error</strong> elements in the response, using <strong>paramError</strong> elements in the response, as is shown in the following example:
as is shown in the following example:
</p> </p>
<example caption='Setting a (partial) control form, Failure'> <example caption='Setting a (partial) control form, Failure'>
<![CDATA[ <![CDATA[
@ -745,14 +812,15 @@
from='dimmer@clayster.com' from='dimmer@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='6'> id='6'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='FormError'> <error type='modify'>
<error var='OutputPercent'>Invalid parameter value.</error> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</setResponse> <paramError xmlns='urn:xmpp:iot:control' var='OutputPercent'>Invalid parameter value.</error>
</error>
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
</section2> </section2>
<section2 topic='Controlling devices behind a concentrator'> <section2 topic='Controlling devices behind a concentrator' anchor='concentrator'>
<p> <p>
Controlling devices behind a concentrator can be done by specifying what device(s) to control using <strong>node</strong> elements within the Controlling devices behind a concentrator can be done by specifying what device(s) to control using <strong>node</strong> elements within the
command elements sent to the concentrator. The following sub-sections show examples of how this is done. 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' from='concentrator@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='7'> id='7'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OtherError'> <error type='modify'>
<error var='Output'>Invalid parameter type.</error> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</setResponse> <paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
</error>
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
@ -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 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 <strong>node</strong> elements to a <strong>getForm</strong> command sent to the concentrator, as is shown in the following example: adding a sequence of <strong>node</strong> elements to a <strong>getForm</strong> command sent to the concentrator, as is shown in the following example:
</p> </p>
<example caption='Getting a control form'> <example caption='Getting a control form from multiple nodes'>
<![CDATA[ <![CDATA[
<iq type='get' <iq type='get'
from='master@clayster.com/amr' from='master@clayster.com/amr'
@ -851,7 +920,6 @@
from='concentrator@clayster.com' from='concentrator@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='8'> id='8'>
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
<x type='form' <x type='form'
xmlns='jabber:x:data' xmlns='jabber:x:data'
xmlns:xdv='http://jabber.org/protocol/xdata-validate' xmlns:xdv='http://jabber.org/protocol/xdata-validate'
@ -870,7 +938,6 @@
<xdd:notSame/> <xdd:notSame/>
</field> </field>
</x> </x>
</getFormResponse>
</iq>]]> </iq>]]>
</example> </example>
<p> <p>
@ -880,9 +947,8 @@
</section3> </section3>
<section3 topic='Getting a control form from multiple nodes, Failure'> <section3 topic='Getting a control form from multiple nodes, Failure'>
<p> <p>
A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza, and detailing the error in the <strong>result</strong> A device can reject a control form request. It does this returning an <strong>error</strong> iq stanza. The following example shows the device rejecting
attribute of the <strong>getFormResponse</strong> element. The following example shows the device rejecting a control form request, because it does not support a control form request, because it does not support the handling of common parameters between multiple nodes:
the handling of common parameters between multiple nodes:
</p> </p>
<example caption='Getting a control form from multiple nodes, Failure'> <example caption='Getting a control form from multiple nodes, Failure'>
<![CDATA[ <![CDATA[
@ -902,7 +968,10 @@
from='concentrator@clayster.com' from='concentrator@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='9'> id='9'>
<getFormResponse xmlns='urn:xmpp:iot:control' result='NotImplemented'/> <error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang='en'>Cannot merge control forms from different nodes.</text>
</error>
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
@ -937,15 +1006,14 @@
from='concentrator@clayster.com' from='concentrator@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='10'> id='10'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/> <setResponse xmlns='urn:xmpp:iot:control' />
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
<section3 topic='Setting a (partial) control form to multiple nodes, Failure'> <section3 topic='Setting a (partial) control form to multiple nodes, Failure'>
<p> <p>
A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza, and detailing the error in the <strong>result</strong> A device can reject a control form submission. It does this returning an <strong>error</strong> iq stanza. The following example shows the device rejecting a
attribute of the <strong>setResponse</strong> element. The following example shows the device rejecting a control form submission because one of the control parameters, 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.
even though it exists on all nodes, is not of the same type on all nodes.
</p> </p>
<example caption='Setting a (partial) control form to multiple nodes'> <example caption='Setting a (partial) control form to multiple nodes'>
<![CDATA[ <![CDATA[
@ -973,13 +1041,14 @@
</set> </set>
</iq> </iq>
<iq type='result' <iq type='error'
from='concentrator@clayster.com' from='concentrator@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='11'> id='11'>
<setResponse xmlns='urn:xmpp:iot:control' responseCode='FormError'> <error type='modify'>
<error var='Output'>Invalid type</error> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</setResponse> <paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid type.</error>
</error>
</iq>]]> </iq>]]>
</example> </example>
</section3> </section3>
@ -1015,10 +1084,72 @@
</p> </p>
</section1> </section1>
<section1 topic='Implementation Notes' anchor='impl'> <section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Reading current control states'> <section2 topic='IQ Error Stanzas' anchor='errors'>
<p> <p>
If a client wants to know the current status of control parameters, it must perform a readout of <strong>Momentary</strong> and <strong>Status</strong> values 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
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: lists recommended error type for each error. Error stanzas may also include <strong>paramError</strong> 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 <strong>text</strong>
element.
</p>
<table caption='XMPP Errors when rejecting a readout request'>
<tr>
<th>Error Type</th>
<th>Error Element</th>
<th>Namespace</th>
<th>Description</th>
</tr>
<tr>
<td>cancel</td>
<td>forbidden</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If the caller lacks privileges to perform the action.</td>
</tr>
<tr>
<td>cancel</td>
<td>item-not-found</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If an item, parameter or data source could not be found.</td>
</tr>
<tr>
<td>modify</td>
<td>bad-request</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.</td>
</tr>
<tr>
<td>cancel</td>
<td>feature-not-implemented</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>If an action has not been implemented in the device.</td>
</tr>
<tr>
<td>wait</td>
<td>conflict</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
<td>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.</td>
</tr>
</table>
</section2>
<section2 topic='Reading current control states' anchor='currentstates'>
<section3 topic='Using Control Forms'>
<p>
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;.
</p>
<p>
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.
</p>
</section3>
<section3 topic='Using XEP-0323 (Sensor Data)'>
<p>
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.
</p>
<p>
If a client wants to know the current status of control parameters using this method, it performs a readout of <strong>Momentary</strong> and <strong>Status</strong> 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:
</p> </p>
<ul> <ul>
<li> <li>
@ -1035,115 +1166,164 @@
the control parameter. the control parameter.
</p> </p>
</li> </li>
<li>
<p>
To simplify mapping, a <strong>writable</strong> 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.
</p>
</li>
</ul> </ul>
<p> <p>
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 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 guaranteed to contain correct current values, as described above.
process described in this section.
</p> </p>
<p> <p>
The following table shows how corresponding field values should be converted to the corresponding control parameter value based on field type (x-axis) and 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. control parameter type (y-axis). An empty cell means conversion has no meaning and types are not compatible.
</p> </p>
<table caption='Conversion of Field Value to Control Parameter Value based on types'> <table caption='Conversion of Field Value to Control Parameter Value based on types'>
<tr> <tr>
<th></th> <th>325 \ 323</th>
<th>boolean</th>
<th>date</th>
<th>dateTime</th>
<th>duration</th>
<th>enum</th>
<th>int</th>
<th>long</th>
<th>numeric</th> <th>numeric</th>
<th>string</th> <th>string</th>
<th>boolean</th> <th>time</th>
<th>dateTime</th>
<th>timeSpan</th>
<th>enum</th>
</tr> </tr>
<tr> <tr>
<th>boolean</th> <th>boolean</th>
<td>!=0</td>
<td>N/A</td>
<td>x</td> <td>x</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>&nbsp;</td>
<td>!=0</td>
<td>!=0</td>
<td>!=0</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
<th>color</th> <th>color</th>
<td>N/A</td> <td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>RRGGBB or RRGGBBAA</td> <td>RRGGBB or RRGGBBAA</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr> </tr>
<tr> <tr>
<th>date</th> <th>date</th>
<td>N/A</td> <td>&nbsp;</td>
<td>(1)</td> <td>x</td>
<td>N/A</td>
<td>Date part</td> <td>Date part</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>(1)</td>
<td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
<th>dateTime</th> <th>dateTime</th>
<td>N/A</td> <td>&nbsp;</td>
<td>(2)</td>
<td>N/A</td>
<td>x</td> <td>x</td>
<td>N/A</td> <td>x</td>
<td>N/A</td> <td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>(2)</td>
<td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
<th>double</th> <th>double</th>
<td>Z2</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>x</td>
<td>x</td>
<td>x</td> <td>x</td>
<td>(3)</td> <td>(3)</td>
<td>Z2</td> <td>&nbsp;</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr> </tr>
<tr> <tr>
<th>duration</th> <th>duration</th>
<td>N/A</td> <td>&nbsp;</td>
<td>(4)</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>x</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>(4)</td>
<td>x</td> <td>x</td>
<td>N/A</td>
</tr> </tr>
<tr> <tr>
<th>int</th> <th>int</th>
<td>x</td>
<td>(5)</td>
<td>Z2</td> <td>Z2</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>Ordinal</td>
<td>x</td>
<td>Thunk</td>
<td>Thunk</td>
<td>(5)</td>
<td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
<th>long</th> <th>long</th>
<td>x</td>
<td>(5)</td>
<td>Z2</td> <td>Z2</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>N/A</td> <td>&nbsp;</td>
<td>Ordinal</td>
<td>x</td>
<td>x</td>
<td>Thunk</td>
<td>(5)</td>
<td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
<th>string</th> <th>string</th>
<td>(6)</td>
<td>x</td>
<td>xs:boolean</td> <td>xs:boolean</td>
<td>xs:date</td>
<td>xs:dateTime</td> <td>xs:dateTime</td>
<td>xs:duration</td> <td>xs:duration</td>
<td>x</td> <td>x</td>
<td>xs:int</td>
<td>xs:long</td>
<td>(6)</td>
<td>x</td>
<td>xs:time</td>
</tr> </tr>
<tr> <tr>
<th>time</th> <th>time</th>
<td>N/A</td> <td>&nbsp;</td>
<td>(7)</td> <td>&nbsp;</td>
<td>N/A</td>
<td>Time part</td> <td>Time part</td>
<td>(7)</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>(8)</td> <td>(8)</td>
<td>N/A</td> <td>x</td>
</tr> </tr>
</table> </table>
<p> <p>
@ -1198,15 +1378,15 @@
<tr> <tr>
<td>(7)</td> <td>(7)</td>
<td> <td>
The client should try to convert the string to a time value according to the format specified by the XML data type xs:time. 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.
</td> </td>
</tr> </tr>
<tr> <tr>
<td>(8)</td> <td>(8)</td>
<td> <td>
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 The client should try to convert the string to a time value according to the format specified by the XML data type xs:time.
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.
</td> </td>
</tr> </tr>
<tr> <tr>
@ -1217,10 +1397,6 @@
<td>Z2</td> <td>Z2</td>
<td>true = 1, false = 0.</td> <td>true = 1, false = 0.</td>
</tr> </tr>
<tr>
<td>N/A</td>
<td>Not applicable. Conversion has no meaning. Value types are not compatible.</td>
</tr>
<tr> <tr>
<td>!=0</td> <td>!=0</td>
<td>Nonzero = true, Zero = false.</td> <td>Nonzero = true, Zero = false.</td>
@ -1241,6 +1417,14 @@
<td>Time part</td> <td>Time part</td>
<td>Only the time part of the xs:dateTime value should be used.</td> <td>Only the time part of the xs:dateTime value should be used.</td>
</tr> </tr>
<tr>
<td>Ordinal</td>
<td>Each enumeration value may in the implementation correspond to an ordinal number.</td>
</tr>
<tr>
<td>Thunk</td>
<td>The value is thunked down to lower precision in the canonical way.</td>
</tr>
<tr> <tr>
<td>xs:boolean</td> <td>xs:boolean</td>
<td>Conversion to a string should follow the rules specified for the XML datatype xs:boolean.</td> <td>Conversion to a string should follow the rules specified for the XML datatype xs:boolean.</td>
@ -1258,6 +1442,31 @@
<strong>Note:</strong> the namespace prefix <strong>xs</strong> is here supposed to be linked with the XML Schema namespace <strong>Note:</strong> the namespace prefix <strong>xs</strong> is here supposed to be linked with the XML Schema namespace
<link url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</link>. <link url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</link>.
</p> </p>
</section3>
<section3 topic='Harmonization with XEP-0323 (Sensor Data)' anchor='harmonization'>
<p>
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):
</p>
<p>
The <strong>enum</strong> field value data type is not available in XEP-0325 (this document). Instead enumeration valued parameters are represented as <strong>string</strong> 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 <strong>enum</strong> element contains a data type attribute, that can be used to identify the type of the enumeration.
</p>
<p>
The <strong>numeric</strong> 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 <strong>double</strong> control parameters, which lack a unit attribute. They are assumed to have the same unit as
the corresponding <strong>numeric</strong> field value. On the other hand, floating point valued control parameters without units, are reported using the <strong>numeric</strong>
field element, but leaving the unit blank.
</p>
<p>
Control pameters of type <strong>color</strong> 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.
</p>
<p>
The <strong>boolean</strong>, <strong>date</strong>, <strong>dateTime</strong>, <strong>duration</strong>, <strong>int</strong>, <strong>long</strong>, <strong>string</strong>
and <strong>time</strong> field value data types correspond to control parameters having the same types and same element names.
</p>
</section3>
</section2> </section2>
<section2 topic='Difference between node parameters and node control parameters' anchor='nodeparamsvscontrolparams'> <section2 topic='Difference between node parameters and node control parameters' anchor='nodeparamsvscontrolparams'>
<p> <p>
@ -1345,7 +1554,6 @@
from='spotlight@clayster.com' from='spotlight@clayster.com'
to='master@clayster.com/amr' to='master@clayster.com/amr'
id='12'> id='12'>
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
<x type='form' <x type='form'
xmlns='jabber:x:data' xmlns='jabber:x:data'
xmlns:xdv='http://jabber.org/protocol/xdata-validate' xmlns:xdv='http://jabber.org/protocol/xdata-validate'
@ -1386,7 +1594,6 @@
<parameterGroup xmlns='urn:xmpp:iot:control' name='direction'/> <parameterGroup xmlns='urn:xmpp:iot:control' name='direction'/>
</field> </field>
</x> </x>
</getFormResponse>
</iq>]]> </iq>]]>
</example> </example>
<p> <p>
@ -1398,7 +1605,7 @@
which defines a set of interoperable interfaces and their abilities. which defines a set of interoperable interfaces and their abilities.
</p> </p>
</section2> </section2>
<section2 topic='Node commands vs. control parameters'> <section2 topic='Node commands vs. control parameters' anchor='commandsvsparameters'>
<p> <p>
Nodes behind a concentrator, as defined in <link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>, have an additional means of Nodes behind a concentrator, as defined in <link url='http://xmpp.org/extensions/xep-0326.html'>Internet of Things - Concentrators</link>, have an additional means of
publishing control interfaces: Node Commands. 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. as defined in this document, and implementing the simpler more intuitive control actions as described in this document.
</p> </p>
</section2> </section2>
<section2 topic='Tokens'> <section2 topic='Tokens' anchor='tokens'>
<p> <p>
If control interaction is performed in a context of delegated trust, as defined in the Sensor Network Provisioning XEP-0324 &xep0324;, 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. 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 <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link>. For more information about provisioning, see <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link>.
</p> </p>
</section2> </section2>
<section2 topic='Controlling devices in large subsystems'> <section2 topic='Controlling devices in large subsystems' anchor='largesubsystems'>
<p> <p>
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 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 very many actuators containing many different control actions have to be controlled, as is documented in
@ -1484,7 +1691,7 @@
</section2> </section2>
</section1> </section1>
<section1 topic='Internationalization Considerations' anchor='i18n'> <section1 topic='Internationalization Considerations' anchor='i18n'>
<section2 topic='Time Zones'> <section2 topic='Time Zones' anchor='timezones'>
<p> <p>
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. 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.
</p> </p>
@ -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. If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible.
</p> </p>
</section2> </section2>
<section2 topic='xml:lang'> <section2 topic='xml:lang' anchor='lang'>
<p> <p>
Control commands sent using IQ stanzas instead of messages, should consider using the <strong>xml:lang</strong> attribute to specify the desired language Control commands sent using IQ stanzas instead of messages, should consider using the <strong>xml:lang</strong> attribute to specify the desired language
used (if possible) when returning information back to the caller, like error messages, localized control forms, etc. 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. 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. The following sections provide some general items that should be considered.
</p> </p>
<section2 topic='Encryption &amp; Authentication'> <section2 topic='Encryption &amp; Authentication' anchor='encauth'>
<p> <p>
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 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. certificate properly validated.
@ -1518,7 +1725,7 @@
on the device. on the device.
</p> </p>
</section2> </section2>
<section2 topic='Provisioning'> <section2 topic='Provisioning' anchor='provisioning'>
<p> <p>
Consider using provisioning servers to allow for detailed control of who can do what in a sensor network. Implementing proper provisioning support decreases 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. the risk for adverse effects, not only from intentional hacking, but also from unintentional errors.
@ -1582,12 +1789,13 @@
<xs:complexType> <xs:complexType>
<xs:choice minOccurs='0' maxOccurs='unbounded'> <xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='node' type='NodeReference'/> <xs:element name='node' type='NodeReference'/>
<xs:element name='error' type='ParameterError'/> <xs:element name='parameter' type='Parameter'/>
</xs:choice> </xs:choice>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name='paramError' type='ParameterError'/>
<xs:element name='getForm'> <xs:element name='getForm'>
<xs:complexType> <xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'> <xs:sequence minOccurs='0' maxOccurs='unbounded'>
@ -1597,15 +1805,6 @@
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name='getFormResponse'>
<xs:complexType>
<xs:sequence>
<xs:element ref='xd:x' minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attributeGroup ref='responseCode'/>
</xs:complexType>
</xs:element>
<xs:element name='parameterGroup'> <xs:element name='parameterGroup'>
<xs:complexType> <xs:complexType>
<xs:attribute name='name' type='xs:string' use='required'/> <xs:attribute name='name' type='xs:string' use='required'/>
@ -1624,11 +1823,7 @@
<xs:attribute name='userToken' type='xs:string' use='optional'/> <xs:attribute name='userToken' type='xs:string' use='optional'/>
</xs:attributeGroup> </xs:attributeGroup>
<xs:attributeGroup name='responseCode'> <xs:complexType name='Parameter'>
<xs:attribute name='result' type='ResponseCode' use='required'/>
</xs:attributeGroup>
<xs:complexType name='Parameter' abstract='true'>
<xs:attribute name='name' type='xs:string' use='required'/> <xs:attribute name='name' type='xs:string' use='required'/>
</xs:complexType> </xs:complexType>
@ -1730,18 +1925,6 @@
</xs:restriction> </xs:restriction>
</xs:simpleType> </xs:simpleType>
<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:schema>]]> </xs:schema>]]>
</code> </code>
</section1> </section1>