diff --git a/inbox/sensors.xml b/inbox/sensors.xml index 28769a3f..94a1233c 100644 --- a/inbox/sensors.xml +++ b/inbox/sensors.xml @@ -7,7 +7,7 @@
Sensor-Over-XMPP - This specification provides a description of a communication protocol for a sensing and actuation system. Data is transported using the XMPP publish-subscribe mechanism described in XEP-0060. + 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. 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. @@ -23,8 +23,8 @@ XMPP Core XEP-0001 - XEP-0004 XEP-0060 + XEP-0082 @@ -50,6 +50,55 @@ css@google.com + + 0.0.18 + 2011-04-08 + css +

Add data element to enclose transducerValue and transducerSetValue.

 + + + + 0.0.17 + 2011-03-25 + css +

Cleanup typo's and wording.

 + + + + 0.0.16 + 2011-03-24 + css +

Move device type and units into the xsd.

 + + + + 0.0.15 + 2011-03-23 + css +

Text and example cleanup.

 + + + + 0.0.14 + 2011-03-22 + css +

First attempt at how/why split.

 + + + + 0.0.13 + 2011-03-10 + gnb +

Minor cleanup.

 + + + + 0.0.12 + 2011-03-10 + css +

Change TransducerValue packet's TypedValue from float to string.

 + + 0.0.11 2011-03-03 @@ -135,13 +184,14 @@
-

This document specifies a format for exchanging sensor and actuator data. The schema described here is a specialized context (“profile”) of the XMPP Publish-Subscribe extension described in XEP-0060. The purpose of this document is to outline the schema and describe various expected usage scenarios. This schema focuses on describing the transducers and their data rather than the physical phenomenon that they sense or control. This 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.

