Sensor Data Request/Response communication pattern

You can retrieve sensor data from a device, or nodes in a device, by sending a request to the device. This document describes this pattern. This document outlines the XML representation of sensor data. The XML representation is modelled using an annotated XML Schema:

Sensor Data
Namespace:	`urn:nfi:iot:sd:1.0`
Schema:	SensorData.xsd

Table of Contents

Motivation and design goal
Requirements
Building the request
1. XML representation
Responses
Tokens
Legacy
Determining Support
Examples
1. Simple readout

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.

Requirements

The Sensor Data namespace defines the following elements that can be sent in stanzas. The following table lists the elements, the type of stanza used, the entities that can or need to handle incoming stanzas containing the corresponding element, as well as implementation requirements, if the namespace is present in the device’s XEP-0030 Service Discovery response. Elements associated with any response stanzas are assumed to be implemented by the entity making the corresponding request. Both the Sensor Client and Sensor Server entities are XMPP clients. The Sensor Data namespace is primarily intended for connected clients. The broker is only involved in routing stanzas between sensor clients and sensor servers.

Namespace elements
Element	Stanza Type	Sensor Client	Sensor Server
`req`	`iq get`	⇒	Required
`accepted`	`iq result`	Required¹	⇐
`started`	`iq result`	Required²	⇐
	`message`	Required³	⇐
`resp`	`iq result`	Required⁴	⇐
	`message`	Required⁵	⇐
`cancel`	`iq set`	⇒	Required
`done`	`message`	Required⁶	⇐

A sensor server can choose to start readout at a later time, and returning the accepted element in the response, to let the client know the request has been received and been accepted, but the sensor data readout has not yet started.
A sensor server can choose to return the started element in the response, to let the client know the request has been accepted, and that the sensor data readout has started, but there are yet no data to return.
If the sensor server responded to the request with an accepted response, it sends the started element in a message stanza, when the readout starts.
The sensor server can choose to return sensor data directly in the response to the request, by returning a resp element in the iq result stanza. This means the request has been accepted, the readout has started, and sensor data is being returned. The sensor data does not have to be complete, and further data can be sent in subsequent message stanzas. This is indicated using a more attribute on the resp element.
If the sensor server has responded to the request using any of the accepted, started or resp elements, any further sensor data reported is sent in separate message stanzas. Any of the resp elements without a more attribute having value true indicates that the readout is complete.
If the sensor server has indicated that more information is to be sent (either by returning accepted or started in the response, but not included any resp messages, or by sending an resp in a message, with a more attribute set to true), but there is no more sensor data to report, a done element is sent in a message to conclude the readout.

Building the request

The request is sent using an <iq type="get"/> stanza with a <req/> element to the device. The request may optionally include references to nodes (if the device supports nodes) and field names the request should be limited to. If no field names are provided, all field names are implied. If no node references are provided, only devices not supporting nodes are implied. Concentrators should interpret this as an empty request, reading 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 using a from and a to attribute. The readout can also be scheduled by using the when attribute. Distributed transactions can be executed by the use of tokens.

XML representation

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
			`to`	`xs:dateTime`	Optional	Only return fields not newer than this timestamp
			`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
Field	`f`	Optional	`n`	`xs:string`	Required	Unlocalized field name

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

A simple readout just returns the sensor data in an <iq type="result"/> stanza with a <resp/> element. This is typically the pattern of small devices having the current values in internal memory.

Slow responses

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

Scheduled or queued responses

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

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.

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

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

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.

Cancelling request

A request that has been scheduled or queued, can be cancelled. Cancelling a request is done by sending an <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 cancellation of ongoing readouts.

Request identities

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

Sensor Data

The <resp/> element contains sensor data 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

Tokens

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.

Legacy

The following data model is based on work done in the XMPP Standards Foundation (XSF), XEP-0323: Internet of Things - Sensor Data.

Apart from the differences noted in the Sensor Data document, regarding the sensor data representation, here follows a list of notable 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 signaled 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.

Determining Support

Devices supporting the protocol described in this document should advertise this fact, by including the urn:nfi:iot:sd:1.0 namespace in the features list in responses to Service Discovery requests.

Examples

Simple readout

Request:

<iq type='get' from='client@example.org/1234' to='device@example.org/abcd' id='R0001'>
  <req xmlns="urn:nfi:iot:sd:1.0" id="00000001" all="true"/>
</iq>

Simple response:

<iq type='result' from='device@example.org/abcd' to='client@example.org/1234' id='R0001'>
  <resp xmlns="urn:nfi:iot:sd:1.0" id="00000001">
    <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>