-
Notifications
You must be signed in to change notification settings - Fork 13
/
Copy pathxep-0000-IoT-Chat.xml
1743 lines (1707 loc) · 78.5 KB
/
xep-0000-IoT-Chat.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'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<!--
© Clayster 2013-2014
Author: Peter Waher
-->
<xep>
<header>
<title>Chat Interface for Internet of Things Devices</title>
<abstract>
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.
</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0004</spec>
<spec>XEP-0068</spec>
<spec>XEP-0071</spec>
<spec>XEP-0122</spec>
<spec>XEP-0137</spec>
<spec>XEP-0141</spec>
<spec>XEP-0323</spec>
<spec>XEP-0325</spec>
<spec>XEP-0326</spec>
<spec>XEP-0331</spec>
<spec>XEP-0336</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iot-h2m-chat</shortname>
<author>
<firstname>Peter</firstname>
<surname>Waher</surname>
<email>[email protected]</email>
<jid>[email protected]</jid>
<uri>http://www.linkedin.com/in/peterwaher</uri>
</author>
<author>
<firstname>Joachim</firstname>
<surname>Lindborg</surname>
<email>[email protected]</email>
<jid>[email protected]</jid>
<uri>http://se.linkedin.com/in/joachimlindborg/</uri>
</author>
<revision>
<version>0.0.1</version>
<date>2013-10-30</date>
<initials>pw</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
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>
<li>
simple and user-friendly for human users.
</li>
<li>
possible to automate by machines.
</li>
<li>
is consistent between manufacturers.
</li>
<li>
is consistent with other Internet-of-Things extensions and possible underlying architecture.
</li>
<li>
include both reading of sensors and control of actuators and configuration.
</li>
<li>
possibile to extend
</li>
</ul>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>
Clients and devices must support sending and receiving of normal text messages. See XMPP core specifications for more details about syntax.
</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>The following table lists common terms and corresponding descriptions.</p>
<dl>
<di>
<dt>Actuator</dt>
<dd>Device containing at least one configurable property or output that can and should be controlled by some other entity or device.</dd>
</di>
<di>
<dt>Computed Value</dt>
<dd>A value that is computed instead of measured.</dd>
</di>
<di>
<dt>Concentrator</dt>
<dd>Device managing a set of devices which it publishes on the XMPP network.</dd>
</di>
<di>
<dt>Data Source</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>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. 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>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>Node Type</dt>
<dd>Each node has a Node Type. The Node Type defines the functionality of the node in the system.</dd>
</di>
<di>
<dt>Parameter</dt>
<dd>
Readable and/or writable property on a node/device. The XEP-0326 &xep0326; deals with reading and writing parameters
on nodes/devices. Fields are not parameters, and parameters are not fields.
</dd>
</di>
<di>
<dt>Peak Value</dt>
<dd>A maximum or minimum value during a given period.</dd>
</di>
<di>
<dt>Precision</dt>
<dd>
In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision
determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and
delivering field information in sensor networks should always retain the number of decimals in a message.
</dd>
</di>
<di>
<dt>Sensor</dt>
<dd>
Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc.
Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
</dd>
</di>
<di>
<dt>SN</dt>
<dd>Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.</dd>
</di>
<di>
<dt>Status Value</dt>
<dd>A value displaying status information about something.</dd>
</di>
<di>
<dt>Timestamp</dt>
<dd>Timestamp of value, when the value was sampled or recorded.</dd>
</di>
<di>
<dt>Token</dt>
<dd>
A client, device or user can get a token from a provisioning server. These tokens can be included in requests to other entities in the network, so these entities can validate
access rights with the provisioning server.
</dd>
</di>
<di>
<dt>Unit</dt>
<dd>Physical unit of value. Example: MWh, l/s, etc.</dd>
</di>
<di>
<dt>Value</dt>
<dd>A field value.</dd>
</di>
<di>
<dt>Value Status</dt>
<dd>Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.</dd>
</di>
<di>
<dt>Value Type</dt>
<dd>Can be numeric, string, boolean, Date & 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 and services requesting sensor data can be XMPP clients.</dd>
</di>
</dl>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>
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 &xep0071; 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>
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>
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>
<strong>Note 1:</strong> 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>
<strong>Note 2:</strong> 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>
<strong>Note 3:</strong> When the client sends a column based respons it MUST use \t TAB between them.
</p>
<section2 topic='Readout of devices'>
<section3 topic='Readout of standalone devices'>
<section4 topic='Reading momentary values from single device or currently selected device'>
<p>
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>
<example caption='Requesting a readout of momentary values from single device or currently selected device'>
<![CDATA[
?]]>
</example>
<p>
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>
<example caption='Momentary value response without localized field names'>
<![CDATA[
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]]>
</example>
<p>
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
<!-- TODO: should we write out that no localization of units are done on the device that needs to be done by any parser alternativt upp till device tillverkaren -->
<!-- TODO: i exemplet nedan skall väl inte original fält namn vara med utan localiserade fält skall ligga först -->
</p>
<example caption='Momentary value response with localized field names'>
<![CDATA[
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)]]>
</example>
<p>
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>
<example caption='Multi-line regular expression for parsing readout results'>
<![CDATA[
^(?'FieldName'[^\t]+)\t(?'Value'[^\t\n]+)(\t[(](?'Localized'[^)]+)[)])?]]>
</example>
</section4>
<section4 topic='Reading all values from single device or currently selected device'>
<p>
Using a double ?? makes a deeper introspection and gives a more thorough value set in return
<!-- TODO: should precision be part of the result? -->
</p>
<example caption='Requesting a readout of momentary values from single device or currently selected device'>
<![CDATA[
??]]>
</example>
<!-- TODO: Write descriptive text
Note: The readout is performed asynchronously, which may imply a delay before the response is returned.-->
<example caption='Full readout response without localized field names'>
<![CDATA[
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]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Full readout response with localized field names'>
<![CDATA[
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]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Multi-line regular expression for parsing readout results'>
<![CDATA[
^(?'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]+)]]>
</example>
</section4>
<section4 topic='Reading specific momentary field value from single device or currently selected device'>
<p>
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>
<example caption='Requesting a readout of a specific momentary value from single device or currently selected device'>
<![CDATA[
Temperature?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Specific momentary value response without localized field names'>
<![CDATA[
Readout of klart.se - Stockholm (2) - Albano started...
Temperature 0 °C]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Specific momentary value response with localized field names'>
<![CDATA[
Temperature?
Urläsning av klart.se - Stockholm (2) - Albano påbörjad...
Temperature 0 °C (Temperatur)]]>
</example>
<!-- TODO: Write descriptive text.
Same regular expression for parsing as for ?
Note: if X points to an object in the current data source in a concentrator, X? requests a readout of momentary values from X.
-->
</section4>
<section4 topic='Reading specific field values from single device or currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Requesting a readout of specific field values from single device or currently selected device'>
<![CDATA[
Temperature??]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Full readout response without localized field names'>
<![CDATA[
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]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Full readout response with localized field names'>
<![CDATA[
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]]>
</example>
<!-- TODO: Write descriptive text.
Same regular expression for parsing as for ??
Note: if X points to an object in the current data source in a concentrator, X?? requests a full readout of X.
-->
</section4>
</section3>
<section3 topic='Readout of device behind concentrator'>
<section4 topic='Reading momentary values from device behind concentrator'>
<p>
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>
<example caption='Requesting a readout of momentary values from a device behind a concentrator'>
<![CDATA[
Vina del Mar?]]>
</example>
<!-- TODO: Write descriptive text.
Output same as in the corresponding example above concerning readout from a single device or the currently selected device.
If list of objects was last displayed (with positive index values N), the following is synonymous:
N?-->
</section4>
<section4 topic='Reading all values from device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Requesting a readout of all values from a device behind a concentrator'>
<![CDATA[
Vina del Mar??]]>
</example>
<!-- TODO: Write descriptive text.
Output same as in the corresponding example above concerning readout from a single device or the currently selected device.
If list of objects was last displayed (with positive index values N), the following is synonymous:
N??-->
<!-- TODO: Should we have recursion? -->
</section4>
<section4 topic='Reading specific momentary field value from device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Requesting a readout of a specific momentary value from a device behind a concentrator'>
<![CDATA[
Vina del Mar.Temperature?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method of requesting a readout of a specific momentary value from a device behind a concentrator'>
<![CDATA[
Temperature@Vina del Mar?]]>
</example>
<!-- TODO: Write descriptive text.
Output same as in the corresponding example above concerning readout from a single device or the currently selected device.
If list of objects was last displayed (with positive index values N), the following are synonymous:
N.Temperature?
Temperature@N?
-->
</section4>
<section4 topic='Reading specific field values from device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Requesting a readout of specific field values from a device behind a concentrator'>
<![CDATA[
Vina del Mar.Temperature??]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method of requesting a readout of specific field values from a device behind a concentrator'>
<![CDATA[
Temperature@Vina del Mar??]]>
</example>
<!-- TODO: Write descriptive text.
Output same as in the corresponding example above concerning readout from a single device or the currently selected device.
If list of objects was last displayed (with positive index values N), the following are synonymous:
N.Temperature??
Temperature@N??-->
</section4>
</section3>
</section2>
<section2 topic='Control of devices'>
<section3 topic='Control of standalone devices'>
<section4 topic='Setting control parameter on single device or currently selected device'>
<p>
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>
<example caption='Requesting a control parameter to be set to a new value on a single device or currently selected device'>
<![CDATA[
Output=75]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for requesting a control parameter to be set to a new value on a single device or currently selected device'>
<![CDATA[
Output!75]]>
</example>
<!-- TODO: Write descriptive text
Note: Control is performed asynchronously, which may imply a delay before the response is returned.
-->
<example caption='Control parameter response when parameter has been successfully set'>
<![CDATA[
Output=75]]>
</example>
<!-- TODO: Write descriptive text
If list of control parametrs was last displayed (with positive index values N), the following are synonymous:
N=75
N!75
Note: If control action not successful, an error message will be displayed. Link to section about error messages.
-->
</section4>
<section4 topic='Listing control parameters on single device or currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Listing control parameters on single device or currently selected device'>
<![CDATA[
=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for listing control parameters on single device or currently selected device'>
<![CDATA[
!?]]>
</example>
<!-- TODO: Write descriptive text
Note: Control is performed asynchronously and current values might not be available. Therefore, do not consider the values presented
along the control parameters as factual.
-->
<example caption='List of control parameters'>
<![CDATA[
1. Output=0 (Output)
0. Tillbaka]]>
</example>
<!-- TODO: Write descriptive text
Note: Parameters in menu above can be used by referring to the corresponding menu item index.
-->
<p>
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 <link url='#dataforms'>Data Forms</link> for more information. Submitting the
form means executing the corresponding control commands.
</p>
<example caption='Using menu shortcuts'>
<![CDATA[
C: =?
S: 1. Output=0 (Output)
S: 0. Tillbaka
C: 1=75
S: Output=75]]>
</example>
</section4>
<section4 topic='Displaying current value of control parameter on single device or currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Displaying current value of control parameter on single device or currently selected device'>
<![CDATA[
Output=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for displaying current value of control parameter on single device or currently selected device'>
<![CDATA[
Output!?]]>
</example>
<!-- TODO: Write descriptive text
Note: Control is performed asynchronously and current values might not be available. Therefore, do not consider the values presented
along the control parameters as factual.
-->
<example caption='Listing control parameter'>
<![CDATA[
Output=0]]>
</example>
<!-- TODO: Write descriptive text
Note: Parameters in menu above can be used by referring to the corresponding menu item index.
-->
<example caption='Using menu shortcuts'>
<![CDATA[
C: =?
S: 1. Output=0 (Output)
S: 0. Tillbaka
C: 1=?
S: Output=75]]>
</example>
</section4>
</section3>
<section3 topic='Control of device behind concentrator'>
<section4 topic='Setting control parameter on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Requesting a control parameter to be set to a new value on a single device behind concentrator'>
<![CDATA[
Analog Output.Output=75]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for requesting a control parameter to be set to a new value on a single device behind concentrator'>
<![CDATA[
Analog Output.Output!75]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 2 for requesting a control parameter to be set to a new value on a single device behind concentrator'>
<![CDATA[
Output@Analog Output=75]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 3 for requesting a control parameter to be set to a new value on a single device behind concentrator'>
<![CDATA[
Output@Analog Output!75]]>
</example>
<!-- TODO: Write descriptive text
Output same as in the corresponding example above concerning control of a single device or the currently selected device.
-->
<example caption='Control parameter response when parameter has been successfully set'>
<![CDATA[
Output=75]]>
</example>
<!-- TODO: Write descriptive text
Note: If control action not successful, an error message will be displayed. Link to section about error messages.
Note 2: Control is performed asynchronously, which may imply a delay before the response is returned.
If list of nodes was last displayed (with positive index values N), the following are synonymous:
N.Output=75
N.Output!75
Output@N=75
Output@N!75
-->
</section4>
<section4 topic='Listing control parameters on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Listing control parameters on single device behind concentrator'>
<![CDATA[
Analog Output=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for listing control parameters on single device behind concentrator'>
<![CDATA[
Analog Output!?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 2 for listing control parameters on single device behind concentrator'>
<![CDATA[
Analog Output.=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 3 for listing control parameters on single device behind concentrator'>
<![CDATA[
Analog Output.!?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 4 for listing control parameters on single device behind concentrator'>
<![CDATA[
@Analog Output=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 5 for listing control parameters on single device behind concentrator'>
<![CDATA[
@Analog Output?]]>
</example>
<!-- TODO: Write descriptive text
Note: Control is performed asynchronously and current values might not be available. Therefore, do not consider the values presented
along the control parameters as factual.
Output same as in the corresponding example above concerning control of a single device or the currently selected device.
-->
<p>
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 <link url='#dataforms'>Data Forms</link> for more information. Submitting the
form means executing the corresponding control commands.
</p>
</section4>
<section4 topic='Displaying current value of control parameter on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Displaying current value of control parameter on single device behind concentrator'>
<![CDATA[
Analog Output.Output=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method for displaying current value of control parameter on single device behind concentrator'>
<![CDATA[
Analog Output.Output!?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 2 for displaying current value of control parameter on single device behind concentrator'>
<![CDATA[
Output@Analog Output=?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative method 3 for displaying current value of control parameter on single device behind concentrator'>
<![CDATA[
Output@Analog Output!?]]>
</example>
<!-- TODO: Write descriptive text
Note: Control is performed asynchronously and current values might not be available. Therefore, do not consider the values presented
along the control parameters as factual.
Output same as in the corresponding example above concerning displaying current control parameter on a single device or the currently selected device.
-->
</section4>
</section3>
</section2>
<section2 topic='Configuring devices'>
<section3 topic='Configuring standalone devices'>
<section4 topic='Listing configuration parameters on currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Listing configuration parameters on currently selected device'>
<![CDATA[
:?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='List of configuration parameters'>
<![CDATA[
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]]>
</example>
<p>
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 <link url='#dataforms'>Data Forms</link> for more information. Submitting the
form means configuring the node.
</p>
</section4>
<section4 topic='Displaying current value of configuration parameter on currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Displaying current value of configuration parameter on currently selected device'>
<![CDATA[
phase:?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Value of configuration parameter'>
<![CDATA[
phase:Installation]]>
</example>
<!-- TODO: Write descriptive text
If previous menu listed configuration parameters with positive integers N, the following is synonymous:
N:?
Note: If a node command is selected, this command points to parameters in the node command parameter set, not configuration parameter set.
-->
</section4>
<section4 topic='Editing configuration parameter on currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Editing configuration parameter on currently selected device'>
<![CDATA[
phase:Test]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Acknowledge that configuration was performed'>
<![CDATA[
OK]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Configuration error'>
<![CDATA[
C: phase:test
S: ! Select a value from the list. (Installation, Test, Production)]]>
</example>
<!-- TODO: Write descriptive text:
If previous menu listed configuration parameters with positive integers N, the following is synonymous:
N:Value
Note: If a node command is selected, this command points to parameters in the node command parameter set, not configuration parameter set.
-->
</section4>
</section3>
<section3 topic='Configuration of device behind concentrator'>
<section4 topic='Listing configuration parameters on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Listing configuration parameters on single device behind concentrator'>
<![CDATA[
Analog Output:?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='List of configuration parameters'>
<![CDATA[
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]]>
</example>
<p>
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 <link url='#dataforms'>Data Forms</link> for more information. Submitting the
form means configuring the node.
</p>
</section4>
<section4 topic='Displaying current value of configuration parameter on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Displaying current value of configuration parameter on single device behind concentrator'>
<![CDATA[
Analog Output.phase:?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative way to displaying current value of configuration parameter on single device behind concentrator'>
<![CDATA[
phase@Analog Output:?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Value of configuration parameter'>
<![CDATA[
phase:Installation]]>
</example>
</section4>
<section4 topic='Editing configuration parameter on single device behind concentrator'>
<!-- TODO: Write descriptive text -->
<example caption='Editing configuration parameter on single device behind concentrator'>
<![CDATA[
Analog Output.phase:Test]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Alternative way to edit configuration parameter on single device behind concentrator'>
<![CDATA[
phase@Analog Output:Test]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Acknowledge that configuration was performed'>
<![CDATA[
OK]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Configuration error'>
<![CDATA[
C: Analog Output.phase:test
S: ! Select a value from the list. (Installation, Test, Production)]]>
</example>
<!-- TODO: Write descriptive text:
Note: If a node command is selected, this command points to parameters in the node command parameter set, not configuration parameter set.
-->
</section4>
</section3>
</section2>
<section2 topic='Node Commands on devices'>
<section3 topic='Node Commands on standalone devices'>
<section4 topic='Displaying commands available on currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Displaying commands available on currently selected device'>
<![CDATA[
>?]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Menu of available commands'>
<![CDATA[
1. ChangeToProduction (Change lifecycle phase to Production)
2. ChangeToTest (Change lifecycle phase to Test)
3. ClearMessages (Clear all messages)
4. Disable
5. LogCustomMessage (Log message...)
0. Back]]>
</example>
<!-- TODO: Write descriptive text -->
</section4>
<section4 topic='Selecting command on currently selected device'>
<!-- TODO: Write descriptive text -->
<example caption='Selecting command on currently selected device using Command ID'>
<![CDATA[
>LogCustomMessage]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Selecting command on currently selected device using Command Name'>
<![CDATA[
>Log message...]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Selecting command on currently selected device using menu shortcut'>
<![CDATA[
>5]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Command menu for parametrized command'>
<![CDATA[
1. KeepPrevious:true (Keep previous messages.)
2. Type:Information (Message Type)
3. Level:Minor (Message Level)
4. Message: (Message Text)
0. Back
!. Executes the current command.]]>
</example>
<p>
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 <link url='#dataforms'>Data Forms</link> for more information. Submitting
the form means executing the command.
</p>
<!-- TODO: Write descriptive text -->
<example caption='Command menu for simple unparametrized command'>
<![CDATA[
0. Back
!. Executes the current command.]]>
</example>
</section4>
<section4 topic='Editing command parameter in currently selected node command'>
<!-- TODO: Write descriptive text -->
<example caption='Editing command parameter in currently selected node command'>
<![CDATA[
Message:Hello there]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Using parameter menu shortcut'>
<![CDATA[
4:Hello there]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Acknowledging parameter is successfully edited'>
<![CDATA[
OK]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Errors in input'>
<![CDATA[
C: Level:major
S: ! Select a value from the list. (Minor, Medium, Major)]]>
</example>
<!-- TODO: Write descriptive text:
Note: This can only be done if a node command has been selected.
-->
</section4>
<section4 topic='Executing currently selected node command'>
<!-- TODO: Write descriptive text -->
<example caption='Executing currently selected node command'>
<![CDATA[
!]]>
</example>
<!-- TODO: Write descriptive text -->
<example caption='Some commands require confirmation'>
<![CDATA[
C: >Disable
S: 1. recursive:false (Disable recursive for all children.)
S: 0. Back
S: !. Executes the current command.
C: !
S: Are you sure you want to disable this node?
S: This node will not take part of any jobs, readouts or configurations when disabled.
S: <[email protected]> (Type Yes or No)
C: Yes
S: Node disabled successfully.]]>
</example>
<!-- TODO: Write descriptive text
Note: