COVESA VISS version 3.0-Transport

The Vehicle Information Service Specification (VISS) is a service for accessing vehicle information, including signals from sensors on control units within a vehicle's network. This information is exposed through a hierarchical, tree-like taxonomy as defined in the COVESA Vehicle Signal Specification (VSS), and is provided in JSON format. The VISS service may be hosted within the vehicle or on external servers, using data that has already been off-boarded.

This specification describes the third version of VISS, which has been implemented and deployed in production vehicles. The first version of VISS supported only WebSocket as a transport protocol, the second version is generalized to work across different protocols as some are better suited for different use cases. The second version added support for the HTTP and MQTT transport protocols, improved subscription capabilities and added an access control mechanism.

This specification consists of three parts, [[CORE]], [[PAYLOAD ENCODING]], and TRANSPORT. This document, the VISS version 3.0 TRANSPORT specification, describes the VISSv3 transport protocols, and how the message layer is mapped to each transport. The companion specification [[CORE]] describes the messaging layer, and [[PAYLOAD ENCODING]] describes payload encodings to/from the primary JSON payload format.

Protocol name	Reference
HTTP	[[RFC9112]]
MQTT	[[MQTT]]
gRPC	[gRPC]

Error Number (Code)	Error Reason	Error Description
400 (Bad Request)	bad_request	The request is malformed
400 (Bad Request)	invalid_data	Data in the request is invalid
401 (Unauthorized)	invalid_token	Access token is invalid
403 (Forbidden)	forbidden_request	The server refuses to carry out the request
404 (Not Found)	unavailable_data	The requested data was not found
408 (Request Timeout)	request_timeout	Subscribe duration limit exceeded
429 (Too Many Requests)	too_many_requests	Rate-limiting due to too many requests
502 (Bad Gateway)	bad_gateway	The upstream server response was invalid
503 (Service Unavailable)	service_unavailable	The server is temporarily unable to handle the request
504 (Gateway Timeout)	gateway_timeout	The upstream server took too long to respond

Error Scenario	Error Message	Comment
Incorrect datatype	400 - invalid_data - Incorrect data type	Mismatch with the datatype in the VSS tree
Signal currently not available	404 - unavailable_data - Data temporarily unaccessible	Vehicle is currently not offering the signal
Unknown signal	404 - unavailable_data - Data is unknown	Signal is not part of the VSS tree
Misused filter	400 - bad_request - Missing or invalid filter	Missing or invalid filter
Incorrect filter	400 - bad_request - Incorrect filter	Filter type not allowed with request method
Unknown subscription Id	404 - unavailable_data - Unknown subscription Id	Filter type not allowed with request method
Unsupported feature Id	404 - unavailable_data - Unsupported feature	The feature is not a server capability
Invalid access rights	401 - invalid_token - Access token is invalid	Access right is expired or otherwise invalid

Transport Protocols

The VISSv3.0 specification lists the transport protocols HTTP, WebSocket, gRPC, and MQTT as supported. However, this is not necessarily a final list as says that any protocol that transport the primary payloads of this specification, or an encoded version of the primary payloads, can be included on this list.
The specification does not mandate the use of a specific transport protocol, but at least one of the listed transport protocols MUST be supported.

Secure WebSocket

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. As it does not implicitly provide a logical association between the request and response messages, a key-value pair with the key name "requestId" MUST be added to the data components, as described in the [[CORE]] document.
Additionally, since WebSocket does not define explicit methods, another key-value pair, "action", MUST also be included. Refer to for detailed descriptions of these key-value pairs. All data components are mapped to the payload.

Session Life Time Management

Initialization

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.

A WebSocket can also be initiated from a native application (e.g., written in C++) or from a managed runtime environment such as Java or C#. In these cases, it is assumed that the client uses a standards-compliant WebSocket library to request a connection with the server.

Implementations that support additional devices or multiple VISSv3 services should provide discovery. Alternatively, the location of a particular VISSv3 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 'wwwVISSv3' hostname in this specification is used an example.

A client running on the vehicle is able to connect to the VISSv3 Server instance using the hostname e.g. 'wwwVISSv3' and uses the default port 6443. The hostname 'wwwVISSv3' may locally be mapped to the localhost IP address 127.0.0.1 e.g. by adding an entry to the /etc/hosts file.

The sub-protocol name SHALL be 'VISSv3' with the digit 3 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.


              var vehicle  = new WebSocket("wss://wwwVISSv3:6443", "VISSv3");

The client SHALL connect to the server over HTTPS and request that the server opens a WebSocket. All WebSocket communications between the client and server MUST use ‘wss’ (WebSocket Secure). Non encrypted communication is not supported, hence the server MUST reject ‘ws’ connection requests.

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 MAY reject to open a subsequent WebSocket connection and the client is responsible for handling this gracefully.

If multiple WebSocket connection is established between a client application and the server then each connection MUST be managed independently. For example, subscriptions created through one connection can only trigger events through that same connection, and the client MUST use the same connection to unsubscribe.

If multiple 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. For instance, simultaneous updates to the same signal from different connections could result in conflicts.

Unless explicitly stated otherwise, the client MAY assume that the server implements a basic concurrency model, meaning that lost updates or dirty reads could occur when multiple WebSocket connections are in use.

Closure

The WebSocket connection MAY be closed by either the client or the server by invoking the ‘close()’ method on the WebSocket instance.

The following example shows the typical lifecycle of a WebSocket connection on the client side:


              // Open the WebSocket
              var vehicle  = new WebSocket("wss://wwwVISSv3:6443", "VISSv3");
              …
              // Close the WebSocket
              vehicle.close();

The VISSv3 server MAY also terminate the connection if it does not receive any requests from the client within a server-defined timeout period. In such cases, the client MUST handle the closure gracefully, and if needed, re-establish the connection and request new subscriptions, where required.

Transport Messages

Read

The client MAY send a getRequest message to the server to get the value of one or more vehicle signals. If the server can fulfill the request, it SHALL return a getSuccessResponse message. If an error occurs, the server SHALL return a getErrorResponse message. The structure of these message objects is defined in the tables below:

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

Object Name	Attribute	Type	Required
getSuccessResponse	action	Action	Yes
	requestId	string	Yes
	data	object/array	Yes
	ts	string	Yes

In the table above, the "data" attribute is either an object containing "value" and "ts" name/value pairs, or an array of such objects.

Object Name	Attribute	Type	Required
getErrorResponse	action	Action	Yes
	requestId	string	Yes
	error	Error	Yes
	ts	string	Yes

Example:
Request:


              {
                "action": "get",
                "path": "Vehicle.Powertrain.CombustionEngine.RPM",
                "requestId": "8756"
              }

Successful response:


              {
                "action": "get",
                "requestId": "8756",
                "data":{"path":"Vehicle.Powertrain.CombustionEngine.RPM",
                        "dp":{"value":"2372", "ts":"2020-04-15T13:37:00Z"}
                },
                "ts":"2020-04-15T13:37:05Z"
              }

Error response:


              {
                "action": "get",
                "requestId": "8756",
                "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
                "ts": "2020-04-15T13:37:00Z"
              }

Authorized Read

If the operation on the addressed VSS node requires authorization, the request MUST include the "authorization" field, containing a valid JWT token as its value. The token validation MUST be successful for a getSuccessResponse to be returned. If validation fails, a getErrorResponse SHALL be returned. JWT tokens can be used with all types of read requests.

Example:
Request:


              {
                "action": "get",
                "path": "Vehicle.Powertrain.CombustionEngine.RPM",
                "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds",
                "requestId": "8657"
              }

Response:


              {
                "action": "get",
                "requestId": "8657",
                "data":{"path":"Vehicle.Powertrain.CombustionEngine.RPM",
                        "dp":{"value":"2372", "ts":"2020-04-15T13:37:00Z"}
                },
                "ts":"2020-04-15T13:37:01Z"
              }

Search Read

The client MAY issue a search read request to retrieve multiple signal values in one request message. This is realized by adding a "filter" object following the chapter 7.1 Paths Filter Operation described in the [[CORE]] specification.

Example:
Request:


              {
                "action": "get",
                "path": "Vehicle.Cabin",
                "filter": {"variant":"paths", "parameter":["Door.*.*.IsOpen", "DriverPosition"]},
                "requestId": "5688"
              }

Response:


              {
                "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:01Z"}},
                        {"path":"Vehicle.Cabin.DriverPosition", "dp":{"value":"1", "ts":"2020-04-15T07:00:01Z"}}
                       ],
                "requestId": "5688",
                "ts":"2020-04-15T07:00:02Z"
              }

History Read

A client MAY issue a history read request to retrieve previously recorded data points. This is realized by adding a "filter" object following the chapter 7.2 History Filter Operation described in the [[CORE]] specification.

Example:
Request:


              {
                "action": "get",
                "path": "Vehicle.Acceleration.Longitudinal",
                "filter": {"variant":"history", "parameter":"P2DT12H"},
                "requestId": "5688"
              }

Response:


              {
                "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:02Z"}]},
                "requestId": "5688",
                "ts": "2020-04-15T13:37:02Z"
              }

Signal Discovery Read

To retrieve metadata about the VSS tree, the client MAY issue a signal discovery read request. This is realized by adding a "filter" object following the chapter 7.7 Metadata Filter Operation described in the [[CORE]] specification. The response includes metadata for all nodes in the subtree rooted at the node specified by the path, limited to the number of generations set by the "parameter" value.

Example:
Request:


              {
                "action": "get",
                "path": "Vehicle.Powertrain.FuelSystem",
                "filter":{"variant":"metadata", "parameter":"2"},
                "requestId": "5687"
              }

Response:


              {
                "action": "get",
                "requestId": "5687",
                "metadata": {"FuelSystem":{"type":"branch","children":["HybridType", ... ]}},
                "ts": "2020-04-15T13:37:00Z"
              }

Update

The client MAY send a request to the server to set the value of a signal. If the server can fulfill the request successfully, it SHALL return a setSuccessResponse message. If an error occurs, the server SHALL return a setErrorResponse message. The structure of these message objects is defined below:

Object Name	Attribute	Type	Required
setRequest	action	Action	Yes
	path	string	Yes
	value	string/array/object	Yes
	authorization	string	Optional
	requestId	string	Yes

Object Name	Attribute	Type	Required
setSuccessResponse	action	Action	Yes
	requestId	string	Yes
	ts	string	Yes

Object Name	Attribute	Type	Required
setErrorResponse	action	Action	Yes
	requestId	string	Yes
	error	Error	Yes
	ts	string	Yes

Example:
Request:


              {
                "action": "set",
                "path": "Vehicle.Powertrain.Transmission.PerformanceMode",
                "value": "sport",
                "requestId": "5687"
              }

Successful response:


              {
                "action": "set",
                "requestId": "5687",
                "ts": "2020-04-15T13:37:00Z"
              }

Error response:


              {
                "action": "set",
                "requestId": "5687",
                "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
                "ts": "2020-04-15T13:37:00Z"
              }

Authorized Update

If the operation on the targeted VSS node requires authorization, the request MUST include the "authorization" field, containing a valid JWT token. The token MUST be successfully validated by the server to return a setSuccessResponse. If validation fails, a setErrorResponse SHALL be returned. Authorization tokens MAY be used with all types of update requests.

Example:
Request:


              {
                "action": "set",
                "path": "Vehicle.Powertrain.Transmission.PerformanceMode",
                "value": "sport",
                "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds",
                "requestId": "5687"
              }

Response:


              {
                "action": "set",
                "requestId": "5687",
                "ts": "2020-04-15T13:37:00Z"
              }

The client MAY send a subscribeRequest message to request a subscription to one or more signals, thereby requesting the server to repeatedly return subscription event messages based on the chapter 7. Filter Request described in the [[CORE]] specification. To reduce processing load, the server MAY limit the number of subcriptionEvent messages sent.
If the server can fulfill the request, it SHALL return a subscribeSuccessResponse message. If an error occurs while processing the request, the server SHALL return a subscribeErrorResponse message.
If an error occurs during an active subscription session, the server SHALL return a subscriptionErrorEvent message.
The structure of the subscription messages is defined below.
As specified in the [[CORE]] document, the supported subscription variants are:

timebased: Event messages are issued at a regular time interval,
change: Event messages are issued when the value has changed as specified,
range: Event messages are issued when the value is in the specified range,
curvelog: Event messages are issued when the buffer is full, and then processed according to the curve logging algorithm.

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

Object Name	Attribute	Type	Required
subscribeSuccessResponse	action	Action	Yes
	requestId	string	Yes
	subscriptionId	string	Yes
	ts	string	Yes

Object Name	Attribute	Type	Required
subscribeErrorResponse	action	Action	Yes
	requestId	string	Yes
	error	Error	Yes
	ts	string	Yes

Object Name	Attribute	Type	Required
subscriptionEvent	action	Action	Yes
	subscriptionId	string	Yes
	data	object/array	Yes
	ts	string	Yes

Object Name	Attribute	Type	Required
subscriptionErrorEvent	action	Action	Yes
	subscriptionId	string	Yes
	error	Error	Yes
	ts	string	Yes

Example:
Request:


              {
                "action": "subscribe",
                "path": "Vehicle.Powertrain.FuelSystem.Level",
                "filter": {"variant":"timebased", "parameter":{"period":"500"}},
                "requestId": "6578"
              }

Successful response:


              {
                "action": "subscribe",
                "subscriptionId": "12345",
                "requestId": "6578",
                "ts": "2020-04-15T13:37:00Z"
              }

Error response:


              {
                "action": "subscribe",
                "requestId": "6578",
                "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
                "ts": "2020-04-15T13:37:00Z"
              }

Event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "data": {"path": "Vehicle.Powertrain.FuelSystem.Level",
                        "dp": {"value": "50", "ts": "2020-04-15T13:37:00Z"}
                },
                "ts": "2020-04-15T13:37:00Z"
              }

Error event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "error": {"number": "401", "reason": "expired_token", "description": "Access token has expired."},
                "ts": "2020-04-15T13:37:00Z"
              }

Authorized Subscribe

If the operation on the addressed VSS node requires authorization, the request MUST include the "authorization" field with a valid JWT token as its value. The token MUST be successfully validated for a subscribeSuccessResponse to be returned. If validation fails, a subscribeErrorResponse SHALL be returned. An "authorization" key-value pair can be combined with all types of subscription requests.

Example:
Request:


              {
                "action": "subscribe",
                "path": "Vehicle.Powertrain.FuelSystem.Level",
                "filter": {"variant":"range", "parameter":[{"logic-op":"gt", "boundary":"49"}, {"logic-op":"lt", "boundary":"51"}]},
                "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds",
                "requestId": "6578"
              }

Successful response:


              {
                "action": "subscribe",
                "subscriptionId": "12345",
                "requestId": "6578",
                "ts": "2020-04-15T13:37:00Z"
              }

Event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "data": {"path": "Vehicle.Powertrain.FuelSystem.Level",
                        "dp": {"value": "50", "ts": "2020-04-15T13:37:00Z"}
                },
                "ts": "2020-04-15T13:37:00Z"
              }

Curve Logging Subscribe

Curve logging data compression by eliminating data points that are within a set error margin is activated via a subscription request. Event messages will be issued when the buffer becomes full, after insignificant data points have been eliminated, refer to the chapter 7.6 Curve logging Filter Operation in the [[CORE]] specification.

Example:
Request:


              {
                "action": "subscribe",
                "path": "Vehicle.Powertrain.FuelSystem.Level",
                "filter": {"variant":"curvelog", "parameter":{"maxerr":"0.5", "bufsize":"100"}},
                "requestId": "6578"
              }

Successful response:


              {
                "action": "subscribe",
                "subscriptionId": "12345",
                "requestId": "6578",
                "ts": "2020-04-15T13:37:00Z"
              }

Event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
                        "dp":[{"value": "50", "ts": "2020-04-15T13:38:00Z"}, ..., {"value": "25", "ts": "2020-04-15T13:39:30Z"}]
                },
                "ts": "2020-04-15T13:37:00Z"
              }

Range Subscribe

Subscription to a range of values, that can have either a single boundary, or multipe boundaries as in the example below. For a more information how to use range of values, refer to the chapter 7.4 Range Filter Operation in the [[CORE]] specification.

Example:
Request:


              {
                "action": "subscribe",
                "path": "Vehicle.Powertrain.FuelSystem.Level",
                "filter": "filter":{"variant":"range","parameter":[{"logic-op":"lt","boundary":"50","combination-op":"OR"},{"logic-op":"gt","boundary":"55"}]},
                "requestId": "6578"
              }

Successful response:


              {
                "action": "subscribe",
                "subscriptionId": "12345",
                "requestId": "6578",
                "ts": "2020-04-15T13:37:00Z"
              }

Event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
                        "dp":{"value": "51", "ts": "2020-04-15T14:00:00Z"}},
                "ts": "2020-04-15T14:00:00Z"
              }

Change Subscribe

Subscription to when a signal has changed between two sequential captures. For a more information how to use change of values, refer to the chapter 7.5 Change Filter Operation in the [[CORE]] specification.

