xeps/inbox/iot-events.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
    <header>
        <title>Internet of Things - Events</title>
        <abstract>This specification describes an architecture based on the XMPP protocol whereby Things can subscribe to events from other Things based on sensor data available.</abstract>
        &LEGALNOTICE;
        <number>xxxx</number>
        <status>ProtoXEP</status>
        <type>Standards Track</type>
        <sig>Standards</sig>
        <approver>Council</approver>
        <dependencies>
            <spec>XMPP Core</spec>
            <spec>XEP-0001</spec>
            <spec>XEP-0030</spec>
            <spec>XEP-0323</spec>
            <spec>XEP-0324</spec>
            <spec>XEP-0326</spec>
        </dependencies>
        <supersedes/>
        <supersededby/>
        <shortname>iot-events</shortname>
        <author>
            <firstname>Peter</firstname>
            <surname>Waher</surname>
            <email>peter.waher@clayster.com</email>
            <jid>peter.waher@jabber.org</jid>
            <uri>http://www.linkedin.com/in/peterwaher</uri>
        </author>
        <revision>
            <version>0.0.1</version>
            <date>2014-08-13</date>
            <initials>pw</initials>
            <remark>
                <p>First draft.</p>
            </remark>
        </revision>
    </header>
    <section1 topic='Introduction' anchor='intro'>
        <p>
            This document specifies a method whereby devices or applications can subscribe to events from a Thing, based on sensor data, as defined in XEP-0323: &xep0323;. While XEP-0323 defines a method
            whereby the device or application can request sensor data information from a Thing when the device or application requires it, this document specifies a method whereby the Thing itself
            informs the device or application of desired sensor data, when certain conditions have been met, defined by the device or application.
        </p>
        <p>
            The architecture defined in this document, permits the specification of conditions individually, something that would not be possible, or very difficult to achieve, if a centralized 
            publish/subscribe or multi-cast pattern would have been used. By allowing individual conditions to be specified, devices or applications can be informed of information that best suit them, 
            and when it suits them, instead of having to figure out, from the Thing perspective, a common denominator, sufficiently good for all intended devices or applications. Furthermore, 
            by aligning itself with XEP-0323 and the request/response pattern, the Thing can easily integrate with a provisioning server, as defined in XEP-0324: &xep0324;, to allow for delegation 
            of trust and allowing detailed provisioning of who is allowed to receive what information. Through the use of attributes defined in XEP-0326: &xep0326; subscriptions can be extended
            to underlying nodes controlled by the Thing as well.
        </p>
        <p>
            Internet of Things contains many different architectures and use cases. For this reason, the IoT standards have been divided into multiple XEPs according to the following table:
        </p>
        <table caption='Internet of Things XEPs'>
            <tr>
                <th>XEP</th>
                <th>Description</th>
            </tr>
            <tr>
                <td>xep-0000-IoT-BatteryPoweredSensors</td>
                <td>Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.</td>
            </tr>
            <tr>
                <td>xep-0000-IoT-Events</td>
                <td>This specification. Defines how Things send events, how event subscription, hysteresis levels, etc., are configured.</td>
            </tr>
            <tr>
                <td>xep-0000-IoT-Interoperability</td>
                <td>Defines guidelines for how to achieve interoperability in Internet of Things, publishing interoperability interfaces for different types of devices.</td>
            </tr>
            <tr>
                <td>xep-0000-IoT-Multicast</td>
                <td>Defines how sensor data can be multicast in efficient ways.</td>
            </tr>
            <tr>
                <td>xep-0000-IoT-PubSub</td>
                <td>Defines how efficient publication of sensor data can be made in Internet of Things.</td>
            </tr>
            <tr>
                <td>xep-0000-IoT-Chat</td>
                <td>Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.</td>
            </tr>
            <tr>
                <td>XEP-0322</td>
                <td>
                    Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not an Internet of Things specific XEP, this XEP should be considered
                    in all Internet of Things implementations where memory and packet size is an issue.
                </td>
            </tr>
            <tr>
                <td>XEP-0323</td>
                <td>
                    Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks.
                    It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other
                    Internet of Things XEPs.
                </td>
            </tr>
            <tr>
                <td>XEP-0324</td>
                <td>Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.</td>
            </tr>
            <tr>
                <td>XEP-0325</td>
                <td>Defines how to control actuators and other devices in Internet of Things.</td>
            </tr>
            <tr>
                <td>XEP-0326</td>
                <td>Defines how to handle architectures containing concentrators or servers handling multiple Things.</td>
            </tr>
            <tr>
                <td>XEP-0331</td>
                <td>Defines extensions for how color parameters can be handled, based on &xep0004;</td>
            </tr>
            <tr>
                <td>XEP-0336</td>
                <td>Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.</td>
            </tr>
            <tr>
                <td>XEP-0347</td>
                <td>Defines the peculiars of Thing discovery in Internet of Things. Apart from discovering Things by JID, it also defines how to discover Things based on location, etc.</td>
            </tr>
        </table>
    </section1>
    <section1 topic='Glossary' anchor='glossary'>
        <p>The following table lists common terms and corresponding descriptions.</p>
        <dl>
            <di>
                <dt>Actuator</dt>
                <dd>Device containing at least one configurable property or output that can and should be controlled by some other entity or device.</dd>
            </di>
            <di>
                <dt>Computed Value</dt>
                <dd>A value that is computed instead of measured.</dd>
            </di>
            <di>
                <dt>Concentrator</dt>
                <dd>Device managing a set of devices which it publishes on the XMPP network.</dd>
            </di>
            <di>
                <dt>Field</dt>
                <dd>
                    One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc.
                    Fields should be unique within the triple (Node ID, Field Name, Timestamp).
                </dd>
            </di>
            <di>
                <dt>Field Name</dt>
                <dd>Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.</dd>
            </di>
            <di>
                <dt>Field Type</dt>
                <dd>What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.</dd>
            </di>
            <di>
                <dt>Historical Value</dt>
                <dd>A value stored in memory from a previous timestamp.</dd>
            </di>
            <di>
                <dt>Identification Value</dt>
                <dd>A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)</dd>
            </di>
            <di>
                <dt>Localization information</dt>
                <dd>Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.</dd>
            </di>
            <di>
                <dt>Meter</dt>
                <dd>A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.</dd>
            </di>
            <di>
                <dt>Momentary Value</dt>
                <dd>A momentary value represents a value measured at the time of the read-out.</dd>
            </di>
            <di>
                <dt>Node</dt>
                <dd>
                    Graphs contain nodes and edges between nodes. In Internet of Things, sensors, actuators, meters, devices, gateways, etc., are often depicted as nodes whereas links between sensors (friendships)
                    are depicted as edges. In abstract terms, it's easier to talk about a Node, rather than list different possible node types (sensors, actuators, meters, devices, gateways, etc.).
                    Each Node has a Node ID.
                </dd>
            </di>
            <di>
                <dt>Node ID</dt>
                <dd>
                    An ID uniquely identifying a node within its corresponding context. If a globally unique ID is desired, an architecture should be used using a universally accepted
                    ID scheme.
                </dd>
            </di>
            <di>
                <dt>Parameter</dt>
                <dd>
                    Readable and/or writable property on a node/device. The XEP-0326 &xep0326; deals with reading and writing parameters
                    on nodes/devices. Fields are not parameters, and parameters are not fields.
                </dd>
            </di>
            <di>
                <dt>Peak Value</dt>
                <dd>A maximum or minimum value during a given period.</dd>
            </di>
            <di>
                <dt>Precision</dt>
                <dd>
                    In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision
                    determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and
                    delivering field information in sensor networks should always retain the number of decimals in a message.
                </dd>
            </di>
            <di>
                <dt>Sensor</dt>
                <dd>
                    Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc.
                    Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
                </dd>
            </di>
            <di>
                <dt>SN</dt>
                <dd>Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.</dd>
            </di>
            <di>
                <dt>Status Value</dt>
                <dd>A value displaying status information about something.</dd>
            </di>
            <di>
                <dt>Timestamp</dt>
                <dd>Timestamp of value, when the value was sampled or recorded.</dd>
            </di>
            <di>
                <dt>Token</dt>
                <dd>
                    A client, device or user can get a token from a provisioning server. These tokens can be included in requests to other entities in the network, so these entities can validate
                    access rights with the provisioning server.
                </dd>
            </di>
            <di>
                <dt>Unit</dt>
                <dd>Physical unit of value. Example: MWh, l/s, etc.</dd>
            </di>
            <di>
                <dt>Value</dt>
                <dd>A field value.</dd>
            </di>
            <di>
                <dt>Value Status</dt>
                <dd>Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.</dd>
            </di>
            <di>
                <dt>Value Type</dt>
                <dd>Can be numeric, string, boolean, Date &amp; Time, Time Span or Enumeration.</dd>
            </di>
            <di>
                <dt>WSN</dt>
                <dd>Wireless Sensor Network, a sensor network including wireless devices.</dd>
            </di>
            <di>
                <dt>XMPP Client</dt>
                <dd>Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.</dd>
            </di>
        </dl>
    </section1>
    <section1 topic='Use Cases' anchor='usecases'>
        <p>
            Subscribing to events is performed much the same way as requesting sensor data from a device, as defined in <link url='http://xmpp.org/extensions/xep-0323.html#usecases'>XEP-0323</link>.
            Instead of requesting the data using the <strong>req</strong> element of the <strong>urn:xmpp:iot:sensordata</strong> namespace, it is done using the <strong>subscribe</strong> element 
            of the <strong>urn:xmpp:iot:events</strong> namespace. Much of the syntax of this <strong>subscribe</strong> element coincides with that of the <strong>req</strong> element,
            with some differences, as will be described in this document.
        </p>
        <p>
            Responses and sensor data is then sent from the device to the subscriber, in the same way as defined in XEP-0323, with one notable difference: The sequence number <strong>seqnr</strong>
            provided in the request, is not forgotten once a readout has been completed, but will be reused every time the Thing reports data to the subscriber. The subscriber must use this sequence
            number to correlate incoming sensor data with original request. Furthermore, the subscriber must not reuse the sequence number in other sensor data requests to the Thing, while the subscription
            is alive.
        </p>
        <p>
            A subscription is cancelled by the subscriber sending a request with an <strong>unsubscribe</strong> element in it to the Thing. The Thing can also automatically remove subscriptions
            if the corresponding friendship ends. Furthermore, event conditions should only be evaluated if the corresponding subscriber is online. This, to avoid offline messages to pile up.
            Once a friend comes online, any subscription conditions corresponding to that friend should be evaluated to inform it of the current state of the Thing.
        </p>
        <section2 topic='Request Subscription of momentary values' anchor='subscribemomentary'>
            <p>
                The client that wishes to receive momentary values regularly from the sensor initiates the request using the <strong>subscribe</strong> element sent to the device.
                In the following example, a subscription is made to receive momentary values every five minutes (specified by the <strong>maxInterval</strong> attribute), with no 
                field-specific conditions attached.
            </p>
            <example caption='Subscription request of momentary values from a device'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0001'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' momentary='true' maxInterval='PT5M' req='true'/>
   </iq>]]>
            </example>
            <p>
                When the device has received and accepted the request, it responds as follows, using the <strong>accepted</strong> element defined in XEP-0323. Sensor data is later reported
                in a way similar to XEP-0323, with the exception that the <strong>seqnr</strong> will be reused every time the event occurs. If the event causes multiple messages to be sent,
                the receiver knows which one is the last message, by looking at the <strong>done</strong> attribute. Since the <strong>req</strong> attribute is set to <strong>true</strong>,
                an event will be sent back immediately (i.e. emulating a parallel readout request operation).
            </p>
            <example caption='Subscription request accepted by device'>
                <![CDATA[
   <iq type='result'
       from='device@clayster.com'
       to='client@clayster.com/amr'
       id='S0001'>
      <accepted xmlns='urn:xmpp:iot:sensordata' seqnr='1'/>
   </iq>]]>
            </example>
        </section2>
        <section2 topic='Subscription rejected' anchor='subscriptionrejected'>
            <p>
                If for some reason, the device rejects the subscription request, the communication sequence might look as follows:
            </p>
            <example caption='Momentary read-out rejected'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0002'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' momentary='true' maxInterval='PT5M'/>
   </iq>
   
   <iq type='error'
       from='device@clayster.com'
       to='client@clayster.com/amr'
       id='S0002'>
      <error type='cancel'>
         <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
         <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang='en'>Access denied.</text>
      </error>
   </iq>]]>
            </example>
            <p>
                Depending on the reason for rejecting the request, different XMPP errors can be returned, according to the description in the following table. The table also
                lists recommended error type for each error. Any custom error message is returned in a <strong>text</strong> element, as in the example above.
            </p>
            <table caption='XMPP Errors when rejecting a subscription request'>
                <tr>
                    <th>Error Type</th>
                    <th>Error Element</th>
                    <th>Namespace</th>
                    <th>Description</th>
                </tr>
                <tr>
                    <td>cancel</td>
                    <td>forbidden</td>
                    <td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
                    <td>If the caller lacks privileges to perform the action.</td>
                </tr>
                <tr>
                    <td>cancel</td>
                    <td>item-not-found</td>
                    <td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
                    <td>If an item or data source could not be found.</td>
                </tr>
                <tr>
                    <td>modify</td>
                    <td>bad-request</td>
                    <td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
                    <td>If the request was malformed. Examples can include trying to subscribe to information from a device behind a concentrator, without including node information.</td>
                </tr>
            </table>
        </section2>
        <section2 topic='Unsubscribing a subscription' anhor='unsubscribe'>
            <p>
                To unsubscribe a subscription, send the <strong>unsubscribe</strong> element in a request to the Thing with the <strong>seqnr</strong> sequence number corresponding to the
                subscription. The Thing responds with an empty response to acknowledge the un-subscription, regardless if the subscription existed or not.
            </p>
            <example caption='Unsubscribing a subscription'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0003'>
      <unsubscribe xmlns='urn:xmpp:iot:events' seqnr='1'/>
   </iq>
   
   <iq type='result'
       from='device@clayster.com'
       to='client@clayster.com/amr'
       id='S0003'/>]]>
            </example>
        </section2>
        <section2 topic='Requesting subscription of changes to fields values' anchor='subscribechanges'>
            <p>
                The client that wishes to receive information when a field or a set fields change, can do so by specifying amount of change allowed in the corresponding
                <strong>field</strong> elements in the subscription. It can also provide optional current values from which the change is measured. If current values are not
                provided, the Thing uses its corresponding set of current values at the time it receives the request. Current values use the corresponding unit held by the field.
                To find out, if unsure, you need to make a sensor data readout first.
            </p>
            <p>
                In the following example, events are sent when light changes by more than 5 units (of a percent), or if a motion detector changes value. Temperature information at the
                time of the event is also requested. If the conditions are not met within fifteen minutes, an event is raised anyway (as defined using the <strong>maxInterval</strong>
                attribute). The <strong>minInterval</strong> attribute makes sure events are not sent more often than every five seconds.
            </p>
            <example caption='Requesting subscription of changes to fields values'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0004'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' momentary='true' maxInterval='PT15M' minInterval='PT5S'>
          <field name='Light' changedBy='5'/>
          <field name='Motion' changedBy='1' currentValue='0'/>
          <field name='Temperature'/>
      </subscribe>
   </iq>]]>
            </example>
        </section2>
        <section2 topic='Requesting subscription of historical data correlated to events' anchor='subscribehistory'>
            <p>
                Any type of sensor data can be included in an event subscription, including historical data. To limit the amount of historical data to return in an event,
                the <strong>maxAge</strong> attribute can be used, instead of the absolute <strong>from</strong> and <strong>to</strong> attributes available in the
                corresponding <strong>req</strong> element. The following example requests the last five minutes of historical temperature and light data as soon as the motion detector
                detects motion (change upwards of 1).
            </p>
            <example caption='Requesting subscription of historical data correlated to events'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0005'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' all='true' minInterval='PT1M' maxAge='PT5M'>
          <field name='Temperature'/>
          <field name='Light'/>
          <field name='Motion' changedUp='1'/>
      </subscribe>
   </iq>]]>
            </example>
        </section2>
        <section2 topic='Requesting subscription of historical data correlated to events' anchor='subscribehistory'>
            <p>
                Any type of sensor data can be included in an event subscription, including historical data. To limit the amount of historical data to return in an event,
                the <strong>maxAge</strong> attribute can be used, instead of the absolute <strong>from</strong> and <strong>to</strong> attributes available in the
                corresponding <strong>req</strong> element. The following example requests the last five minutes of historical temperature and light data as soon as the motion detector
                detects motion (change upwards of 1).
            </p>
            <example caption='Requesting subscription of historical data correlated to events'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='device@clayster.com'
       id='S0006'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' all='true' minInterval='PT1M' maxAge='PT5M'>
          <field name='Temperature'/>
          <field name='Light'/>
          <field name='Motion' changedUp='1'/>
      </subscribe>
   </iq>]]>
            </example>
        </section2>
        <section2 topic='Requesting subscription of nodes behind a concentrator' anchor='subscribenodes'>
            <p>
                To subscribe to events from one or more nodes behind a concentrator, the nodes have to be specified using <strong>node</strong> elements in the subscription request.
                If more than one node is present, the subscription request is assumed to be made to each node individually. When the subscription conditions are met, the corresponding
                node sends its sensor data back to the subscriber. Note that only the node where the conditions are met include data in the message sent to the subscriber. Event subscriptions
                are handled individually for each node.
            </p>
            <p>
                In the following example, a subscription of any changes to a sequence of digital inputs handled by a PLC is made.
            </p>
            <example caption='Requesting subscription of nodes behind a concentrator'>
                <![CDATA[
   <iq type='get'
       from='client@clayster.com/amr'
       to='plc@clayster.com'
       id='S0007'>
      <subscribe xmlns='urn:xmpp:iot:events' seqnr='1' momentary='true' minInterval='PT5S' maxInternval='PT1H'>
          <node nodeId='DI1'/>
          <node nodeId='DI2'/>
          <node nodeId='DI3'/>
          <node nodeId='DI4'/>
          <field name='State' changeBy='1' currentValue='0'/>
      </subscribe>
   </iq>]]>
            </example>
        </section2>
    </section1>
	<section1 topic='Determining Support' anchor='support'>
		<p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:events" in response to &xep0030; information requests.</p>
		<example caption="Service discovery information request">
			<![CDATA[
<iq type='get'
    from='client@clayster.com/amr'
    to='device@clayster.com'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]>
		</example>
		<example caption="Service discovery information response">
			<![CDATA[
<iq type='result'
    from='device@clayster.com'
    to='client@clayster.com/amr'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:iot:events'/>
    ...
  </query>
</iq>]]>
		</example>
		<p>
			In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined
			in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
		</p>
	</section1>
	<section1 topic='Implementation Notes' anchor='impl'>
		<section2 topic='Change conditions' anchor='changeconditions'>
			<p>
				An integral part of conditions, is the measurement of changes of magnitudes of field values. Three attributes available on the <strong>field</strong> element, can be used to define
				how to measure changes. The <strong>changedUp</strong> attribute provides a numerical value limiting the amount of upwards change in the field before an event is triggered.
				The <strong>changedDown</strong> attributes provides a similar means to control the amount of downwards change in the field, before an event is triggered. If only one of these
				are provided, only changes in that direction trigger events. If the <strong>changedBy</strong> attribute is provided, the other two attributes are ignored, and assumed to
				be of the same value as the <strong>changedBy</strong> attribute value. All changes are specified using positive numbers.
			</p>
			<p>
				The following table shows how magnitudes are calculated for field values of different types:
			</p>
			<table caption='Magnitude of change per field type'>
				<tr>
					<th>Type</th>
					<th>Magnitude</th>
				</tr>
				<tr>
					<th>boolean</th>
					<td>Magnitude is 0 if false, and 1 if true.</td>
				</tr>
				<tr>
					<th>date</th>
					<td>Number of seconds since an implementation specific point in time. Since only changes are measured, actual point in time is not important.</td>
				</tr>
				<tr>
					<th>dateTime</th>
					<td>Number of seconds since an implementation specific point in time. Since only changes are measured, actual point in time is not important.</td>
				</tr>
				<tr>
					<th>duration</th>
					<td>Corresponding number of seconds.</td>
				</tr>
				<tr>
					<th>enum</th>
					<td>Any change to this value, corresponds to a change by 1. If direction of change is important, values are ordered by lexical order.</td>
				</tr>
				<tr>
					<th>int</th>
					<td>The value itself.</td>
				</tr>
				<tr>
					<th>long</th>
					<td>The value itself.</td>
				</tr>
				<tr>
					<th>numeric</th>
					<td>The value itself, without unit. The magnitude specified in any change attributes is assumed to be specified using the same unit as the corresponding field.</td>
				</tr>
				<tr>
					<th>string</th>
					<td>Any change to this value, corresponds to a change by 1. If direction of change is important, values are ordered by lexical order.</td>
				</tr>
				<tr>
					<th>time</th>
					<td>Corresponding number of seconds.</td>
				</tr>
			</table>
		</section2>
		<section2 topic='When to check event conditions' anchor='whentocheck'>
			<p>
				Event conditions should be checked, if the following conditions are true for the corresponding event:
			</p>
			<ul>
				<li>
					One of the following conditions are true:
					<ul>
						<li>A new value is available.</li>
						<li>A subscriber comes online.</li>
						<li>The minimum interval timer expires, if specified.</li>
						<li>The maximum interval timer expires, if specified.</li>
					</ul>
				</li>
				<li>The corresponding subscriber is online.</li>
				<li>
					The corresponding event has not been triggered within <strong>minInterval</strong> seconds, if specified.
				</li>
			</ul>
		</section2>
		<section2 topic='Removal of friendships' anchor='friendships'>
			<p>
				If a friendship is lost, i.e. presence information from the corresponding contact is unsubscribed, the Thing has to automatically remove any
				event subscriptions available for that contact. If a new friendship is created with the same contact at a later stage, the contact has to request
				new subscriptions.
			</p>
		</section2>
		<section2 topic='Power-down and persistence of subscriptions' anchor='persistence'>
			<p>
				It is up to the thing, if it wants to persist event subscriptions or not. If not persisting event subscriptions, they will automatically be lost if the
				Thing rests or restarts for some reason.
			</p>
			<p>
				If the subscriber considers an event subscription important, and wants to make sure a subscription survives any resets of the thing, the <strong>maxInterval</strong>
				attribute should be used when requesting the subscription. If an event is not delivered within this time and a margin, the subscriber can assume the subscription
				has been lost, and a new subscription can be made.
			</p>
		</section2>
		<section2 topic='Overriding subscriptions' anchor='overriding'>
			<p>
				A subscriber can only have one active subscription per node on a Thing. If a Thing does not support nodes, each subscriber can only have one active subscription 
				per corresponding Thing. This means, that a new event subscription automatically overrides (or unsubscribes) any existing subscription on the corresponding node or Thing.
				This in turn makes it easier for subscribers to handle restarts and avoids multiplicity problems due to lack of synchronization between subscriber and Thing.
			</p>
		</section2>
    </section1>
    <section1 topic='Security Considerations' anchor='security'>
		<section2 topic='Re-evaluation of subscription contents' anchor='reevaluation'>
			<p>
				If a Thing is connected to a provisioning server, as defined in <span class='ref'>
					<link url='http://xmpp.org/extensions/xep-0324.html'>XEP-324: Internet of Things - Provisioning</link>
				</span>, it should re-evaluate event subscriptions contents if a <strong>clearCache</strong> command is received from the provisioning server.
				To be able to do this properly, the contents of the original event subscription should be remembered. Re-evaluating active event subscriptions
				after a <strong>clearCache</strong> command enables the owner of the Thing to modify current access rights in the Thing in real-time, including
				contents send in events.
			</p>
			<p>
				Existing event subscriptions that are no longer permitted by the new set of rules in the provisioning server, can be removed from memory, without
				informing the subscriber about the fact. The subscriber will be informed when re-subscribing, that access rights have been lost.
			</p>
		</section2>
	</section1>
	<section1 topic='IANA Considerations' anchor='iana'>
		<p>This document requires no interaction with &IANA;.</p>
	</section1>
	<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
		<p>
			The <link url="#schema">protocol schema</link> needs to be added to the list of <link url="http://xmpp.org/resources/schemas/">XMPP protocol schemas</link>.
		</p>
	</section1>
	<section1 topic='XML Schema' anchor='schema'>
		<code>
			<![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:iot:events'
    xmlns='urn:xmpp:iot:events'
    xmlns:sd='urn:xmpp:iot:sensordata'
    elementFormDefault='qualified'>

	<xs:import namespace='urn:xmpp:iot:sensordata'/>
	
	<xs:element name='subscribe'>
		<xs:complexType>
			<xs:choice minOccurs='0' maxOccurs='unbounded'>
				<xs:element name='node'>
					<xs:complexType>
						<xs:attribute name='nodeId' type='xs:string' use='required'/>
						<xs:attribute name='sourceId' type='xs:string' use='optional'/>
						<xs:attribute name='cacheType' type='xs:string' use='optional'/>
					</xs:complexType>
				</xs:element>
				<xs:element name='field'>
					<xs:complexType>
						<xs:attribute name='name' type='xs:string' use='required'/>
						<xs:attribute name='currentValue' type='xs:double' use='optional'/>
						<xs:attribute name='changedBy' type='PositiveDouble' use='optional'/>
						<xs:attribute name='changedUp' type='PositiveDouble' use='optional'/>
						<xs:attribute name='changedDown' type='PositiveDouble' use='optional'/>
					</xs:complexType>
				</xs:element>
			</xs:choice>
			<xs:attribute name='seqnr' type='xs:int' use='required'/>
			<xs:attributeGroup ref='sd:fieldTypes'/>
			<xs:attribute name='all' type='xs:boolean' use='optional' default='false'/>
			<xs:attribute name='historical' type='xs:boolean' use='optional' default='false'/>
			<xs:attribute name='maxAge' type='xs:duration' use='optional'/>
			<xs:attribute name='minInterval' type='xs:duration' use='optional'/>
			<xs:attribute name='maxInterval' type='xs:duration' use='optional'/>
			<xs:attribute name='serviceToken' type='xs:string' use='optional'/>
			<xs:attribute name='deviceToken' type='xs:string' use='optional'/>
			<xs:attribute name='userToken' type='xs:string' use='optional'/>
			<xs:attribute name='req' type='xs:boolean' use='optional' default='false'/>
		</xs:complexType>
	</xs:element>

	<xs:element name='unsubscribe'>
		<xs:complexType>
			<xs:attribute name='seqnr' type='xs:int' use='required'/>
		</xs:complexType>
	</xs:element>

	<xs:simpleType name='PositiveDouble'>
		<xs:restriction base='xs:double'>
			<xs:minExclusive value='0'/>
		</xs:restriction>
	</xs:simpleType>

</xs:schema>]]>
		</code>
	</section1>
	<section1 topic='For more information' anchor='moreinfo'>
		<p>
			For more information, please see the following resources:
		</p>
		<ul>
			<li>
				<p>
					The <link url='http://wiki.xmpp.org/web/Tech_pages/SensorNetworks'>Sensor Network section of the XMPP Wiki</link> contains further information about the
					use of the sensor network XEPs, links to implementations, discussions, etc.
				</p>
			</li>
			<li>
				<p>
					The XEP's and related projects are also available on <link url='https://github.com/joachimlindborg/'>github</link>, thanks to Joachim Lindborg.
				</p>
			</li>
			<li>
				<p>
					A presentation giving an overview of all extensions related to Internet of Things can be found here:
					<link url='http://prezi.com/esosntqhewhs/iot-xmpp/'>http://prezi.com/esosntqhewhs/iot-xmpp/</link>.
				</p>
			</li>
		</ul>
	</section1>
</xep>