Transport Protocols
436 |
437 | The VISSv3.0 specification lists the transport protocols HTTP, WebSocket, gRPC, and MQTT as supported.
438 | However, this is not necessarily a final list as says that any protocol that transport the primary payloads of this specification,
439 | or an encoded version of the primary payloads, can be included on this list.
440 | The specification does not mandate the use of a specific transport protocol,
441 | but at least one of the listed transport protocols MUST be supported.
442 |
Secure WebSocket
446 |
447 | The WebSocket protocol is used in this document to provide examples of a protocol that does not apply any deviations to the primary payload format.
448 | As it does not implicitly provide a logical association between the request and response messages,
449 | a key-value pair with the key name "requestId" MUST be added to the data components, as described in the [[CORE]] specification.
450 | Additionally, since WebSocket does not define explicit methods, another key-value pair, "action", MUST also be included.
451 | Refer to the for detailed descriptions of these key-value pairs.
452 | All data components are mapped to the payload.
453 |
Session Life Time Management
457 | 458 |Initialization
460 | 461 |If the client application is an HTML Application running in a web runtime or is a web page running 462 | in a browser, the WebSocket instance may either be instantiated natively or be created using 463 | a 'standards compliant' WebSocket JavaScript library.
464 |A WebSocket can also be initiated from a native application (e.g., written in C++) 465 | or from a managed runtime environment such as Java or C#. 466 | In these cases, it is assumed that the client uses a standards-compliant WebSocket library 467 | to request a connection with the server.
468 | 469 |Implementations that support additional devices or multiple VISSv3 services 470 | should provide discovery. Alternatively, the location of a particular VISSv3 471 | Server instance on the local vehicle network may be handled by 472 | configuration, either as part of a package manifest or by consulting a 473 | registry on application install. The 'wwwVISSv3' hostname in this 474 | specification is used an example. 475 |
476 | 477 |A client running on the vehicle is able to connect to the 478 | VISSv3 Server instance using the hostname e.g. 'wwwVISSv3' and uses the 479 | default port 6443. The hostname 'wwwVISSv3' may locally be mapped to the localhost 480 | IP address 127.0.0.1 e.g. by adding an entry to the /etc/hosts file.
481 | 482 |The sub-protocol name SHALL be 'VISSv3' with the digit 3 being the version number. 483 | The sub-protocol version will 484 | be associated with exactly one VISS Server Specification version so that the client and server can 485 | correctly validate and parse request and response message packets.
486 |
487 | var vehicle = new WebSocket("wss://wwwVISSv3:6443", "VISSv3");
488 | The client SHALL connect to the server over HTTPS and request that 490 | the server opens a WebSocket. All WebSocket communications between 491 | the client and server MUST use ‘wss’ (WebSocket Secure). Non encrypted communication 492 | is not supported, hence the server MUST reject ‘ws’ connection requests.
493 | 494 |This specification assumes that a single WebSocket is used to enable communication between a client application 495 | and the server. The client MAY open more than one websocket. 496 | However, the server MAY reject to open a subsequent WebSocket connection and 497 | the client is responsible for handling this gracefully. 498 |
499 |If multiple WebSocket connection is established between a client application and the server 500 | then each connection MUST be managed independently. For example, subscriptions created 501 | through one connection can only trigger events through that same connection, 502 | and the client MUST use the same connection to unsubscribe. 503 |
504 |If multiple WebSocket connection has been established 505 | between one or more clients and a particular server instance, there 506 | is a risk that race conditions and concurrency issues could occur. 507 | For instance, simultaneous updates to the same signal from different connections 508 | could result in conflicts. 509 |
510 | 511 |Unless explicitly stated otherwise, the client MAY assume that the server implements 512 | a basic concurrency model, meaning that lost updates or dirty reads could occur 513 | when multiple WebSocket connections are in use. 514 |
515 |Closure
519 |The WebSocket connection MAY be closed by either the client or the 520 | server by invoking the ‘close()’ method on the WebSocket 521 | instance.
522 | 523 |The following example shows the typical lifecycle of a WebSocket connection on the client side:
524 |
525 | // Open the WebSocket
526 | var vehicle = new WebSocket("wss://wwwVISSv3:6443", "VISSv3");
527 | …
528 | // Close the WebSocket
529 | vehicle.close();
530 | 532 | The VISSv3 server MAY also terminate the connection if it does not receive any requests from the client 533 | within a server-defined timeout period. 534 | In such cases, the client MUST handle the closure gracefully, and if needed, re-establish the connection and request new subscriptions, where required. 535 |
536 |Transport Messages
541 | 542 |Read
544 |The client MAY send a getRequest 545 | message to the server to get the value of one or more vehicle signals. 546 | If the server can fulfill the request, it SHALL return a 547 | getSuccessResponse message. 548 | If an error occurs, the server SHALL return a 549 | getErrorResponse message. 550 | The structure of these message objects is defined in the tables below: 551 |
552 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| getRequest | action | Action | Yes |
| path | string | Yes | |
| filter | string | Optional | |
| authorization | string | Optional | |
| data compression | string | Optional | |
| requestId | string | Yes |
566 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| getSuccessResponse | action | Action | Yes |
| requestId | string | Yes | |
| data | object/array | Yes | |
| ts | string | Yes |
578 | In the table above, the "data" attribute is either an object containing "value" and "ts" name/value pairs, or an array of such objects. 579 |
580 || Object Name | Attribute | Type | Required |
|---|---|---|---|
| getErrorResponse | action | Action | Yes |
| requestId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
592 | Example:
593 | Request:
594 |
595 | {
596 | "action": "get",
597 | "path": "Vehicle.Powertrain.CombustionEngine.RPM",
598 | "requestId": "8756"
599 | }
600 |
603 | {
604 | "action": "get",
605 | "requestId": "8756",
606 | "data":{"path":"Vehicle.Powertrain.CombustionEngine.RPM",
607 | "dp":{"value":"2372", "ts":"2020-04-15T13:37:00Z"}
608 | },
609 | "ts":"2020-04-15T13:37:05Z"
610 | }
611 |
614 | {
615 | "action": "get",
616 | "requestId": "8756",
617 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
618 | "ts": "2020-04-15T13:37:00Z"
619 | }
620 | Search Read
660 |The client MAY issue a search read request to retrieve multiple signal values in one request message. 661 | This is realized by adding a "filter" object following the section 7.1 Paths Filter Operation described in the [[CORE]] specification. 662 |
663 |
664 | Example:
665 | Request:
666 |
667 | {
668 | "action": "get",
669 | "path": "Vehicle.Cabin",
670 | "filter": {"variant":"paths", "parameter":["Door.*.*.IsOpen", "DriverPosition"]},
671 | "requestId": "5688"
672 | }
673 |
676 | {
677 | "action": "get",
678 | "data":[{"path":"Vehicle.Cabin.Door.Row1.Left.IsOpen", "dp":{"value":"false", "ts":"2020-04-15T13:37:00Z"}},
679 | {...},…
680 | {"path":"Vehicle.Cabin.Door.Row4.Right.IsOpen", "dp":{"value":"true", "ts":"2020-04-15T13:37:01Z"}},
681 | {"path":"Vehicle.Cabin.DriverPosition", "dp":{"value":"1", "ts":"2020-04-15T07:00:01Z"}}
682 | ],
683 | "requestId": "5688",
684 | "ts":"2020-04-15T07:00:02Z"
685 | }
686 | History Read
692 |A client MAY issue a history read request to retrieve previously recorded data points. 693 | This is realized by adding a "filter" object following the section 7.2 History Filter Operation described in the [[CORE]] specification. 694 |
695 |
696 | Example:
697 | Request:
698 |
699 | {
700 | "action": "get",
701 | "path": "Vehicle.Acceleration.Longitudinal",
702 | "filter": {"variant":"history", "parameter":"P2DT12H"},
703 | "requestId": "5688"
704 | }
705 |
708 | {
709 | "action": "get",
710 | "data": {"path": "Vehicle.Acceleration.Longitudinal", "dp": [{"value": "0.123", "ts": "2020-04-15T13:00:00Z"}, {"value": "0.125", "ts": "2020-04-15T13:37:02Z"}]},
711 | "requestId": "5688",
712 | "ts": "2020-04-15T13:37:02Z"
713 | }
714 | Signal Discovery Read
720 |721 | To retrieve metadata about the VSS tree, the client MAY issue a signal discovery read request. 722 | This is realized by adding a "filter" object following the section 7.7 Metadata Filter Operation described in the [[CORE]] specification. 723 | The response includes metadata for all nodes in the subtree rooted at the node specified by the path, 724 | limited to the number of generations set by the "parameter" value. 725 |
726 |
727 | Example:
728 | Request:
729 |
730 | {
731 | "action": "get",
732 | "path": "Vehicle.Powertrain.FuelSystem",
733 | "filter":{"variant":"metadata", "parameter":"2"},
734 | "requestId": "5687"
735 | }
736 |
739 | {
740 | "action": "get",
741 | "requestId": "5687",
742 | "metadata": {"FuelSystem":{"type":"branch","children":["HybridType", ... ]}},
743 | "ts": "2020-04-15T13:37:00Z"
744 | }
745 | Update
752 |753 | The client MAY send a request to the server to set the value of a signal. 754 | If the server can fulfill the request successfully, it SHALL return a 755 | setSuccessResponse message. 756 | If an error occurs, the server SHALL return a 757 | setErrorResponse message. 758 | The structure of these message objects is defined below: 759 |
760 || Object Name | Attribute | Type | Required |
|---|---|---|---|
| setRequest | action | Action | Yes |
| path | string | Yes | |
| value | string/array/object | Yes | |
| authorization | string | Optional | |
| requestId | string | Yes |
773 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| setSuccessResponse | action | Action | Yes |
| requestId | string | Yes | |
| ts | string | Yes |
784 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| setErrorResponse | action | Action | Yes |
| requestId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
796 | Example:
797 | Request:
798 |
799 | {
800 | "action": "set",
801 | "path": "Vehicle.Powertrain.Transmission.PerformanceMode",
802 | "value": "sport",
803 | "requestId": "5687"
804 | }
805 |
808 | {
809 | "action": "set",
810 | "requestId": "5687",
811 | "ts": "2020-04-15T13:37:00Z"
812 | }
813 |
816 | {
817 | "action": "set",
818 | "requestId": "5687",
819 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
820 | "ts": "2020-04-15T13:37:00Z"
821 | }
822 | Subscribe
860 |
861 | The client MAY send a subscribeRequest message
862 | to request a subscription to one or more signals,
863 | thereby requesting the server to repeatedly return subscription event messages based on
864 | the section 7. Filter Request described in the [[CORE]] specification.
865 | To reduce processing load, the server MAY limit the number of
866 | subcriptionEvent messages sent.
867 | If the server can fulfill the request, it SHALL return a
868 | subscribeSuccessResponse message.
869 | If an error occurs while processing the request, the server SHALL return a
870 | subscribeErrorResponse message.
871 | If an error occurs during an active subscription session, the server SHALL return a
872 | subscriptionErrorEvent message.
873 | The structure of the subscription messages is defined below.
874 | As specified in the [[CORE]] specification, the supported subscription variants are:
875 |
-
876 |
- timebased: Event messages are issued at a regular time interval, 877 |
- change: Event messages are issued when the value has changed as specified, 878 |
- range: Event messages are issued when the value is in the specified range, 879 |
- curvelog: Event messages are issued when the buffer is full, and then processed according to the curve logging algorithm. 880 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| subscribeRequest | action | Action | Yes |
| path | string | Yes | |
| filter | string | Yes | |
| authorization | string | Optional | |
| data compression | string | Optional | |
| requestId | string | Yes |
897 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| subscribeSuccessResponse | action | Action | Yes |
| requestId | string | Yes | |
| subscriptionId | string | Yes | |
| ts | string | Yes |
909 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| subscribeErrorResponse | action | Action | Yes |
| requestId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
921 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| subscriptionEvent | action | Action | Yes |
| subscriptionId | string | Yes | |
| data | object/array | Yes | |
| ts | string | Yes |
933 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| subscriptionErrorEvent | action | Action | Yes |
| subscriptionId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
945 | Example:
946 | Request:
947 |
948 | {
949 | "action": "subscribe",
950 | "path": "Vehicle.Powertrain.FuelSystem.Level",
951 | "filter": {"variant":"timebased", "parameter":{"period":"500"}},
952 | "requestId": "6578"
953 | }
954 |
957 | {
958 | "action": "subscribe",
959 | "subscriptionId": "12345",
960 | "requestId": "6578",
961 | "ts": "2020-04-15T13:37:00Z"
962 | }
963 |
966 | {
967 | "action": "subscribe",
968 | "requestId": "6578",
969 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
970 | "ts": "2020-04-15T13:37:00Z"
971 | }
972 |
975 | {
976 | "action": "subscription",
977 | "subscriptionId": "12345",
978 | "data": {"path": "Vehicle.Powertrain.FuelSystem.Level",
979 | "dp": {"value": "50", "ts": "2020-04-15T13:37:00Z"}
980 | },
981 | "ts": "2020-04-15T13:37:00Z"
982 | }
983 |
986 | {
987 | "action": "subscription",
988 | "subscriptionId": "12345",
989 | "error": {"number": "401", "reason": "expired_token", "description": "Access token has expired."},
990 | "ts": "2020-04-15T13:37:00Z"
991 | }
992 | Curve Logging Subscribe
1042 |1043 | Curve logging data compression by eliminating data points that are within a set error margin is activated via a subscription request. 1044 | Event messages will be issued when the buffer becomes full, after insignificant data points have been eliminated, 1045 | refer to the section 7.6 Curve logging Filter Operation in the [[CORE]] specification. 1046 |
1047 |
1048 | Example:
1049 | Request:
1050 |
1051 | {
1052 | "action": "subscribe",
1053 | "path": "Vehicle.Powertrain.FuelSystem.Level",
1054 | "filter": {"variant":"curvelog", "parameter":{"maxerr":"0.5", "bufsize":"100"}},
1055 | "requestId": "6578"
1056 | }
1057 |
1060 | {
1061 | "action": "subscribe",
1062 | "subscriptionId": "12345",
1063 | "requestId": "6578",
1064 | "ts": "2020-04-15T13:37:00Z"
1065 | }
1066 |
1069 | {
1070 | "action": "subscription",
1071 | "subscriptionId": "12345",
1072 | "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
1073 | "dp":[{"value": "50", "ts": "2020-04-15T13:38:00Z"}, ..., {"value": "25", "ts": "2020-04-15T13:39:30Z"}]
1074 | },
1075 | "ts": "2020-04-15T13:37:00Z"
1076 | }
1077 | Range Subscribe
1083 |1084 | Subscription to a range of values, 1085 | that can have either a single boundary, or multipe boundaries as in the example below. 1086 | For a more information how to use range of values, refer to the section 7.4 Range Filter Operation in the [[CORE]] specification. 1087 |
1088 |
1089 | Example:
1090 | Request:
1091 |
1092 | {
1093 | "action": "subscribe",
1094 | "path": "Vehicle.Powertrain.FuelSystem.Level",
1095 | "filter": "filter":{"variant":"range","parameter":[{"logic-op":"lt","boundary":"50","combination-op":"OR"},{"logic-op":"gt","boundary":"55"}]},
1096 | "requestId": "6578"
1097 | }
1098 |
1101 | {
1102 | "action": "subscribe",
1103 | "subscriptionId": "12345",
1104 | "requestId": "6578",
1105 | "ts": "2020-04-15T13:37:00Z"
1106 | }
1107 |
1110 | {
1111 | "action": "subscription",
1112 | "subscriptionId": "12345",
1113 | "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
1114 | "dp":{"value": "51", "ts": "2020-04-15T14:00:00Z"}},
1115 | "ts": "2020-04-15T14:00:00Z"
1116 | }
1117 | Change Subscribe
1123 |1124 | Subscription to when a signal has changed between two sequential captures. 1125 | For a more information how to use change of values, refer to the section 7.5 Change Filter Operation in the [[CORE]] specification. 1126 |
1127 |
1128 | Example:
1129 | Request:
1130 |
1131 | {
1132 | "action": "subscribe",
1133 | "path": "Vehicle.Powertrain.FuelSystem.Level",
1134 | "filter":{"variant":"change","parameter":{"logic-op":"gt","diff":"10"}},
1135 | "requestId": "6578"
1136 | }
1137 |
1140 | {
1141 | "action": "subscribe",
1142 | "subscriptionId": "12345",
1143 | "requestId": "6578",
1144 | "ts": "2020-04-15T13:37:00Z"
1145 | }
1146 |
1149 | {
1150 | "action": "subscription",
1151 | "subscriptionId": "12345",
1152 | "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
1153 | "dp":{"value": "101", "ts": "2020-04-15T14:00:00Z"}},
1154 | "ts": "2020-04-15T14:00:00Z"
1155 | }
1156 | Unsubscribe
1163 |
1164 | To unsubscribe from a subscription, the client SHALL send an
1165 | unsubscribeRequest message to the server.
1166 | If the server can fulfill the request successfully, it SHALL returns an
1167 | unsubscribeSuccessResponse message.
1168 | If an error occurs, an
1169 | unsubscribeErrorResponse message SHALL be returned.
1170 |
1171 | If the client has created multiple WebSocket instance, it MUST unsubscribe
1172 | using the same WebSocket instance that was originally used to create the subscription.
1173 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeRequest | action | Action | Yes |
| subscriptionId | string | Yes | |
| requestId | string | Yes |
1185 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeSuccessResponse | action | Action | Yes |
| requestId | string | Yes | |
| ts | string | Yes |
1196 |
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeErrorResponse | action | Action | Yes |
| requestId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
1208 | Example:
1209 | Request:
1210 |
1211 | {
1212 | "action": "unsubscribe",
1213 | "subscriptionId": "12345",
1214 | "requestId": "5786"
1215 | }
1216 |
1219 | {
1220 | "action": "unsubscribe",
1221 | "requestId": "5786",
1222 | "ts": "2020-04-15T13:37:00Z"
1223 | }
1224 |
1227 | {
1228 | "action": "unsubscribe",
1229 | "requestId": "6578",
1230 | "error": {"number": "400", "reason": "invalid_data", "description": "Data present in the request is invalid."},
1231 | "ts": "2020-04-15T13:37:00Z"
1232 | }
1233 | HTTPS
1241 |1242 | The message data components described in the [[CORE]] specification are primarily mapped to standard HTTP parameters. 1243 | Only when no suitable mapping is available are they included in the payload. 1244 | The most significant deviations are as follows: 1245 |
-
1246 |
- The path is included as part of the URL. 1247 |
- A filter expression is added to the URL as a query string. 1248 |
- The HTTP methods GET and POST are used instead of the "action" field. 1249 |
Session Life Time Management
1255 | 1256 |Initialization
1258 |Initialization involves setting up a secure HTTPS session between the client and the server.
1259 | This ensures encrypted communication for data transmission.
1260 | To initialize a secure session, the client sends a request to the server using the HTTPS protocol.
1261 | This is achieved by connecting to the server's designated URL using the 'https://' scheme.
1262 | The client can use a web browser, a native application, or a suitable library in the case of programmatically managed sessions.
1263 | While the client typically connects to the server using the specified hostname, which often includes the "www" prefix,
1264 | 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.
1265 | The communication SHALL use port 443, the default port for secure HTTPS connections.
1266 | Hostname resolution can be achieved using DNS or configured through local settings.
1267 |
Closure
1272 |Closure entails ending the established HTTPS session when the communication is complete or when the client no longer requires the connection.
1273 | 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,
1274 | indicating the intent to close the connection.
1275 | Upon session closure, any allocated resources, such as server-side threads or memory, are released, improving overall system efficiency.
1276 |
Transport Messages
1282 | 1283 |Read
1285 |1286 | 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). 1287 | If the server can fulfill the request, it SHALL return a response containing the requested value(s). 1288 | If the server is unable to fulfill the request, e.g. because the client is not authorized to retrieve one or more of the signals, 1289 | then it SHALL respond with an appropriate error status code. 1290 |
1291 |1292 | Example: 1293 | Request: 1294 |
1295 | GET /Vehicle/Cabin/SeatPosCount HTTP/1.1
1296 | Host: 127.0.0.1:1337
1297 | Accept: application/json
1298 | ...
1299 |
1302 | HTTP/1.1 200 OK
1303 | Content-Type: application/json; charset=utf-8
1304 | ...
1305 | {
1306 | "data":{"path":"Vehicle.Cabin.SeatPosCount",
1307 | "dp":{"value":["2", "3", "2"], "ts":"2020-04-15T13:37:00Z"}
1308 | },
1309 | "ts": "2020-04-15T13:37:00Z"
1310 | }
1311 |
1314 | HTTP/1.1 404 Not Found
1315 | Content-Type: application/json; charset=utf-8
1316 | ...
1317 | {
1318 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
1319 | "ts": "2020-04-15T13:37:00Z"
1320 | }
1321 | Search Read
1371 |
1372 | The search read request uses the section 7.1 Paths Filter Operation
1373 | described in the [[CORE]] specification to define one or more path expressions, relative to the path in the GET URL.
1374 | Example:
1375 | Request:
1376 |
1377 | GET /Vehicle/Cabin/Door?filter={"variant":"paths", "parameter":"*/*/IsOpen"} HTTP/1.1
1378 | Host: 127.0.0.1:1337
1379 | Accept: application/json
1380 | ...
1381 |
1384 | HTTP/1.1 200 OK
1385 | Content-Type: application/json; charset=utf-8
1386 | ...
1387 | {
1388 | "data":[{"path":"Vehicle.Cabin.Door.Row1.Left.IsOpen", "dp":{"value":"false", "ts":"2020-04-15T13:37:00Z"}},
1389 | {...},…
1390 | {"path":"Vehicle.Cabin.Door.Row4.Right.IsOpen", "dp":{"value":"true", "ts":"2020-04-15T13:37:00Z"}}
1391 | ],
1392 | "ts": "2020-04-15T13:37:00Z"
1393 | }
1394 |
1397 | HTTP/1.1 404 Not Found
1398 | Content-Type: application/json; charset=utf-8
1399 | ...
1400 | {
1401 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
1402 | "ts": "2020-04-15T13:37:00Z"
1403 | }
1404 | History Read
1410 |
1411 | The history read request uses the section 7.2 History Filter Operation
1412 | described in the [[CORE]] specification to read recorded values
1413 | for a specific past duration.
1414 | Example:
1415 | Request:
1416 |
1417 | GET /Vehicle.Acceleration.Longitudinal?filter={"variant":"history", "parameter":"P2DT12H"} HTTP/1.1
1418 | Host: 127.0.0.1:1337
1419 | Accept: application/json
1420 | ...
1421 |
1424 | HTTP/1.1 200 OK
1425 | Content-Type: application/json; charset=utf-8
1426 | ...
1427 | {
1428 | "data":{"path":"Vehicle.Acceleration.Longitudinal", "dp":[{"value":"0.123", "ts":"2020-04-15T13:00:00Z"}, ..., {"value":"0.125", "ts":"2020-04-15T13:37:00Z"}]},
1429 | "ts": "2020-04-15T13:37:00Z"
1430 | }
1431 | Signal Discovery Read
1437 |
1438 | The signal discovery request uses the section 7.7 Metadata Filter Operation
1439 | described in the [[CORE]] specification to retrieve metadata from a specified subtree in the VSS tree.
1440 | A successful response will contain the requested metadata from all nodes of the subtree defined by
1441 | the subtree root node addressed by the path.
1442 | The depth of metadata retrieval is controlled by the "parameter" value.
1443 | Example:
1444 | Request:
1445 |
1446 | GET /Vehicle/Powertrain/FuelSystem?filter={"variant":"metadata", "parameter":"0"} HTTP/1.1
1447 | Host: 127.0.0.1:1337
1448 | Accept: application/json
1449 | ...
1450 |
1453 | HTTP/1.1 200 OK
1454 | Content-Type: application/json; charset=utf-8
1455 | ...
1456 | {
1457 | "metadata": {"FuelSystem":{"type":"branch","description":"Fuel system data.","children":{"HybridType, ... }}},
1458 | "ts": "2020-04-15T13:37:00Z"
1459 | }
1460 | Update
1467 |1468 | The client MAY send a request to update the value of a signal. 1469 | If the server can fulfill the request, it SHALL return a 1470 | setSuccessResponse message. 1471 | If an error occurs, e.g. because the client is not authorized to set the requested value, or the value is read-only, 1472 | the server SHALL return a 1473 | setErrorResponse message. 1474 |
1475 |1476 | Example: 1477 |
1478 | POST /Vehicle/Powertrain/Transmission/PerformanceMode HTTP/1.1
1479 | Host: 127.0.0.1:1337
1480 | Accept: application/json
1481 | ...
1482 | {
1483 | "value": "sport"
1484 | }
1485 |
1488 | HTTP/1.1 200 OK
1489 | Content-Type: application/json; charset=utf-8
1490 | ...
1491 | {
1492 | "ts": "2020-04-15T13:37:00Z"
1493 | }
1494 |
1497 | HTTP/1.1 404 Not Found
1498 | Content-Type: application/json; charset=utf-8
1499 | ...
1500 | {
1501 | "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
1502 | "ts": "2020-04-15T13:37:00Z"
1503 | }
1504 | MQTT
1532 |
1533 | The MQTT protocol operates on a publish-subscribe communication model, whereas the VISS is designed around a client-server interaction model.
1534 | To reconcile these differences, a lightweight application-level protocol is introduced on top of MQTT.
1535 | This protocol encapsulates VISS messages within MQTT messages and includes additional metadata required to support client-server semantics.
1536 | Details of this abstraction mechanism are provided in the following sections.
1537 | The VISS messages transmitted over MQTT SHALL conform to the primary payload format without modification.
1538 |
Application Level Protocol
1542 |
1543 | For MQTT to support the full VISSv3 interface, as decribed in the section 5. Interface of the [[CORE]] specification,
1544 | an application-level protocol that runs on top of MQTT is required.
1545 | This protocol is described below and illustrated in the accompanying sequence diagram.
1546 | To emulate the client-server pattern that is described in the [[CORE]] specification,
1547 | the vehicle server—via its vehicle-side client—MUST subscribe to the broker on a topic named VID/Vehicle,
1548 | where VID represents a unique identifier that links the vehicle to the access control ecosystem.
1549 | This vehicle identifier is not necessarily the manufacturer's Vehicle Identification Number (VIN).
1550 | The cloud-side client is expected to have access to this vehicle identifier.
1551 | How it obtains it is out of scope for this specification.
1552 | When the cloud client intends to send a request to the vehicle server,
1553 | it first generates a unique topic name and subscribes to it via the broker.
1554 | The client then generates a JSON formatted payload with the following structure:
1555 |
1556 | {"topic":"aUniqueTopic", "request":"VISSv3Request"}
1557 | 1566 | For subscription requests, the vehicle client MUST store the subscriptionId from the subscribe response, 1567 | together with the topic name associated to the subscribe request. When the vehicle server later issues event messages, 1568 | the vehicle client SHALL extract the subscriptionId from it, and retrieve the topic name associated to it. 1569 | The vehicle client SHALL delete the saved topic name and subscriptionId when it receives 1570 | an unsubscribe request in a message from the broker.
1571 | In subsequent requests from the cloud client, the unique topic name MAY be reused from the previous request-response cycle, 1572 | or a new unique topic name MAY be generated. If a new topic name is used, the previous one SHOULD be unsubscribed. 1573 | The vehicle client MAY continue using the topic name to which it initially subscribed.
1574 | The payload format of all response and event messages SHALL conform to the primary payload format defined in this specification. 1575 | The access control model is also applicable to this transport mechanism. 1576 | The Access Token Server SHOULD implement its own version of the application-level protocol described here, 1577 | using the topic name "VID/ATS". Similarly, the Access Grant Token Server MAY implement the same mechanism using the topic "VID/AGTS", 1578 | or if it is deployed in the cloud it MAY expose the HTTPS interface defined in this specification. 1579 | 1580 |
1582 | Security Aspects
1589 |1590 | The MQTT architecture requires the use of a broker, which serves as an intermediary between the client and server endpoints 1591 | (referred to as the subscriber and publisher in MQTT terminology). 1592 | Since each TLS channel terminates at the broker, it has full access to all plaintext communication 1593 | between these endpoints. 1594 | This security consideration SHALL be taken into account when selecting MQTT as a transport protocol. 1595 |
1596 |Transport Messages
1600 |1601 | As described in the "Application Level Protocol" section, each request message sent to the broker SHALL include 1602 | two JSON-formatted key-value pairs. 1603 | The value of the request key MUST be a string containing the client request intended for the vehicle server. 1604 | This request MUST strictly adhere to the primary payload format defined in this specification. 1605 |
1606 |gRPC
1611 |1612 | The gRPC protocol uses Protocol Buffers (Protobuf) for message serialization. 1613 | The Protobuf message definitions SHALL be specified in a .proto file. 1614 | The .proto file that defines the encoding of the VISS primary payload format is provided in the [[PAYLOAD ENCODING]] specification. 1615 | A Protobuf compiler (e.g., protoc) is used to generate source code from the .proto file. 1616 | This generated code facilitates the encoding and decoding between Protobuf and JSON payload formats. 1617 | This code can be implemented in different languages, and is out of scope for the VISS standardization. 1618 | An example implementation in the Go programming language can be found 1619 | here. 1620 |
1621 |