Vehicle Information API Specification

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

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

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.

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

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.

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