SensorDataRequestResponse.md 12.3 KB
Newer Older
1 2 3
Sensor Data Request/Response communication pattern
========================================================

4 5 6 7 8
You can retrieve sensor data from a device, or nodes in a device, by sending an request to the device. This document describes this pattern.

This document outlines the XML representation of sensor data, as defined by the IEEE XMPP IoT Working Group. The XML representation is modelled using
an annotated XML Schema:

9 10
| Sensor Data                                           ||
| ------------|------------------------------------------|
11
| Namespace:  | urn:ieee:iot:sd:1.0                      |
12
| Schema:     | [SensorData.xsd](Schemas/SensorData.xsd) |
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

Motivation and design goal
----------------------------

The request/response pattern for sensor data described in this document, is designed with the following goals in mind:

* Pattern should allow fast, quick readouts, where possible.
* Pattern should support slow asynchronous processes, with progress updates.
* Pattern should support both small and large data sets.
* Pattern should support both queueing and scheduling of requests.
* Pattern should support secure distributed transactions.
* Pattern should support limitation of requests.


Building the request
-------------------------

30
The request is sent using an `iq[type=get]` stanza with a `req` element to the device. This request may optionally include references to nodes 
31 32 33 34 35 36 37 38 39 40 41 42
(if the device supports nodes) and field names the request should be limited to. If no field names are provided, all fields names are implied.
If no node references are provided, only devices not supporting nodes are implied. Concentrators should interpret this as an empty request, readong zero nodes.

