There are a growing number of Internet connected devices that sense and actuate physical elements in the environment. A variety of applications exist that would benefit from sharing information between these types of devices. XMPP provides an easy-to-use, decentralized and secure communication mechanism that is ideal for supporting these types of sensing and control applications.

The “publish-subscribe” design philosophy is very well suited for interfacing with sensor and actuator systems for the following reasons. First, subscription-based data dissemination shelters resource-constrained devices from external requests. In many cases, a transducer exists at the leaf-node of a system that is resource constrained (i.e. a temperature sensor as part of a BACnet network) and could not practically push or reply to tens or hundreds of data requests. Second, presence information as well as push-based asynchronous distribution of data helps decouple timing requirements between data producers and consumers. Devices can easily declare that they are active and then push data to subscribers at their preferred rate. Finally, XMPP’s provides decentralized addressing, authentication, encrypted communication as well as per-node access control for these devices. With the addition of a common messaging schema, this provides an ideal platform for the sharing of sensor data.

Internet-connected devices that interface with transducers can leverage XMPP communication infrastructure to allow remote monitoring and control of physical phenomena. Each one of these devices can be associated with one or more XMPP event nodes through which it is able to communicate with XMPP users following the access control rules defined by the XMPP server. Without the extension described herein, there are a couple of obstacles to doing this. The first, is the need for a common and extensible messaging schema for describing the properties of the transducer as well as the data that is being communicated. Such a sechema is defined in this document in later sections. The second, equally important, issue is that for this to work properly there needs to be a set of recommended guidelines to follow when developing the software components required to produce and consume the data being exchanged.

In general terms, the exchange of information can be described very briefly. In the case of sensing, a transducer (e.g., a temperature sensor, a power meter) is interfacing with an internet-enabled device (e.g., a smart phone, a computer) through a software entity running on this device, that is able to collect measurements from the transducer, perform some local processing and publish a value of interest to a pre-specified XMPP event node. We refer to this piece of software as the adapter. At the other end of the communication channel, software agents that are subscribed (and have proper access) to this event node will receive the pushed message and, given that it is using a common schema, will be able to parse it and process the data however they choose to.

For actuation, a similar process is followed. A transducer, in this case an actuator, is interfacing with an internet-enabled device running an adapter. This adapter is able to communicate with both the XMPP server and the actuator. An XMPP event node is used to communicate the actuation commands as well as the state of the actuator. By default, the adapter will be subscribed to this event node. When an actuation message is published to the event node, the adapter will receive the message, parse it, and issue the appropriate actuation command. The resulting state of the transducer or controlled element after this actuation will then be published back to the same event node by the adapter. In this way, the software agent that originally issued the actuation command can receive an acknolwedgement through the same XMPP event node.

In essence, one can look at the device/adapter model described here as being analogous to the device/device driver model used by operating systems. In the case of an operating system, device drivers work with physical devices (i.e. keyboards, serial ports, disk drives, etc) as well as software-only devices (i.e. ramdisks, loopback devices, etc) to create a common access method (i.e. block and character devices). In this case, adapters work with devices that have a variety of device specific access controls, attributes and access methodologies to create a common access method - specifically the common access method described here. Continuing this anaolgy, an agent is an entity that interacts with the information provided by one or more adapters in much the same way that an application interacts with information provided by one or more device drivers.

An event node is a pubsub node created for any piece of information that needs to be broadcast to multiple users or observers. The most common use case is an event node for each Device that consists of multiple sensors and actuators. An event node can also be created for each transducer if such granularity is desired. Event nodes are created with specific IDs which serve as unique identifiers.

There are two types of XMPP accounts that are involved: Admin and Users.

Users are entities that serve as publishers or subscribers of information being exchanged through an Event Node. A Publisher sends information to an event node, and a Subscriber receives information from an event node, in accordance with the definitions within the pubsub protocol. In this context, "user" may not be associated with a person, but rather is used as a way to provide security so that one can define which entities are allowed to access and/or control other entities.

