-
Notifications
You must be signed in to change notification settings - Fork 13
/
Copy pathxep-0000-IoT-Chat.html
2004 lines (1767 loc) · 98.9 KB
/
xep-0000-IoT-Chat.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>XEP-xxxx: Chat Interface for Internet of Things Devices</title>
<link rel="stylesheet" type="text/css" href="xmpp.css">
<link href="prettify.css" type="text/css" rel="stylesheet">
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"><script type="text/javascript" src="prettify.js"></script><meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=2.0">
<meta name="DC.Title" content="Chat Interface for Internet of Things Devices">
<meta name="DC.Creator" content="Peter Waher">
<meta name="DC.Creator" content="Joachim Lindborg">
<meta name="DC.Description" content="
 This specification provides guidelines for how to create a chat interface for Internet of Things devices based on XMPP that both is intuitive for human users
 but at the same time is consistent with other Internet of Things extensions and underlying architecture. The ambition is also to create an interface that is
 both user friendly for human users and at the same time can be automated by machines and is consistent between manufacturers, in case other IoT-related extensions
 cannot be implemented.
 ">
<meta name="DC.Publisher" content="XMPP Standards Foundation">
<meta name="DC.Contributor" content="XMPP Extensions Editor">
<meta name="DC.Date" content="2013-10-30">
<meta name="DC.Type" content="XMPP Extension Protocol">
<meta name="DC.Format" content="XHTML">
<meta name="DC.Identifier" content="XEP-xxxx">
<meta name="DC.Language" content="en">
<meta name="DC.Rights" content="This XMPP Extension Protocol is copyright © 1999 - 2013 by the XMPP Standards Foundation (XSF).">
</head>
<body onload="prettyPrint()">
<h1>XEP-xxxx: Chat Interface for Internet of Things Devices</h1>
<table>
<tr valign="top">
<td><strong>Abstract:</strong></td>
<td>
This specification provides guidelines for how to create a chat interface for Internet of Things devices based on XMPP that both is intuitive for human users
but at the same time is consistent with other Internet of Things extensions and underlying architecture. The ambition is also to create an interface that is
both user friendly for human users and at the same time can be automated by machines and is consistent between manufacturers, in case other IoT-related extensions
cannot be implemented.
</td>
</tr>
<tr valign="top">
<td><strong>Authors:</strong></td>
<td>Peter Waher, Joachim Lindborg</td>
</tr>
<tr valign="top">
<td><strong>Copyright:</strong></td>
<td>© 1999 - 2013 XMPP Standards Foundation. <a href="#appendix-legal">SEE LEGAL NOTICES</a>.</td>
</tr>
<tr valign="top">
<td><strong>Status:</strong></td>
<td>ProtoXEP</td>
</tr>
<tr valign="top">
<td><strong>Type:</strong></td>
<td>Standards Track</td>
</tr>
<tr valign="top">
<td><strong>Version:</strong></td>
<td>0.0.1</td>
</tr>
<tr valign="top">
<td><strong>Last Updated:</strong></td>
<td>2013-10-30</td>
</tr>
</table>
<hr>
<p style="color:red">WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <<a href="http://xmpp.org/extensions/">http://xmpp.org/extensions/</a>> and announced on the <standards@xmpp.org> mailing list.</p>
<hr>
<h2>Table of Contents</h2>
<div class="indent">
<p><br>1. <a href="#intro">Introduction</a><br>2. <a href="#reqs">Requirements</a><br>3. <a href="#glossary">Glossary</a><br>4. <a href="#usecases">Use Cases</a><br>
4.1. <a href="#sect-ID0E3FAC">Readout of devices</a><br>
4.1.1. <a href="#sect-ID0EAGAC">Readout of standalone devices</a><br>
4.1.1.1. <a href="#sect-ID0EEGAC">Reading momentary values from single device or currently selected device</a><br>
4.1.1.2. <a href="#sect-ID0EKHAC">Reading all values from single device or currently selected device</a><br>
4.1.1.3. <a href="#sect-ID0EIIAC">Reading specific momentary field value from single device or currently selected device</a><br>
4.1.1.4. <a href="#sect-ID0EAJAC">Reading specific field values from single device or currently selected device</a><br>
4.1.2. <a href="#sect-ID0EXJAC">Readout of device behind concentrator</a><br>
4.1.2.1. <a href="#sect-ID0E2JAC">Reading momentary values from device behind concentrator</a><br>
4.1.2.2. <a href="#sect-ID0EJKAC">Reading all values from device behind concentrator</a><br>
4.1.2.3. <a href="#sect-ID0EXKAC">Reading specific momentary field value from device behind concentrator</a><br>
4.1.2.4. <a href="#sect-ID0EILAC">Reading specific field values from device behind concentrator</a><br>
4.2. <a href="#sect-ID0E2LAC">Control of devices</a><br>
4.2.1. <a href="#sect-ID0E6LAC">Control of standalone devices</a><br>
4.2.1.1. <a href="#sect-ID0EDMAC">Setting control parameter on single device or currently selected device</a><br>
4.2.1.2. <a href="#sect-ID0E2MAC">Listing control parameters on single device or currently selected device</a><br>
4.2.1.3. <a href="#sect-ID0E3NAC">Displaying current value of control parameter on single device or currently selected device</a><br>
4.2.2. <a href="#sect-ID0EWOAC">Control of device behind concentrator</a><br>
4.2.2.1. <a href="#sect-ID0E1OAC">Setting control parameter on single device behind concentrator</a><br>
4.2.2.2. <a href="#sect-ID0E1PAC">Listing control parameters on single device behind concentrator</a><br>
4.2.2.3. <a href="#sect-ID0EIBAE">Displaying current value of control parameter on single device behind concentrator</a><br>
4.3. <a href="#sect-ID0EFCAE">Configuring devices</a><br>
4.3.1. <a href="#sect-ID0EJCAE">Configuring standalone devices</a><br>
4.3.1.1. <a href="#sect-ID0ENCAE">Listing configuration parameters on currently selected device</a><br>
4.3.1.2. <a href="#sect-ID0EEDAE">Displaying current value of configuration parameter on currently selected device</a><br>
4.3.1.3. <a href="#sect-ID0EVDAE">Editing configuration parameter on currently selected device</a><br>
4.3.2. <a href="#sect-ID0EMEAE">Configuration of device behind concentrator</a><br>
4.3.2.1. <a href="#sect-ID0EQEAE">Listing configuration parameters on single device behind concentrator</a><br>
4.3.2.2. <a href="#sect-ID0EHFAE">Displaying current value of configuration parameter on single device behind concentrator</a><br>
4.3.2.3. <a href="#sect-ID0E2FAE">Editing configuration parameter on single device behind concentrator</a><br>
4.4. <a href="#sect-ID0EYGAE">Node Commands on devices</a><br>
4.4.1. <a href="#sect-ID0E3GAE">Node Commands on standalone devices</a><br>
4.4.1.1. <a href="#sect-ID0EAHAE">Displaying commands available on currently selected device</a><br>
4.4.1.2. <a href="#sect-ID0ERHAE">Selecting command on currently selected device</a><br>
4.4.1.3. <a href="#sect-ID0EXIAE">Editing command parameter in currently selected node command</a><br>
4.4.1.4. <a href="#sect-ID0ESJAE">Executing currently selected node command</a><br>
4.4.2. <a href="#sect-ID0EEKAE">Node Commands on device behind concentrator</a><br>
4.4.2.1. <a href="#sect-ID0EIKAE">Displaying commands available on single device behind concentrator</a><br>
4.4.2.2. <a href="#sect-ID0EZKAE">Selecting command on single device behind concentrator</a><br>
4.5. <a href="#sect-ID0EBMAE">Browsing Data Sources and Nodes on a concentrator</a><br>
4.5.1. <a href="#sect-ID0EFMAE">Selecting Root Node in current data source</a><br>
4.5.2. <a href="#sect-ID0EWMAE">Selecting Root Data Source</a><br>
4.5.3. <a href="#sect-ID0EHNAE">Selecting Item</a><br>
4.6. <a href="#sect-ID0EQOAE">Menu Commands</a><br>
4.6.1. <a href="#currentoptions">List current options</a><br>
4.6.2. <a href="#sect-ID0EPPAE">Go to previous menu</a><br>
4.7. <a href="#sect-ID0E3PAE">User authentication</a><br>5. <a href="#dataforms">Data Forms</a><br>6. <a href="#syntax">Syntax</a><br>7. <a href="#output">Output format</a><br>8. <a href="#support">Determining Support</a><br>9. <a href="#impl">Implementation Notes</a><br>
9.1. <a href="#sect-ID0E24AE">Chat sessions</a><br>10. <a href="#i18n">Internationalization Considerations</a><br>
10.1. <a href="#sect-ID0EH5AE">Localization</a><br>11. <a href="#security">Security Considerations</a><br>12. <a href="#iana">IANA Considerations</a><br>13. <a href="#registrar">XMPP Registrar Considerations</a><br>14. <a href="#moreinfo">For more information</a></p>
<p><a href="#appendices">Appendices</a><br> <a href="#appendix-docinfo">A: Document Information</a><br> <a href="#appendix-authorinfo">B: Author Information</a><br> <a href="#appendix-legal">C: Legal Notices</a><br> <a href="#appendix-xmpp">D: Relation to XMPP</a><br> <a href="#appendix-discuss">E: Discussion Venue</a><br> <a href="#appendix-conformance">F: Requirements Conformance</a><br> <a href="#appendix-notes">G: Notes</a><br> <a href="#appendix-revs">H: Revision History</a></p>
</div>
<hr>
<h2>1.
<a name="intro">Introduction</a></h2>
<p class="" style="">
Internet of Things (IoT) is often believed to be just an extension of machine-to-machine communication over internet but the human interface to devices are one of the biggest advantage in IoT.
There are numerous interfaces, mobile applications,html and html5 pages in here we create a human-to-machine interface using plain chat messages. One reason for this is to create a simple
interface that can be accessed from mobile phones without special software and that can be used during installation of devices. This extension create rules for
how such an interface is constructed, including chat syntax. The goal is to make the interface:
</p>
<ul class="" style="">
<li class="" style="">
simple and user-friendly for human users.
</li>
<li class="" style="">
possible to automate by machines.
</li>
<li class="" style="">
is consistent between manufacturers.
</li>
<li class="" style="">
is consistent with other Internet-of-Things extensions and possible underlying architecture.
</li>
<li class="" style="">
include both reading of sensors and control of actuators and configuration.
</li>
<li class="" style="">
possibile to extend
</li>
</ul>
<h2>2.
<a name="reqs">Requirements</a></h2>
<p class="" style="">
Clients and devices must support sending and receiving of normal text messages. See XMPP core specifications for more details about syntax.
</p>
<h2>3.
<a name="glossary">Glossary</a></h2>
<p class="" style="">The following table lists common terms and corresponding descriptions.</p>
<div class="indent">
<dl>
<di>
<dt><strong>Actuator</strong></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><strong>Computed Value</strong></dt>
<dd>A value that is computed instead of measured.</dd>
</di>
<di>
<dt><strong>Concentrator</strong></dt>
<dd>Device managing a set of devices which it publishes on the XMPP network.</dd>
</di>
<di>
<dt><strong>Data Source</strong></dt>
<dd>
A Data source contains a collection of nodes. Three types of data sources exist: Singular, Flat and Tree. Singular data sources only include one object.
Flat data sources contain a list of objects and Tree data sources contain nodes formed as a tree graph with one root element.
</dd>
</di>
<di>
<dt><strong>Field</strong></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><strong>Field Name</strong></dt>
<dd>Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.</dd>
</di>
<di>
<dt><strong>Field Type</strong></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><strong>Historical Value</strong></dt>
<dd>A value stored in memory from a previous timestamp.</dd>
</di>
<di>
<dt><strong>Identification Value</strong></dt>
<dd>A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)</dd>
</di>
<di>
<dt><strong>Localization information</strong></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><strong>Meter</strong></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><strong>Momentary Value</strong></dt>
<dd>A momentary value represents a value measured at the time of the read-out.</dd>
</di>
<di>
<dt><strong>Node</strong></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. Nodes belong to a data source, and all nodes have a Node Type. Some nodes have a parent node, and some nodes have child nodes. Nodes with the same
parent nodes a called sibling nodes.
</dd>
</di>
<di>
<dt><strong>Node ID</strong></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><strong>Node Type</strong></dt>
<dd>Each node has a Node Type. The Node Type defines the functionality of the node in the system.</dd>
</di>
<di>
<dt><strong>Parameter</strong></dt>
<dd>
Readable and/or writable property on a node/device. The XEP-0326 <span class="ref" style=""><a href="http://xmpp.org/extensions/xep-0326.html">Internet of Things - Concentrators</a></span> [<a href="#nt-ID0EFBAC">1</a>] deals with reading and writing parameters
on nodes/devices. Fields are not parameters, and parameters are not fields.
</dd>
</di>
<di>
<dt><strong>Peak Value</strong></dt>
<dd>A maximum or minimum value during a given period.</dd>
</di>
<di>
<dt><strong>Precision</strong></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><strong>Sensor</strong></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><strong>SN</strong></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><strong>Status Value</strong></dt>
<dd>A value displaying status information about something.</dd>
</di>
<di>
<dt><strong>Timestamp</strong></dt>
<dd>Timestamp of value, when the value was sampled or recorded.</dd>
</di>
<di>
<dt><strong>Token</strong></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><strong>Unit</strong></dt>
<dd>Physical unit of value. Example: MWh, l/s, etc.</dd>
</di>
<di>
<dt><strong>Value</strong></dt>
<dd>A field value.</dd>
</di>
<di>
<dt><strong>Value Status</strong></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><strong>Value Type</strong></dt>
<dd>Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.</dd>
</di>
<di>
<dt><strong>WSN</strong></dt>
<dd>Wireless Sensor Network, a sensor network including wireless devices.</dd>
</di>
<di>
<dt><strong>XMPP Client</strong></dt>
<dd>Application connected to an XMPP network, having a JID. Note that sensors, as well as applications and services requesting sensor data can be XMPP clients.</dd>
</di>
</dl>
</div>
<h2>4.
<a name="usecases">Use Cases</a></h2>
<p class="" style="">
All communication between two peers (human or machine) is done using normal text messages. Therefore, all examples in this document will only specify
the actual text messages being sent, not the underlying XMPP XML stanzas. IoT devices can choose to use forms <span class="ref" style=""><a href="http://xmpp.org/extensions/xep-0071.html">XHTML-IM</a></span> [<a href="#nt-ID0EYEAC">2</a>] to enhance text output, but automatons
interpreting received messages should use the normal text message as source for their interpretation. This document does not specify any HTML formats used.
</p>
<p class="" style="">
For each usecase there are two specific views one when communicating with a single device and the other when comunicating with devices behind a concentrator.
Commands are just the same but the graphical structure behind the concentrator can be big.
</p>
<p class="" style="">
Together with the examples, suggested regular expressions will be provided to facilitate machine extraction of information from the text. This document does not
require the use of regular expressions in any implementation. These expressions act as a documentation of the exact syntax or format of the corresponding text messages.
</p>
<p class="" style="">
<span class="strong">Note 1:</span> The client sending commands should not expect messages to be sent for each row, nor expect all rows in a response to be sent in one message.
The sender is free to send any number of messages, with any number of rows in each message. Each row SHOULD be separated by a CRLF character sequence.
</p>
<p class="" style="">
<span class="strong">Note 2:</span> In examples where messages are sent in both directions, messages from the requesting party (client) will be prefixed by C:
and messages from the answering party (server) will be prefixed by S: This is for readability purposes only, and do not represent actual characters
send in messages.
</p>
<p class="" style="">
<span class="strong">Note 3:</span> When the client sends a column based respons it MUST use \t TAB between them.
</p>
<div class="indent">
<h3>4.1 <a name="sect-ID0E3FAC">Readout of devices</a></h3>
<div class="indent">
<h3>4.1.1 <a name="sect-ID0EAGAC">Readout of standalone devices</a></h3>
<div class="indent">
<h3>4.1.1.1 <a name="sect-ID0EEGAC">Reading momentary values from single device or currently selected device</a></h3>
<p class="" style="">
This is the first and most basic usage after the client has logged in. The single ? asks for a momentary readout of values
from the fields at the device. If the device has a structure each node in the graph kan be traversed and momentary read out
This is not a recursive command
</p>
<p class="caption"><a name="example-1"></a>Example 1. Requesting a readout of momentary values from single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
?
</pre>
</div>
<p class="" style="">
If no locale is present in the message from the client or the device cannot support locale the output comes as fieldnames with values and units
Note: The readout is performed asynchronously, which may imply a delay before the response is returned.
</p>
<p class="caption"><a name="example-2"></a>Example 2. Momentary value response without localized field names</p>
<div class="indent">
<pre class="prettyprint">
Readout of Vina del Mar started...
Condition Fair
Condition Code 34
Temperature 18 °C
Chill 18 °C
Wind Direction 330 °
Wind Speed 14,48 km/h
Humidity 52 %
Visibility 9,99 km
Pressure 1015,92 mbar
Pressure Trend Steady
</pre>
</div>
<p class="" style="">
If locale is present in the message and the client can support the provided locale. The output is extended with the localized fieldnames
NOTE When doing automation it is recomended not to use locale
</p>
<p class="caption"><a name="example-3"></a>Example 3. Momentary value response with localized field names</p>
<div class="indent">
<pre class="prettyprint">
Urläsning av Vina del Mar påbörjad...
Condition Fair (Tillstånd)
Condition Code 34 (Tillståndskod)
Temperature 19 °C (Temperatur)
Chill 19 °C (Nedkylning)
Wind Direction 200 ° (Vindriktning)
Wind Speed 25,75 km/h (Vindhastighet)
Humidity 46 % (Luftfuktighet)
Visibility 9,99 km (Visibilitet)
Pressure 1015,92 mbar (Tryck)
Pressure Trend Falling (Lufttryckstrend)
</pre>
</div>
<p class="" style="">
When creation automation with this as basis the result can be parsed with this suggested regular expression.
The device MUST use \t as the dividor between parts and CRLF pair as end row
</p>
<p class="caption"><a name="example-4"></a>Example 4. Multi-line regular expression for parsing readout results</p>
<div class="indent">
<pre class="prettyprint">
^(?'FieldName'[^\t]+)\t(?'Value'[^\t\n]+)(\t[(](?'Localized'[^)]+)[)])?
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.1.2 <a name="sect-ID0EKHAC">Reading all values from single device or currently selected device</a></h3>
<p class="" style="">
Using a double ?? makes a deeper introspection and gives a more thorough value set in return
</p>
<p class="caption"><a name="example-5"></a>Example 5. Requesting a readout of momentary values from single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
??
</pre>
</div>
<p class="caption"><a name="example-6"></a>Example 6. Full readout response without localized field names</p>
<div class="indent">
<pre class="prettyprint">
Readout of Vina del Mar started...
Latitude Latitude -33,02 ° 2013-11-06 16:49:56 Identity AutomaticReadout
Longitude Longitude -71,55 ° 2013-11-06 16:49:56 Identity AutomaticReadout
Condition Condition Fair 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Condition Code Condition Code 34 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Temperature Temperature 19 °C 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Description Description Yahoo! Weather - Vina del Mar, CL 2013-11-06 16:49:56 StatusValues AutomaticReadout
City City Vina del Mar 2013-11-06 16:49:56 StatusValues AutomaticReadout
Country Country Chile 2013-11-06 16:49:56 StatusValues AutomaticReadout
Chill Chill 19 °C 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Wind Direction Wind Direction 200 ° 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Wind Speed Wind Speed 25,75 km/h 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Humidity Humidity 46 % 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Visibility Visibility 9,99 km 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Pressure Pressure 1015,92 mbar 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Pressure Trend Pressure Trend Falling 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
</pre>
</div>
<p class="caption"><a name="example-7"></a>Example 7. Full readout response with localized field names</p>
<div class="indent">
<pre class="prettyprint">
Urläsning av Vina del Mar påbörjad...
Latitude Latitud -33,02 ° 2013-11-06 16:49:56 Identity AutomaticReadout
Longitude Longitud -71,55 ° 2013-11-06 16:49:56 Identity AutomaticReadout
Condition Tillstånd Fair 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Condition Code Tillståndskod 34 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Temperature Temperatur 19 °C 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Description Beskrivning Yahoo! Weather - Vina del Mar, CL 2013-11-06 16:49:56 StatusValues AutomaticReadout
City Stad Vina del Mar 2013-11-06 16:49:56 StatusValues AutomaticReadout
Country Land Chile 2013-11-06 16:49:56 StatusValues AutomaticReadout
Chill Nedkylning 19 °C 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Wind Direction Vindriktning 200 ° 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Wind Speed Vindhastighet 25,75 km/h 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Humidity Luftfuktighet 46 % 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Visibility Visibilitet 9,99 km 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Pressure Tryck 1015,92 mbar 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
Pressure Trend Lufttryckstrend Falling 2013-11-06 16:49:56 MomentaryValues AutomaticReadout
</pre>
</div>
<p class="caption"><a name="example-8"></a>Example 8. Multi-line regular expression for parsing readout results</p>
<div class="indent">
<pre class="prettyprint">
^(?'FieldName'[^\t]+)\t(?'Localized'[^\t]+)\t(?'Value'[^\t]+)\t(?'Year'\d{4})-(?'Month'\d{2})-(?'Day'\d{2}) (?'Hour'\d{2}):(?'Minute'\d{2}):(?'Second'\d{2})\t(?'Type'[^\t]+)\t(?'Status'[^\n]+)
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.1.3 <a name="sect-ID0EIIAC">Reading specific momentary field value from single device or currently selected device</a></h3>
<p class="" style="">
Instead of doing full readouts a specific field value can be requested from the device.
Note the caption is important when sending field names
</p>
<p class="caption"><a name="example-9"></a>Example 9. Requesting a readout of a specific momentary value from single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Temperature?
</pre>
</div>
<p class="caption"><a name="example-10"></a>Example 10. Specific momentary value response without localized field names</p>
<div class="indent">
<pre class="prettyprint">
Readout of klart.se - Stockholm (2) - Albano started...
Temperature 0 °C
</pre>
</div>
<p class="caption"><a name="example-11"></a>Example 11. Specific momentary value response with localized field names</p>
<div class="indent">
<pre class="prettyprint">
Temperature?
Urläsning av klart.se - Stockholm (2) - Albano påbörjad...
Temperature 0 °C (Temperatur)
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.1.4 <a name="sect-ID0EAJAC">Reading specific field values from single device or currently selected device</a></h3>
<p class="caption"><a name="example-12"></a>Example 12. Requesting a readout of specific field values from single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Temperature??
</pre>
</div>
<p class="caption"><a name="example-13"></a>Example 13. Full readout response without localized field names</p>
<div class="indent">
<pre class="prettyprint">
Readout of klart.se - Stockholm (2) - Albano started...
Temperature Temperature 0 °C 2013-11-06 16:00:00 MomentaryValues AutomaticReadout
Temperature Temperature 5 °C 2013-11-06 04:00:00 Computed AutomaticReadout
Temperature Temperature 6 °C 2013-11-06 10:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-06 16:00:00 Computed AutomaticReadout
Temperature Temperature 3 °C 2013-11-07 04:00:00 Computed AutomaticReadout
Temperature Temperature 6 °C 2013-11-07 10:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-07 16:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-08 04:00:00 Computed AutomaticReadout
Temperature Temperature 6 °C 2013-11-08 10:00:00 Computed AutomaticReadout
Temperature Temperature 6 °C 2013-11-08 16:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-09 03:00:00 Computed AutomaticReadout
Temperature Temperature 7 °C 2013-11-09 09:00:00 Computed AutomaticReadout
Temperature Temperature 6 °C 2013-11-09 15:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-10 03:00:00 Computed AutomaticReadout
Temperature Temperature 5 °C 2013-11-10 09:00:00 Computed AutomaticReadout
Temperature Temperature 4 °C 2013-11-10 15:00:00 Computed AutomaticReadout
</pre>
</div>
<p class="caption"><a name="example-14"></a>Example 14. Full readout response with localized field names</p>
<div class="indent">
<pre class="prettyprint">
Urläsning av klart.se - Stockholm (2) - Albano påbörjad...
Temperature Temperatur 0 °C 2013-11-06 16:00:00 MomentaryValues AutomaticReadout
Temperature Temperatur 5 °C 2013-11-06 04:00:00 Computed AutomaticReadout
Temperature Temperatur 6 °C 2013-11-06 10:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-06 16:00:00 Computed AutomaticReadout
Temperature Temperatur 3 °C 2013-11-07 04:00:00 Computed AutomaticReadout
Temperature Temperatur 6 °C 2013-11-07 10:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-07 16:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-08 04:00:00 Computed AutomaticReadout
Temperature Temperatur 6 °C 2013-11-08 10:00:00 Computed AutomaticReadout
Temperature Temperatur 6 °C 2013-11-08 16:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-09 03:00:00 Computed AutomaticReadout
Temperature Temperatur 7 °C 2013-11-09 09:00:00 Computed AutomaticReadout
Temperature Temperatur 6 °C 2013-11-09 15:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-10 03:00:00 Computed AutomaticReadout
Temperature Temperatur 5 °C 2013-11-10 09:00:00 Computed AutomaticReadout
Temperature Temperatur 4 °C 2013-11-10 15:00:00 Computed AutomaticReadout
</pre>
</div>
</div>
</div>
<div class="indent">
<h3>4.1.2 <a name="sect-ID0EXJAC">Readout of device behind concentrator</a></h3>
<div class="indent">
<h3>4.1.2.1 <a name="sect-ID0E2JAC">Reading momentary values from device behind concentrator</a></h3>
<p class="" style="">
To request data from devices behind a concentrator you do the same as for single devices but you need to traverse the graph through the concentrator to extract values
the traversal is done with the menu numbers returned at each junction in the graph of nodes see the menu command below
</p>
<p class="caption"><a name="example-15"></a>Example 15. Requesting a readout of momentary values from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Vina del Mar?
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.2.2 <a name="sect-ID0EJKAC">Reading all values from device behind concentrator</a></h3>
<p class="caption"><a name="example-16"></a>Example 16. Requesting a readout of all values from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Vina del Mar??
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.2.3 <a name="sect-ID0EXKAC">Reading specific momentary field value from device behind concentrator</a></h3>
<p class="caption"><a name="example-17"></a>Example 17. Requesting a readout of a specific momentary value from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Vina del Mar.Temperature?
</pre>
</div>
<p class="caption"><a name="example-18"></a>Example 18. Alternative method of requesting a readout of a specific momentary value from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Temperature@Vina del Mar?
</pre>
</div>
</div>
<div class="indent">
<h3>4.1.2.4 <a name="sect-ID0EILAC">Reading specific field values from device behind concentrator</a></h3>
<p class="caption"><a name="example-19"></a>Example 19. Requesting a readout of specific field values from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Vina del Mar.Temperature??
</pre>
</div>
<p class="caption"><a name="example-20"></a>Example 20. Alternative method of requesting a readout of specific field values from a device behind a concentrator</p>
<div class="indent">
<pre class="prettyprint">
Temperature@Vina del Mar??
</pre>
</div>
</div>
</div>
</div>
<div class="indent">
<h3>4.2 <a name="sect-ID0E2LAC">Control of devices</a></h3>
<div class="indent">
<h3>4.2.1 <a name="sect-ID0E6LAC">Control of standalone devices</a></h3>
<div class="indent">
<h3>4.2.1.1 <a name="sect-ID0EDMAC">Setting control parameter on single device or currently selected device</a></h3>
<p class="" style="">
When setting a value on a field we use the = or !. The notion for ! is that the value i applied onto the node object. which will
analog with the applying commands and cofigurations later.
The caption is important when specifying the the fieldname
</p>
<p class="caption"><a name="example-21"></a>Example 21. Requesting a control parameter to be set to a new value on a single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Output=75
</pre>
</div>
<p class="caption"><a name="example-22"></a>Example 22. Alternative method for requesting a control parameter to be set to a new value on a single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Output!75
</pre>
</div>
<p class="caption"><a name="example-23"></a>Example 23. Control parameter response when parameter has been successfully set</p>
<div class="indent">
<pre class="prettyprint">
Output=75
</pre>
</div>
</div>
<div class="indent">
<h3>4.2.1.2 <a name="sect-ID0E2MAC">Listing control parameters on single device or currently selected device</a></h3>
<p class="caption"><a name="example-24"></a>Example 24. Listing control parameters on single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
=?
</pre>
</div>
<p class="caption"><a name="example-25"></a>Example 25. Alternative method for listing control parameters on single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
!?
</pre>
</div>
<p class="caption"><a name="example-26"></a>Example 26. List of control parameters</p>
<div class="indent">
<pre class="prettyprint">
1. Output=0 (Output)
0. Tillbaka
</pre>
</div>
<p class="" style="">
After the list of parameters has been sent, the device can optionally send a data form with the same parameters. If the client supports
forms it can present the form in a more user friendly window. See <a href="#dataforms">Data Forms</a> for more information. Submitting the
form means executing the corresponding control commands.
</p>
<p class="caption"><a name="example-27"></a>Example 27. Using menu shortcuts</p>
<div class="indent">
<pre class="prettyprint">
C: =?
S: 1. Output=0 (Output)
S: 0. Tillbaka
C: 1=75
S: Output=75
</pre>
</div>
</div>
<div class="indent">
<h3>4.2.1.3 <a name="sect-ID0E3NAC">Displaying current value of control parameter on single device or currently selected device</a></h3>
<p class="caption"><a name="example-28"></a>Example 28. Displaying current value of control parameter on single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Output=?
</pre>
</div>
<p class="caption"><a name="example-29"></a>Example 29. Alternative method for displaying current value of control parameter on single device or currently selected device</p>
<div class="indent">
<pre class="prettyprint">
Output!?
</pre>
</div>
<p class="caption"><a name="example-30"></a>Example 30. Listing control parameter</p>
<div class="indent">
<pre class="prettyprint">
Output=0
</pre>
</div>
<p class="caption"><a name="example-31"></a>Example 31. Using menu shortcuts</p>
<div class="indent">
<pre class="prettyprint">
C: =?
S: 1. Output=0 (Output)
S: 0. Tillbaka
C: 1=?
S: Output=75
</pre>
</div>
</div>
</div>
<div class="indent">
<h3>4.2.2 <a name="sect-ID0EWOAC">Control of device behind concentrator</a></h3>
<div class="indent">
<h3>4.2.2.1 <a name="sect-ID0E1OAC">Setting control parameter on single device behind concentrator</a></h3>
<p class="caption"><a name="example-32"></a>Example 32. Requesting a control parameter to be set to a new value on a single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.Output=75
</pre>
</div>
<p class="caption"><a name="example-33"></a>Example 33. Alternative method for requesting a control parameter to be set to a new value on a single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.Output!75
</pre>
</div>
<p class="caption"><a name="example-34"></a>Example 34. Alternative method 2 for requesting a control parameter to be set to a new value on a single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Output@Analog Output=75
</pre>
</div>
<p class="caption"><a name="example-35"></a>Example 35. Alternative method 3 for requesting a control parameter to be set to a new value on a single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Output@Analog Output!75
</pre>
</div>
<p class="caption"><a name="example-36"></a>Example 36. Control parameter response when parameter has been successfully set</p>
<div class="indent">
<pre class="prettyprint">
Output=75
</pre>
</div>
</div>
<div class="indent">
<h3>4.2.2.2 <a name="sect-ID0E1PAC">Listing control parameters on single device behind concentrator</a></h3>
<p class="caption"><a name="example-37"></a>Example 37. Listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output=?
</pre>
</div>
<p class="caption"><a name="example-38"></a>Example 38. Alternative method for listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output!?
</pre>
</div>
<p class="caption"><a name="example-39"></a>Example 39. Alternative method 2 for listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.=?
</pre>
</div>
<p class="caption"><a name="example-40"></a>Example 40. Alternative method 3 for listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.!?
</pre>
</div>
<p class="caption"><a name="example-41"></a>Example 41. Alternative method 4 for listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
@Analog Output=?
</pre>
</div>
<p class="caption"><a name="example-42"></a>Example 42. Alternative method 5 for listing control parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
@Analog Output?
</pre>
</div>
<p class="" style="">
After the list of parameters has been sent, the device can optionally send a data form with the same parameters. If the client supports
forms it can present the form in a more user friendly window. See <a href="#dataforms">Data Forms</a> for more information. Submitting the
form means executing the corresponding control commands.
</p>
</div>
<div class="indent">
<h3>4.2.2.3 <a name="sect-ID0EIBAE">Displaying current value of control parameter on single device behind concentrator</a></h3>
<p class="caption"><a name="example-43"></a>Example 43. Displaying current value of control parameter on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.Output=?
</pre>
</div>
<p class="caption"><a name="example-44"></a>Example 44. Alternative method for displaying current value of control parameter on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output.Output!?
</pre>
</div>
<p class="caption"><a name="example-45"></a>Example 45. Alternative method 2 for displaying current value of control parameter on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Output@Analog Output=?
</pre>
</div>
<p class="caption"><a name="example-46"></a>Example 46. Alternative method 3 for displaying current value of control parameter on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Output@Analog Output!?
</pre>
</div>
</div>
</div>
</div>
<div class="indent">
<h3>4.3 <a name="sect-ID0EFCAE">Configuring devices</a></h3>
<div class="indent">
<h3>4.3.1 <a name="sect-ID0EJCAE">Configuring standalone devices</a></h3>
<div class="indent">
<h3>4.3.1.1 <a name="sect-ID0ENCAE">Listing configuration parameters on currently selected device</a></h3>
<p class="caption"><a name="example-47"></a>Example 47. Listing configuration parameters on currently selected device</p>
<div class="indent">
<pre class="prettyprint">
:?
</pre>
</div>
<p class="caption"><a name="example-48"></a>Example 48. List of configuration parameters</p>
<div class="indent">
<pre class="prettyprint">
1. id:Analog Output (ID)
2. customPrivilegeId: (Required User Privilege)
3. name: (Name)
4. class:Other (Class)
5. phase:Installation (Lifecycle Phase)
6. enabled:true (Enabled)
7. meterLocationId: (Meter Location ID)
8. meterNumber: (Meter Number)
...
0. Back
</pre>
</div>
<p class="" style="">
After the list of parameters has been sent, the device can optionally send a data form with the same parameters. If the client supports
forms it can present the form in a more user friendly window. See <a href="#dataforms">Data Forms</a> for more information. Submitting the
form means configuring the node.
</p>
</div>
<div class="indent">
<h3>4.3.1.2 <a name="sect-ID0EEDAE">Displaying current value of configuration parameter on currently selected device</a></h3>
<p class="caption"><a name="example-49"></a>Example 49. Displaying current value of configuration parameter on currently selected device</p>
<div class="indent">
<pre class="prettyprint">
phase:?
</pre>
</div>
<p class="caption"><a name="example-50"></a>Example 50. Value of configuration parameter</p>
<div class="indent">
<pre class="prettyprint">
phase:Installation
</pre>
</div>
</div>
<div class="indent">
<h3>4.3.1.3 <a name="sect-ID0EVDAE">Editing configuration parameter on currently selected device</a></h3>
<p class="caption"><a name="example-51"></a>Example 51. Editing configuration parameter on currently selected device</p>
<div class="indent">
<pre class="prettyprint">
phase:Test
</pre>
</div>
<p class="caption"><a name="example-52"></a>Example 52. Acknowledge that configuration was performed</p>
<div class="indent">
<pre class="prettyprint">
OK
</pre>
</div>
<p class="caption"><a name="example-53"></a>Example 53. Configuration error</p>
<div class="indent">
<pre class="prettyprint">
C: phase:test
S: ! Select a value from the list. (Installation, Test, Production)
</pre>
</div>
</div>
</div>
<div class="indent">
<h3>4.3.2 <a name="sect-ID0EMEAE">Configuration of device behind concentrator</a></h3>
<div class="indent">
<h3>4.3.2.1 <a name="sect-ID0EQEAE">Listing configuration parameters on single device behind concentrator</a></h3>
<p class="caption"><a name="example-54"></a>Example 54. Listing configuration parameters on single device behind concentrator</p>
<div class="indent">
<pre class="prettyprint">
Analog Output:?
</pre>
</div>
<p class="caption"><a name="example-55"></a>Example 55. List of configuration parameters</p>
<div class="indent">
<pre class="prettyprint">