From e11174490a37c11bd0501153c7bf8c48710439dd Mon Sep 17 00:00:00 2001 From: tguild Date: Tue, 29 Nov 2022 14:42:36 -0500 Subject: [PATCH 1/5] providing additional details on use etc --- viss2-explainer.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/viss2-explainer.md b/viss2-explainer.md index a72a0ee..bf22e9a 100644 --- a/viss2-explainer.md +++ b/viss2-explainer.md @@ -1,30 +1,30 @@ # VISS - Vehicle Information Service Specification Explainer -Modern vehicles use hundreds of sensors which produce thousands of different data points, or signals, amounting to terabytes of data per vehicle per day. -There is no question vehicles are transforming, becoming connected, electric and autonomous all of which relies extensively on signals data. -To facilitate innovation and development on various use cases the W3C established a strategic alliance with COVESA and formed the Common Vehicle Interface -Initiative (CVII). At the center of this effort is a common data model for these vehicle signals, namely the Vehicle Signal Specification ([VSS](https://covesa.github.io/vehicle_signal_specification/)) which has its own [explainer](https://www.covesa.global/sites/default/files/COVESA%20Vehicle%20Signal%20Specification_060122.pdf). The W3C Automotive Working Group is creating the means to access this data in a standardized way with the Vehicle Information Service Specification (VISS). The service can reside either in the vehicle, or in the cloud. Client applications can also reside in the vehicle, cloud or running on a nomad device such as a smartphone. +Modern vehicles use hundreds of sensors which produce thousands of different data points, or signals, amounting to terabytes of data available per vehicle per day. There are thousands of signals or data points available on modern vehicles ranging from door lock state, fuel or charge level to tire pressure sensors and anti-lock brake control unit status. There is no question vehicles are transforming, becoming connected, electric and autonomous all of which relies extensively on signals data. +To facilitate innovation and development on various use cases the W3C established a strategic alliance with [COVESA](https://covesa.global). +At the center of this effort is a common data model for these vehicle signals, namely the Vehicle Signal Specification ([VSS](https://covesa.github.io/vehicle_signal_specification/)) which has its own [explainer](https://www.covesa.global/sites/default/files/COVESA%20Vehicle%20Signal%20Specification_060122.pdf). The W3C Automotive Working Group is creating the means to access this data in a standardized way with the Vehicle Information Service Specification (VISS). The service can reside either in the vehicle, or in the cloud. Client applications can also reside in the vehicle, cloud or running on a nomad device such as a smartphone. Vehicle signals, the definition and access to them, has historically been OEM proprietary. This has made it difficult for suppliers, commercial fleets, -tech companies and other interested parties to integrate across vehicle brands. Furthermore, since VISS and VSS are open standards their use will reduce -cost, promote innovation, interoperability and facilitate third party software development. +tech companies, insurance companies, regulators and other interested parties to integrate across vehicle brands. Furthermore, since VISS and VSS are open standards their use will reduce cost, promote innovation, interoperability and facilitate third party software development. VSS uses a tree structure with well defined open definitions, but it also has the ability to be extended to handle new and /or proprietary signals if -needed. The transport and the access (API) is defined by the VISS specification, it includes HTTPS, MQTT, as well as Websockets which was the only -transport protocol supported in the first version. The second and current version of the specification includes a complete access control model, and -filtering techniques to better fit OEM requirements. +needed. The [transport](https://www.w3.org/standards/history/viss2-transport) and [access (API)](https://www.w3.org/TR/viss2-core/) together comprise by the VISS version 2 specification, it includes HTTPS, MQTT, as well as Websockets which was the only +transport protocol supported in the [first version of VISS](https://www.w3.org/TR/vehicle-information-service/). The second and current version of the VISS includes a complete access control model, and filtering techniques to better fit OEM requirements. + +VISS version 1 deferred on access control to individual implementations and as mentioned only supported Websockets. Of the thousands of data points potentially available, a client application could subscribe to an allowed subset, receive initial and updated values over time. The second version expanded on the filters available for Websocket subscriptions and allows for individual requests over HTTPS or MQTT of individual signals or if allowed a logical branch of signals. For example, requesting /Vehicle/Drivetrain/Transmission would, if authorized, return all data available for a vehicle's transmission. _Notes on implementation and use_ -VISS has known implementations by Volvo, BMW, JLR, AWS Fleetwise, Renesas, Bosch, Visteon, Geotab, AGL and Mitsubishi Electric to name a few. -The underlying data model VSS is seeing much wider adoption since its uses go far beyond a single API. -General use for telematics - include EV, insurance, ... +VISS has known implementations by Volvo, BMW, JLR, Renesas, Bosch, Visteon, Geotab, AGL and Mitsubishi Electric to name a few. +The underlying data model VSS is seeing much wider adoption, eg within AWS Fleetwise or accompanying ontology ([VSSo](https://www.w3.org/TR/vsso/)) for machine learning, since its uses go far beyond a single API. + +A client application for example could reside on the vehicle itself on an on-board logic, telematics or head unit. From there it can authenticate itself against VISS and based on permissions granted for the specific application, can read or even write data to/from the vehicle. Applications may be user facing, providing information to operator or occupants or performing data sampling for analysis. + +There are multiple uses for vehicle telematics data. Electric vehicle charging events can be combined with charging infrastructure, route planning and weather conditions to plan trips on a vehicles' behalf and ensure battery is not depleted. Insurance companies use it, with owner/operator permission and typically in exchange for a discount on premium, to assess driving behavior. Fleet operators and mechanic services can assess vehicles performance and predict maintenance issues before they arise and leave a vehicle stranded. Information about a vehicles' status, location, fuel/charge level, diagnostics, etc can be conveyed to the owner on the head unit/in-vehicle infotainment or a trusted, paired smartphone. The [W3C / COVESA CVII](https://wiki.covesa.global/display/WIK4/Common+Vehicle+Interface+Initiative+-+Home) is broad in scope and VISS is an important component, to address needs within the vehicle, cloud, AI/knowledge graph, service and solution level all centered on the common vehicle data model VSS. -VISS is a vital component in the realization of telematics use cases, such as fleet management, electric vehicle charging, driver behavior and usage based -vehicle insurance, etc. A standards based interface, and data model, supports interoperability between vehicle brands, and thus enables an open ecosystem where innovation of new services can thrive. From 60606da358e042b55289bf3d0f7e5aa1efcea99c Mon Sep 17 00:00:00 2001 From: tguild Date: Tue, 29 Nov 2022 14:52:56 -0500 Subject: [PATCH 2/5] scope on privacy --- viss2-explainer.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/viss2-explainer.md b/viss2-explainer.md index bf22e9a..030c318 100644 --- a/viss2-explainer.md +++ b/viss2-explainer.md @@ -12,6 +12,8 @@ VSS uses a tree structure with well defined open definitions, but it also has th needed. The [transport](https://www.w3.org/standards/history/viss2-transport) and [access (API)](https://www.w3.org/TR/viss2-core/) together comprise by the VISS version 2 specification, it includes HTTPS, MQTT, as well as Websockets which was the only transport protocol supported in the [first version of VISS](https://www.w3.org/TR/vehicle-information-service/). The second and current version of the VISS includes a complete access control model, and filtering techniques to better fit OEM requirements. +The intention is to use web technologies to facilitate development of applications with limited, trusted entities and to not make vehicles available for arbitrary connections over the web. Access to specific data points and use of the information is outside of the scope of this work. It is expected automotive manufacturers will govern which parties can run logic on or against vehicles, manage permissions, conduct security and legal/privacy audits. Regulators and courts, [Massachussets Right to Repair lawsuit as an example](https://www.natlawreview.com/article/automakers-lawsuit-opposing-updates-to-massachusetts-right-to-repair-law-lingers), will undoubtedly influence this as well. + VISS version 1 deferred on access control to individual implementations and as mentioned only supported Websockets. Of the thousands of data points potentially available, a client application could subscribe to an allowed subset, receive initial and updated values over time. The second version expanded on the filters available for Websocket subscriptions and allows for individual requests over HTTPS or MQTT of individual signals or if allowed a logical branch of signals. For example, requesting /Vehicle/Drivetrain/Transmission would, if authorized, return all data available for a vehicle's transmission. _Notes on implementation and use_ From 674962479360b001b208123d24acedecfd9e6808 Mon Sep 17 00:00:00 2001 From: tguild Date: Tue, 29 Nov 2022 14:56:25 -0500 Subject: [PATCH 3/5] bp --- viss2-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/viss2-explainer.md b/viss2-explainer.md index 030c318..0aa58c9 100644 --- a/viss2-explainer.md +++ b/viss2-explainer.md @@ -12,7 +12,7 @@ VSS uses a tree structure with well defined open definitions, but it also has th needed. The [transport](https://www.w3.org/standards/history/viss2-transport) and [access (API)](https://www.w3.org/TR/viss2-core/) together comprise by the VISS version 2 specification, it includes HTTPS, MQTT, as well as Websockets which was the only transport protocol supported in the [first version of VISS](https://www.w3.org/TR/vehicle-information-service/). The second and current version of the VISS includes a complete access control model, and filtering techniques to better fit OEM requirements. -The intention is to use web technologies to facilitate development of applications with limited, trusted entities and to not make vehicles available for arbitrary connections over the web. Access to specific data points and use of the information is outside of the scope of this work. It is expected automotive manufacturers will govern which parties can run logic on or against vehicles, manage permissions, conduct security and legal/privacy audits. Regulators and courts, [Massachussets Right to Repair lawsuit as an example](https://www.natlawreview.com/article/automakers-lawsuit-opposing-updates-to-massachusetts-right-to-repair-law-lingers), will undoubtedly influence this as well. +The intention is to use web technologies to facilitate development of applications with limited, trusted entities and to not make vehicles available for arbitrary connections over the web. Access to specific data points and use of the information is outside of the scope of this work. It is expected automotive manufacturers will govern which parties can run logic on or against vehicles, manage permissions, conduct security and legal/privacy audits. Regulators and courts, [Massachussets Right to Repair lawsuit as an example](https://www.natlawreview.com/article/automakers-lawsuit-opposing-updates-to-massachusetts-right-to-repair-law-lingers), will undoubtedly influence this as well. The W3C Automotive Working Group, together with the COVESA Security and Data Expert Groups will likely produce formal best practices which will include security and privacy aspects. VISS version 1 deferred on access control to individual implementations and as mentioned only supported Websockets. Of the thousands of data points potentially available, a client application could subscribe to an allowed subset, receive initial and updated values over time. The second version expanded on the filters available for Websocket subscriptions and allows for individual requests over HTTPS or MQTT of individual signals or if allowed a logical branch of signals. For example, requesting /Vehicle/Drivetrain/Transmission would, if authorized, return all data available for a vehicle's transmission. From c3ef5871db37c9376c5d80a3c00b656ce259b383 Mon Sep 17 00:00:00 2001 From: tguild Date: Tue, 29 Nov 2022 15:05:15 -0500 Subject: [PATCH 4/5] Update services-explainer.md --- services-explainer.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/services-explainer.md b/services-explainer.md index 4015d89..75c2962 100644 --- a/services-explainer.md +++ b/services-explainer.md @@ -2,6 +2,10 @@ ## Status: PUBLIC ## Last Updated: 2018-07-27 +## Status + +Deprecated, [updated or supplemental explainer](https://github.com/w3c/automotive/blob/gh-pages/viss2-explainer.md) + ## Introduction: The W3C Automotive Working Group is creating standards to expose services within vehicles using Web Technology. Specifically we areworking on signals, media (services and library), navigation, notifications with potentially others to follow. From a8f9d53d9dd322678d67834d00c6494b9f76b8dc Mon Sep 17 00:00:00 2001 From: Ulf Bjorkengren Date: Mon, 2 Jan 2023 15:49:59 +0100 Subject: [PATCH 5/5] Issue 469: notification changed to event. --- spec/VISSv2_Core.html | 38 +++++++++++++++---------------- spec/VISSv2_Transport.html | 46 +++++++++++++++++++------------------- 2 files changed, 42 insertions(+), 42 deletions(-) diff --git a/spec/VISSv2_Core.html b/spec/VISSv2_Core.html index c1afaad..02079d0 100644 --- a/spec/VISSv2_Core.html +++ b/spec/VISSv2_Core.html @@ -188,7 +188,7 @@

Definitions

The message being returned by the server to the client when no error is encountered. These are specific per request type
error message
The message being returned by the server to the client when an error is encountered. It can be a synchronous response message, - or an asynchrounous notification message.
+ or an asynchrounous event message.
data point
A structure containing one or more value, timestamp tuplets.
value
@@ -379,22 +379,22 @@

Update

Subscribe

Purpose: Get asynchronous messages containing the value(s) addressed by the path. - The triggering rules for issuing the notification messages are set by the filter data.

+ The triggering rules for issuing the event messages are set by the filter data.

The client MAY have to obtain an authorization token before being able to subscribe to the vehicle signal(s). - The server MUST issue a notification if a trigger rule is fulfilled. + The server MUST issue an event message if a trigger rule is fulfilled. If the server is able to satisfy the request it MUST return a success response. If the server is unable to fulfil the request, then the server MUST return an error response. - If an error occurs during the subscription period, the server SHOULD return an error notification.

+ If an error occurs during the subscription period, the server SHOULD return an error event.

Arguments, of which path and filter are mandatory:

  • path The path as defined in VSS to one or more nodes in the VSS tree.
    • -
  • filter The rule set describing triggering criterias for issuance of asynchronous notification messages.
    • +
  • filter The rule set describing triggering criterias for issuance of asynchronous event messages.
  • authorization The authorization token.

Success response:

    -
  • subscriptionId A handle identifying notification messages associated with the subscription.
    • +
  • subscriptionId A handle identifying event messages associated with the subscription.
  • timestamp The start time for the subscription period.

@@ -403,7 +403,7 @@

Subscribe

Unsubscribe

Purpose: Termination of the subscription period started by a previous subscribe request.

If the server is able to satisfy the request it MUST return a success response, - and it MUST stop issuing notifications associated to the subscription handle. + and it MUST stop issuing event messages associated to the subscription handle. If the server is unable to fulfil the request, then the server MUST return an error response.

Arguments, of which subscriptionId is mandatory:

    @@ -419,9 +419,9 @@

    Unsubscribe

Subscription

-

Purpose: Asynchronous client notification according to the subscribe request trigger rules.

-

The server MUST issue a notification message when a triggering rule associated with the subscription is met. - If the server cannot fulfill the triggering rules it MUST issue an error notification and terminate the subscription. +

Purpose: Asynchronous client event message according to the subscribe request trigger rules.

+

The server MUST issue an event message when a triggering rule associated with the subscription is met. + If the server cannot fulfill the triggering rules it MUST issue an error event message and terminate the subscription.

Arguments:

    @@ -440,8 +440,8 @@

    Subscription

    Error Message

    The server MUST inform a client about errors ocurring in interactions between the two, whether it is in a synchronous - error response, or an asynchronous error notification as a result of a previous subscribe. The error message has three arguments, - of which subscriptionId is mandatory only for error notifications. + error response, or an asynchronous error event message as a result of a previous subscribe. The error message has three arguments, + of which subscriptionId is mandatory only for error event messages.

    Arguments:

      @@ -622,7 +622,7 @@

      Paths Filter Operation

      A path in the filter value may contain the wildcard character (*) as a representative for a single path segment.
      Every path element in an value array must address at least one node in the tree, or else an error response is returned.
      Different elements of the value array may address the same node, - in which case it is the responsibility of the server to resolve this to a singleton in the notifications.
      + in which case it is the responsibility of the server to resolve this to a singleton in the event messages.
      Examples can be found in the search read on HTTPS and search read on WebSocket in [[viss2-transport]] specification.

      @@ -667,7 +667,7 @@

      Range Filter Operation

      Single Boundary Range

      One logical "boundary operator" evaluates the current signal value in relation to the boundary. - If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. + If evaluated to true, the server issues an event message containing the signal value to the subscribing client. The boundary operator MUST be one of the values shown in the footer (**).
      Examples
      {"boundary-op":"gt", "boundary": "5"} // x > 5
      @@ -679,7 +679,7 @@

      Multi Boundary Range

      Two boundaries with respective boundary operators are evaluated relative to the current signal value. The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. - If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. + If evaluated to true, the server issues an event message containing the signal value to the subscribing client. Besides the mandatory "boundary-op", and "boundary" key-value pairs in each JSON object, the first object may contain a "combination-op" key value pair, which then MUST have either the value "AND", or the value "OR". If omitted, the result of the two boundary evaluations is per default applied to an AND operation. @@ -892,18 +892,18 @@

      Response syntax

    -
    -

    Subscription Notification Triggering

    +
    +

    Subscription Event Triggering

    A subscription request must always contain a filter operation that describes the trigger event that leads to - that the server dispatches an asynchronous notification message. + that the server dispatches an asynchronous event message. For the filter types "range" or "change", the triggering is dependent on the signal value. When the request addresses multiple signals, the triggering condition shall only be evaluated on one of the signals, which is the first signal in the value array of paths. The first path in the array must therefore not contain wildcards to address multiple signals. In this case one of the path addresses in the wildcard expression must be selected as the first array element, which can then be followed by the wildcard expression. - The duplicate reference to one signal that this leads to shall be resolved by the server to a singleton in the notifications. + The duplicate reference to one signal that this leads to shall be resolved by the server to a singleton in the event messages.

    diff --git a/spec/VISSv2_Transport.html b/spec/VISSv2_Transport.html index feeceb9..18973c5 100644 --- a/spec/VISSv2_Transport.html +++ b/spec/VISSv2_Transport.html @@ -663,7 +663,7 @@

    Session Life Time Management

    If more than one WebSocket connection is established between a client application and the server then each connection MUST be managed independently. For example, subscriptions created using a particular - WebSocket connection shall only trigger notifications via that connection and the client + WebSocket connection shall only trigger event messages via that connection and the client MUST use that WebSocket connection to unsubscribe.

    @@ -1021,26 +1021,26 @@

    Subscribe

    The client may send a subscribeRequest message to request a subscription to one or more signals, - thereby requesting the server to repeatedly return subscription notification messages, as specified by + thereby requesting the server to repeatedly return subscription event messages, as specified by the filter request described in the [[viss2-core]]. The server MAY reduce the number of - subcriptionNotification + subcriptionEvent messages sent to the client in order to reduce processing demands.
    If the server is able to satisfy the request it SHALL return a subscribeSuccessResponse message. If an error occurs e.g. because the client is not authorized to read the requested value, the server SHALL return a subscribeErrorResponse message. If an error occurs during the subscription session, the server shall return an - subscriptionErrorNotification message.
    + subscriptionErrorEvent message.
    The subscription variants are, as described in the [[viss2-core]] document:

      -
    • timebased: notifications are issued at a regular time interval,
      • -
    • change: notifications are issued when the value has changed as specified,
      • -
    • range: notifications are issued when the value is in the specified range,
      • -
    • curvelog: notifications are issued when the buffer is full, and then processed according to the curve logging algorithm.
      • +
    • 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.
    If none of the above trigger condition variants is specified, - then a notification will be issued whenever the underlying vehicle system supplies a new data point to the server. + then an event message will be issued whenever the underlying vehicle system supplies a new data point to the server.

    @@ -1084,7 +1084,7 @@

    Subscribe

    - + @@ -1095,7 +1095,7 @@

    Subscribe

    - + @@ -1130,7 +1130,7 @@

    Subscribe

    "ts": "2020-04-15T13:37:00Z" } - Notification: + Event: 
    
               {
                 "action": "subscription",
@@ -1141,7 +1141,7 @@ 
    Subscribe
    
                 "ts": "2020-04-15T13:37:00Z"
               }
    - Error notification: + Error event: 
    
               {
                 "action": "subscription",
@@ -1184,7 +1184,7 @@ 
    Authorized Subscribe
    
                 "ts": "2020-04-15T13:37:00Z"
               }
    - Notification: + Event: 
    
               {
                 "action": "subscription",
@@ -1202,7 +1202,7 @@ 
    Authorized Subscribe
    
             
    Curve Logging Subscribe
    
             
    
             Curve logging data compression by eliminating data points that are within a set error margin is activated via a subscription request. 
-            Notifications will be issued when the buffer becomes full, after insignificant data points have been eliminated, 
+            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 [[viss2-core]] documentation.
             
    
             
    
@@ -1225,7 +1225,7 @@ 
    Curve Logging Subscribe
    
                 "ts": "2020-04-15T13:37:00Z"
               }
    - Notification: + Event: 
    
               {
                 "action": "subscription",
@@ -1265,7 +1265,7 @@ 
    Range Subscribe
    
                 "ts": "2020-04-15T13:37:00Z"
               }
    - Notification: + Event: 
    
               {
                 "action": "subscription",
@@ -1304,7 +1304,7 @@ 
    Change Subscribe
    
                 "ts": "2020-04-15T13:37:00Z"
               }
    - Notification: + Event: 
    
               {
                 "action": "subscription",
@@ -1427,14 +1427,14 @@ 
    Application Level Protocol
    
             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 [[viss2-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 notifications, 
+            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 responses/notifications SHALL follow the payload format that is specified 
+            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, 
@@ -1654,11 +1654,11 @@ 
    Action Definitions
    
 	  
    set
    
 	  
    Enables the client to update one value.
    
 	  
    subscribe
    
-	  
    Enables the client to request notifications containing a JSON data structure with values for one or more vehicle signal.
    
+	  
    Enables the client to request event messages containing a JSON data structure with values for one or more vehicle signal.
    
 	  
    unsubscribe
    
-	  
    Enables the client to request that it should no longer receive notifications based on that subscription.
    
+	  
    Enables the client to request that it should no longer receive event messages based on that subscription.
    
 	  
    subscription
    
-	  
    Enables the server to send notifications to the client containing a JSON data structure with values for one or more vehicle signals.
    
+	  
    Enables the server to send event messages to the client containing a JSON data structure with values for one or more vehicle signals.
    Object NameAttributeTypeRequired
    subscriptionNotificationactionActionYes
    subscriptionEventactionActionYes
    subscriptionIdstringYes
    dataobject/arrayYes
    Object NameAttributeTypeRequired
    subscriptionErrorNotificationactionActionYes
    subscriptionErrorEventactionActionYes
    subscriptionIdstringYes
    errorErrorYes
    tsstringYes