Vehicle Information API Specification

W3C Working Group Note

This version:
https://www.w3.org/TR/2018/NOTE-vehicle-information-api-20180626/
Latest published version:
https://www.w3.org/TR/vehicle-information-api/
Latest editor's draft:
https://w3c.github.io/automotive/vehicle_information_api/vehicle_information_api_specification.html
Previous version:
https://www.w3.org/TR/2017/WD-vehicle-information-api-20170621/
Editors:
Powell Kinney (until 2017, while at Vinli) (Vinli)
Shinjiro Urata (ACCESS)
Mike Aro (IBM Corporation)
Repository and Participation:
We are on github.
File a bug/issue.
Commit history.
Mailing list archive.

Abstract

This specification defines a high level API for accessing to vehicle signals and data attributes.

The purpose of the specification is to promote a client implementation with a standard API that enables application development in a consistent manner across participating automotive manufacturers.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The W3C Automotive Working Group resolved to cease work on VIAS and not continue towards REC. Javascript and other implementations of VIAS meant to facilitate application development accessing underlying VISS is encouraged.

We do not anticipate further changes to this specification. This snapshot should generally be considered frozen. The Working Group may continue to make modifications. Implementers and interested parties should monitor VIAS wiki for any resulting changes, corrections, clarifications or shared code.

This document was published by the Automotive Working Group as a Working Draft. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-automotive@w3.org (subscribe, archives).

Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

1. Introduction

This section is non-normative.

The following documents the specification required for a high level API designed to interface with vehicle signals. This specification is responsible for the following:

In general, the client should strive for the following goals:

This API specification is designed assuming to communicate with in-vehicle data servers which provide vehicle signals and data attributes. A server conforms to definition in Vehicle Information Service Specification (hereafter VISS) is a typical example of in-vehicle data server, however servers of other types which have appropriate functions should also be applicable.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST and SHOULD are to be interpreted as described in [RFC2119].

3. Terminology

The term 'VISS' is used to refer to 'W3C Vehicle Information Service Specification'[vehicle-information-service] which is in the process of development in W3C Automotive Working Group along with this document. The term 'VIS Server' is used to refer to a server which conforms to the 'VISS' specification.

The term 'VIAS' is used to refer to 'W3C Vehicle Information API Specification' which is this document.

The term 'VSS' is used to refer to the 'Vehicle Signal Specification'[VSS] which is defined in GENIVI Alliance activity.

The term 'WebSocket' is used to refer to W3C WebSocket API [websockets] and the IETF's WebSocket Protocol [rfc6455].

4. Security and Privacy Considerations

This specification defines an interface to the underling server and does not expose any platform capabilities by itself. The underling server is responsible for managing privileges of each client connection and the VIAS implementation is responsible for passing requests and responses securely between clients and the server.

One of possible implementation methods of VIAS would be as a form of JavaScript library.
In that case, as a necessary security consideration, the JavaScript library SHOULD be provided from a trusted origin. Otherwise a malicious library could be loaded instead and any data goes through the library could be eavesdropped or tampered. Authorization tokens may goes through the library as well and if token leaking happens, security of the underlying server could be damaged. The underlying server itself should be considered as one of trusted origins from the VIAS JavaScript library implementation.

Some part of vehicle data is considered as privacy sensitive and client programs SHOULD treat these data with respect to the user's right. As a privacy protection enforcer, the VIAS implementation MUST obtain user's permission for exposing vehicle data to a client program. If the implementation have an exceptional behavior to treat private information in emergent cases, the behavior also SHOULD be covered by the permission.

5. VISClient Interface

[Constructor,
 Constructor(VISClientOptions options)]
interface VISClient {
  readonly attribute DOMString? host;
  readonly attribute DOMString? protocol;
  readonly attribute unsigned short? port;

