Sensor Data

This document outlines the XML representation of sensor data. The XML representation is modelled using an annotated XML Schema:

Motivation and design goal

The representation of sensor data described in this document, is designed with the following goals in mind:

• The representation must be loosely coupled with the type of device and the data being represented. Loose coupling guarantees that infrastructure and software components do not need to be updated, by the introduction of new types of devices into the network.

• Sufficient meta-data must be available, to be able to process the data in a generic sense and create both Machine-to-Machine (M2M) and Human-to-Machine (H2M) interfaces automatically.

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.

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

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

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

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

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

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

Conceptual model

The XML representation of Sensor Data used by the Neuro-Foundation IoT interfaces is based on a three or four level abstraction:

Either the device is a simple device, with one identity, or it consists of a set of nodes. The latter is also sometimes referred to as a concentrator, as it concentrates several nodes, or virtual devices, into one entity. Each device then reports a set of fields (or errors), each stamped with a timestamp to which they correspond. In XMPP, devices are addressed using an XMPP Address, also referred to as a Jabber ID or a JID.

The nodes are identified using one to three identifiers, depending on the size and needs of the concentrator. The required attribute, is the Node ID. The Source ID allows a concentrator to divide the set of nodes into different data sources. If data sources are not used, this attribute can be omitted. Partitions allow the concentrator to divide a data source into multiple pieces. This attribute can also be omitted, if not used. It is the triple (Node ID, Source ID, Partition) that must be unique inside the device.

XML representation

Fields

The sensor data model defines different types of fields, depending on the data type required to represent its value.

XML representation

Common field attributes

The different field types share a set of common attributes. All fields include the required name, then optional localization information for languages, and if the field corresponds to a control parameter with the same name. More on localization below. The field can also be annotated with category and quality of service information.

Field categories

Apart from the field type, each field can also be categorized using a set of category attributes. These can be used in requests, to limit responses to certain categories. The categories can also be combined.

Quality of service

Individual fields can also be annotated with Quality of Service information, using a set of predefined attributes:

Some of the Quality of Service levels are mutually exclusive, others can be combined. Some introduce a natural order of “quality”, that can be used to decide if a reported value is has a higher quality, and thus can overwrite an existing value of lesser quality:

ms < ms+so < pr < pr+so < ae < ae+so < me < me+so < mr < mr+so < ar < ar+so < so < iv < iv+so < ic < ic+so

The significance of the so attribute is to tell the system the value has been signed by an authorized human operator and can thus be used to override existing values.

Custom extensions

Each field can be extended using custom elements and custom attributes. This is done by including an <x/> element as a child node to the corresponding field node. The <x/> element can take any number of attributes and child elements of any type. Note however, that only fully qualified elements and attributes, that have been approved by a standards group can be used for interoperable features.

Errors

Errors can be reported at the same level as fields in the sensor data model. It is done using the <err/> element. It is a simple type of type xs:string.

Localization

The sensor data model allows for localization of field names. The required name attribute n defines the field, while the optional lns and loc attributes can be used to localize the name. The possibility to localize field names, however, should not discourage the use of human readable names on fields. Instead, the localization parameters should be seen as a way to represent the field name in multiple languages in human interfaces.

The principle behind localization, is the use of namespaces, and then identifying each translatable element of a string, with a positive integer in that corresponding namespace. The translation of a string can then be made using a sequence of translation steps, each one consisting of a String ID, an optional Namespace and an optional Seed value. The localized string in each step, can include the values %0%, corresponding to the result of the previous step, and %1%, corresponding to the seed value. If no namespace is provided, the default namespace is used, which is provided in the lns attribute. The loc attribute is then formed of the individual translation steps delimited by commas (,). The different parts of each step are delimited using pipe characters (|).

In the following examples, assume lns="NS":

Note: Providing localized strings, ordered by namespace and language, would be the only components required to be updated in software supporting the architecture described in this document. But such strings constitute data, and not code, so no actual software updates are required. Furthermore, interfaces will still work without the actual localized versions of the strings, if human readable strings are chosen as default field names when reporting fields. Preferable, all field names are chosen in a globally understood language, such as English.

Control parameters

If reporting sensor data from an actuator, you can highlight the correlation of sensor data fields with the corresponding control parameters having the same name, by using the ctr attribute on the corresponding field. If the field name appears multiple times in the sensor data readout, only the momentary value should be flagged with the ctrattribute.

Legacy

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

• A Neuro-Foundation namespace is used.
• Names of elements and attributes have been shortened.
• A separation of XML representation and communication pattern has been done.
• The schema is now annotated.
• Historical periods have been removed and replaced with a single historical field category.
• It is possible to customize the annotation of fields.
• Sensor data spanning multiple messages are correlated using a string-valued id attribute, instead of a sequence number.
• The node element is now optional.
• Localization is somewhat simplified.
• Errors can now be embedded with the sensor data and is not related to the communication pattern.
• Documentation has been simplified.
• It has been made easier for small/quick devices to respond.
• A more attribute is used instead of a done attribute.

Examples

A simple example containing sensor data from a temperature sensor.

<ts v="2017-09-22T15:22:33Z" xmlns="urn:nfi:iot:sd:1.0">
  <q n="Temperature" v="12.3" u="°C" m="true" ar="true"/>
  <s n="SN" v="12345678" i="true" ar="true"/>
</ts>

If this temperature sensor would be a node inside a concentrator, the same data would be represented as:

<nd id="Node1" xmlns="urn:nfi:iot:sd:1.0">
  <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>
</nd>