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.

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 produced by a group operating under the W3C Patent Policy.

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]].

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.

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

        /* 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});
        

        callback SubscriptionCallback = void (VISValue value);
        callback ErrorCallback = void (VISError error);
        

Example

        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}`);
        });
      

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.

Example

        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);
        });
      

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.

Example

        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}`);
        });