  [NewObject] Promise< void> connect();
  [NewObject] Promise< unsigned long> authorize(object tokens);
  [NewObject] Promise< Metadata> getMetadata(DOMString path);
  [NewObject] Promise< VISValue> get(DOMString path);
  [NewObject] Promise< void> set(DOMString path, any value);
  VISSubscription subscribe(DOMString path, SubscriptionCallback subscriptionCallback, ErrorCallback errorCallback,optional  VISSubscribeFilters filters);
  [NewObject] Promise< void> unsubscribe(VISSubscription subscription);
  [NewObject] Promise< void> unsubscribeAll();
  [NewObject] Promise< void> disconnect();
};

dictionary VISClientOptions {
  DOMString? host;
  DOMString? protocol;
  unsigned short? port;
};

dictionary VISValue {
  any value;
  DOMTimeStamp timestamp;
};

dictionary VISError {
  unsigned short number;
  DOMString? reason;
  DOMString? message;
  DOMTimeStamp timestamp;
};

5.1 Constructor

The VISClient interface has two kinds of constructor. One of constructor takes VISClientOptions object as a parameter. In this case (Secure)WebSocket or HTTP(S) protocol is primarily assumed as underlying communication method and to specify in-vehicle data server's host, port and protocol to communicate, the parameterVISClient is used.

In addition, since this specification does not define underlying communication method, other protocols could be employed (e.g. MQTT, COAP, IPC, etc.) Some other protocol may require information not included in VISClientOptions definition. To support such case, VISClientOptions may be extended according to necessities in the future update.

The other constructor does not take a parameter and this assumes a case that a VIAS implementation does not expose communication detail to API users as an abstraction purpose. For this case, scenarios such as "VIAS implementation already has connection information to in-vehicle data server" or "VIAS implementation is integrated with vehicel data souce", could be included.

Example 1
/* Case that no parameter is required. */
const client = new VISClient();

/* Case that VISClientOptions paramter is required. */
const client = new VISClient({'host':'wwwivi', 'protocol':'wss', 'port':443});

5.2 Attributes

Attribute Type Description
host DOMString Readonly, nullable.
The 'host' value configured by constructor argument VISClientOptions.
protocol DOMString Readonly, nullable.
The 'protocol' value configured by constructor argument VISClientOptions.
port unsigned short Readonly, nullable.
The 'port' value configured by constructor argument VISClientOptions.

5.3 Methods

Once created, a VISClient object provides methods shown below for interacting with the server.

Most of the methods listed below require a `path` string to be passed that identifies the target vehicle data items defined in GENIVI VSS. See Metadata interface below for how to generate this string based on traversing the GENIVI VSS data tree.

Method Description Parameters
connect () Initializes the connection with the server.
When a VIAS implementation assumes underlying network as `connectionless` type(e.g. http), establishing connection with this method is not necessary.
In such case, this method can be implemented as an empty function which returns `501 not implemented` error when executed.
This method returns Promise.
authorize (tokens) Request access to signals and data attributes that are under access control.
This method returns Promise.
  • tokens (object) - Tokens provided by authorization authority. Structure of tokens depend on underlying server's specification.
getMetadata (path) Requests a metadata object which matches with specified path.
This method returns Promise.
  • path (DOMString)- a String representing a location within the metadata object tree
get (path) Receives a single value from the server.
This method returns Promise.
  • path (DOMString)- a String representing a location within the metadata object tree
set (path, value) Sends a single value to the server.
This method returns Promise.
  • path (DOMString) - a String representing a location within the metadata object tree
  • value (any) - the value to pass to the server. This must match the type as specified in the VSS.
subscribe (path, subscriptionCallback, errorCallback, filters) subscribes to the given path with the filters provided and returns a VISSubscription as the return value.
After that, continuously returns the value of signals specified by 'path' with timing condition specified in 'filters'.
  • path (DOMString) - a String representing a location within the metadata object tree
  • subscriptionCallback (SubscriptionCallback) - A function called each time subscribed value is notified from the server.
    This function will be passed:
  • errorCallback (ErrorCallback) - A function called when an error relevant to this method has been occurred.
  • filters (VISSubscribeFilters) - applies a server-side filter to data sent. The structure of this option depends on underlying server's specification.