Admin is the entity that has the ability to choose which users are allowed to communicate with which other users. For example, if one user is a temperature sensor, a second user is a heater control and a third user is a thermostat agent, the admin would setup access so that the temperature sensor JID is a publisher for an event node T, the heater control JID is a subscriber for event node H, and the thermostat agent JID is a subscriber to event node T and a publisher to event node H.

The "Device" is a top-level encapsulation entity that contains a list of transducers or transducer properties.

This data tends to change infrequently.

The "Transducer" element contains information about a particular transducer. A "Device" can contain multiple transducers which may or may not have a physical counterpart. For instance, a thermistor is a transducer (a sensor) that directly measures a physical phenomena (temperature). However, other transducers such as an occupancy sensor, a dew point sensor or a mobile robot, exist as virtual transducers given that the relationship between them and the physical phenomena being measured and control is not straightforward.

This data tends to change infrequently.

The protocol documentation for the Location type is defined in XEP-0080.

It is possible to define new name-value pairs to extend the protocol if required. Only use this if no other schema value captures the property since other clients will not understand custom data in these fields. For example, CMU uses a "dataHandlerId" property name to provides a way to tie the transducers and the devices to an application-specific meta-data repository. Specifically, the "dataHandlerId" property value contains a unique database key for logging individual transducer values.

An agent could be created that subscribes to all event nodes in the system and populates an external database (such as MySQL) so that others can look at historical information regarding sensors and actuators. Since this is an agent, there is no event node that it owns, but instead it scans a list of available event nodes and subscribes to all of them.

A consumer has purchased an energy monitoring device for use in her home. An adapter is written to grab data from the device and presents it in the format described in this document.

NOTE: How the adapter gets the data is irrelevant. It could be reading values from a usb port, it could be scraping a web page provided by the device, it could be something else. The details for getting the data are the responsibility of the adapter and are not relevant to the consumers of the data.

A month later, the same consumer adds a second energy sensor to the monitoring device purchased above. The adapter can then include the additional information.

The occupant of a building wants to automate the temperature control for his building. There are two temperature sensors indoors and a weather station on the roof. The heating unit has a simple on/off control. The A/C unit has four settings: off, low, medium and high. An agent will be used to combine the various temperature sensors to turn the heater on/off and the setting for the A/C unit.

A consumer has a web camera which can sense movement and has a light which can be turned on or off. An agent will be used to monitor when motion has occured, turn on the light, and, using XEP-0166 (Jingle), initiate a connection to an XMPP client to allow a human to watch the motion.

A car enthusiast purchases an iPhone and connects it to the OBDII diagnostic bus of her car. An adapter is run on the iPhone to capture sensor data from the iPhone as well as sensor data from the car and send it wirelessly to her home XMPP server. This example is unusual in that data which is normally thought of as relatively static (location) is actually very dynamic (lat/long of the car).

This example is also similar to a business owner interested in tracking the performace of a fleet of vehicles. Instead of capturing and transmitting the information for a single car, the fleet owner would capture and transmit information for each vehicle.

A single XMPP server is likely to be able to handle all of the above interactions and more. Further, as more adapters are added, additional capabilites become available. For example, a "nearby" adapter could subscribe to vehicle information event nodes and publish to its own event nodes the distance to the vehicles from a know point (such as a home). A home automation system could then subscribe to the "nearby" event information and make decisions related to heating and cooling as well as energy conservation (for example, as the occupents get closer to the home, the home automation system could start adjusting the temperature, turn on lights, etc). A data logger as described above would allow data logging of all the events in the system. Even as new adapters, agents and events are added, the adapters and agents would not need to implement their own logging mechanism.

To reduce the amount of information being exchanged and allow for more efficient software development, we recommend creating pairs of event nodes instead of single event nodes for each device or transducer. The pair would consist of a "data" event node, and a "meta-data" event node. The former, would be restricted to messages that communicate data values from sensors and actuation commands (the dynamic part of the schema), weheras the "meta-data" nodes will be restricted to messages utilizing the other parts of the schema (the relatively static part) which describes the transducers and their properties.

For the sake of interoperability, we suggest the following naming conventions for event nodes:

• Each event node SHOULD be composed of a universal unique identifier (UUID) as defined by RFC 4122.
• Additionally, if the above implementation note is followed, this UUID SHOULD be followed by either "_data" or "_meta".

Thus, for the schema shown above, the Device and Transducer would all be part of the UUID_meta event node and the TransducerValue and TransducerCommand would be part of a corresponding UUID_data event node.

OPTIONAL: Instead of putting all of the transducer values into a single UUID_data event node, an adapter MAY want to break up the transducer values into multiple event 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). Since the tuple (event node id X, transducer id Y) MUST be unique (see above), adapters which want to create event nodes for individual transducers MUST use an event node 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 event node.

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

NOTE: For every transducer listed in the UUID_meta node, the transducer value MUST be provided in either the UUID_data event node or its own UUID_TransducerID event node, but not both. The _meta data indicates to consumers which event node it should subscribe to in order to be notified when new data is available for their chosen transducer.

To expand on the example provided above where there is a temperature event node T and a heater control node H, there would actually be 4 event nodes:

1. Event node T_meta which contains the device and transducer XML information for the temperature sensor.
2. Event node T_data which contains the transducer value XML information for the temperature sensor.
3. Event node H_meta which contains the device and transducer XML information for the heater control.
4. Event node H_data which contains the transducer value and transducer command XML information for the heater control.

• The temperature sensor adapter would be a publisher for T_meta and T_data.
• The heater control adapter would be a publisher for H_meta and a subscriber to H_data.
• The thermostat agent would be a subscriber to T_meta, T_data, H_meta and would be a publisher to H_data.

To make it easier for agents to sort through available adapters, it is desirable for implementations to use a common set of types. The following are recommended types:

For the sake of interoperability, it is desirable for implementations to transform native sensor units into the closest relevant SI form. In order to avoid multiple instances of the same unit name, we suggest using the SI conventions for units shown in the The Unified Code For Units of Measurement. When listing the units for each sensor, please include only the name and do not use the symbols (they are listed below just for reference). The following table summarizes frequently used units:

After specifying the units of the transducer device, you can then also specify an SI scalar prefix value. 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-hours with a resolution to the nearest 0.1 kWh. ]]> If no prefix value is specified, then a base scalar of 1 is assumed. The following table contains the common SI scalar prefix names:

Prefix	Abberviation	Factor	Example
yotta	Y	1 000 000 000 000 000 000 000 000
zeta	Z	1 000 000 000 000 000 000 000
exa	E	1 000 000 000 000 000 000
peta	P	1 000 000 000 000 000
tera	T	1 000 000 000 000
giga	G	1 000 000 000
mega	M	1 000 000
kilo	k	1 000	kilogram, 1 kg = 1,000 g
hecto	h	100	hectoliter, 1 hL = 100 L
deka	da	10	dekameter, 1 dam = 10 m
		1	meter, liter
deci	d	.1	decigram, 1 dg = 0.1 g
centi	c	.01	centimeter, 1 cm = 0.01 m
milli	m	.001	milliliter, 1 mL = 0.001 L
micro	u	.000 001	micrometer, 1 μm = 0.000 001 m
nano	n	.000 000 001
pico	p	.000 000 000 001
femto	f	.000 000 000 000 001
atto	a	.000 000 000 000 000 001
zepto	z	.000 000 000 000 000 000 001
yocto	y	.000 000 000 000 000 000 000 001

Timestamps MUST be expressed as UTC values in one of the two formats described below. Adapters and agents are expected to convert between local time and UTC time if needed.

Timestamp values can be provided in a subset of the format defined in RFC 3339. If using the RFC 3339 style format, timestamps MUST be provided only in the form YYYY-MM-DDThh:mm:ss.sssZ where:

