<abstract>This 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.</abstract>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2011 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>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.</permissions>
<warranty>## 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. ##</warranty>
<liability>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.</liability>
<conformance>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 <<linkurl='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
<p>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 <linkurl='http://www.xmpp.org/extensions/xep-0060.html'><cite>XEP-0060</cite></link>.
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.
<li>Provide a common data structure and access method between producers and consumers to foster interoperability.
</li>
<li>Allow multiple consumers of sensor information to access data from resource constrained producers with minimal burdon on the producers.
</li>
<li>Provide a mechanism whereby an entity is notified when new sensor data is available (i.e. allow consumers of data to avoid polling).
</li>
<li>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).
</li>
<li>Provide a mechanism whereby an entity that requests an action can get confirmation that the action has occured.
</li>
<li>Provide a mechanism whereby an entity is notified that an action has occured (i.e. allow requestors to avoid polling while waiting for confirmation).
</li>
<li>Provide security such that an authoritative entity (such as an administrator) can decide which consumers are allowed access to which producers.
</li>
</ol>
</section1>
<section1topic='Glossary'anchor='glossary'>
<p>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.)</p>
<dl>
<di><dt>Sensor </dt><dd> A device that measures a physical quantity.</dd></di>
<di><dt>Actuator </dt><dd> A device for moving or controlling a mechanism or system. </dd></di>
<di><dt>Transducer </dt><dd> 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.</dd></di>
<di><dt>PubSub Service </dt><dd> An XMPP server or component that adheres to the protocol defined in &xep0060;.</dd></di>
<di><dt>Subscriber</dt><dd>An entity that is allowed to subscribe to a node.</dd></di>
<di><dt>Publisher</dt><dd>An entity that is allowed to publish items to a node and that is automatically subscribed to the node.</dd></di>
<di><dt>Adapter</dt><dd>An entity that converts native transducer values into XMPP messages and vice-versa.</dd></di>
<di><dt>Agent</dt><dd>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.</dd></di>
<p>To ensure uniquness, a logical device SHOULD be identified by
a universal unique identifier (UUID) as defined by <linkurl='http://tools.ietf.org/html/rfc4122'><cite>RFC 4122</cite></link>.
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 (<linkurl='http://xmpp.org/extensions/xep-0248.html'><cite>XEP-0248</cite></link>: 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.
</p>
<p>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.
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.
<p>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:
<p>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 <linkurl='http://aurora.regenstrief.org/~ucum/ucum.html'>The Unified Code For Units of Measurement</link>.
</p>
<p>
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.
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.
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).
<p>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).
</p>
<p>
As mentioned earlier, if the XMPP service is capable of handling pub-sub collections (<linkurl='http://xmpp.org/extensions/xep-0248.html'><cite>XEP-0248</cite></link>: 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.
</p>
<p>
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 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.
</p>
<p>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.
<p>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.
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.
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.
<p>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.
<li>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.</li>
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 response to this the agent could start recording the video, send an email, use the <linkurl='http://www.xmpp.org/extensions/xep-0166.html'><cite>XEP-0166</cite></link> (Jingle) extension to send the video to an XMPP client, etc.
<p>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).
</p>
<p>
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.
<p>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).</p>
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.
<p>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.</p>
<p>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.</p>
<p>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.</p>
The publication of sensor information is not known to introduce any new security considerations above and beyond those defined in
<linkurl='http://www.xmpp.org/extensions/xep-0060.html'><cite>XEP-0060</cite></link> and <linkurl='http://tools.ietf.org/html/rfc3920'><cite>XMPP Core</cite></link>.
<p>The ®ISTRAR; 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.</p>