unsubscribe (subscription) Unsubscribe from the subscription passed.
This method returns Promise.
  • subscription (VISSubscription) - the subscription object is obtained from callback function for `subscribe()` method
unsubscribeAll () Unsubscribe all the subscriptions.
This method returns Promise.
disconnect () Closes the connection.
The same VISClient object can be used again by calling the `connect()` method, but subscriptions, authorization, and other state will not persist after a disconnection.
When underlying network is `connectionless` type(e.g. http(s)), use of this method is not necessary.
In such case, this method could be implemented as empty function which returns '501 not implemented' error when executed.
This method returns Promise.

5.4 Callbacks

The following callback functions are defined to be used with methods of VISClient.

callback SubscriptionCallback = void (VISValue value);
callback ErrorCallback = void (VISError error);
Callback Description Parameter Type
SubscriptionCallback A function called each time the data value of subscribed path is notified from the server.
The data value is passed by value parameter.
value VISValue
ErrorCallback A function called when a error occurred in the associated method.
Error information is passed by error parameter.
error VISError

5.5 VISClientOptions Dictionary

VISClientOptions dictionary is designed assuming a connection to a vehicle signal server which is specifiable by protocol, host and port. In case the underlying connection requires other parameters, implementer can add parameters according to the requirement.

Member Type Default Description
host String wwwivi hostname of the server
protocol String wss protocol for the connection to a vehicle signal server. All the communications between the client and server MUST be appropriately encrypted. Therefore, in case of WebSocket, 'wss' is required and in case of http, 'https' is required. Non encrypted communication is not supported.
port Integer 443 TCP port for the connection to a vehicle signal server.

5.6 VISValue Dictionary

VISValue conveys a vehicle signal or attribute value.

Member Type Description
value any The type of 'value' varies according to the target signal or attribute. For detail, refer VSS spec.
timestamp DOMTimeStamp The Coordinated Universal Time (UTC) time that the server returned the response (expressed as number of milliseconds.)

5.7 VISError Dictionary

Error number, reason, message represents both of client-side and server-side error. Server-side error definition depends on underlying server. Client-side error definition is implementation dependent and not defined in this document.

Member Type Description
number unsigned short Error number (error code).
reason DOMString Nullable. Error reason.
message DOMString Nullable. Error message.
timestamp DOMTimeStamp The Coordinated Universal Time (UTC) time that the server returned the response (expressed as number of milliseconds.)

Example

Example 2
const client = new VISClient({
  host: 'wwwivi',
  protocol: 'wss',
  port: 443,
});

client.connect().then( () => {
  console.log(`Connected to ${client.protocol}://${client.host}:${client.port}`);
  return client.authorize(/* TOKEN */);
}).then( (ttl) => {
  console.log(`Authorize succeeded. TTL: ${ttl}`);
}).catch( (err) => {
  console.error(`Error : ${error.number}`);
});

6. VISSubscription Interface

interface VISSubscription {
  readonly attribute DOMString path;
  readonly attribute VISSubscribeFilters? filters;
};

dictionary VISSubscribeFilters {
  unsigned long? interval;
  VISSubscribeRange? range;
  unsigned long? minChange;
};

dictionary VISSubscribeRange {
  long? below;
  long? above;
};

The VISSubscription object is obtained as return value of the subscribe() method. Once created the object can be used to access to the subscribe settings. And also for unsubscribe the subscription, VISSubscription object should be passed to the unsubscribe() method. The Subscription object does not has methods, but just contains the following attributes:

VISSubscriptions are immutable once created.

Attribute Type Description
path DOMString The path String used when creating the Subscription
filters VISSubscribeFilters Nullable
Object containing the filter conditions passed to the subscribe() method. Structure of this object depends on underlying server's specification.
The following attributes are defined for the case of connecting to VIS Server and not mandatory.
  • interval
  • range
  • minChange

6.1 VISSubscribeFilters Dictionary

Parameters in VISSubscribeFilters are originally defined in 'VISS' and this specifiation refers to those definitions.