- +

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

    @@ -169,8 +219,7 @@ To achive this, the specific requirements are:
    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;.
     -
    Event Node
    An entity that represents a transducer address used to facilitate data transfer.
     -
    Creator / Owner
    An entity that created an event node and is automatically a publisher and subscriber.
     +
    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.
     @@ -178,70 +227,94 @@ To achive this, the specific requirements are: - -

    The basic structure revolves around the XMPP Publish-Subscribe mechanism as described in XEP-0060. There are multiple types of entities involved. Event nodes are used to supply information that need to be shared. Publishers and Subscribers act as producers and consumers of the information. These are described in more detail in this section. + + +

    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.

    - -

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

    +     + +Adapter publishes device meta data: - - - - - - - - - - - - - - + + + + + + + + + + + + + + + ]]> - - +

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

    + + + + + + + + + + + + + + + +]]> +
    @@ -280,7 +353,8 @@ The "Device" is a top-level encapsulation entity that contains a list of transdu timestamp @@ -293,48 +367,16 @@ The "Device" is a top-level encapsulation entity that contains a list of transdu
    @@ -264,7 +337,7 @@ The "Device" is a top-level encapsulation entity that contains a list of transdu id - A unique identifier for the device. This SHOULD be the same as the device event node idor the base string for event nodes for this device (see below). + A unique identifier for the logical device. This SHOULD be the UUID that corresponds to the logical device.
    - Timestamp in the format described below + Format as defined in +XEP-0082: XMPP Date and Time Profiles.
    - deviceID + serialNumber - An identifier for the device itself (such as a serial number) + A serial number or other unique identifier for the physical device
    -     - -

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

    - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - +
    @@ -371,10 +413,10 @@ The tuple (event node id X, transducer id Y) MUST be unique such that a publish @@ -387,10 +429,10 @@ The tuple (event node id X, transducer id Y) MUST be unique such that a publish @@ -398,7 +440,6 @@ The tuple (event node id X, transducer id Y) MUST be unique such that a publish transducerTypeName @@ -418,6 +459,14 @@ The tuple (event node id X, transducer id Y) MUST be unique such that a publish Manufacturer's part number of the transducer + + + +
    @@ -358,7 +400,7 @@ The "Device" is a top-level encapsulation entity that contains a list of transdu A unique identifier for the transducer used within the XML packet to enumerate different transducers within a single packet -The tuple (event node id X, transducer id Y) MUST be unique such that a publish operation to an event node X with the transducer id Y unambiguously refers to one and only one transducer. +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.
    - unitScalerPrefix + unitScaler - Prefix for the unit of measure (see below) + The scale of the unit as a power of 10 (i.e. n for 10 ** n)
    - hasOwnEventNode + hasOwnNode - Indicates whether the transducer has its own event node or whether it is part of a larger data node (see below) + Indicates whether the transducer data has its own node or whether it is part of the generic data value node (see below)
    -
    A human readable indication of the type of transducer
    + serialNumber + + Manufacturer's serial number of the transducer +
    minValue @@ -460,247 +509,10 @@ The tuple (event node id X, transducer id Y) MUST be unique such that a publish
    - - -

    The "TransducerValue" is an element that captures the latest value of the transducer. -This is a dynamic parameter that has been optimized for size, which is why there are no associated descriptions of the value. -Information about the value (like the units, scale, etc) are stored as relatively static information in the "Transducer" packets which are generally only transferred as part of a setup operation and are not repeated within every value packet. + +

    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:

    - - - - - - - - -]]> - - - - - - - - - - - - - - - - - - - - - - - - -
    - Attribute - - Description/Purpose -
    - id - - The transducer id. -This MUST correspond to a transducer ID as defined in the transducer packet. -The tuple (event node id X, transducer id Y) MUST be unique such that a publish operation to an event node X 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 - - The timestamp of when the value for this transducer was obtained in the format as described below -
    - 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). -
    -     - - - - - - - - - -]]> - - - - - - - - - - - - - - - - - - - - -
    - Attribute - - Description/Purpose -
    - id - - The transducer id. -This MUST correspond to a transducer ID as defined in the transducer packet. -The tuple (event node id X, transducer id Y) MUST be unique such that a publish operation to an event node X 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. -
    -     - -     - - -

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

    - - - - - - -]]> -     -     - - -

    -The following are example use cases which this XEP would enable. -Example data structures for implementing these use cases is given in a later section. -

    - -

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

    -     -     - -In this section we address conventions required to implement an interoperable system using the Sensor Over XMPP schema. This includes conventions related to units, scaling, timestamps, and naming of event nodes. - - -

    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".
      • -
    - We suggest using this naming scheme to simplify storage of relatively static and relatively dynamic data about transducers in a way that is compatible with current pub/sub implementations. -

    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. -
    2. Event node T_data which contains the transducer value XML information for the temperature sensor.
      3. -
    3. Event node H_meta which contains the device and transducer XML information for the heater control.
      4. -
    4. Event node H_data which contains the transducer value and transducer command XML information for the heater control.
      5. -
    -Further: -
      -
    • 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: -

    - +
    @@ -800,433 +612,521 @@ The following are recommended types:
    @@ -744,18 +556,18 @@ The following are recommended types:
    - video camera + multimedia input - Sensors and controls associated with a video camera + Sensors and controls associated with multimedia input (video camera, microphone, etc)
    - still camera + multimedia output - Sensors and controls associated with a still (non-video) camera + Sensors and controls associated with multimedia output (screen, speakers, etc)
    -     - -

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Base QuantityNameSymbol
    length meter m
    mass gram g
    volume liter l
    time second s
    thermodynamic temperature celsius °C
    amount of substance mole mol
    luminous intensity candela cd
    Illuminance lux lx
    luminous flux lumen lm
    energy joule J
    force newton N
    pressure,stress pascal Pa
    electric real power watt W
    electric reactive power volt-amp reactive Var
    electric complex power volt-amp VA
    electric apparent power volt-amp VA
    electric voltage volt V
    electric current ampere A
    electric current phase radian rad
    electric energy watt hour Wh
    magnetic field tesla T
    inductance henry H
    electric charge coulomb C
    electric capacitance farad F
    electric conductance siemens S
    magnetic flux weber Wb
    electric resistance ohm ω
    radioactivity becquerelBq
    frequency hertzHz
    catalytic activity katalkat
    plane angle radianrad
    solid angle steradiansr
    percentage percent%
    enumeration of values enum
    location latitude latitude
    location longitude longitude
    velocity (meters/second) velocitym/s
    acceleration (meters/second^2) accelerationm/s2
    + + +

    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 prefix value. The following example shows how to specify a sensor in centimeters. +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-hours with a resolution to the nearest 0.1 kWh. +The following example shows how to specify a sensor in kilowatt-second 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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    PrefixAbberviationFactorExample
    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
    - +If no unitScaler value is specified, then a unitScaler of 0 (aka 10**0 = 1) is assumed.

    -     - -

    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.

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

    -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
      • -
    -For example December 7th, 2010 at 3:32pm UTC in the afternoon would be: 2010-12-07T15:32:00Z. +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 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
      • -
    - -For example February 2nd, 2011 19:53:35 UTC (1296676415 decimal seconds since the Unix epoch) and 0 nano-seconds would be 0x4D49B63F00000000 (since the nano-seconds is zero, the lower 4 byts are all zero). +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.

    - ]]> - + + + + + + + + + + + +]]>

    -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. +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 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. +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 event node. +Any interested agent can always verify the latest state of the actuator by subscribing to the actuator's 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.

    -     + +     - + +

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

    -

    A consumer has purchased an energy monitoring device for use in her home. +

    Lady Capulet 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).

    + + + + + + + + + -4d4335b0-4134-11e0-9207-0800200c9a66_meta - -Example data published to the _meta node: - - - deviceID="8341gvhv5w9" - - - - -Event Node ID: - -4d4335b0-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node: - - - + + + + + + + + + + + ]]> -

    Later, the same consumer adds a second energy sensor to the monitoring device purchased above. +

    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 the additional information in the _meta and _data nodes. +The adapter provides this additional information in the meta node and data value node.

    + + + + + minValue='0' maxValue='100' resolution='0.01'/> + + + + + + -Example data published to the _meta node: - - - deviceID="8341gvhv5w9" - - minValue="0" maxValue="100" resolution="0.01"> - - - - - -Event Node ID: 4d4335b0-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node: - - - - - -]]> -     - - -

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

    - - - - - - - - -Event Node ID: 4d4335b1-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node: - - - - - - -Evnet Node ID: 4d4335b2-4134-11e0-9207-0800200c9a66_meta - -Example data published to the _meta node: - - - - - - - - -Event Node ID: 4d4335b2-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node: - - - - - - -Evnet Node ID: 4d4335b3-4134-11e0-9207-0800200c9a66_meta - -Example data published to the _meta node: - - - - minValue="0" maxValue="1"> - - - -Event Node ID: 4d4335b3-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node (heater is off): - - - - -Evnet Node ID: 4d4335b4-4134-11e0-9207-0800200c9a66_meta - -Example data published to the _meta node: - - - - - - -Event Node ID: 4d4335b4-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node (A/C is at medium): - - + + + + + + + + + + + + ]]>     -

    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 +

    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 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). +the adapter implements the OPTIONAL ability that allows a transducer value to have its own node.

    + + + + + + + + + + + + - - - - - - + + + + + + + + + + + -Event Node ID: 4d4335b5-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node (no movement): - - - - -Event Node ID: 4d4335b5-4134-11e0-9207-0800200c9a66_tid2 - -Example data published to the _tid2 node (light is off): - - - + + + + + + + + + + + ]]>

    When there is movement, the following would be published by the camera adapter. @@ -1234,37 +1134,54 @@ Example data published to the _tid2 node (light is off): - + + + + + + + + + + + ]]>

    Two things to note:

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

    + + + + + + + + + + + ]]>

    @@ -1272,15 +1189,23 @@ In response, the camera adapter would turn on the light and publish an acknowled

    - + + + + + + + + + + + ]]>

    @@ -1289,80 +1214,90 @@ In response to this the agent could start recording the video, send an email, us -

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

    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 (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. +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' + + + + + + + + + + + + + + + -Example data published to the _meta node: - - - deviceID="license: HI 2ABC123" - - - - - - - - - - - - - - - - - - - - - - -Event Node ID: 4d4335b6-4134-11e0-9207-0800200c9a66_data - -Example data published to the _data node: - - - - - - - + + + + + + + + + + + + + ]]> -

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

    +

    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 event node (such as in this example). +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. @@ -1370,29 +1305,30 @@ 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 +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 node +Have the adapter periodicly update all values in the data value node
    • -Put infrequent events in their own event nodes and use _data for frequent events +Put infrequent events in their own nodes and use data value node for frequent events
    • -Put frequent events in their own event nodes and use _data for infrequent 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 event nodes -(instead of putting them all into the _data event node), remember that a transducer value MUST appear in either the _data node or its own 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. +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.

    -

    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.

    +

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

    +

    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.

         @@ -1402,182 +1338,181 @@ For example, an adapter could be written to compute the distance a vehicle is fr     -

    The data published to a pubsub node might contain sensitive information (e.g., a user's occupancy data) or allow control of a device (e.g., a power outlet switch). Therefore, node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsibility of the "using protocol". XMPP networks use TLS (&rfc4346;) for channel encryption, SASL (&rfc4422;) for authentication, and the Domain Name System (&rfc1034;) for weak validation of server hostnames; these technologies help to ensure the identity of sending entities and to encrypt XML streams.

    - - -

    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:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AffiliationSubscribeRetrieve ItemsPublish ItemsDelete Single ItemPurge NodeConfigure NodeDelete Node
    Creator (Owner)YesYesYesYesYesYesYes
    PublisherYesYesYesYes *Yes *NoNo
    Subscriber (Member)YesYesNoNoNoNoNo
    NoneYesNoNoNoNoNoNo
    OutcastNoNoNoNoNoNoNo

    -* Note: see XEP-0060 (Publish-Subscribe) for details regarding affiliations and their privileges. +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 ®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.

    +

    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.

         + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + - - The protocol documented in the Location type is defined in - XEP-0080: http://www.xmpp.org/extensions/xep-0080.html - + + The protocol documented by this schema is defined in + XEP-????: http://xmpp.org/extensions/xep-????.html + - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> +