HTTPS
+The message data components described in the [[viss3-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 most significant deviations are: +
-
+
- The path is part of the URL. +
- A filter expression is appended to the URL as a query. +
- The HTTP methods GET, POST replaces the use of "action". +
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 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.
+
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 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. +
++ Example: + Request: +
+ GET /Vehicle/Cabin/SeatPosCount HTTP/1.1
+ Host: 127.0.0.1:1337
+ Accept: application/json
+ ...
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscription",
- "subscriptionId": "12345",
- "data": {"path": "Vehicle.Drivetrain.FuelSystem.Level",
- "dp": {"value": "50", "ts": "2020-04-15T13:37:00Z"}
- },
- "ts": "2020-04-15T13:37:00Z"
+ "data":{"path":"Vehicle.Cabin.SeatPosCount",
+ "dp":{"value":["2", "3", "2"], "ts":"2020-04-15T13:37:00Z"}
+ }
}
-
+ HTTP/1.1 404 Not Found
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscription",
- "subscriptionId": "12345",
- "error": {"number": 401, "reason": "expired_token", "message": "Access token has expired."},
+ "error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
- Authorized Subscribe
+ + +Search Read
+
+ The search read request uses the paths filter operation described in the [[viss3-core]] document to provide one or more path expressions,
+ relative to the path in the GET URL.
+ Example:
Request:
- {
- "action": "subscribe",
- "path": "Vehicle.Drivetrain.FuelSystem.Level",
- "filter": {"variant":"range", "parameter":[{"boundary-op":"gt", "boundary":"49"}, {"boundary-op":"lt", "boundary":"51"}]},
- "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds",
- "requestId": "6578"
- }
-
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscribe",
- "subscriptionId": "12345",
- "requestId": "6578",
- "ts": "2020-04-15T13:37:00Z"
+ "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"}}
+ ]
}
-
+ HTTP/1.1 404 Not Found
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscription",
- "subscriptionId": "12345",
- "data": {"path": "Vehicle.Drivetrain.FuelSystem.Level",
- "dp": {"value": "50", "ts": "2020-04-15T13:37:00Z"}
- },
- "ts": "2020-04-15T13:37:00Z"
+ "error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
+ "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 the Curve logging Filter Operation chapter in the [[viss3-core]] documentation. -
+History Read
- Example:
+ The history read request uses the history filter operation described in the [[viss3-core]] document to read recorded values
+ for a given period backwards in time.
+ Example:
Request:
- {
- "action": "subscribe",
- "path": "Vehicle.Drivetrain.FuelSystem.Level",
- "filter": {"variant":"curvelog", "parameter":{"maxerr":"0.5", "bufsize":"100"}},
- "requestId": "6578"
- }
-
- {
- "action": "subscribe",
- "subscriptionId": "12345",
- "requestId": "6578",
- "ts": "2020-04-15T13:37:00Z"
- }
-
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscription",
- "subscriptionId": "12345",
- "data":{"path": "Vehicle.Drivetrain.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"
+ "data":{"path":"Vehicle.Acceleration.Longitudinal", "dp":[{"value":"0.123", "ts":"2020-04-15T13:00:00Z"}, ..., {"value":"0.125", "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 the Range Filter Operation chapter in the [[viss3-core]] documentation. -
+Signal Discovery Read
- Example:
+ The signal discovery request uses the static metadata filtering type as described in the [[viss3-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.
+
+ Example:
Request:
- {
- "action": "subscribe",
- "path": "Vehicle.Drivetrain.FuelSystem.Level",
- "filter": "filter":{"variant":"range","parameter":[{"boundary-op":"lt","boundary":"50","combination-op":"OR"},{"boundary-op":"gt","boundary":"55"}]},
- "requestId": "6578"
- }
-
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscribe",
- "subscriptionId": "12345",
- "requestId": "6578",
+ "metadata": {"FuelSystem":{"type":"branch","description":"Fuel system data.","children":{"HybridType, ... }}},
"ts": "2020-04-15T13:37:00Z"
}
-
- {
- "action": "subscription",
- "subscriptionId": "12345",
- "data":{"path": "Vehicle.Drivetrain.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 the Change Filter Operation chapter in the [[viss3-core]] documentation. -
+Dynamic Metadata Read
- Example:
+ 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 [[viss3-core]], Dynamic Metadata Filter Operation chapter.
+
+ Example:
Request:
- {
- "action": "subscribe",
- "path": "Vehicle.Drivetrain.FuelSystem.Level",
- "filter":{"variant":"change","parameter":{"logic-op":"gt","diff":"10"}},
- "requestId": "6578"
- }
-
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "subscribe",
- "subscriptionId": "12345",
- "requestId": "6578",
+ "metadata": {"filter":["timebased", "change", "paths", "curvelog", "dynamic-metadata"], "access_ctrl": ["short_term", "signalset_claim"], "transport_protocol": "https", "wss"},
"ts": "2020-04-15T13:37:00Z"
}
-
- {
- "action": "subscription",
- "subscriptionId": "12345",
- "data":{"path": "Vehicle.Drivetrain.FuelSystem.Level",
- "dp":{"value": "101", "ts": "2020-04-15T14:00:00Z"}},
- "ts": "2020-04-15T14:00:00Z"
- }
- Unsubscribe
+Update
- To unsubscribe from a subscription, the client SHALL send an
- unsubscribeRequest message to the server.
- If the server is able to satisfy the request it returns an
- unsubscribeSuccessResponse message.
- If an error occurs, for example because an invalid subscriptionId is passed to the server, an
- unsubscribeErrorResponse message is returned.
-
- If the client has created more than one WebSocket instance, it MUST always unsubscribe
- using the same WebSocket instance that was originally used to create the subscription.
+ 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.
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeRequest | action | Action | Yes |
| subscriptionId | string | Yes | |
| requestId | string | Yes |
-
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeSuccessResponse | action | Action | Yes |
| subscriptionId | string | Yes | |
| requestId | string | Yes | |
| ts | string | Yes |
-
| Object Name | Attribute | Type | Required |
|---|---|---|---|
| unsubscribeErrorResponse | action | Action | Yes |
| subscriptionId | string | Yes | |
| requestId | string | Yes | |
| error | Error | Yes | |
| ts | string | Yes |
- Example:
- Request:
+ Example:
+ POST /Vehicle/Drivetrain/Transmission/PerformanceMode HTTP/1.1
+ Host: 127.0.0.1:1337
+ Accept: application/json
+ ...
{
- "action": "unsubscribe",
- "subscriptionId": "12345",
- "requestId": "5786"
+ "value": "sport"
}
-
+ HTTP/1.1 200 OK
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "unsubscribe",
- "requestId": "5786",
"ts": "2020-04-15T13:37:00Z"
}
-
+ HTTP/1.1 404 Not Found
+ Content-Type: application/json; charset=utf-8
+ ...
{
- "action": "unsubscribe",
- "requestId": "6578",
- "error": {"number": 400, "reason": "invalid_data", "message": "Data present in the request is invalid."},
+ "error": {"number": 404, "reason": "unavailable_data", "message": "The requested data was not found."},
"ts": "2020-04-15T13:37:00Z"
}
- 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 he 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 [[viss3-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 [[viss3-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.
+ For MQTT to support the complete VISSv3 interface, as decribed in the interface chapter of the [[viss3-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 [[viss3-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 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
+ 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.
- 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.
+ 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 payload format that is specified in the Websocket chapter of this specification.
- 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,
+ 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.
+ 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 payload format that is specified in the Websocket chapter 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
+ 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,
+ 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 [[viss3-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
+ 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.
+ 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 payload format that is specified
- in the Websocket chapter 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",
+ The payload format of the response/event messages SHALL follow the payload format that is specified
+ in the Websocket chapter 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 HTTP interface that is defined in this specification.
-
+
Application Level Protocol
Security Aspects
Security Aspects
Transport Messages
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 [[viss3-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. +
+Term Definitions
Action Definitions
The Action enumeration is used to define the type of action requested by the client. - All client messages MUST contain a JSON structure that has an + All client messages MUST contain a JSON structure that has an action name/value pair and the - value of the action property + value of the action property MUST be one of the values specified in the enumeration:
-
@@ -1515,9 +1566,9 @@
Action Definitions
Error Definitions
-The error number SHOULD be a status code defined in [[RFC2616]], c. f. chapter "Status codes". +
The error number SHOULD be a status code defined in [[RFC2616]], c. f. chapter "Status codes". The error reason SHOULD be short. two or three words connected by underscor. - It SHOULD relate to the reason-phrase from [[RFC2616]] for the corresponding status code. + It SHOULD relate to the reason-phrase from [[RFC2616]] for the corresponding status code. The error message is meant to give a more precise description of the error.
| number | integer | Yes |
| reason | string | Yes |
| message | string | Yes |