• YYYY is the four digit year
• MM is a two digit month
• DD is the two digit day
• T is the literal character 'T' to separate the date from the time
• hh is the 24 hour-per-day hour
• mm is the minutes
• ss.sss is the seconds with optional fractional seconds
• Z is the literal character 'Z' to indicate the timestamps are UTC

As an alternative, the timestamp can be formatted as a 64-bit sensor value composed of 32-bits of seconds and 32-bits of nanoseconds represented in hexidecimal form since the Unix epoch (aka seconds since Jan 1, 1970). If using this format, it MUST be encoded in the following form: SSSSSSSSnnnnnnnn where:

• SSSSSSSS represents the 4-byte hex value of seconds since the Unix time epoch
• nnnnnnnn represents the 4-byte additional nanoseconds value

Consumers of the timestamp data SHOULD look for the literal character 'T' in the eleventh position of the timestamp string to determine if a subset of RFC 3339 format was used or the 64-bit hex format.

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 event nodes. An agent can publish an actuation request to the event 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 event node. This last step allows an interested agent to subscribe to this event 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 event node.

To complete the example provided above where there are temperature event nodes T_meta and T_data and heater control nodes H_meta and H_data, the heater control adapter would also be a publisher for event node H_data so that it can publish the fact that it has turned the heater on or off. Finally, the thermostat agent could choose to subscribe to event node H_data so that it can confirm that the heater control has acted upon its request.

A data logging agent does not need to create or publish any event nodes. Instead, it would use the XMPP pub/sub disco# ability to list available event nodes and contact the admin entity to subscribe to the nodes of interest.

A consumer has purchased an energy monitoring device for use in her home. The sensor used is accurate to the nearest 10 Wh. Below are example data structures for an energy node E_meta and E_data where E is a UUID value (4d4335b0-4134-11e0-9207-0800200c9a66 in this example).

Later, the same consumer 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 the additional information in the _meta and _data nodes.

The occupant of a building wants to automate the temperature control for his building. Below is one possible way for the event nodes to be created.

A consumer has a web camera which can sense movement and has a light which can be turned on or off. The consumer also has an agent which responds to the camera motion detector by turning on the camera light. For security reasons, it is desired to allow an entity 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 event node. Below are example data structures for a camera node C_meta and C_data as well as a transducer specific event node C_tid2 where C is a UUID value (4d4335b5-4134-11e0-9207-0800200c9a66 in this example).

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

Two things to note:

1. The tuple ("4d4335b5-4134-11e0-9207-0800200c9a66_data", "tid1") uniquely identifies the motion sensor for this camera adapter.
2. 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 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.

A car enthusiast purchases an iPhone and connects it to the diagnostic bus of her car. Below are example data structures for an vehicle node V_meta and V_data where V is a UUID value (4d4335b6-4134-11e0-9207-0800200c9a66 in this example).
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 (rotations per second) (i.e. multiply the rpm value by 60 to get hertz) before publishing and an agent could optionally convert the value back to rpm (i.e. divide the hertz value by 60 to get back to rpm) for display.

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 node. Consumers of the _data 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 event 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 event node in the xmpp server so old entries can be obtained
• Have the adapter periodicly update all values in the _data node
• Put infrequent events in their own event nodes and use _data for frequent events
• Put frequent events in their own event nodes and use _data for infrequent events

Finally, in the case of a fleet owner, the logging agent described above could be used to keep historical information (including location and performance) for all of the vehicles in the fleet. We will leave it as an exercise for the reader to ponder the implications of allowing automotive transducers to be modified on the fly via non-local agents.

Whether or not additional event 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 event 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.

Each event node contains access control in the form of Affiliations similar to those described in Multi-User Chat (XEP-0045). All affiliations MUST be based on a bare JID &BAREJID; of a full JID &FULLJID;. By default the “owner” of a node has both publish and subscribe permissions. Access control over newly created nodes is server and client implementation specific. As a general rule, clients SHOULD NOT allow open publish access by default. Below are the relevant JID affiliations and their access models:

* Note: see XEP-0060 (Publish-Subscribe) for details regarding affiliations and their privileges.

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.