The request also contains an **Identity**, that will be used to match response messages to the original request. Field **categories** are also included in the
request. The device filters the response, as to only return fields in these categories. The special `all` attribute can be used, to mean all categories.
**Time intervals** can be defined usign a `from` and a `to` attribute. The readout can also be `scheduled`. Distributed transactions can be executed by the
use of [tokens](#tokens).

![Sensor Data Request](Diagrams/SensorDataRequest.png)

### XML representation

43 44 45 46 47 48 49 50 51 52 53
| Entity    | Element   | Use      | Attributes | Type          | Use      | Description                                       |
|-----------|-----------|----------|------------|---------------|----------|---------------------------------------------------|
| Request   | `req`     | Required | `id`       | `xs:string`   | Required | Request identity.                                 |
|           |           |          | `m`        | `xs:boolean`  | Optional | Include momentary values.                         |
|           |           |          | `p`        | `xs:boolean`  | Optional | Include peak values.                              |
|           |           |          | `s`        | `xs:boolean`  | Optional | Include status values.                            |
|           |           |          | `c`        | `xs:boolean`  | Optional | Include computed values.                          |
|           |           |          | `i`        | `xs:boolean`  | Optional | Include identity values.                          |
|           |           |          | `h`        | `xs:boolean`  | Optional | Include historical values.                        |
|           |           |          | `all`      | `xs:boolean`  | Optional | Include all categories of fields.                 |
|           |           |          | `from`     | `xs:dateTime` | Optional | Only return fields not older than this timestamp. |
54
|           |           |          | `to`       | `xs:dateTime` | Optional | Only return fields not newer than this timestamp. |
55 56 57 58 59 60 61
|           |           |          | `when`     | `xs:dateTime` | Optional | Timestamp of when the request is to be executed.  |
|           |           |          | `st`       | `xs:string`   | Optional | Service token.                                    |
|           |           |          | `dt`       | `xs:string`   | Optional | Device token.                                     |
|           |           |          | `ut`       | `xs:string`   | Optional | User token.                                       |
| Node      | `nd`      | Optional | `id`       | `xs:string`   | Required | Node identity.                                    |
|           |           |          | `src`      | `xs:string`   | Optional | Source identity.                                  |
|           |           |          | `pt`       | `xs:string`   | Optional | Partition.                                        |
62
| Field     | `f`       | Optional | `n`        | `xs:string`   | Required | Unlocalized field name.                           |
63 64 65 66 67 68 69 70 71 72 73 74 75 76


Responses
------------

When receiving a request, a device can respond in several manners:

* Returning the sensor data immediately.
* Returning a response, letting the client know the readout has commenced, but data is not yet available.
* Returning a response, letting the client know the request has been accepted, but not yet started.
* Returning an error response.

### Returning sensor data immediately

77
A simple readout just returns the sensor data in a `iq[type=result]` stanza with a `resp` element. This is typically the pattern of small devices having
78 79 80 81 82 83
the current values in internal memory.

![Simple Readout](Diagrams/SimpleReadout.png)

### Slow responses

84
If it takes time to collect the data to return, the device returns a `started` element in an `iq[type=result]` stanza immediately to the client. This allows the
85 86 87 88 89 90 91
client to know the request has been accepted and started, and that data will be sent later. When data is available, it is sent asynchronously to the client,
using the `message` stanza containing a `resp` element.

![Slow Readout](Diagrams/SlowReadout.png)

### Scheduled or queued responses

92
If a request is scheduled or queued for some reason, the device returns an `accepted` element in an `iq[type=result]` stanza back to the client. The client then knows
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
the request has been accepted, and either scheduled for execution at a later time, or queued for execution as soon as the device is able. The `accepted` element
has a `queued` attribute that can be used to let the client know the request has been queued.

![Scheduled Readout](Diagrams/ScheduledReadout.png)

Depending on the type of readout, the device can either send the response back immediately, using a `resp` element in a `message` stanza, or first send a `started` 
element in a separate `message` stanza, before the actual response is returned.

![Scheduled Slow Readout](Diagrams/ScheduledSlowReadout.png)

### Fragmented responses

Responses are allowed to be fragmented. Reasons can be to either fit a large data set into the limited maximum stanza size provided by the XMPP network, 
reporting multiple nodes in separate response messages, or to allow the client to continously follow the progress of a long readout process. Fragmentation
is done by setting the `more` attribute in the `resp` element to `true`. This alerts the client that more is on the way. If the `more` attribute is
omitted, or explicitly set to `false`, no more fragments are expected for the current request.

![Simple Fragmented Response](Diagrams/SimpleFragmentedResponse.png)

Fragmented responses can be used in any of the response patterns described.

![Scheduled Slow Fragmented Response](Diagrams/ScheduledSlowFragmentedResponse.png)

### Completion

It might happen that the device, when sending the last response message, doesn't know it is the last response message. For such cases, a separate `done`
element can be sent in a `message` stanza back to the client, to notify the client the request has been completely processed.

![Asynchronous Completion](Diagrams/AsynchronousCompletion.png)

### Cancelling request

125 126
A request that has been scheduled or queued, can be cancelled. Cancelling a request is done by sending a `iq[type=set]` stanza with a `cancel` element to the 
device, with the identifier used to identify the request. The device responds with an empty `iq[type=result]` stanza. Optionally, a device may also support the 
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
cancellation of ongoing readouts. 

![Cancel Readout](Diagrams/CancelReadout.png)

### Request identities

Request identities are strings. The identities are invented by the client, and are supposed to be unique frrom the full JID of the client
making the request.

### Sensor Data

The `resp` element contains [sensor data](SensorData.md) as payload. If the device supports nodes, `nd` elements should be used to identify which
nodes are reporting sensor data back. If nodes are not supported, the response contains `ts` elements, corresponding to the timestamps where data
is being reported back.

### XML representation

| Entity              | Element    | Use      | Attributes | Type          | Use      | Description                                                                    |
|---------------------|------------|----------|------------|---------------|----------|--------------------------------------------------------------------------------|
| Response            | `resp`     | Required | `id`       | `xs:string`   | Required | Request identity.                                                              |
|                     |            |          | `more`     | `xs:boolean   | Optional | If more data is expected. Default value is `false`.                            |
| Accept notification | `accepted` | Optional | `id`       | `xs:string`   | Required | Request identity.                                                              |
|                     |            |          | `queued`   | `xs:boolean   | Optional | If the request has been queued for later processing. Default value is `false`. |
| Start notification  | `started`  | Optional | `id`       | `xs:string`   | Required | Request identity.                                                              |
| Completion          | `done`     | Optional | `id`       | `xs:string`   | Required | Request identity.                                                              |
| Cancel request      | `cancel`   | Optional | `id`       | `xs:string`   | Required | Request identity.                                                              |
| Request cancelled   | `cancel`   | Optional | `id`       | `xs:string`   | Required | Request identity.                                                              |


Tokens
------------

159 160 161 162
To support distributed transactions, where the identity of the original actors are used to authorize requests, a set of **tokens** can be 
provided in the request. Tokens can be used to identify a **device**, a **service** and a **user**. They can be validated and challenged.
For more information, see the article on [Tokens](Tokens.md).

163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178

Legacy
-------------

The following data model is based on work done in the [XMPP Standards Foundation (XSF)](https://xmpp.org/about/xmpp-standards-foundation.html),
[XEP-0323: Internet of Things - Sensor Data](https://xmpp.org/extensions/xep-0323.html).

Apart from the differences noted in the [Sensor Data document](SensorData.md#legacy), regarding the sensor data representation, here follows a 
list of noteable differences:

* A separation of XML representation and communication pattern has been done.
* Documentation has been simplified.
* Easier to respond for small/quick devices.
* More data is signalled using a `more` attribute, instead of a lack of a `done` attribute.
* The `cancelled` element has been removed.
* Request identities are now strings, instead of sequence numbers.
Peter Waher's avatar
Peter Waher committed
179 180


Peter Waher's avatar
Peter Waher committed
181 182 183
Determining Support
-------------------------

184
Devices supporting the protocol described in this document should advertise this fact, by including the `urn:ieee:iot:sd:1.0` feature in responses to
Peter Waher's avatar
Peter Waher committed
185 186 187
[Service Discover](https://xmpp.org/extensions/xep-0030.html) requests.


Peter Waher's avatar
Peter Waher committed
188 189 190 191 192 193 194 195 196
Examples
-----------------

### Simple readout

Request:

```xml
<iq type='get' from='client@example.org/1234' to='device@example.org/abcd' id='R0001'>
197
  <req xmlns="urn:ieee:iot:sd:1.0" id="00000001" all="true"/>
Peter Waher's avatar
Peter Waher committed
198 199 200 201 202 203 204
</iq>
```

Response:

```xml
<iq type='result' from='device@example.org/abcd' to='client@example.org/1234' id='R0001'>
205
  <resp xmlns="urn:ieee:iot:sd:1.0" id="00000001">
Peter Waher's avatar
Peter Waher committed
206 207 208 209 210 211 212
    <ts v="2017-09-22T15:22:33Z">
      <q n="Temperature" v="12.3" u="C" m="true" ar="true"/>
      <s n="SN" v="12345678" i="true" ar="true"/>
    </ts>
  </resp>
</iq>
```