<!-- TODO: Sub-namespace for Registration Clients.
urn:xmpp:iot:discovery:regunit - Registration Units (can claim ownership)
-->
<!-- TODO: TBD items -->
<!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 - Discovery</title>
<abstract>This specification describes an architecture based on the XMPP protocol whereby Things can be installed and safely discovered by their owners and connected into networks of Things.</abstract>
<p>Introduced possibility for hosting Thing Registry as a Jabber Server Component, using XEP-0114.</p>
<p>
Expanded de section <linkurl='#support'>Determining Support</link>, explaining how to search through server components.
</p>
<p>Removed the possibility to search for nick names, as a way of finding Thing Registries.</p>
<p>Added Security and Implementation Notes describing the pros and cons of hosting a Thing Registry as a Server Component vs. as a Client.</p>
</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2014-04-07</date>
<initials>pw</initials>
<remark>
<p>Removed any hard-coded account names.</p>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2014-03-11</date>
<initials>pw,rk</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>
When installing massive amounts of Things into public networks care has to be taken to make installation simple, but at the same time secure so that the Things cannot be
hijacked or hacked, making sure access to the Thing is controlled by the physical owner of the Thing. One of the main problems is how
to match the characteristics of a Thing, like serial number, manufacturer, model, etc., with information automatically created by the Thing itself, like perhaps its JID, in
an environment with massive amount of Things without rich user interfaces. Care has also to be taken when specifying rules for access rights and user privileges.
</p>
<p>
This document provides a network architecture based on the XMPP protocol that provides a means to safely install, configure, find and connect massive amounts of Things together, and
at the same time minimizing the risk that Things get hijacked. It also provides information how each individual step in the process can be performed with as little manual intervention
as possible, aiming where possible at zero-configuration networking. Furthermore, this document specifies how to create a registry that allows simple access to public Things
without risking their integrity unnecessarily.
</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>
<tablecaption='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>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>
<td>This specification. 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>
<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>Authority</dt>
<dd>Used synonymously with Provisioning Server.</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>Provisioning Server</dt>
<dd>
An application that can configure a network and provide services to users or Things. In Internet of Things, a Provisioning Server knows who knows whom,
what privileges users have, who can read what data and who can control what devices and what parts of these devices.
</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>Thing</dt>
<dd>
Internet of Things basically consists of Things connected to the Internet. Things can be any device, sensor, actuator etc., that can have an
Internet connection.
</dd>
</di>
<di>
<dt>Thing Registry</dt>
<dd>
A registry where Things can register for simple and secure discovery by the owner of the Thing. The registry can also be used as a database for meta information
about Things in the network.
</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 & 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>
<section1topic='Use Cases'anchor='usecases'>
<p>
The life cycle of a Thing can be divided into multiple steps. The following sections will list many of these steps in possible order of occurrence during the
During production of a Thing, decisions have to be made whether the following parameters should be pre-configured, manually entered after installation or
automatically found and/or created by the device if possible (zero-configuration networking):
</p>
<ul>
<li>
Address and domain of XMPP Server.
</li>
<li>
JID of the Thing.
</li>
<li>
JID of Thing Registry, if separate from the XMPP Server.
</li>
<li>
JID of first Provisioning Server, if separate from Thing Registry or XMPP Server.
</li>
</ul>
<p>
A decision has to be made at this point if global/manufacturer/customer servers should be used, or if local resources should be searched for and used if found.
The first option is easy to configure in a production environment and might have commercial significance,
but cannot use local resources where available. The second leaves much responsibility to the Thing for finding local resources, but has the advantage of allowing for a more
decentralized network architecture. A detailed discussion of the two alternatives goes beyond the scope of this specification, and will not be presented here.
Apart from physical installation, and connection to power and communication infrastructure, the installation phase of a Thing might also require manual entry of values that
could not be set in the production environment. Since Things might have very limited human user interfaces, external tools might be required to provide this information. Due
to its complexity, any manual entry of configuration parameters should be avoided, if possible. However, manual entry of some parameters might allow for Things to use local
resources where such cannot be found nor set in a production environment.
If the address of an XMPP Server is not preconfigured, the Thing must attempt to find one in its local surroundings. This can be done using one of several methods:
</p>
<ul>
<li>DHCP</li>
<li>Multicast DNS</li>
<li>SSDP/UPnP</li>
</ul>
<p>
The following sections describe them in more detail.
DHCP offers an internal structure for advertising configuration information to clients in a network.
This includes configuration parameters and other control elements, which are transmitted in special marked data elements, called 'options', as described in
<linkurl='http://www.iana.org/assignments/bootp-dhcp-parameters/bootp-dhcp-parameters.txt'>Dynamic Host Configuration Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters</link> lists currently assigned 'options' by IANA.
<strong>Note:</strong> There does exist no 'option' for XMPP at the moment.
Options 224 to 254 are marked as 'site-specific option range' to support local (to a site) configuration options (i.e., reserved as 'Private Use').
</p>
<p>
Possible codes for the XMPP server option:
</p>
<ul>
<li>Use 'site-specific option range'. Use of 'option-code' 224.</li>
<li>
<strong>TBD:</strong> Define and register DHCP and BOOTP option as described in <linkurl='#option'>Parameters for IoT Discovery</link>. Use of 'option-code' 84.
This option specifies the name of the XMPP server.
The name may or may not be qualified with the local domain name.
See &rfc1035; for character set restrictions.
</p>
<p>
The code for this option is 224 (for 'site-specific option range') or 84 (for <linkurl='#option'>DHCP and BOOTP Parameters for IoT Discovery</link>), and its minimum length is 1.
</p>
<examplecaption='IoT Discovery DHCP Option'>
<![CDATA[
<optioncode><datalength> machine]]>
</example>
<p>So, for example, if the machine name is "pronto", the code for the option is 224, the XMPP server option would be as follows:</p>
<p>The following parameters in use as of MONTH 201x. Refer to the DHCP and BOOTP parameters itself for a complete and current list of parameters (this specification might or might not be revised when new parameters are registered).</p>
<examplecaption='IoT Discovery DHCP and BOOTP Parameters Registry'>
A TXT record whose name is the same as the SRV record and whose value follows the format described in the <linkurl='#txt'>TXT Record</link> section of this document, consisting of a set of strings that typically represent a series of key-value pairs such as the following:
</p>
<examplecaption='TXT record'>
<![CDATA[
txtvers=1
ordom=example.com
regis=registry
provis=provisioning]]>
</example>
<p>Note: The DNS-SD specification stipulates that the TXT record MUST be published, but that it MAY contain no more than a single zero byte (e.g., if the server does not wish to publish any personal information).</p>
</li>
</ol>
<p>
For the purpose of IoT Discovery we are interested only in the "xmpp-client" service.
An XMPP server MUST publish four different kinds of DNS records to advertise its availability using the services of type "xmpp-client".
An XMPP chat client (actually its mDNS daemon) can send out multicast DNS queries for services of type "xmpp-client".
<strong>Note:</strong> the service of type "xmpp-client" is the reservered name for client-to-server connections by IANA, as described in &rfc6120;.
</p>
<p>So, for example, if the machine name is "pronto", the IP address is "10.2.1.188", and the personal information, the DNS records would be as follows:</p>
<examplecaption='IoT Discovery DNS Records Example'>
<p>The IPv4 and IPv6 addresses associated with a machine might vary depending on the local network to which the machine is connected. For example, on an Ethernet connection the physical address might be "192.168.0.100" but when the machine is connected to a wireless network the physical address might change to "10.10.1.188". See &rfc3927; for details.</p>
<p>If the machine name asserted by a client is already taken by another machine on the network, the client MUST assert a different machine name, which SHOULD be formed by adding the character "-" and digit "1" to the end of the machine name string (e.g., "pronto-1"), adding the character "-" and digit "2" if the resulting machine name is already taken (e.g., "pronto-2"), and similarly incrementing the digit until a unique machine name is constructed.</p>
<p>
<strong>Note:</strong> DNS-SD enables service definitions to include a TXT record that specifies parameters to be used in the context of the relevant service type. For detailed information refer to &xep0174; (Link-Local Messaging - TXT Record).
</p>
</section4>
<section4topic='IoT Discovery TXT Record Parameters Registry'anchor='txt'>
<p>The registration process is described in &xep0174; (Link-Local Messaging - Registration Process).</p>
<p>The following submission registers parameters in use as of MONTH 201x. Refer to the registry itself for a complete and current list of parameters (this specification might or might not be revised when new parameters are registered).</p>
<examplecaption='IoT Discovery TXT Record Parameters Registry'>
<