Member Type Description
interval unsigned long Nullable.
Request to provide data notifications by 'n' milliseconds interval.
This can reduce the server side load if client does not require notifications more frequent than specified interval.
range VISSubscribeRange Nullable.
Request to provide data notifications only when a value satisfies the given conditions.
minChange unsigned long Nullable.
Request to provide data notification when a value has changed by specified minimum change amount.

6.2 VISSubscribeRange Dictionary

Parameters in VISSubscribeRange are originally defined in 'VISS' and this specification refers to those definitions.

Member Type Description
below long Nullable.
Request to provide data notification when a value is below below value.
above long Nullable.
Request to provide data notification when a value is above above value.

Example

Example 3
const client = new VISClient({ host: 'wwwivi' });

client.connect().then( () => {
  const filters = {
    interval: 100,
    range: { above: 100, below: 200 },
    minChange: 50
  };

  let subscription = client.subscribe('body.mirrors.left', (val) => {
    if (val) {
      console.log(`Value received: ${val}`);
    }

    /* ... after some time or some event, unsubscribe from the subscription: */
    client.unsubscribe(subscription).then( () => {
      console.log(`Unsubscribe succeeded`);
    }).catch( (err) => {
      console.error(`Error while unsubscribing: ${err.number}`);
    });
  }, (err) => {
      console.error(`Error while subscribing: ${err.number}`);
  }, filters);
});

7. Metadata Interface

interface Metadata {
  sequence<DOMString> pathsByCSS(DOMString cssSelector);
  boolean pathExistsByCSS(DOMString cssSelector);
  boolean canGet(DOMString path);
  boolean canSet(DOMString path);
  object at(DOMString? path);
};

The Metadata object returned by the getMetadata() method above should provide APIs sufficient to fully traverse the metadata object tree and determine what signals are available at the current permission level.
Although traversing the object tree can be accomplished using any of a number of query languages (i.e. CSS path selectors, XPath, etc.), CSS-based querying API is defined at this time and additional query languages may be added in the future.
It is out of scope here to define the exact traversal methods and feature set and they are left as implementation dependent matter, but these methods SHOULD follow standards protocols such as CSS or XPATH.

Method Description
pathsByCSS (cssSelector) Returns array of paths that match the given selector.
pathExistsByCSS (cssSelector) Returns a boolean as to whether or not there exist any path that matches the given selector.
canGet (path) Returns a boolean as to whether or not the current socket (given the tokens provided up to this point) has permission to read the given path.
canSet (path) Returns a boolean as to whether or not the current socket (given the tokens provided up to this point) has permission to set the given path.
at ([path]) Returns the raw metadata tree object rooted at path (if provided), otherwise returns the entire tree. Regarding raw metadata object definition, refer VSS spec document.

Example

Example 4
const client = new VISClient({
  host: 'wwwivi',
});

client.connect().then( () => {
  return client.getMetadata('Signal.Cabin');
}).then( (metadata) => {
  const paths = metadata.pathsByCSS('Row1 Left Window > Position');
  if (paths.length > 1 && metadata.canSet(paths[0])) {
    return client.set(paths[0], 100); // '100' means window full open
  }
}).then( () => {
  console.log(`Set window ${paths[0]} to open succeeded`);
}).catch( (err) => {
  console.error(`Set window ${paths[0]} to open failed: ${err.number}`);
});

A. References

A.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[VSS]
Vehicle Signal Specification. GENIVI Alliance. March 2017. 1.0. URL: https://github.com/GENIVI/vehicle_signal_specification

A.2 Informative references

[rfc6455]
The WebSocket Protocol. I. Fette; A. Melnikov. IETF. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6455
[vehicle-information-service]
Vehicle Information Service Specification. Kevin Gavigan; Adam Crofts; WonSuk Lee; Powell Kinney. W3C. 13 February 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vehicle-information-service/
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[websockets]
The WebSocket API. Ian Hickson. W3C. 20 September 2012. W3C Candidate Recommendation. URL: https://www.w3.org/TR/websockets/