Commit 4282e958 authored by Peter Waher's avatar Peter Waher

Adding data form control example

parent 92fe4b86
Data Form Control Actions
==========================
Data form control actions can be used if human interfaces are used to interact with users. Forms can also be used to get an inventory of available
control parameters, and how they are grouped, validated and supposed to work. The data form is first retrieved from the control server by sending a
`getForm` in an `iq` stanza of type `get` to the control server. It will respond with a data form. To set the parameters retrieved in the form, two
options are available. Either the parameters are set using [simple control actions](ControlSimpleActions.md), or they are set sending a form of type
`submit` in a `set` element to the control server. Note that it is allowed to send only a partial form back to the control server.
![Simple Control](Diagrams/DataFormControl.png)
If the device is divided into nodes, both the `getForm` and the `set` elements can include node definitions to specify which nodes are implied.
The response is also the same, regardless if a form or a set of simple control parameter actions are sent. It is either an `iq` of type `error`,
in case the operation is rejected, or an `iq` of type `result`, in case the operation succeeded, or was partially accepted. The result contains
the nodes and parameters successfully operated on. If this set is smaller than the original request, the device decided to reduce the request,
probably due to restrictions based on the sender identity. If the device denies all control operations, an error is returned instead of a partial result.
Examples
---------------
Getting a control form from a spotlight:
```xml
<iq type='get' from='client@example.org/1234' to='device@example.org/abcd' id='R0001'>
<getForm xmlns='urn:ieee:iot:ctr:1.0'/>
</iq>
```
Data form response:
```xml
<iq type='result' from='device@example.org/abcd' to='client@example.org/1234' id='R0001'>
<x type='form'
xmlns='jabber:x:data'
xmlns:xdv='http://jabber.org/protocol/xdata-validate'
xmlns:xdl='http://jabber.org/protocol/xdata-layout'
xmlns:xdd='urn:xmpp:xdata:dynamic'>
<title>Spotlight</title>
<xdl:page label='Output'>
<xdl:fieldref var='MainSwitch'/>
</xdl:page>
<xdl:page label='Direction'>
<xdl:fieldref var='HorizontalAngle'/>
<xdl:fieldref var='ElevationAngle'/>
</xdl:page>
<field var='xdd session' type='hidden'>
<value>83CAA4BC-6D3A-40E6-90DC-5C3CAA030AE1</value>
</field>
<field var='MainSwitch' type='boolean' label='Main switch'>
<desc>If the spotlight is turned on or off.</desc>
<value>true</value>
<xdd:notSame/>
</field>
<field var='HorizontalAngle' type='text-single' label='Horizontal angle:'>
<desc>Horizontal angle of the spotlight.</desc>
<value>0</value>
<xdv:validate datatype='xs:double'>
<xdv:range min='-180' max='180'/>
</xdv:validate>
<xdd:notSame/>
<pGroup xmlns='urn:ieee:iot:ctr:1.0' name='direction'/>
</field>
<field var='ElevationAngle' type='text-single' label='Elevation angle:'>
<desc>Elevation angle of the spotlight.</desc>
<value>0</value>
<xdv:validate datatype='xs:double'>
<xdv:range min='-90' max='90'/>
</xdv:validate>
<xdd:notSame/>
<pGroup xmlns='urn:ieee:iot:ctr:1.0' name='direction'/>
</field>
</x>
</iq>
```
Setting parameters using a data form. In this case, note that only the field values and types are included, as outlined in
[XEP-0004](https://xmpp.org/extensions/xep-0004.html):
```xml
<iq type='set' from='client@example.org/1234' to='device@example.org/abcd' id='R0002'>
<set xmlns='urn:ieee:iot:ctr:1.0'>
<x type='submit' xmlns='jabber:x:data'>
<field var='xdd session' type='hidden'>
<value>83CAA4BC-6D3A-40E6-90DC-5C3CAA030AE1</value>
</field>
<field var='MainSwitch' type='boolean'>
<value>true</value>
</field>
<field var='HorizontalAngle' type='text-single'>
<value>0</value>
</field>
<field var='ElevationAngle' type='text-single'>
<value>0</value>
</field>
</x>
</set>
</iq>
```
Response:
```xml
<iq type='result' from='device@example.org/abcd' to='client@example.org/1234' id='R0002'>
<resp xmlns='urn:ieee:iot:ctr:1.0'>
<p n="MainSwitch"/>
<p n="HorizontalAngle"/>
<p n="ElevationAngle"/>
</resp>
</iq>
```
<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="299px" preserveAspectRatio="none" style="width:382px;height:299px;" version="1.1" viewBox="0 0 382 299" width="382px" zoomAndPan="magnify"><defs><filter height="300%" id="f51al4jeeeosh" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="71.2656" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="200.5" y="69.2969"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="34.1328" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="205.5" y="106.4297"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="71.2656" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="200.5" y="169.6953"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="34.1328" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="205.5" y="206.8281"/><line style="stroke: #A80036; stroke-width: 1.0; stroke-dasharray: 5.0,5.0;" x1="36" x2="36" y1="38.2969" y2="259.0938"/><line style="stroke: #A80036; stroke-width: 1.0; stroke-dasharray: 5.0,5.0;" x1="205" x2="205" y1="38.2969" y2="259.0938"/><rect fill="#FEFECE" filter="url(#f51al4jeeeosh)" height="30.2969" style="stroke: #A80036; stroke-width: 1.5;" width="53" x="8" y="3"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="39" x="15" y="22.9951">Client</text><rect fill="#FEFECE" filter="url(#f51al4jeeeosh)" height="30.2969" style="stroke: #A80036; stroke-width: 1.5;" width="53" x="8" y="258.0938"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="39" x="15" y="278.0889">Client</text><rect fill="#FEFECE" filter="url(#f51al4jeeeosh)" height="30.2969" style="stroke: #A80036; stroke-width: 1.5;" width="61" x="173" y="3"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="47" x="180" y="22.9951">Device</text><rect fill="#FEFECE" filter="url(#f51al4jeeeosh)" height="30.2969" style="stroke: #A80036; stroke-width: 1.5;" width="61" x="173" y="258.0938"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="47" x="180" y="278.0889">Device</text><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="71.2656" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="200.5" y="69.2969"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="34.1328" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="205.5" y="106.4297"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="71.2656" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="200.5" y="169.6953"/><rect fill="#FFFFFF" filter="url(#f51al4jeeeosh)" height="34.1328" style="stroke: #A80036; stroke-width: 1.0;" width="10" x="205.5" y="206.8281"/><polygon fill="#A80036" points="188.5,65.2969,198.5,69.2969,188.5,73.2969,192.5,69.2969" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="36.5" x2="194.5" y1="69.2969" y2="69.2969"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="145" x="43.5" y="64.3638">iq[type=get](getForm)</text><line style="stroke: #A80036; stroke-width: 1.0;" x1="210.5" x2="257.5" y1="93.5625" y2="93.5625"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="257.5" x2="257.5" y1="93.5625" y2="106.5625"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="216.5" x2="257.5" y1="106.5625" y2="106.5625"/><polygon fill="#A80036" points="226.5,102.5625,216.5,106.5625,226.5,110.5625,222.5,106.5625" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="100" x="222.5" y="88.4966">get parameters</text><polygon fill="#A80036" points="47.5,136.5625,37.5,140.5625,47.5,144.5625,43.5,140.5625" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="41.5" x2="204.5" y1="140.5625" y2="140.5625"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="113" x="53.5" y="135.6294">iq[type=result](x)</text><polygon fill="#A80036" points="188.5,165.6953,198.5,169.6953,188.5,173.6953,192.5,169.6953" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="36.5" x2="194.5" y1="169.6953" y2="169.6953"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="127" x="43.5" y="164.7622">iq[type=set](set(x))</text><line style="stroke: #A80036; stroke-width: 1.0;" x1="210.5" x2="257.5" y1="193.9609" y2="193.9609"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="257.5" x2="257.5" y1="193.9609" y2="206.9609"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="216.5" x2="257.5" y1="206.9609" y2="206.9609"/><polygon fill="#A80036" points="226.5,202.9609,216.5,206.9609,226.5,210.9609,222.5,206.9609" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="148" x="222.5" y="188.895">set parameters in form</text><polygon fill="#A80036" points="47.5,236.9609,37.5,240.9609,47.5,244.9609,43.5,240.9609" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.0;" x1="41.5" x2="204.5" y1="240.9609" y2="240.9609"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="134" x="53.5" y="236.0278">iq[type=result](resp)</text><!--
@startuml
Client -> Device : iq[type=get](getForm)
Activate Device
Device -> Device : get parameters
Activate Device
Client <- Device : iq[type=result](x)
Deactivate Device
Deactivate Device
Client -> Device : iq[type=set](set(x))
Activate Device
Device -> Device : set parameters in form
Activate Device
Client <- Device : iq[type=result](resp)
Deactivate Device
Deactivate Device
@enduml
PlantUML version 1.2017.18(Fri Oct 06 16:56:32 UTC 2017)
(GPL source distribution)
Java Runtime: Java(TM) SE Runtime Environment
JVM: Java HotSpot(TM) 64-Bit Server VM
Java Version: 1.7.0_25-b15
Operating System: Linux
Default Encoding: UTF-8
Language: en
Country: US
--></g></svg>
\ No newline at end of file
@startuml
Client -> Device : iq[type=get](getForm)
Activate Device
Device -> Device : get parameters
Activate Device
Client <- Device : iq[type=result](x)
Deactivate Device
Deactivate Device
Client -> Device : iq[type=set](set(x))
Activate Device
Device -> Device : set parameters in form
Activate Device
Client <- Device : iq[type=result](resp)
Deactivate Device
Deactivate Device
@enduml
\ No newline at end of file
......@@ -18,6 +18,7 @@ Communication Patterns
* [Sensor Data Request/Response communication pattern](SensorDataRequestResponse.md)
* [Sensor Data Event Subscription communication pattern](SensorDataEventSubscription.md)
* [Simple Control Actions](ControlSimpleActions.md)
* [Data Form Control Actions](ControlDataForm.md)
Schemas
-------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment