-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathxep-0347.xml
2121 lines (2094 loc) · 93.3 KB
/
xep-0347.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='UTF-8'?>
<!-- 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>
&LEGALNOTICE;
<number>0347</number>
<status>Deferred</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-0077</spec>
<spec>XEP-0114</spec>
<spec>XEP-0174</spec>
<spec>XEP-0323</spec>
<spec>XEP-0324</spec>
<spec>XEP-0325</spec>
<spec>XEP-0326</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iot-discovery</shortname>
&peterwaher;
<author>
<firstname>Ronny</firstname>
<surname>Klauck</surname>
<email>rklauck@informatik.tu-cottbus.de</email>
<jid>TBD</jid>
<uri>http://www-rnks.informatik.tu-cottbus.de/~rklauck</uri>
</author>
<revision>
<version>0.5.1</version>
<date>2018-11-03</date>
<initials>pep</initials>
<remark>Fix a bunch of typos, batch-style.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2017-09-11</date>
<initials>XEP Editor (jwi)</initials>
<remark>Defer due to lack of activity.</remark>
</revision>
<revision>
<version>0.4.1</version>
<date>2016-08-20</date>
<initials>XSF Editor: ssw</initials>
<remark>Replace external image with data URI.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2015-11-09</date>
<initials>pw</initials>
<remark>
<p>Updated contact information.</p>
<p>Updated example JIDs to example.org</p>
</remark>
</revision>
<revision>
<version>0.3</version>
<date>2014-11-11</date>
<initials>pw</initials>
<remark>
<p>
Added the possibility for <link url='#ownerupdate'>owners to update metadata about its things</link>.
This is done through the optional attribute <strong>jid</strong> on the <strong>update</strong> element.
</p>
<p>Added <strong>ROOM</strong> to the <link url='#tags'>list of predefined tag names</link>.</p>
<p>Added anchors to section headers.</p>
</remark>
</revision>
<revision>
<version>0.2</version>
<date>2014-09-07</date>
<initials>pw</initials>
<remark>
<p>Added a small note regarding URL encoding of hash signs, and corrected the Google Chart URL example.</p>
</remark>
</revision>
<revision>
<version>0.1</version>
<date>2014-04-10</date>
<initials>editor (mam)</initials>
<remark>
<p>Initial published version approved by XMPP Council.</p>
</remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2014-04-09</date>
<initials>pw</initials>
<remark>
<p>Introduced possibility for hosting Thing Registry as a Jabber Server Component, using XEP-0114.</p>
<p>
Expanded de section <link url='#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>
<section1 topic='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>
<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>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>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>
</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>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>
<section1 topic='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
life cycle of the Thing.
</p>
<section2 topic='Production' anchor='production'>
<p>
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.
</p>
</section2>
<section2 topic='Installation' anchor='installation'>
<p>
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.
</p>
</section2>
<section2 topic='Finding XMPP Server' anchor='findingserver'>
<p>
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.
</p>
<section3 topic='DHCP' anchor='dhcp'>
<p>
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
<span class='ref'>
<link url='http://tools.ietf.org/html/rfc3942'>RFC 3942</link>
</span> <note>
RFC 3942: Reclassifying Dynamic Host Configuration Protocol version 4 (DHCPv4) Options <<link url='http://tools.ietf.org/html/rfc3942'>http://tools.ietf.org/html/rfc3942</link>>.
</note>.
</p>
<p>
<link url='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 <link url='#option'>Parameters for IoT Discovery</link>. Use of 'option-code' 84.
</li>
</ul>
<section4 topic='XMPP Server Option' anchor='serveroption'>
<p>
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 <link url='#option'>DHCP and BOOTP Parameters for IoT Discovery</link>), and its minimum length is 1.
</p>
<example caption='IoT Discovery DHCP Option'>
<![CDATA[
<option code> <data length> 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>
<example caption='IoT Discovery DHCP Option Example'>
<![CDATA[
224 12 pronto.local]]>
</example>
</section4>
<section4 topic='Dynamic Host Configuration Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters for IoT Discovery' anchor='dhcpoption'>
<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>
<example caption='IoT Discovery DHCP and BOOTP Parameters Registry'>
<![CDATA[
<tag>84</tag>
<name>XMPP server</name>
<data length>N</data length>
<meaning>XMPP Servers DHCP Option</meaning>
<reference>[RFC6120]</reference>]]>
</example>
</section4>
</section3>
<section3 topic='Multicast DNS (mDNS) and DNS Service Discovery (DNS-SD)' anchor='dns'>
<p>
An introduction of mDNS/DNS-SD (e.g., how it works and terminology) is described in &xep0174; (i.e., sections [1.2] and [2]).
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>
<section4 topic='DNS Records' anchor='dnsrecords'>
<p>In order to advertise its availability, a server MUST publish four different kinds of DNS records:</p>
<ol>
<li>
<p>A PTR record of the following form:</p>
<example caption='PTR record'>
<![CDATA[
_xmpp-client._tcp.local. PTR machine._xmpp-client._tcp.local.]]>
</example>
</li>
<li>
<p>An address ("A" or "AAAA") record of the following form (where the IP address can be either an IPv4 address or an IPv6 address):</p>
<example caption='A record'>
<![CDATA[
machine.local. A ip-address]]>
</example>
</li>
<li>
<p>A SRV record of the following form:</p>
<example caption='SRV record'>
<![CDATA[
machine._xmpp-client._tcp.local <ttl> SRV <priority> <weight> port-number machine.local.]]>
</example>
</li>
<li>
<p>
A TXT record whose name is the same as the SRV record and whose value follows the format described in the <link url='#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>
<example caption='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>
<example caption='IoT Discovery DNS Records Example'>
<![CDATA[
_xmpp-client._tcp.local. PTR pronto._xmpp-client._tcp.local.
pronto._xmpp-client._tcp.local. SRV 5222 pronto.local.
pronto.local. A 10.2.1.188
pronto._xmpp-client._tcp.local. IN TXT
"txtvers=1"
"ordom=example.com"
"regis=registry"
"provis=provisioning"]]>
</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>
<section4 topic='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>
<example caption='IoT Discovery TXT Record Parameters Registry'>
<![CDATA[
<param>
<name>ordom</name>
<desc>The "origin domain" of the XMPP service.</desc>
<status>recommended</status>
</param>
<param>
<name>regis</name>
<desc>
The username portion of the JID to Thing Registry;
can contain a space-separated list of more than one JID.
</desc>
<status>optional</status>
</param>
<param>
<name>provis</name>
<desc>
The username portion of the JID to provisioning server;
can contain a space-separated list of more than one JID.
</desc>
<status>optional</status>
</param>]]>
</example>
</section4>
<!-- Ref: XEP-0174 -->
</section3>
<section3 topic='SSDP/UPnP' anchor='upnp'>
<p>TBD</p>
<!-- TODO -->
</section3>
<p>
<strong>Note:</strong> If server-less messaging is to be used, as described in &xep0174; this step can be used to find the Thing Registry and optionally the
Provisioning Server and other peers it want to connect to. The next section can thus be skipped.
</p>
</section2>
<section2 topic='Connection to XMPP Server' anchor='connection'>
<p>
Once an XMPP Server has been found, a connection can be made. If multiple XMPP Servers are found, the client is free to choose the one that best suits its purposes.
</p>
<p>
If the Thing does not have an account already, an account can be registered along what is specified in &xep0077;. If multiple servers are available, the first XMPP server that
allows account creation can be used.
</p>
</section2>
<section2 topic='Finding Thing Registry' anchor='findingregistry'>
<p>
If a Thing Registry is not preconfigured, one must be found. A Thing Registry can be hosted either as a server component using &xep0114; or as an XMPP Client accessible through
a JID. The following lists methods to obtaining the Component Address or JID for the Thing Registry. Note that the last one has <link url='#security'>security considerations</link>
that need to be taken into account, if implemented.
</p>
<ol>
<li>
Preconfigured Component Address of Thing Registry. A Component address is normally a subdomain to the domain of the XMPP Server that hosts the component.
</li>
<li>
Preconfigured bare JID of Thing Registry.
</li>
<li>
Preconfigured subdomain part of Component Address. This will be added to the domain of the XMPP Server used to connet to.
</li>
<li>
Preconfigured user name of JID. This will be added to the domain of the XMPP Server used to connected to.
</li>
<li>
Searching through Server Components on the XMPP Server currently connected to, as described in <link url='#support'>Determining Support</link>.
</li>
</ol>
</section2>
<section2 topic='Registering Thing' anchor='register'>
<p>
Once a Thing Registry has been found and been befriended, the Thing can register itself with the registry, as follows:
</p>
<example caption='Register Thing'>
<![CDATA[
<iq type='set'
from='thing@example.org/imc'
to='discovery.example.org'
id='1'>
<register xmlns='urn:xmpp:iot:discovery'>
<str name='SN' value='394872348732948723'/>
<str name='MAN' value='www.ktc.se'/>
<str name='MODEL' value='IMC'/>
<num name='V' value='1.2'/>
<str name='KEY' value='4857402340298342'/>
</register>
</iq>
<iq type='result'
from='discovery.example.org'
to='thing@example.org/imc'
id='1'/>]]>
</example>
<p>
There are two types of tags: Tags with string values and tags with numerical values. The distinction is important, since the type of value affects how
comparisons are made later when performing searches in the registry.
</p>
<p>
The Thing should only register parameters required to be known by the owner of the Thing. Dynamic meta information must be avoided at this point.
To claim the ownership of the Thing, the owner needs to present the same meta information as registered by the Thing. Before an owner has claimed
ownership of the Thing, it will not be returned in any search results. A list of predefined meta tag names can be found in the <link url='#tags'>Meta Tags</link>
section below.
</p>
<p>
The Thing can register itself as many times as it wants, and the response is always empty. Only one record per resource-less JID must be created. A new
registration overrides any previous information, including meta tags previously reported but not available in the new registration. Once a Thing has been
claimed by an owner, it should not register itself again, unless it is reset and the installation process restarted.
</p>
<p>
If the Thing tries to register itself even though the Thing has already been claimed in the registry, the registry must not update any meta data in the registry, and instead
respond with the following response. When the thing receives this, it can safely extract the JID of the owner and switch its internal state to claimed.
</p>
<example caption='Registration response when alrady claimed'>
<![CDATA[
<iq type='result'
from='discovery.example.org'
to='thing@example.org/imc'
id='1'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='owner@example.org'/>
</iq>]]>
</example>
<p>
<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
</p>
</section2>
<section2 topic='Register self-owned Thing' anchor='registerselfowner'>
<p>
If a thing is self-owned, it can register itself with the Registry as normal, with the addition of setting the attribute <strong>selfOwned</strong> to <strong>true</strong>,
as is shown below. This registers the Thing directly as PUBLIC CLAIMED, with no need for an owner to claim ownership of the device. This can be useful if
installing Things that should be publically available.
</p>
<example caption='Register self-owned Thing'>
<![CDATA[
<iq type='set'
from='thing@example.org/imc'
to='discovery.example.org'
id='2'>
<register xmlns='urn:xmpp:iot:discovery' selfOwned='true'>
<str name='SN' value='394872348732948723'/>
<str name='MAN' value='www.ktc.se'/>
<str name='MODEL' value='IMC'/>
<num name='V' value='1.2'/>
<str name='KEY' value='4857402340298342'/>
</register>
</iq>
<iq type='result'
from='discovery.example.org'
to='thing@example.org/imc'
id='2'/>]]>
</example>
</section2>
<section2 topic='Register Thing behind Concentrator' anchor='registerconcentrator'>
<p>
A Thing might reside behind a gateway or concentrator and might not be directly connected to the XMPP network itself, as is described in &xep0326;. In these cases, there are three optional
attributes that can be used to identify the Thing behind the JID: The <strong>nodeId</strong> attribute gives the ID of the Thing (a.k.a. "Node"). The Node might reside in
specific Data Source (large systems might have multiple sources of nodes). In this case, the data source is specified in the <strong>sourceId</strong> attribute. Normally, the Node ID
is considered to be unique within the concentrator. If multiple data sources are available, the Node ID is unique within the data source. However, a third attribute allows the uniqueness
to be restricted to a given <strong>cacheType</strong>. Finally, it is the triple (<strong>nodeId</strong>, <strong>sourceId</strong>, <strong>cacheType</strong>) which guarantees
uniqueness within the concentrator.
</p>
<p>
For a Thing controlled by a concentrator to register itself in the Thing Registry, it simply adds the optional attributes <strong>nodeId</strong>, <strong>sourceId</strong>
and <strong>cacheType</strong> as appropriate to the registration request, as follows:
</p>
<example caption='Register Thing behind Concentrator'>
<![CDATA[
<iq type='set'
from='rack@example.org/plcs'
to='discovery.example.org'
id='3'>
<register xmlns='urn:xmpp:iot:discovery' nodeId='imc1' sourceId='MeteringTopology'>
<str name='SN' value='394872348732948723'/>
<str name='MAN' value='www.ktc.se'/>
<str name='MODEL' value='IMC'/>
<num name='V' value='1.2'/>
<str name='KEY' value='4857402340298342'/>
</register>
</iq>
<iq type='result'
from='discovery.example.org'
to='rack@example.org/plcs'
id='3'/>]]>
</example>
<p>
If the Thing behind the concentrator is self-owned, it simply adds the <strong>selfOwned</strong> attribute to the request and sets it to <strong>true</strong>.
</p>
</section2>
<section2 topic='Claiming Ownership of a Thing' anchor='claim'>
<p>
As mentioned above, the owner of the Thing must provide the information provided by the Thing to the Registry, in order to claim ownership over it. To avoid the
possibility that somebody can guess the information, the information must necessarily be long. This creates the problem of transfer of information. One method to solve this
is through the use of QR-codes. Such codes can be either printed on a sticker and put on the Thing itself, its wrapping, or displayed on its display when not claimed.
This QR-code can then be photographed by a smart phone or tablet, decoded and the information retrieved can be used in the ownership claim call.
</p>
<p>
If QR-codes are used to transfer Thing meta data for ownership claims, it must be generated as follows: To the string "IoTDisco" is appended all meta tags in order.
Each tag name is prefixed by a semi-colon (;), and if the tag is numeric, the tag is prefixed by an additional hash sign (#). Each tag value is prefixed by a colon (:).
If the meta value contains semi-colons or back-slashes, each one is prefixed by a back-slash. When decoding the string, this allows the decoder to correctly differ
between tag delimiters and characters belonging to tag values. A tag name must never contain colon, hash sign or white space characters.
</p>
<p>
The above meta data would therefore generate the string:
</p>
<example caption='String to encode as a QR-code'>
<![CDATA[
IoTDisco;SN:394872348732948723;MAN:www.ktc.se;MODEL:IMC;#V:1.2;KEY:4857402340298342]]>
</example>
<p>
Using UTF-8 encoding when generating the QR-code, this string returns the following QR-code:
</p>
<p>
<img src='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABmJLR0QA/wD/AP+gvaeTAAAE9klEQVR4nO3d0WojORCG0WSZ93/l7MXeGAaDOqpPbXvPuQweuRN+NEVJLX3//Px8wbR/7n4APpNgkRAsEoJFQrBICBYJwSIhWCQEi4RgkRAsEoJFQrBICBYJwSIhWCQEi4RgkRAsEoJFQrBICBYJwSIhWCQEi8Sf2eG+v79nB/z6+nr2rvbjd+28z73yzI/jT33v1ed59gxTZn8XMxYJwSIhWCSGa6xHRd2zUlus1CgrP3825krNd3X8HXV9+TtmLBKCRUKwSIQ11qOrvaKVzzyOebW+eVYzXe1RTdVVU7XO1N95nxmLhGCRECwSh2qsKVPraDv109SYO32112fGIiFYJASLxJvVWDt9qZ3xV75r5TMrPbO71hxnmbFICBYJwSJxqMaaqg+uruVdrbem+kxX92xNrRW+Th1mxiIhWCQEi0RYY3X7qX/3DDs9pJ1xVmq1nT7cK/yd/2bGIiFYJASLxPfrdD4KV/dv7awV1mc6vBczFgnBIiFYJF7ofKyp85+u9o2e2fnM1F6rnRrx3lrQjEVCsEgIFonhPlZRG62MX5wRddfZp1Pfq8biAwkWCcEiEa4V3vWu3844z8Yszh3d6XVN7TN7Nv4+MxYJwSIhWCTeoI9V3HVT9HjqOuau/tnvmLFICBYJwSJx6C6dV1vnmtqzddUr71ebZcYiIVgkBIvEzX2suh9TP0/RW6r3Y51hxiIhWCQEi8TNfaydPUk7e5gKU+8M7uwDe/a99mPxIQSLhGCRuOEunZ2z1IuzD1YUPaGpM0uffWbl513dacYiIVgkBIvEDTXW1P/3V2udoqd19Yz4FVPvKt7LjEVCsEgIFolD+7GKu5avjl842SebeufxzFlZZiwSgkVCsEgc2o919fNTa2crzzNV30yd9VDXkWd6XWYsEoJFQrBIHLqv8GQf5eSe8al3GKfuw7nrzPq/mbFICBYJwSIRrhVO9XWK2mLle1cU57mvfJf3CvmfEiwSgkUiXCu82oMp9sLfdfb6zl3RxflY55mxSAgWCcEiccN9hSuf2elprTzPjrvu3ql7dfpYvAHBIiFYJA7VWI92+jfPxtl5hhU7+7GmnnNqT9uZ89/NWCQEi4RgkRheK9zZe1S/T1ecjzXVS5vq8917f84jMxYJwSIhWCRu3vN+sn8zpXgHsOg/ua+QDyRYJASLxKEaa6e/VZ8LX7yruKL43afOqthnxiIhWCQEi8Shu3RW/v+u+14r46w8T3EWw7Pxp9YWT96N/R8zFgnBIiFYJA7VWMWdfcW5VifPndp5/qv721bOyJhlxiIhWCQEi8Shc96nvMLZm1PrnvWZWPfuaTNjkRAsEoJFInyvcMrO/YBX38Xb+d6p/WcrdtZDrRXyxgSLhGCReKE7oR9NnUd1cv/WXeMXz7PPjEVCsEgIFokX2o9Vnyla9JmKs92n/q21Qj6QYJEQLBKHaqzCzruKO+uPO+epPvuu4l4ga4V8IMEiIVgk3rjGelScxbDymeLdvbrnd4YZi4RgkRAsEi90PtZVO+tfU2tkO+uPKzXZybO4ZpmxSAgWCcEiEdZYdR9lquaY2iN19X3DnX7VyX1gv2PGIiFYJASLxJudj8W7MGORECwSgkVCsEgIFgnBIiFYJASLhGCRECwSgkVCsEgIFgnBIiFYJASLhGCRECwSgkVCsEgIFgnBIiFYJASLhGCR+BeI2KOmeSzf/QAAAABJRU5ErkJggg=='/>
</p>
<p>
Once the client has the required meta information about the Thing to claim ownership, it sends itself the following request to the Thing Registry:
</p>
<example caption='Claim Ownership of public Thing'>
<![CDATA[
<iq type='set'
from='owner@example.org/phone'
to='discovery.example.org'
id='4'>
<mine xmlns='urn:xmpp:iot:discovery'>
<str name='SN' value='394872348732948723'/>
<str name='MAN' value='www.ktc.se'/>
<str name='MODEL' value='IMC'/>
<num name='V' value='1.2'/>
<str name='KEY' value='4857402340298342'/>
</mine>
</iq>]]>
</example>
<p>
If this claim is successful, the Thing is marked as a public claimed Thing. The thing can always be removed later, but after the claim, the Thing is public. If you want to claim
a private Thing, you can add the <strong>public</strong> attribute with value <strong>false</strong> to the claim, as follows:
</p>
<example caption='Claim Ownership of private Thing'>
<![CDATA[
<iq type='set'
from='owner@example.org/phone'
to='discovery.example.org'
id='4'>
<mine xmlns='urn:xmpp:iot:discovery' public='false'>
<str name='SN' value='394872348732948723'/>
<str name='MAN' value='www.ktc.se'/>
<str name='MODEL' value='IMC'/>
<num name='V' value='1.2'/>
<str name='KEY' value='4857402340298342'/>
</mine>
</iq>]]>
</example>
<p>
In this case, if the claim is successful, the Thing will not be made public in the Thing Registry, after the claim.
</p>
<p>
If a claim is successful, i.e. there's a Thing that has not been claimed with EXACTLY the same meta data (however, the order is not important), the Thing is marked in the
Registry as CLAIMED, and as public or private depending on the <strong>public</strong> attribute, and an empty result is returned as follows. If there's a claimed Thing with
exactly the same meta data, and the JID of the claimant (without resource) matches the JID of the claimer (without resource), a success response is also returned, containing
the resource-less JID of the Thing, as follows:
</p>
<example caption='Ownership claim successful'>
<![CDATA[
<iq type='result'
from='discovery.example.org'
to='owner@example.org/phone'
id='4'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='thing@example.org'/>
</iq>]]>
</example>
<p>
If the Thing that has been claimed resides behind a concentrator, the result will contain those of the attributes <strong>nodeId</strong>, <strong>sourceId</strong>
and <strong>cacheType</strong> that are required to access the Thing in calls made using &xep0323;, &xep0324;, &xep0325; and &xep0326;. The following example illustrates
a response where a Thing behind a Concentrator has been claimed:
</p>
<example caption='Ownership claim of a Thing behind a concentrator successful'>
<![CDATA[
<iq type='result'
from='discovery.example.org'
to='owner@example.org/phone'
id='4'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='rack@example.org/plcs' nodeId='imc1' sourceId='MeteringTopology'/>
</iq>]]>
</example>
<p>
If, on the other hand, no such Thing was found, or if such a Thing was found, but it is already claimed by somebody else, a failure response is returned. This response
should avoid to inform the client in detail why the claim failed, as follows:
</p>
<example caption='Ownership claim failure'>
<![CDATA[
<iq type='error'
from='discovery.example.org'
to='owner@example.org/phone'
id='4'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]>
</example>
<p>
When the Thing has been successfully claimed, the Registry sends information about this to the Thing, to inform it that it has been claimed and the resource-less JID of owner.
After receiving this information, it doesn't need to register itself with the Registry anymore.
</p>
<example caption='Ownership claimed'>
<![CDATA[
<iq type='set'
from='discovery.example.org'
to='thing@example.org/imc'
id='5'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='owner@example.org'/>
</iq>]]>
</example>
<p>
If the Thing was claimed as a private Thing, this is shown using the <strong>public</strong> attribute in the response, as follows:
</p>
<example caption='Ownership claim of private Thing successful'>
<![CDATA[
<iq type='set'
from='discovery.example.org'
to='thing@example.org/imc'
id='5'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='owner@example.org' public='false'/>
</iq>]]>
</example>
<p>
If the <strong>public</strong> attribute is present and has value <strong>false</strong>, it means no further meta data updates are necessary, since
the device is not searchable through the Thing Registry.
</p>
<p>
If the Thing resides behind a concentrator, the request must contain those of the attributes <strong>nodeId</strong>, <strong>sourceId</strong>
and <strong>cacheType</strong> that are required to access the Thing, as follows:
</p>
<example caption='Ownership of Thing behind concentrator claimed'>
<![CDATA[
<iq type='set'
from='discovery.example.org'
to='rack@example.org/plcs'
id='5'>
<claimed xmlns='urn:xmpp:iot:discovery' jid='owner@example.org' nodeId='imc1' sourceId='MeteringTopology'/>
</iq>]]>
</example>
<p>
The Thing simply returns an empty response to acknowledge the receipt of the information, as follows:
</p>
<example caption='Ownership claimed acknowledged'>
<![CDATA[
<iq type='result'
from='thing@example.org/imc'
to='discovery.example.org'
id='5'/>]]>
</example>
<p>
After receiving this, the thing knows it can accept friendship requests from the corresponding owner. It can also safely send a friendship request to the owner.
</p>
<p>
<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
</p>
</section2>
<section2 topic='Removing Thing from Registry' anchor='remove'>
<p>
After a Thing has been claimed and is registed as a PUBLIC CLAIMED Thing in the Registry, it implies the Thing is available in searches. The owner can choose to remove
the Thing from the Registry, to avoid that the Thing appears in searches. To remove a Thing from the Registry the owner simply sends a removal request to the Registry
with the resource-less JID of the Thing to remove, as follows:
</p>
<example caption='Remove Thing'>
<![CDATA[
<iq type='set'
from='owner@example.org/phone'
to='discovery.example.org'
id='6'>
<remove xmlns='urn:xmpp:iot:discovery' jid='thing@example.org'/>
</iq>]]>
</example>
<p>
If the Thing resides behind a concentrator, the request must contain those of the attributes <strong>nodeId</strong>, <strong>sourceId</strong>
and <strong>cacheType</strong> that are required to access the Thing, as follows:
</p>
<example caption='Remove Thing behind concentrator'>
<![CDATA[
<iq type='set'
from='owner@example.org/phone'
to='discovery.example.org'
id='6'>
<remove xmlns='urn:xmpp:iot:discovery' jid='rack@example.org/plcs' nodeId='imc1' sourceId='MeteringTopology'/>
</iq>]]>
</example>
<p>
If such a Thing is found and is owned by the caller, it is removed from the Registry, and an empty response is returned, to acknowledge the removal of the Thing
from the registry, as follows:
</p>
<example caption='Thing removed'>
<![CDATA[
<iq type='result'
from='discovery.example.org'
to='owner@example.org/phone'
id='6'/>]]>
</example>
<p>
However, if such a thing is not found, or if the thing is owned by another, an <strong>item-not-found</strong> error is returned, as follows:
</p>
<example caption='Removal failure'>
<![CDATA[
<iq type='error'
from='discovery.example.org'
to='owner@example.org/phone'
id='6'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]>
</example>
<p>
After successfully removing a Thing from the Registry, and if the Thing is friend to the Registry, the Registry informs the Thing it has been removed from the Registry.
It does this, so the Thing can remove the friendship and stop any meta data updates to the Registry.
</p>
<example caption='Thing removed from registry by owner'>
<![CDATA[
<iq type='set'
from='discovery.example.org'
to='thing@example.org/imc'
id='7'>
<removed xmlns='urn:xmpp:iot:discovery'/>
</iq>
<iq type='result'
from='thing@example.org/imc'
to='discovery.example.org'
id='7'/>]]>
</example>
<p>
If the Thing lies behind a concentrator, the removal request would look as follows:
</p>
<example caption='Thing behind concentrator removed from registry by owner'>
<![CDATA[
<iq type='set'
from='discovery.example.org'
to='rack@example.org/plcs'
id='7'>
<removed xmlns='urn:xmpp:iot:discovery' nodeId='imc1' sourceId='MeteringTopology'/>
</iq>]]>