%ents;
]>
Sensor-Over-XMPPThis specification defines a payload format for communicating sensor and actuation information. The payload format is transported using the publish-subscribe mechanism described in XEP-0060.This XMPP Extension Protocol is copyright (c) 1999 - 2011 by the XMPP Standards Foundation (XSF).Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).xxxxProtoXEPStandards TrackStandardsCouncilXMPP CoreXEP-0001XEP-0060XEP-0082soxGauravBhatiagauravbhatia@cmu.eduAnthonyRoweagr@ece.cmu.eduMarioBergesmarioberges@cmu.eduCharlesSpirakiscss@google.com0.0.182011-04-08css

Add data element to enclose transducerValue and transducerSetValue.

0.0.172011-03-25css

Cleanup typo's and wording.

0.0.162011-03-24css

Move device type and units into the xsd.

0.0.152011-03-23css

Text and example cleanup.

0.0.142011-03-22css

First attempt at how/why split.

0.0.132011-03-10gnb

Minor cleanup.

0.0.122011-03-10css

Change TransducerValue packet's TypedValue from float to string.

0.0.112011-03-03css

Grammar cleanup and minor clarifications.

0.0.102011-03-02css

Move requirements to top. Add optional X_Y event node.

0.0.92011-03-02mbg

Expanded definition of Transducer. General cleanup.

0.0.82011-03-01css

More cleanup.

0.0.72011-03-01css

Adjusted requirements section. More cleanup.

0.0.62011-02-28css

Clean up typos and examples.

0.0.52011-02-27css

Added use cases and examples.

0.0.42011-02-24css

Update xsd and corresponding descriptions.

0.0.32011-02-23css

Add clarifications.

0.0.252011-1-23mbg

Added content to the How it Works section.

0.0.22010-11-18agr

Added some use cases.

0.0.12010-11-18gnb

First draft.

This document defines a payload format for exchanging sensor and actuator data which can be implimented using a generic Publish-Subscribe service as described in XEP-0060.
It can be used as a foundation to support a wide variety of applications including: power distribution metering, home automation, monitoring and control of heating and cooling systems, infrastructure monitoring, etc.

The goal of this XEP is to support ubiquitious, large-scale monitoring, operation and control of infrastructure in a way that is extensible, easy to use and secure.
To achive this, the specific requirements are:

Provide a common data structure and access method between producers and consumers to foster interoperability.

Allow multiple consumers of sensor information to access data from resource constrained producers with minimal burdon on the producers.

Provide a mechanism whereby an entity is notified when new sensor data is available (i.e. allow consumers of data to avoid polling).

Provide a mechanism whereby an entity is notified when a control request is made (i.e. allow controllers to avoid polling while waiting for work).

Provide a mechanism whereby an entity that requests an action can get confirmation that the action has occured.

Provide a mechanism whereby an entity is notified that an action has occured (i.e. allow requestors to avoid polling while waiting for confirmation).

Provide security such that an authoritative entity (such as an administrator) can decide which consumers are allowed access to which producers.

The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a transducer using the pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)

Sensor

A device that measures a physical quantity.

Actuator

A device for moving or controlling a mechanism or system.

Transducer

A device that is a Sensor or Actuator or both. Transducers can also be virtualized, in the sense that they may not necessarily refer to the physical device that is directly measuring or controlling a phenomena, but rather to a software agent that serves as an intermediary.

PubSub Service

An XMPP server or component that adheres to the protocol defined in &xep0060;.

Creator / Owner

An entity that created a node and is automatically a publisher and subscriber.

Subscriber

An entity that is allowed to subscribe to a node.

Publisher

An entity that is allowed to publish items to a node and that is automatically subscribed to the node.

Adapter

An entity that converts native transducer values into XMPP messages and vice-versa.

Agent

An XMPP client that consumes or produces data that is not an adapter. For example a piece of software that collects temperature and humidity data to compute dew-point.

To ensure uniquness, a logical device SHOULD be identified by
a universal unique identifier (UUID) as defined by RFC 4122.
Consumers of logical device data need information about the transducers on the device (meta data) as well as the data values themselves.
If the XMPP service is capable of handling pub-sub collections (XEP-0248: PubSub Collection Nodes), the node id for the collection node SHOULD be the UUID as defined above.
The meta data for the device SHOULD be a leaf node child of the collection node with the name "meta" and the data values for the device SHOULD be a leaf node child of the collection node with the name "data".

