-
Notifications
You must be signed in to change notification settings - Fork 68
/
VISSv2_Transport.html
1621 lines (1550 loc) · 75 KB
/
VISSv2_Transport.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>
<html>
<head>
<meta charset='utf-8'>
<title>VISS version 2-Transport</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove' defer></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
group: "auto",
github: "https://github.com/w3c/automotive",
editors: [{
name: "Ulf Bjorkengren",
company: "Geotab (formerly Volvo Cars)",
companyURL: "https://www.geotab.com",
w3cid: 103092
},
{
name: "이원석(Wonsuk Lee)", company: "한국전자통신연구원(ETRI)",
url: "mailto:wonsuk.lee@etri.re.kr",
companyURL: "https://etri.re.kr/eng/main/main.etri",
w3cid: 34457
}],
formerEditors: [{
name: "Ulf Bjorkengren",
company: "Volvo Cars",
companyURL: "https://www.volvo.com",
w3cid: 103092
},
{
name: "Patrick Lünnemann",
company: "Volkswagen Group",
companyURL: "https://www.volkswagenag.com",
w3cid: 95844
}],
edDraftURI: "https://github.com/w3c/automotive/blob/gh-pages/spec/VISSv2_Transport.html",
shortName: "viss2-transport"
};
</script>
<style>
table.parameters, table.exceptions {
border-spacing: 0;
border-collapse: collapse;
margin: 0.5em 0;
width: 100%;
}
table.parameters { border-bottom: 1px solid #90b8de; }
table.exceptions { border-bottom: 1px solid #deb890; }
.parameters th, .exceptions th {
color: inherit;
padding: 3px 5px;
text-align: left;
font-weight: normal;
}
.parameters th { color: #fff; background: #005a9c; }
.exceptions th { background: #deb890; }
.parameters td, .exceptions td {
padding: 3px 10px;
border-top: 1px solid #ddd;
vertical-align: top;
}
.parameters tr:first-child td, .exceptions tr:first-child td {
border-top: none;
}
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
width: 100px;
}
.parameters td.prmType {
width: 120px;
}
table.exceptions table {
border-spacing: 0;
border-collapse: collapse;
width: 100%;
}
.simple {
width:100%;
}
thead th{
border-bottom: 1px solid black;
}
.simple tbody th{
width:33%;
background: white;
color: black;
}
pre { white-space: pre-wrap;}
</style>
</head>
<body>
<section id='abstract'>
<p>The Vehicle Information Service Specification (VISS) is a
service for accessing vehicle information, signals from sensors
on control units within a vehicle's network. It exposes this
information using a hierarchical tree like taxonomy defined in
COVESA Vehicle Signal Specification (VSS). The service provides
this information in JSON format ([[RFC8259]]). The service may reside in the vehicle,
or on servers in the internet with information already brought off the vehicle.
</p>
<p>This specification describes a second version of VISS which
has been implemented and deployed on production vehicles. It
adds major new capabilities and improvements to the earlier
version. The first version of VISS only supported WebSocket as a
transport protocol, the second version is generalized to work
across different protocols as some are better suited for
different use cases. HTTP and MQTT are now supported with additional
protocols used within the automotive industry being evaluated
for inclusion. Subscription capabilities have been improved and
access control has been added.
</p>
<p>
There are two parts to this specification, [[viss2-core]] and TRANSPORT. This document, the VISS version 2 TRANSPORT specification,
describes the VISSv2 transport protocols, and the mapping of the message layer on these transports.
The companion specification [[viss2-core]] describes the messaging layer.
</p>
</section>
<section id='sotd'></section>
<section id="introduction">
<h2>Introduction</h2>
<p>This document describes the transport bindings of the Vehicle Information Service Specification, version 2.
The split between transport bindings and messaging layer specifications improves readability and simplifies
extending the specification to further transports in the future.
This specification supports multiple transport bindings, the secure versions of HTTP ([[RFC9112]]),
WebSocket ([[RFC6455]]), and MQTT ([[MQTT]]).
</p>
</section>
<section id="conformance"></section>
<section id="terminology">
<h2>Terminology</h2>
<p>The acronym 'VISSv2' is used to refer to this document, the VISS version 2 specification.
The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification' which is defined by the COVESA Alliance.
The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API and the WebSocket Protocol.
</p>
</section>
<section id="transport-common-defs">
<h2>Transport Common Definitions</h2>
<p>This chapter defines features that SHALL be common for all transport protocols.</p>
<section id="status-codes">
<h2>Status Codes</h2>
<p>The server implementation <em class="rfc2119" title="SHALL">SHALL</em> support the error numbers listed in the table below,
with the associated reason and message fields, for all supported transport protocols.</p>
<p>The client <em class="rfc2119" title="SHOULD">SHOULD</em> support any status code defined in [[RFC2616]].</p>
<table id="errorDefs" class="parameters">
<tbody><tr>
<th>Error Number (Code)</th>
<th>Error Reason</th>
<th>Error Message</th>
</tr>
<tr>
<td>400 (Bad Request)</td>
<td>bad_request </td>
<td>The request is malformed.</td>
</tr>
<tr>
<td>400 (Bad Request)</td>
<td>invalid_data</td>
<td>Data present in the request is invalid.</td>
</tr>
<tr>
<td>401 (Unauthorized)</td>
<td>expired_token</td>
<td>Access token has expired.</td>
</tr>
<tr>
<td>401 (Unauthorized)</td>
<td>invalid_token</td>
<td>Access token is invalid.</td>
</tr>
<tr>
<td>401 (Unauthorized)</td>
<td>missing_token</td>
<td>Access token is missing.</td>
</tr>
<tr>
<td>403 (Forbidden)</td>
<td>forbidden_request</td>
<td>The server refuses to carry out the request.</td>
</tr>
<tr>
<td>404 (Not Found)</td>
<td>unavailable_data</td>
<td>The requested data was not found.</td>
</tr>
<tr>
<td>503 (Service Unavailable)</td>
<td>service_unavailable</td>
<td>The server is temporarily unable to handle the request.</td>
</tr>
</tbody></table>
</section>
<section id="transport-payload">
<h2>Transport Payload</h2>
<p>The payload SHALL have JSON format.
See <a href='#json-def'></a> for the payload format of the messages for the different transport protocols.
</p>
</section>
<section id="authorization">
<h2>Authorization</h2>
<p>If authorization is enabled on a signal requested by the client,
it MUST provide a token to the server in order to verify that it is correctly authorized for the service it requests
(see [[viss2-core]] document).Tokens are integrated in HTTP requests in the <code>Authorization</code> header.
For WebSocket and MQTT requests an optional <code>authorization</code> property in the payload can be used.
</p>
</section>
</section>
<section id="transport-protocols">
<h2>Transport Protocols</h2>
<p>The transport protocols supported are the secure versions of HTTP, WebSocket, and MQTT,
the latter on which a thin application layer protocol is applied.<br>
The server MUST support the HTTP and WebSocket protocols, other protocols are optional. <br>
Further transport protocols may be supported in future versions of this specification.
</p>
<section id="https">
<h2>HTTPS</h2>
<p>The message data components described in the [[viss2-core]] document are in the first hand mapped to required HTTP parameters,
and only when there is no appropriate mapping it is mapped to the payload.
The subscribe/unsubscribe messages are not supported by this transport protocol.
</p>
<section id="https-life-time-mngmnt">
<h2>Session Life Time Management</h2>
<section id="https-initialisation">
<h2>Initialization</h2>
<p>Initialization involves setting up a secure HTTPS session between the client and the server.
This ensures encrypted communication for data transmission.
To initialize a secure session, the client sends a request to the server using the HTTPS protocol.
This is achieved by connecting to the server's designated URL using the 'https://' scheme.
The client can use a web browser, a native application, or a suitable library in the case of programmatically managed sessions.<br>
While the client typically connects to the server using the specified hostname, which often includes the "www" prefix,
it's important to note that this convention may not apply in situations where VISS operates within a local, in-vehicle network or if remote vehicle connections are allowed.
The communication typically takes place over port 443, the default port for secure HTTPS connections.
The hostname resolution can be done via DNS or configured through local settings.
</p>
</section>
<section id="https-closure">
<h2>Closure</h2>
<p>Closure entails ending the established HTTPS session when the communication is complete or when the client no longer requires the connection.
Either the client or the server can initiate the session closure. The client can signal the end of the session by sending an appropriate request to the server,
indicating the intent to close the connection.<br>
Upon session closure, any allocated resources, such as server-side threads or memory, are released, improving overall system efficiency.
</p>
</section>
</section>
<section id="https-transport-messages">
<h2>Transport Messages</h2>
<section id="https-read">
<h2>Read</h2>
<p>
The client MAY send a HTTPS GET request message to the server to get one or more value(s) of one or more vehicle signal(s).
If the server is able to satisfy the request it SHALL return a response containing the requested value(s).
If the server is unable to fulfil the request, e.g. because the client is not authorized to retrieve one or more of the signals,
then the server response SHALL have the status code set to indicate error.
</p>
<p>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle/Cabin/SeatPosCount HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
</code></pre>
Successful response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
“data”:{“path”:”Vehicle.Cabin.SeatPosCount”,
“dp”:{“value”:[”2”, "3", "2"], “ts”:”2020-04-15T13:37:00Z”}
}
}
</code></pre>
Error response:
<pre><code>
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
...
{
"error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
<section id="https-authorized-read">
<h2>Authorized Read</h2>
<p>
JWT tokens will be sent in the <code>Authorization</code> header, following with term <code>Bearer</code> and a space character.
</p>
<p>
The following example assumes
<code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds</code>
is the actual token. A token header can be combined with all types of read requests.
<br>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle/Drivetrain/InternalCombustionEngine/RPM HTTP/1.1
Host:127.0.0.1:1337
Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds
</code></pre>
Successful response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
“data”:{“path”:”Vehicle.Drivetrain.InternalCombustionEngine.RPM”,
“dp”:{“value”:”2372”, “ts”:”2020-04-15T13:37:00Z”}
}
}
</code></pre>
Error response:
<pre><code>
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="127.0.0.1:1337",
error="invalid_token",
error_description="The access token is invalid or expired"
Content-Type: application/json; charset=utf-8
...
{
"error": {"number": 401, "reason": "invalid_token", "message": "Access token is invalid."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
</section>
<section id="https-search-read">
<h2>Search Read</h2>
<p>
The search read request uses the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#paths-filter-operation">paths filter operation</a> described in the [[viss2-core]] document to provide one or more path expressions,
relative to the path in the GET URL.<br>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle/Cabin/Door?filter={"type":"paths", "parameter":"*/*/IsOpen"} HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
</code></pre>
Response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
“data”:[{“path”:”Vehicle.Cabin.Door.Row1.Left.IsOpen”, “dp”:{“value”:”false”, “ts”:”2020-04-15T13:37:00Z”}},
{...},…
{“path”:”Vehicle.Cabin.Door.Row4.Right.IsOpen”, “dp”:{“value”:”true”, “ts”:”2020-04-15T13:37:00Z”}}
]
}
</code></pre>
Error response:
<pre><code>
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
...
{
"error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
</section>
<section id="https-history-read">
<h2>History Read</h2>
<p>
The history read request uses the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#history-filter-operation">history filter operation</a> described in the [[viss2-core]] document to read recorded values
for a given period backwards in time.<br>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle.Acceleration.Longitudinal?filter={"type":"history", "parameter":"P2DT12H"} HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
</code></pre>
Response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
“data”:{“path”:”Vehicle.Acceleration.Longitudinal”, “dp”:[{“value”:”0.123”, “ts”:”2020-04-15T13:00:00Z”}, ..., {“value”:”0.125”, “ts”:”2020-04-15T13:37:00Z”}]}
}
</code></pre>
</p>
</section>
<section id="https-service-discovery-read">
<h2>Signal Discovery Read</h2>
<p>
The signal discovery request uses the static metadata filtering type as described in the [[viss2-core]] document to retrieve metadata in the VSS tree.
If the parameter object is set to an empty string, then all metadata in the addressed VSS nodes is returned.
If only specific metadata is desired, the value can be set to this, e. g. "parameter":["type", "datatype"].
The values must be the names as defined in the VSS specification.<br>
<br>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle/Drivetrain/FuelSystem?filter={"type":"static-metadata", "parameter":""} HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
</code></pre>
Response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
"metadata": {"FuelSystem":{"type":"branch","description":"Fuel system data.","children":{"HybridType, ... }}},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
<p>
The dynamic metadata, i. e. any other metadata kept by the vehicle system, is retrieved by the setting the "type" to "dynamic-metadata".
The value MUST be set to one of the domain names as specified in the [[viss2-core]], <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#dynamic-metadata-request">Dynamic Metadata Filter Operation</a> chapter.
<br>
<b>Example:</b>
Request:
<pre><code>
GET /Vehicle?filter={"type":"dynamic-metadata", "parameter":"server_capabilities"} HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
</code></pre>
Response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
"metadata": {"filter":["timebased", "change", "paths", "curvelog", "dynamic-metadata"], "access_ctrl": ["short_term", "signalset_claim"], "transport_protocol": "https", "wss"},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
</section>
</section>
<section id="https-update">
<h2>Update</h2>
<p>
The client may request that the server sets the value of one or more signals e.g. to lock one or more doors or
open a window by sending an HTTPS POST request to the server.
In the case of several signals being set, they MUST all be of the same data type, and be set to the same value.
If the server is able to satisfy the request its response SHALL have a 200 OK status code set.
If an error occurs e.g. because the client is not authorized to set the requested value, or the value is read-only,
the server response SHALL have the status code set to indicate error.
</p>
<p>
<b>Example:</b>
<pre><code>
POST /Vehicle/Drivetrain/Transmission/PerformanceMode HTTP/1.1
Host: 127.0.0.1:1337
Accept: application/json
...
{
"value": "sport"
}
</code></pre>
Successful response:
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Error response:
<pre><code>
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
...
{
"error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
<section id="https-authorized-update">
<h2>Authorized Update</h2>
<p>
JWT tokens will be sent in the <code>Authorization</code> header, following with term <code>Bearer</code> and a space character.
</p>
<p>
The following example assumes
<code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds</code>
is the actual token. A token header can be combined with all types of update requests.
</p>
<pre><code>
POST /Vehicle/Drivetrain/Transmission/PerformanceMode HTTP/1.1
Host:127.0.0.1:1337
Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds
{
"value": "sport"
}
</code></pre>
</section>
</section>
</section>
</section>
<section id="secure-websocket">
<h2>Secure WebSocket</h2>
<p>
As the WebSocket protocol does not implicitly provide a logical association between the request and response messages
described here a key-value pair with the keyname "requestId" is added to the data components described in the [[viss2-core]] document.<br>
As the WebSocket protocol neither specifies a set of explicit methods,
another key-value pair with the keyname "action" is also added. See <a href='#action-def'></a> for the declaration of these new key-value pairs.
All data components are mapped to the payload.
</p>
<section id="wss-lifetime-mngmnt">
<h2>Session Life Time Management</h2>
<section id="wss-initialisation">
<!--OddPage--><h2>Initialization</h2>
<p>If the client application is an HTML Application running in a web
runtime or is a web page running in a browser, the WebSocket
instance may either be instantiated natively or be created using a
'standards compliant' WebSocket JavaScript library.</p>
<p>A WebSocket can also be initiated from a native (e.g. C++) Application
or from an Application written using a 'Managed Runtime' language like
Java or C#. It is assumed that native and managed clients use a
suitable standards compliant WebSocket library to request that a
WebSocket connection is opened on the server.</p>
<p>Implementations that support additional devices or multiple VISSv2 services
should provide discovery. Alternatively, the location of a particular VISSv2
Server instance on the local vehicle network may be handled by
configuration, either as part of a package manifest or by consulting a
registry on application install. The 'wwwVISSv2' hostname in this
specification is used an example.
</p>
<p>A client running on the vehicle is able to connect to the
VISSv2 Server instance using the hostname e.g. 'wwwVISSv2' and uses the
default port 443. The hostname 'wwwVISSv2' may locally be mapped to the localhost
IP address 127.0.0.1 e.g. by adding an entry to the /etc/hosts file.</p>
<p>The sub-protocol name <em class="rfc2119" title="SHALL">SHALL</em> be 'VISSv2' with the digit 2 being the version number.
The sub-protocol version will
be associated with exactly one VISS Server Specification version so that the client and server can
correctly validate and parse request and response message packets.</p>
<pre><code>
var vehicle = new WebSocket("wss://wwwVISSv2:443", "VISSv2");
</code></pre>
<p>The client <em class="rfc2119" title="SHALL">SHALL</em> connect to the server over HTTPS and request that
the server opens a WebSocket. All WebSocket communications between
the client and server <em class="rfc2119" title="MUST">MUST</em> be over ‘wss’. Non encrypted communication
is not supported, hence the server <em class="rfc2119" title="MUST">MUST</em> refuse ‘ws’ connection requests.</p>
<p>This specification assumes that a single WebSocket is used to enable communication between a client application
and the server. The client MAY open more than one websocket.
However, the server <em class="rfc2119" title="MAY">MAY</em> refuse to open a subsequent WebSocket connection and
the client is responsible for handling this gracefully.
</p>
<p>If more than one WebSocket connection is established between a client application and the server then each connection
<em class="rfc2119" title="MUST">MUST</em> be managed independently. For example, subscriptions created using a particular
WebSocket connection shall only trigger event messages via that connection and the client
<em class="rfc2119" title="MUST">MUST</em> use that WebSocket connection to unsubscribe.
</p>
<p>If more than one WebSocket connection has been established
between one or more clients and a particular server instance, there
is a risk that race conditions and concurrency issues could occur.
An example of this would be where two or more WebSocket connections
are used to update a particular setting at the same time.
</p>
<p>Unless explicitly stated otherwise, the client <em class="rfc2119" title="MAY">MAY</em> only assume
that the server implements a simple concurrency model where lost
updates and dirty reads could potentially occur if the server has
more than one WebSocket connection open.
</p>
</section>
<section id="wss-closure">
<!--OddPage--><h2>Closure</h2>
<p>The WebSocket may be closed by either the client or the
server by invoking the ‘close()’ method on the WebSocket
instance.</p>
<p>The following example shows the lifetime of a WebSocket on
the client:</p>
<pre><code>
// Open the WebSocket</span>
var vehicle = new WebSocket("wss://wwwVISSv2:443", "VISSv2");
…
// Close the WebSocket
vehicle.close();
</code></pre>
<p>The VISSv2 Server may terminate the WebSocket connection if it has not received a request for a period determined by
the server. It is the client’s responsibility to handle this gracefully and to recover and request new subscriptions, where required.
</p>
</section>
</section>
<section id="wss-transport-messages">
<h2>Transport Messages</h2>
<section id="wss-read-message">
<h2>Read</h2>
<p>The client <em class="rfc2119" title="MAY">MAY</em> send a <a href="#dfn-getrequest" class="internalDFN" data-link-type="dfn">getRequest</a>
message to the server to get the value of one or more vehicle signals.
If the server is able to satisfy the request it <em class="rfc2119" title="SHALL">SHALL</em> return a
<a href="#dfn-getsuccessresponse" class="internalDFN" data-link-type="dfn">getSuccessResponse</a> message.
If the server is unable to fulfil the request, e.g. because the client is not authorized to retrieve one or more of the signals,
then the server <em class="rfc2119" title="SHALL">SHALL</em> return a
<a href="#dfn-geterrorresponse" class="internalDFN" data-link-type="dfn">getErrorResponse</a> message.
The structure of these message objects is defined below.
</p><br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="5"><dfn data-dfn-type="dfn" id="dfn-getrequest">getRequest</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-path">path</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-filter">filter</a></td><td>string</td><td>Optional</td></tr>
<tr><td><a href="#dfn-authorization">authorization</a></td><td>string</td><td>Optional</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="3"><dfn data-dfn-type="dfn" id="dfn-getsuccessresponse">getSuccessResponse</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-value">data</a></td><td>object/array</td><td>Yes</td></tr>
</tbody>
</table>
<p>
In the table above the "data" attribute is either an object containing "value" and "ts" name/value pairs, or an array of such objects.
</p>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="4"><dfn data-dfn-type="dfn" id="dfn-geterrorresponse">getErrorResponse</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-error">error</a></td><td><a href="#error-def">Error</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-ts">ts</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "get",
"path": "Vehicle.Drivetrain.InternalCombustionEngine.RPM",
"requestId": "8756"
}
</code></pre>
Successful response:
<pre><code>
{
"action": "get",
"requestId": "8756",
“data”:{“path”:”Vehicle.Drivetrain.InternalCombustionEngine/RPM”,
“dp”:{“value”:”2372”, “ts”:”2020-04-15T13:37:00Z”}
}
}
</code></pre>
Error response:
<pre><code>
{
"action": "get",
"requestId": "8756",
"error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
<section id="wss-authorized-read">
<h2>Authorized Read</h2>
<p> If the operation on the VSS node that is addressed requires authorization,
then the request must contain the field "authorization" with its value being a JWT token.
The token validation must be successful for a
<a href="#dfn-getsuccessresponse" class="internalDFN" data-link-type="dfn">getSuccessResponse</a>
to be returned, else a <a href="#dfn-geterrorresponse" class="internalDFN" data-link-type="dfn">getErrorResponse</a> is returned.
A token can be combined with all types of read requests.
</p>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "get",
"path": "Vehicle.Drivetrain.InternalCombustionEngine.RPM",
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds"
"requestId": "8657"
}
</code></pre>
Response:
<pre><code>
{
"action": "get",
"requestId": "8657",
“data”:{“path”:”Vehicle.Drivetrain.InternalCombustionEngine.RPM”,
“dp”:{“value”:”2372”, “ts”:”2020-04-15T13:37:00Z”}
}
}
</code></pre>
</p>
</section>
<section id="wss-search-read">
<h2>Search Read</h2>
<p>A client may issue a search read request to access multiple values in one request message.
This is realized by adding a "filter" object following the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#paths-filter-operation">paths filter operation</a> described in the [[viss2-core]].
</p>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "get",
"path": "Vehicle.Cabin",
"filter": {"type":"paths", "parameter":["Door.*.*.IsOpen", "DriverPosition"]}value
"requestId": "5688"
}
</code></pre>
Response:
<pre><code>
{
"action": "get",
“data”:[{“path”:”Vehicle.Cabin.Door.Row1.Left.IsOpen”, “dp”:{“value”:”false”, “ts”:”2020-04-15T13:37:00Z”}},
{...},…
{“path”:”Vehicle.Cabin.Door.Row4.Right.IsOpen”, “dp”:{“value”:”true”, “ts”:”2020-04-15T13:37:00Z”}},
{“path”:”Vehicle.Cabin.DriverPosition”, “dp”:{“value”:”1”, “ts”:”2020-04-15T07:00:00Z”}}
]
"requestId": "5688",
}
</code></pre>
</p>
</section>
<section id="wss-history-read">
<h2>History Read</h2>
<p>A client may issue a history read request to access recorded data points.
This is realized by adding a "filter" object following the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#history-filter-operation">history filter operation</a> described in the [[viss2-core]].
</p>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "get",
"path": "Vehicle.Acceleration.Longitudinal",
"filter": {"type":"history", "parameter":"P2DT12H"},
"requestId": "5688"
}
</code></pre>
Response:
<pre><code>
{
"action": "get",
“data”: {“path”: ”Vehicle.Acceleration.Longitudinal”, “dp”: [{“value”: ”0.123”, “ts”: ”2020-04-15T13:00:00Z”}, {“value”: ”0.125”, “ts”: ”2020-04-15T13:37:00Z”}]},
"requestId": "5688"
}
</code></pre>
</p>
</section>
<section id="wss-service-discovery-read">
<h2>Signal Discovery Read</h2>
<p>A client may issue a signal discovery read request to access dynamic metadata.
A successful response will contain the requested metadata from all nodes of the subtree defined by
the subtree root node that is addressed by the path.
The static metadata, i. e. the metadata in the VSS tree, is retrieved by the setting the "type" to "static-metadata",
and the parameter object to relevant static metadata.<br>
</p>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "get",
"path": "Vehicle.Drivetrain.FuelSystem",
"filter":{"type":"dynamic-metadata", "parameter":["availability", "validate"]}
"requestId": "5687"
}
</code></pre>
Response:
<pre><code>
{
"action": "get",
"requestId": "5687",
"metadata": {"FuelSystem":{"availability":"available","validate":"read-write","children":{"HybridType", ... }}}
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
</section>
</section>
<section id="wss-update">
<h2>Update</h2>
<p>
The client may request that the server sets the value of one or more signals e.g. to lock one or more doors or open a window by sending a
<a href="#dfn-setrequest" class="internalDFN" data-link-type="dfn">setRequest</a> message to the server.
In the case of several signals being set, they MUST all be of the same data type, and be set to the same value.
If the server is able to satisfy the request it <em class="rfc2119" title="SHALL">SHALL</em> return a
<a href="#dfn-setsuccessresponse" class="internalDFN" data-link-type="dfn">setSuccessResponse</a> message.
If an error occurs e.g. because the client is not authorized to set the requested value, or the value is read-only,
the server <em class="rfc2119" title="SHALL">SHALL</em> return a
<a href="#dfn-seterrorresponse" class="internalDFN" data-link-type="dfn">setErrorResponse</a> message.
</p>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="5"><dfn data-dfn-type="dfn" id="dfn-setrequest">setRequest</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-path">path</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-value">value</a></td><td>string/array/object</td><td>Yes</td></tr>
<tr><td><a href="#dfn-authorization">authorization</a></td><td>string</td><td>Optional</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="3"><dfn data-dfn-type="dfn" id="dfn-setsuccessresponse">setSuccessResponse</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-ts">ts</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="4"><dfn data-dfn-type="dfn" id="dfn-seterrorresponse">setErrorResponse</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-error">error</a></td><td><a href="#error-def">Error</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-ts">ts</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "set",
"path": "Vehicle.Drivetrain.Transmission.PerformanceMode",
"value": "sport",
"requestId": "5687"
}
</code></pre>
Successful response:
<pre><code>
{
"action": "set",
"requestId": "5687",
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Error response:
<pre><code>
{
"action": "set",
"requestId": "5687",
"error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
<section id="wss-authorized-update">
<h2>Authorized Update</h2>
<p>If the operation on the VSS node that is addressed requires authorization,
then the request must contain the field "authorization" with its value being a JWT token.
The token validation must be successful for a
<a href="#dfn-setsuccessresponse" class="internalDFN" data-link-type="dfn">setSuccessResponse</a>
to be returned, else a <a href="#dfn-seterrorresponse" class="internalDFN" data-link-type="dfn">setErrorResponse</a> is returned.
A token can be combined with all types of update requests.
</p>
<p>
<b>Example:</b><br>
Request:
<pre><code>
{
"action": "set",
"path": "Vehicle.Drivetrain.Transmission.PerformanceMode",
"value": "sport",
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds"
"requestId": "5687"
}
</code></pre>
Response:
<pre><code>
{
"action": "set",
"requestId": "5687",
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
</p>
</section>
</section>
<section id="subscribe">
<h2>Subscribe</h2>
<p>
The client may send a <a href="#dfn-subscriberequest" class="internalDFN" data-link-type="dfn">subscribeRequest</a> message
to request a subscription to one or more signals,
thereby requesting the server to repeatedly return subscription event messages, as specified by
the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#filter-request">filter request</a> described in the [[viss2-core]].
The server <em class="rfc2119" title="MAY">MAY</em> reduce the number of
<a href="#dfn-subscriptionevent" class="internalDFN" data-link-type="dfn">subcriptionEvent</a>
messages sent to the client in order to reduce processing demands.<br>
If the server is able to satisfy the request it SHALL return a
<a href="#dfn-subscribesuccessresponse" class="internalDFN" data-link-type="dfn">subscribeSuccessResponse</a> message.
If an error occurs e.g. because the client is not authorized to read the requested value, the server SHALL return a
<a href="#dfn-subscribeerrorresponse" class="internalDFN" data-link-type="dfn">subscribeErrorResponse</a> message.
If an error occurs during the subscription session, the server shall return an
<a href="#dfn-subscriptionerrorevent" class="internalDFN" data-link-type="dfn">subscriptionErrorEvent</a> message.<br>
The subscription variants are, as described in the [[viss2-core]] document:
<ul>
<li>timebased: event messages are issued at a regular time interval,</li>
<li>change: event messages are issued when the value has changed as specified,</li>
<li>range: event messages are issued when the value is in the specified range,</li>
<li>curvelog: event messages are issued when the buffer is full, and then processed according to the curve logging algorithm.</li>
</ul>
If none of the above trigger condition variants is specified,
then an event message will be issued whenever the underlying vehicle system supplies a new data point to the server.
</p>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="5"><dfn data-dfn-type="dfn" id="dfn-subscriberequest">subscribeRequest</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-path">path</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-filter">filter</a></td><td>string</td><td>Optional</td></tr>
<tr><td><a href="#dfn-authorization">authorization</a></td><td>string</td><td>Optional</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="4"><dfn data-dfn-type="dfn" id="dfn-subscribesuccessresponse">subscribeSuccessResponse</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-requestid">requestId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-subscriptionid">subscriptionId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-ts">ts</a></td><td>string</td><td>Yes</td></tr>
</tbody>
</table>
<br>
<table class="simple">
<thead>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>