Example:
Request:


              {
                "action": "subscribe",
                "path": "Vehicle.Powertrain.FuelSystem.Level",
                "filter":{"variant":"change","parameter":{"logic-op":"gt","diff":"10"}},
                "requestId": "6578"
              }

Successful response:


              {
                "action": "subscribe",
                "subscriptionId": "12345",
                "requestId": "6578",
                "ts": "2020-04-15T13:37:00Z"
              }

Event:


              {
                "action": "subscription",
                "subscriptionId": "12345",
                "data":{"path": "Vehicle.Powertrain.FuelSystem.Level",
                        "dp":{"value": "101", "ts": "2020-04-15T14:00:00Z"}},
                "ts": "2020-04-15T14:00:00Z"
              }

Unsubscribe

To unsubscribe from a subscription, the client SHALL send an unsubscribeRequest message to the server. If the server can fulfill the request successfully, it SHALL returns an unsubscribeSuccessResponse message. If an error occurs, an unsubscribeErrorResponse message SHALL be returned.
If the client has created multiple WebSocket instance, it MUST unsubscribe using the same WebSocket instance that was originally used to create the subscription.

Object Name	Attribute	Type	Required
unsubscribeRequest	action	Action	Yes
	subscriptionId	string	Yes
	requestId	string	Yes

Object Name	Attribute	Type	Required
unsubscribeSuccessResponse	action	Action	Yes
	requestId	string	Yes
	ts	string	Yes

Object Name	Attribute	Type	Required
unsubscribeErrorResponse	action	Action	Yes
	requestId	string	Yes
	error	Error	Yes
	ts	string	Yes

Example:
Request:


              {
                "action": "unsubscribe",
                "subscriptionId": "12345",
                "requestId": "5786"
              }

Successful response:


              {
                "action": "unsubscribe",
                "requestId": "5786",
                "ts": "2020-04-15T13:37:00Z"
              }

Error response:


              {
                "action": "unsubscribe",
                "requestId": "6578",
                "error": {"number": "400", "reason": "invalid_data", "description": "Data present in the request is invalid."},
                "ts": "2020-04-15T13:37:00Z"
              }

HTTPS

The message data components described in the [[CORE]] specification are primarily mapped to standard HTTP parameters. Only when no suitable mapping is available are they included in the payload. The most significant deviations are as follows:

The path is included as part of the URL.
A filter expression is added to the URL as a query string.
The HTTP methods GET and POST are used instead of the "action" field.

The subscribe/unsubscribe operations are not supported by this transport protocol.

Session Life Time Management

Initialization

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.
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 SHALL use port 443, the default port for secure HTTPS connections. Hostname resolution can be achieved using DNS or configured through local settings.

Closure

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.
Upon session closure, any allocated resources, such as server-side threads or memory, are released, improving overall system efficiency.

Transport Messages

Read

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 can fulfill the request, it SHALL return a response containing the requested value(s). 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, then it SHALL respond with an appropriate error status code.

Example: Request:


              GET /Vehicle/Cabin/SeatPosCount   HTTP/1.1
              Host: 127.0.0.1:1337
              Accept: application/json
	      ...

Successful response:


              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"}
                       },
                "ts": "2020-04-15T13:37:00Z"
              }

Error response:


              HTTP/1.1 404 Not Found
              Content-Type: application/json; charset=utf-8
	      ...
              {
                "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
                "ts": "2020-04-15T13:37:00Z"
              }

Authorized Read

JWT tokens MUST be included in the Authorization header, prefixed with Bearer and followed by a space character.

The following example assumes eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds is the actual token. A JWT token in the Authorization header can be combined with all types of read requests.
Example: Request:


            GET /Vehicle/Powertrain/CombustionEngine/RPM   HTTP/1.1
            Host:127.0.0.1:1337
            Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds

Successful response:


            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
	    ...
            {
              "data":{"path":"Vehicle.Powertrain.CombustionEngine.RPM",
                      "dp":{"value":"2372", "ts":"2020-04-15T13:37:00Z"}
                     },
                "ts": "2020-04-15T13:37:00Z"
            }

Error response:


            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", "description": "Access token is invalid."},
              "ts": "2020-04-15T13:37:00Z"
            }

Search Read

The search read request uses the chapter 7.1 Paths Filter Operation described in the [[CORE]] specification to define one or more path expressions, relative to the path in the GET URL.
Example: Request:


              GET /Vehicle/Cabin/Door?filter={"variant":"paths", "parameter":"*/*/IsOpen"}   HTTP/1.1
              Host: 127.0.0.1:1337
              Accept: application/json
	      ...

Response:


              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"}}
                       ],
                "ts": "2020-04-15T13:37:00Z"
              }

Error response:


              HTTP/1.1 404 Not Found
              Content-Type: application/json; charset=utf-8
	      ...
              {
                        "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
                        "ts": "2020-04-15T13:37:00Z"
              }

History Read

The history read request uses the chapter 7.2 History Filter Operation described in the [[CORE]] specification to read recorded values for a specific past duration.
Example: Request:


              GET /Vehicle.Acceleration.Longitudinal?filter={"variant":"history", "parameter":"P2DT12H"}   HTTP/1.1
              Host: 127.0.0.1:1337
              Accept: application/json
	      ...

Response:


              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"}]},
                "ts": "2020-04-15T13:37:00Z"
              }

Signal Discovery Read

The signal discovery request uses the chapter 7.7 Metadata Filter Operation described in the [[CORE]] specification to retrieve metadata from a specified subtree in the VSS tree. A successful response will contain the requested metadata from all nodes of the subtree defined by the subtree root node addressed by the path. The depth of metadata retrieval is controlled by the "parameter" value.

Example:
Request:


              GET /Vehicle/Powertrain/FuelSystem?filter={"variant":"metadata", "parameter":"0"}   HTTP/1.1
              Host: 127.0.0.1:1337
              Accept: application/json
	      ...

Response:


              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"
              }

Update

The client may request that the server sets the value of a signal. If the server is able to satisfy the request it SHALL return a setSuccessResponse 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 SHALL return a setErrorResponse message.

Example:


            POST /Vehicle/Powertrain/Transmission/PerformanceMode   HTTP/1.1
            Host: 127.0.0.1:1337
            Accept: application/json
      ...
            {
              "value": "sport"
            }

Successful response:


            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
      ...
            {
              "ts": "2020-04-15T13:37:00Z"
            }

Error response:


            HTTP/1.1 404 Not Found
            Content-Type: application/json; charset=utf-8
      ...
            {
              "error": {"number": "404", "reason": "unavailable_data", "description": "The requested data was not found."},
              "ts": "2020-04-15T13:37:00Z"
            }

Authorized Update

JWT tokens will be sent in the Authorization header, following with term Bearer and a space character.

The following example assumes eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds is the actual token. A token header can be combined with all types of update requests.


          POST /Vehicle/Powertrain/Transmission/PerformanceMode   HTTP/1.1
          Host:127.0.0.1:1337
          Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds
          {
            "value": "sport"
          }

MQTT

As the MQTT protocol is based on a pub-sub model, while VISS is based on a client-server model, it is necessary to apply a thin application level protocol on top of MQTT to abstract the client-server specific behavior. This is done by embedding the VISS messages in the MQTT messages, together with supplementary information that makes this abstraction possible, see the next chapter.
The VISS messages are adhering to the primary payload format without any deviations.

Application Level Protocol

For MQTT to support the complete VISSv3 interface, as decribed in the interface chapter of the [[CORE]] specification, an application level protocol that runs on top of MQTT is added. It is described in the following, please also see the sequence diagram below. To emulate the client-server pattern that is described in the [[CORE]] specification, the vehicle server, via its vehicle client, issues a subscribe request to the broker on a topic named VID/Vehicle, where VID is an identity that uniquely links to the vehicle in the access control ecosystem. This vehicle identity is not necessarily the manufacturer's Vehicle Identification Number (VIN).
The client on the "cloud side" of the broker is expected to have access to this vehicle identity. How it obtains it is out of scope for this specification. When the cloud client wants to issue a request to the vehicle server it first generates a unique topic name, which it subscribes to at the broker. It then generates a JSON formatted payload with the general structure


          {"topic":"aUniqueTopic", "request":"VISSv3Request"}

where "aUniqueTopic" is the uniques topic name it just subscribed to, and "VISSv3Request" is the request for the vehicle server. This request MUST follow the primary payload format of this specification. This JSON message is then issued to the broker, associated to the topic VID/Vehicle. This message will then be forwarded by the broker to the vehicle client, which forwards the string being the value of the "request" key in the message to the vehicle server. When the vehicle client receives the response to this request, it publishes it to the broker associated with the topic name that was the string value of the "topic" key name in the message it previously received from the broker.
The broker will then forward this message to the cloud side client that earlier subscribed to this topic name, which concludes the client-server based request-response as described in the [[CORE]] specification.
In the case of subscription requests the vehicle client needs to save the subscriptionId found in the subscribe response, together with the topic name associated to the subscribe request. When the vehicle server later issues event messages, the vehicle client must parse the subscriptionId from it, and retrieve the topic name associated to it. The vehicle client shall delete the saved topic name and subscriptionId when it receives an unsubscribe request in a message from the broker.
In following requests from the cloud side client, the unique topic name may be reused from the previous request-response cycle, or a new unique topic name may be generated. If a new topic name is generated, an unsubscribe should be issued on the old topic name. The vehicle client can continue to use the topic name it subscribes to.
The payload format of the response/event messages SHALL follow the primary payload format of this specification. The access control model is applicable also over this transport alternative. The Access Token server should then implement its own version of the application level protocol described here, using the topic name "VID/ATS". The Access Grant Token server may also do the same, with the topic name "VID/AGTS", or if it is deployed in the cloud it may expose the HTTPS interface that is defined in this specification.

Security Aspects

The MQTT architecture mandates a "broker" that acts as a middleman in between the client and server endpoints (the subscriber and the publisher in MQTT terminology). This broker has full access to the plaintext communication between the two endpoints as each of the endpoint's TLS channel terminates at the broker. This aspect should be considered when selecting to use the MQTT protocol.

Transport Messages

As mentioned in the "Application Level Protocol" chapter, the "request" messages issued to the broker contains two JSON formatted key-value pairs, where the value of the "request" key is a string that contains the request the vehicle server will respond to. The format of this request MUST follow the primary payload format of this specification.

gRPC

The gRPC protocol uses protobuf for the serialization. The definition of protobuf messages shall be expressed in a .proto-file. The proto file defining the encoding of the VISS primary payload format is found in the [[PAYLOAD ENCODING]] document. A protobuf compiler is used to generate code from the .proto-file that can then be called by the code executing the actual encoding/decoding between the two payload formats. This code can be implemented in different languages, and is out-of-scope for VISS standardization. An example of it in Go language can be found here.

Attribute	Type	Description
action	Action	The type of action requested by the client or delivered by the server.
path	string	The path to a node in the VSS tree, as defined by the Vehicle Signal Specification (VSS).
requestId	string	Unique id value specified by the client. Returned by the server in the response and used by the client to link the request and response messages. The value MAY be an integer or a Universally Unique Identifier (UUID).
subscriptionId	string	Value returned by the server to uniquely identify each subscription.
authorization	string	A JWT formatted security token.
data	object / array	Data contains one or more objects each consisting of a path and a data point.
dp	object / array	A data point contains one or more objects each consisting of a value and a timestamp.
ts	string	The Coordinated Universal Time (UTC) time stamp that represents the capture of the value.
value	string/ object / array	The data value associated with the path.
filter	string	Provides a filtering mechanism to reduce the demands of a subscription on the server. Query format, see [[CORE]], Filter Request chapter.
data compression	string	Compression of path and/or timestamp data.
metadata	object	Metadata describing the potentially available signal (sub)tree.
error	Error	Returns an error code, reason and description.

Introduction

Terminology

Transport Common Definitions

Status Codes

In-line Error Reporting

Common Error Scenarios

400 Bad Request Error Descriptions

400 Invalid Data Error Descriptions

401 Unauthorized Error Descriptions

404 Not Found Error Descriptions

Transport Payload

Authorization

Transport Protocols

Secure WebSocket

Session Life Time Management

Initialization

Closure

Transport Messages

Read

Authorized Read

Search Read

History Read

Signal Discovery Read

Update

Authorized Update

Subscribe

Authorized Subscribe

Curve Logging Subscribe

Range Subscribe

Change Subscribe

Unsubscribe

HTTPS

Session Life Time Management

Initialization

Closure

Transport Messages

Read

Authorized Read

Search Read

History Read

Signal Discovery Read

Update

Authorized Update

MQTT

Application Level Protocol

Security Aspects

Transport Messages

gRPC

Definitions

Term Definitions

Action Definitions

Error Definitions