If the XMPP service is not capable of handling pub-sub collections, the node id for the meta data SHOULD be in the form of the UUID followed by "_" followed by (what would be) the leaf child node id.
Thus, for the meta data, the node id would be UUID_meta and the data value node id would be UUID_data.

For the rest of the document, we will assume that the XMPP service is a basic XEP-0060 compliant service only and use the UUID_??? naming scheme for node id.

Adapter publishes device meta data:
]]>

If the meta node is configured to include payloads, the subscribers will receive payloads with event notifications:

]]>

Attribute

Description/Purpose

name

A human friendly name for the device

id

A unique identifier for the logical device. This SHOULD be the UUID that corresponds to the logical device.

type

The type of the transducer platform (see below)

timestamp

Format as defined in
XEP-0082: XMPP Date and Time Profiles.

description

A human friendly description of the device

serialNumber

A serial number or other unique identifier for the physical device

Attribute

Description/Purpose

name

A human friendly identifier to distinguish between various possible transducers within a device

id

A unique identifier for the transducer used within the XML packet to enumerate different transducers within a single packet
The tuple (UUID X, transducer id Y) MUST be unique such that a publish operation to a data value node X_data with the transducer id Y unambiguously refers to one and only one transducer.

units

Unit of measure (see below)

unitScaler

The scale of the unit as a power of 10 (i.e. n for 10 ** n)

canActuate

Indicates whether the transducer can be actuated

hasOwnNode

Indicates whether the transducer data has its own node or whether it is part of the generic data value node (see below)

transducerTypeName

A human readable indication of the type of transducer

manufacturer

Manufacturer of the transducer

partNumber

Manufacturer's part number of the transducer

serialNumber

Manufacturer's serial number of the transducer

minValue

The expected minimum value for this transducer

maxValue

The expected maximum value for this transducer

resolution

The resolution of the values reported by this transducer

precision

The precision of the values reported by this transducer

accuracy

The accuracy of the values reported by this transducer

To make it easier for agents to sort through available devices and seonsors, it is desirable for implementations to use a common set of types. The following device types are defined:

Type

Description/Purpose

indoor weather

Temperature, humidity, etc sensors located indoors (such as in a building)

outdoor weather

Temperature, humidity, etc sensors located outdoors (such as a rooftop)

hvac

Sensors and controls associated with a Heating, Ventilating and Air Conditioning (HVAC) system

Sensors and controls associated with electricity, gas, water or other resource consumption

resource generation

Sensors and controls associated with electricity, gas, water or other resource generation

other

Other type that isn't listed above

For the sake of interoperability, implementations SHOULD transform native sensor units into the closest relevant SI form. SI units are defined based on
SI conventions as shown in the The Unified Code For Units of Measurement.

After specifying the units of the transducer device, you can then also specify an SI scalar value as powers of 10. The following example shows how to specify a sensor in centimeters.
]]>
The following example shows how to specify a sensor in kilograms.
]]>
The following example shows how to specify a sensor in kilowatt-second with a resolution to the nearest 0.1 kWh.
]]>
If no unitScaler value is specified, then a unitScaler of 0 (aka 10**0 = 1) is assumed.

Values for a transducer are published via the data value node:
]]>

If the data value node is configured to include payloads, the subscribers will receive payloads with event notifications:

]]>

Attribute

Description/Purpose

id

The transducer id.
This MUST correspond to a transducer Id as defined in the transducer packet.
The tuple (UUID X, transducer id Y) MUST be unique such that a publish operation to a data value node X_data with the transducer id Y unambiguously refers to one and only one transducer.

typedValue

The value representing the transducer data which is in the units as defined in the transducer units attribute

timestamp

Format as defined in
XEP-0082: XMPP Date and Time Profiles.

rawValue

The raw value as seen by the transducer. The rawValue can be used to record a non-unit converted value for record keeping (e.g. a raw ADC value before calibration).

OPTIONAL: Instead of putting all of the transducer values into a single data value node, an adapter MAY want to break up the transducer values into multiple nodes.
For example, an adapter may want to do this for reasons of security (allow some entities to subscribe/publish to transducer Y1 and a different set of entities to subscribe/publish to transducer Y2).

As mentioned earlier, if the XMPP service is capable of handling pub-sub collections (XEP-0248: PubSub Collection Nodes), the node id for the collection node SHOULD be the UUID and the leaf child node SHOULD have the same node id as the transducer id listed in the meta node.

If the XMPP service is not capable of handling pub-sub collections, adapters which want to create nodes for individual transducers SHOULD use a node id of the form X_Y where X is the UUID for the device and Y is the transducer id as listed in the UUID_meta node.

]]>

If the fan node is configured to include payloads, the subscribers will receive payloads with event notifications:

]]>

If an adapter chooses to put the transducer value in its own node, it MUST indicate this in the meta node via the Transducer's hasOwnNode field.

NOTE: For every transducer listed in the UUID_meta node, the transducer value MUST be provided in either the UUID_data node or its own UUID_TransducerId node, but not both.
The information in the meta node is used by consumers to determine which node they should subscribe to in order to be notified when new data is available for their chosen transducer.

Values for a transducer can also be set by publishing to the data value node.
]]>

If the data value node is configured to include payloads, the subscribers will receive payloads with event notifications:

]]>

Per the optional note above. If a transducer has the "hasOwnNode" attribute set in the UUID_meta node, then the value set would be done via the UUID_TransducerId node as described above.

]]>

If the fan node is configured to include payloads, the subscribers will receive payloads with event notifications:

]]>

Attribute

Description/Purpose

id

The transducer id.
This MUST correspond to a transducer id as defined in the transducer packet.
The tuple (UUID X, transducer id Y) MUST be unique such that a publish operation to a data value node X_data with the transducer id Y unambiguously refers to one and only one transducer.

typedValue

The value representing the transducer data which is in the units as defined in the transducer units attribute

rawValue

The raw value to be passed to the transducer.
If the adapter can verify that the raw value is an allowable value for the transducer, it SHOULD allow the raw value to take precedence over the typedValue if provided.

Actuation takes place as a split-phase operation with an action signal (publish) followed by a completion callback (subscribed message).
First, adapters that support actuators are required to subscribe to their respective actuator nodes.
An agent can publish an actuation request to the node which is then translated by the adapter into a native command for the actuator.
Once the actuator operation has completed its transaction, a new state value is published back to its node.
This last step allows an interested agent to subscribe to this node to confirm the requested action has completed.

There is the possibility of contention if multiple users attempt to actuate the same device.
This arbitration SHOULD happen at a higher control layer.
Any interested agent can always verify the latest state of the actuator by subscribing to the actuator's node.

The use cases below show examples of the publish side of this protocol.
Event notifications, errors, etc. are all described in XEP-0060 and are not included in the examples below.

A data logging agent does not need to create or publish any nodes.
Instead, it would use the XMPP pub/sub disco# ability to list available nodes and contact the admin entity to subscribe to nodes of interest.
Once subscribed, it can log events, populate an external database (such as MySQL) to allow access to historical information regarding sensors and actuators, provide external notifications based on particular events, etc.
Since the mechanism for setting a transducer uses the same pubsub node as showing the transducer's value, logging style entities can also do auditing, independant validation that a device is responding, timing of acutator set/response, etc.

Lady Capulet has purchased an energy monitoring device for use in her home.
The sensor used is accurate to the nearest 10 Wh.

]]>

Later, Lady Capulet adds a second energy sensor to the monitoring device purchased above.
The new sensor is more accurate and can measure to the nearest 1 Wh.
The adapter provides this additional information in the meta node and data value node.

minValue='0' maxValue='100' resolution='0.01'/>
]]>

Lord Montague purchases a web camera which can sense movement and has a light which can be turned on or off.
He also has an agent which responds to the camera motion detector by turning on the camera light in the hopes of catching Romeo sneaking out at night.
For security reasons, it is desired to allow an agent to publish to the
light (i.e. control the light), but not the motion sensor.
To provide for this,
the adapter implements the OPTIONAL ability that allows a transducer value to have its own node.

]]>

