mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 08:45:04 -05:00
XEP-0325: < see revision history >
This commit is contained in:
Matthew A. Miller
parent
29405ffe48
commit
81faba3b85
463
xep-0325.xml
463
xep-0325.xml
@ -1,5 +1,4 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<!-- TODO: SImple readout: Only control form - no XEP-0323 -->
|
||||
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||||
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||||
%ents;
|
||||
@ -37,6 +36,66 @@
|
||||
<jid>peter.waher@jabber.org</jid>
|
||||
<uri>http://www.linkedin.com/in/peterwaher</uri>
|
||||
</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>
|
||||
<version>0.2</version>
|
||||
<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,
|
||||
the use of <strong>node</strong> elements is not necessary, and control commands are sent directly to the device itself.
|
||||
</p>
|
||||
<section2 topic='Control commands'>
|
||||
<section2 topic='Control commands' anchor='controlcommands'>
|
||||
<section3 topic='Sending a control command using a message stanza'>
|
||||
<p>
|
||||
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'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/>
|
||||
<setResponse xmlns='urn:xmpp:iot:control'/>
|
||||
</iq>]]>
|
||||
</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>
|
||||
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>
|
||||
@ -377,14 +441,18 @@
|
||||
from='analog.output@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='2'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OtherError'>
|
||||
<error var='Output'>Invalid parameter type.</error>
|
||||
</setResponse>
|
||||
<error type='modify'>
|
||||
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
|
||||
</error>
|
||||
</iq>]]>
|
||||
</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>
|
||||
</section2>
|
||||
<section2 topic='Setting control parameters'>
|
||||
<section2 topic='Setting control parameters' anchor='set'>
|
||||
<p>
|
||||
The following sub-sections illustrate how to set parameters of different types in a device.
|
||||
</p>
|
||||
@ -567,7 +635,7 @@
|
||||
</p>
|
||||
</section3>
|
||||
</section2>
|
||||
<section2 topic='Control forms'>
|
||||
<section2 topic='Control forms' anchor='forms'>
|
||||
<section3 topic='Getting a control form' anchor='controlform'>
|
||||
<p>
|
||||
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'
|
||||
to='master@clayster.com/amr'
|
||||
id='3'>
|
||||
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
|
||||
<x type='form'
|
||||
xmlns='jabber:x:data'
|
||||
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
||||
@ -623,7 +690,6 @@
|
||||
<xdd:notSame/>
|
||||
</field>
|
||||
</x>
|
||||
</getFormResponse>
|
||||
</iq>]]>
|
||||
</example>
|
||||
<p>
|
||||
@ -653,8 +719,7 @@
|
||||
</section3>
|
||||
<section3 topic='Getting a control form, Failure'>
|
||||
<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>
|
||||
attribute of the <strong>getFormResponse</strong> element, as is shown in the following example:
|
||||
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:
|
||||
</p>
|
||||
<example caption='Getting a control form, Failure'>
|
||||
<![CDATA[
|
||||
@ -669,7 +734,10 @@
|
||||
from='dimmer@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
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>]]>
|
||||
</example>
|
||||
</section3>
|
||||
@ -706,7 +774,7 @@
|
||||
from='dimmer@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='5'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' />
|
||||
</iq>]]>
|
||||
</example>
|
||||
<p>
|
||||
@ -716,9 +784,8 @@
|
||||
</section3>
|
||||
<section3 topic='Setting a (partial) control form, Failure'>
|
||||
<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>
|
||||
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,
|
||||
as is shown in the following example:
|
||||
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
|
||||
using <strong>paramError</strong> elements in the response, as is shown in the following example:
|
||||
</p>
|
||||
<example caption='Setting a (partial) control form, Failure'>
|
||||
<![CDATA[
|
||||
@ -745,14 +812,15 @@
|
||||
from='dimmer@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='6'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='FormError'>
|
||||
<error var='OutputPercent'>Invalid parameter value.</error>
|
||||
</setResponse>
|
||||
<error type='modify'>
|
||||
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<paramError xmlns='urn:xmpp:iot:control' var='OutputPercent'>Invalid parameter value.</error>
|
||||
</error>
|
||||
</iq>]]>
|
||||
</example>
|
||||
</section3>
|
||||
</section2>
|
||||
<section2 topic='Controlling devices behind a concentrator'>
|
||||
<section2 topic='Controlling devices behind a concentrator' anchor='concentrator'>
|
||||
<p>
|
||||
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.
|
||||
@ -822,9 +890,10 @@
|
||||
from='concentrator@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='7'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OtherError'>
|
||||
<error var='Output'>Invalid parameter type.</error>
|
||||
</setResponse>
|
||||
<error type='modify'>
|
||||
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid parameter type.</error>
|
||||
</error>
|
||||
</iq>]]>
|
||||
</example>
|
||||
</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
|
||||
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>
|
||||
<example caption='Getting a control form'>
|
||||
<example caption='Getting a control form from multiple nodes'>
|
||||
<![CDATA[
|
||||
<iq type='get'
|
||||
from='master@clayster.com/amr'
|
||||
@ -851,7 +920,6 @@
|
||||
from='concentrator@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='8'>
|
||||
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
|
||||
<x type='form'
|
||||
xmlns='jabber:x:data'
|
||||
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
||||
@ -870,7 +938,6 @@
|
||||
<xdd:notSame/>
|
||||
</field>
|
||||
</x>
|
||||
</getFormResponse>
|
||||
</iq>]]>
|
||||
</example>
|
||||
<p>
|
||||
@ -880,9 +947,8 @@
|
||||
</section3>
|
||||
<section3 topic='Getting a control form from multiple nodes, Failure'>
|
||||
<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>
|
||||
attribute of the <strong>getFormResponse</strong> 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 <strong>error</strong> 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:
|
||||
</p>
|
||||
<example caption='Getting a control form from multiple nodes, Failure'>
|
||||
<![CDATA[
|
||||
@ -902,7 +968,10 @@
|
||||
from='concentrator@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
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>]]>
|
||||
</example>
|
||||
</section3>
|
||||
@ -937,15 +1006,14 @@
|
||||
from='concentrator@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='10'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='OK'/>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' />
|
||||
</iq>]]>
|
||||
</example>
|
||||
</section3>
|
||||
<section3 topic='Setting a (partial) control form to multiple nodes, Failure'>
|
||||
<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>
|
||||
attribute of the <strong>setResponse</strong> 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 <strong>error</strong> 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.
|
||||
</p>
|
||||
<example caption='Setting a (partial) control form to multiple nodes'>
|
||||
<![CDATA[
|
||||
@ -973,13 +1041,14 @@
|
||||
</set>
|
||||
</iq>
|
||||
|
||||
<iq type='result'
|
||||
<iq type='error'
|
||||
from='concentrator@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='11'>
|
||||
<setResponse xmlns='urn:xmpp:iot:control' responseCode='FormError'>
|
||||
<error var='Output'>Invalid type</error>
|
||||
</setResponse>
|
||||
<error type='modify'>
|
||||
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<paramError xmlns='urn:xmpp:iot:control' var='Output'>Invalid type.</error>
|
||||
</error>
|
||||
</iq>]]>
|
||||
</example>
|
||||
</section3>
|
||||
@ -1015,10 +1084,72 @@
|
||||
</p>
|
||||
</section1>
|
||||
<section1 topic='Implementation Notes' anchor='impl'>
|
||||
<section2 topic='Reading current control states'>
|
||||
<section2 topic='IQ Error Stanzas' anchor='errors'>
|
||||
<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
|
||||
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:
|
||||
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 <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>
|
||||
<ul>
|
||||
<li>
|
||||
@ -1035,115 +1166,164 @@
|
||||
the control parameter.
|
||||
</p>
|
||||
</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>
|
||||
<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
|
||||
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.
|
||||
guaranteed to contain correct current values, as described above.
|
||||
</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
|
||||
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>
|
||||
<table caption='Conversion of Field Value to Control Parameter Value based on types'>
|
||||
<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>string</th>
|
||||
<th>boolean</th>
|
||||
<th>dateTime</th>
|
||||
<th>timeSpan</th>
|
||||
<th>enum</th>
|
||||
<th>time</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>boolean</th>
|
||||
<td>!=0</td>
|
||||
<td>N/A</td>
|
||||
<td>x</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>!=0</td>
|
||||
<td>!=0</td>
|
||||
<td>!=0</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>color</th>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>RRGGBB or RRGGBBAA</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>date</th>
|
||||
<td>N/A</td>
|
||||
<td>(1)</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td>x</td>
|
||||
<td>Date part</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>(1)</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>dateTime</th>
|
||||
<td>N/A</td>
|
||||
<td>(2)</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td>x</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>x</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>(2)</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>double</th>
|
||||
<td>Z2</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>x</td>
|
||||
<td>x</td>
|
||||
<td>x</td>
|
||||
<td>(3)</td>
|
||||
<td>Z2</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>duration</th>
|
||||
<td>N/A</td>
|
||||
<td>(4)</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>x</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>(4)</td>
|
||||
<td>x</td>
|
||||
<td>N/A</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>int</th>
|
||||
<td>x</td>
|
||||
<td>(5)</td>
|
||||
<td>Z2</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>Ordinal</td>
|
||||
<td>x</td>
|
||||
<td>Thunk</td>
|
||||
<td>Thunk</td>
|
||||
<td>(5)</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>long</th>
|
||||
<td>x</td>
|
||||
<td>(5)</td>
|
||||
<td>Z2</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>Ordinal</td>
|
||||
<td>x</td>
|
||||
<td>x</td>
|
||||
<td>Thunk</td>
|
||||
<td>(5)</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>string</th>
|
||||
<td>(6)</td>
|
||||
<td>x</td>
|
||||
<td>xs:boolean</td>
|
||||
<td>xs:date</td>
|
||||
<td>xs:dateTime</td>
|
||||
<td>xs:duration</td>
|
||||
<td>x</td>
|
||||
<td>xs:int</td>
|
||||
<td>xs:long</td>
|
||||
<td>(6)</td>
|
||||
<td>x</td>
|
||||
<td>xs:time</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>time</th>
|
||||
<td>N/A</td>
|
||||
<td>(7)</td>
|
||||
<td>N/A</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>Time part</td>
|
||||
<td>(7)</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>(8)</td>
|
||||
<td>N/A</td>
|
||||
<td>x</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>
|
||||
@ -1198,15 +1378,15 @@
|
||||
<tr>
|
||||
<td>(7)</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>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>(8)</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
|
||||
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.
|
||||
The client should try to convert the string to a time value according to the format specified by the XML data type xs:time.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
@ -1217,10 +1397,6 @@
|
||||
<td>Z2</td>
|
||||
<td>true = 1, false = 0.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N/A</td>
|
||||
<td>Not applicable. Conversion has no meaning. Value types are not compatible.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>!=0</td>
|
||||
<td>Nonzero = true, Zero = false.</td>
|
||||
@ -1241,6 +1417,14 @@
|
||||
<td>Time part</td>
|
||||
<td>Only the time part of the xs:dateTime value should be used.</td>
|
||||
</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>
|
||||
<td>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
|
||||
<link url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</link>.
|
||||
</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 topic='Difference between node parameters and node control parameters' anchor='nodeparamsvscontrolparams'>
|
||||
<p>
|
||||
@ -1345,7 +1554,6 @@
|
||||
from='spotlight@clayster.com'
|
||||
to='master@clayster.com/amr'
|
||||
id='12'>
|
||||
<getFormResponse xmlns='urn:xmpp:iot:control' result='OK'>
|
||||
<x type='form'
|
||||
xmlns='jabber:x:data'
|
||||
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
||||
@ -1386,7 +1594,6 @@
|
||||
<parameterGroup xmlns='urn:xmpp:iot:control' name='direction'/>
|
||||
</field>
|
||||
</x>
|
||||
</getFormResponse>
|
||||
</iq>]]>
|
||||
</example>
|
||||
<p>
|
||||
@ -1398,7 +1605,7 @@
|
||||
which defines a set of interoperable interfaces and their abilities.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='Node commands vs. control parameters'>
|
||||
<section2 topic='Node commands vs. control parameters' anchor='commandsvsparameters'>
|
||||
<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
|
||||
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.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='Tokens'>
|
||||
<section2 topic='Tokens' anchor='tokens'>
|
||||
<p>
|
||||
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 <link url='http://xmpp.org/extensions/xep-0324.html'>Internet of Things - Provisioning</link>.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='Controlling devices in large subsystems'>
|
||||
<section2 topic='Controlling devices in large subsystems' anchor='largesubsystems'>
|
||||
<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
|
||||
very many actuators containing many different control actions have to be controlled, as is documented in
|
||||
@ -1484,7 +1691,7 @@
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
||||
<section2 topic='Time Zones'>
|
||||
<section2 topic='Time Zones' anchor='timezones'>
|
||||
<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.
|
||||
</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.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='xml:lang'>
|
||||
<section2 topic='xml:lang' anchor='lang'>
|
||||
<p>
|
||||
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.
|
||||
@ -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.
|
||||
</p>
|
||||
<section2 topic='Encryption & Authentication'>
|
||||
<section2 topic='Encryption & Authentication' anchor='encauth'>
|
||||
<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
|
||||
certificate properly validated.
|
||||
@ -1518,7 +1725,7 @@
|
||||
on the device.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='Provisioning'>
|
||||
<section2 topic='Provisioning' anchor='provisioning'>
|
||||
<p>
|
||||
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 @@
|
||||
<xs:complexType>
|
||||
<xs:choice minOccurs='0' maxOccurs='unbounded'>
|
||||
<xs:element name='node' type='NodeReference'/>
|
||||
<xs:element name='error' type='ParameterError'/>
|
||||
<xs:element name='parameter' type='Parameter'/>
|
||||
</xs:choice>
|
||||
<xs:attributeGroup ref='responseCode'/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='paramError' type='ParameterError'/>
|
||||
|
||||
<xs:element name='getForm'>
|
||||
<xs:complexType>
|
||||
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
|
||||
@ -1597,15 +1805,6 @@
|
||||
</xs:complexType>
|
||||
</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:complexType>
|
||||
<xs:attribute name='name' type='xs:string' use='required'/>
|
||||
@ -1624,11 +1823,7 @@
|
||||
<xs:attribute name='userToken' type='xs:string' use='optional'/>
|
||||
</xs:attributeGroup>
|
||||
|
||||
<xs:attributeGroup name='responseCode'>
|
||||
<xs:attribute name='result' type='ResponseCode' use='required'/>
|
||||
</xs:attributeGroup>
|
||||
|
||||
<xs:complexType name='Parameter' abstract='true'>
|
||||
<xs:complexType name='Parameter'>
|
||||
<xs:attribute name='name' type='xs:string' use='required'/>
|
||||
</xs:complexType>
|
||||
|
||||
@ -1730,18 +1925,6 @@
|
||||
</xs:restriction>
|
||||
</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>]]>
|
||||
</code>
|
||||
</section1>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user