When there is movement, the following would be published by the camera adapter.

]]>

Two things to note:

The tuple ('4d4335b5-4134-11e0-9207-0800200c9a66_data', 'tid1') uniquely identifies the motion sensor for this camera adapter.

It is not relevant to the subscriber of this node (the consumer of information) whether the camera has motion detection built in or whether the adapter is capturing images from the camera and using its own methodology for determining motion.

To continue this example further, let's assume an agent is subscribed to the data value node and can also publish to the tid2 node which controls the light.
In this case, an agent will receive notification that movement was sensed and can take action.
One action could be to turn on the light, in which case the agent would publish:

]]>

In response, the camera adapter would turn on the light and publish an acknowledgement.

]]>

In response to this the agent could start recording the video, send an email, use the XEP-0166 (Jingle) extension to send the video to an XMPP client, etc.

Juliet purchases a smartphone and connects it to the diagnostic bus of her chariot. She is interested in capturing real time information regarding the chariot's location and performance.
The smartphone is providing some of the data (accelerometer and GPS) while the chariot diagnostic bus is providing the rest (horsepower, engine information, etc).

Note: it is not relevant to the consumers of the data which sensors are connected to the smartphone and which are not.
Consumers only need to know the UUID for the chariot adapter's logical device and the corresponding transducer id's to access the specific transducer data by subscribing to the node(s) of interest.
The chariot adapter (potentially running on the smart phone) hides the details of data acquisition.

Note: normally engine information is provided as rotations per minute (rpm), but the "on-wire" format should use the base units provided above - in this case hertz is a measure of cycles (or rotations) per second.
Thus, the adapter would be required to convert rpm into hertz (i.e. multiply the rpm value by 60 to get hertz) before publishing and an agent could optionally convert the value back to rpm for display.

serialNumber='license: HI 2ABC123'
]]>

Since the timestamp indicates the time of data collection, the adapter could store some of the sensor values and then batch publish the values to the data value node.
Consumers of the data value node information would get delayed results (increased latency), but this mechanism may provide for improved bandwidth (fewer pub/sub notification overhead for each "unit" of data).

NOTE: It is permissible to publish a subset of transducers in the data value node (such as in this example).
If an adapter chooses to publish a subset of transducer data (for example, only
the changed values), it is possible for consumers who are off line or recently
activated to miss older values.
There are a variety of ways to handle this depending on the needs of the
implementor including (but not limited to):

Increase the history size of the node in the xmpp server so old entries can be obtained

Have the adapter periodicly update all values in the data value node

Put infrequent events in their own nodes and use data value node for frequent events

Put frequent events in their own nodes and use data value node for infrequent events

If an implementaion chooses to put some transducers values into their own nodes
(instead of putting them all into the data value node), remember that a transducer value MUST appear in either the data value node or its own node, but not both.
The meta node indicates to consumers which node they should subscribe to in order to be notified when new data is available for their chosen transducer.

One could carry this further to allow Lord Capulet to keep track of all the chariots in his fleet.
For example, the logging agent described above could be used to keep historical information (including location and performance) for all of the vehicles in his fleet.
We will leave it as an exercise for the reader to ponder the implications of allowing chariot transducers to be modified on the fly via non-local agents.

Whether or not additional nodes are needed depends on how the information is combined.
For example, an adapter could be written to compute the distance a vehicle is from a particular point and the result could be a published to a new node that other adapters and agents could use in their calculations.

The Data Forms shown in this specification include English-language labels for various fields; implementations that will display such forms to human users SHOULD provide localized label text for fields that are defined for the registered FORM_TYPEs.

The publication of sensor information is not known to introduce any new security considerations above and beyond those defined in
XEP-0060 and XMPP Core.

This document does not require interaction with &IANA;.

The &REGISTRAR; includes "http://jabber.org/protocol/pubsub" and "http://jabber.org/protocol/pubsub#errors" and "http://jabber.org/protocol/pubsub#event" and "http://jabber.org/protocol/pubsub#owner" in its registry of protocol namespaces.

The protocol documented by this schema is defined in
XEP-????: http://xmpp.org/extensions/xep-????.html
]]>