1. Introduction

The vehicle SHALL expose vehicle signals via a WebSocket. This enables a client to GET or SET vehicle signals and data; to SUBSCRIBE to receive notifications and to UNSUBSCRIBE from receiving notifications.

A future revision of this specification may consider additionally exposing vehicle signals via a RESTful web service but this is out of scope for this version of the specification.

The W3C WebSocket API is defined here and the WebSocket Protocol is defined in RFC6455.

A component or module running on the vehicle is required to create a WebSocket and listen for inbound connections from application clients to enable secure access to vehicle signals. In this specification this module are referred to as the ‘WebSocket Vehicle Signal Server’ (WVSS) or for simplicity as ‘the server’.

This specification assumes that a single WebSocket is used to enable communication between the client application and the server in order to reduce processing overhead.

It is not explicitly prohibited for the client to request that the server opens more than one WebSocket. However, the server MAY refuse to open a subsequent WebSocket connection and the client is responsible for handling this gracefully.

If more than one WebSocket connection is established between a Client Application and the server then each connection is managed independently. For example, subscriptions created using a particular WebSocket connection only trigger notifications via that connection and the client must use that WebSocket instance to unsubscribe.

If more than one WebSocket connection has been established between one or more clients and a particular server instance, there is a risk that race conditions and concurrency issues could occur. An example of this would be, where two or more WebSocket connections are used to update a particular setting at the same time.

Unless explicitly stated otherwise, the client can only assume that the server implements a simple concurrency model where lost updates and dirty reads could potentially occur if the server has more than one WebSocket connection open.

The following example illustrates how a client could invoke the API. This simplified example is for illustrative purposes only, it does not show error handling and is not intended to be commercial code.

// open WebSocket
var vehicle  = new WebSocket("wss://wwwivi", "wvss1.0");

// establish authorization
vehicle.onopen = function () {
  vehicle.send('{"action": "authorize",
    "tokens": {"authorization": "<user_token_value>"},
    "requestId": 103}');
};

// request a signal
if (vehicle.readyState === OPEN) {
  vehicle.send('{"action": "get", "path": "Signal.Drivetrain.Transmission.Speed"}');

  // process messages from the server
  vehicle.onmessage = function(event){
    var msg = JSON.parse(event.data);
    if(msg.path == "Signal.Drivetrain.Transmission.Speed" && msg.value){
      console.log("The current speed is " + msg.value);
    }
  };
}

// close the WebSocket
vehicle.close();

The following example shows a JavaScript client subscription request and response.

// set a subscription, assuming the same authorization and set up from Example 1
if (vehicle.readyState === OPEN) {
  vehicle.send('{"action": "subscribe", "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
      "requestId": 104}');
  vehicle.onmessage = function(event){
    var msg = JSON.parse(event.data);
    if(msg.hasOwnProperty("requestId") && msg.requestId == 104){
      console.log("Latest RPM is " + msg.value);
    }
  };
}

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 MAY, MUST, and SHALL are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: specifically the 'in-vehicle' WebSocket Vehicle Signal Server that implements the interfaces, semantics and behaviour defined in this document. For simplicity, this usually is referred to as the 'WebSocket Server' or just 'the server'

3. Terminology

The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API (see here) and the WebSocket Protocol (see RFC6455).

4. Table of Figures

• Fig. 1 Diagram showing Components that implement the W3C Vehicle Signal APIs and their clients
• Fig. 2 Diagram showing an example Vehicle Signal Tree
• Fig. 3 Diagram showing WebSocket Security Token flow

6. Security and Privacy Considerations

Introduction

The server implementation MAY optionally restrict access to one or more vehicle signals so that they can only be accessed in response to a request from an authorized user and/or device. This could be for a variety of reasons, including safety, privacy or commercial considerations.

Hence, a request to GET, SET, SUBSCRIBE or UNSUBSCRIBE to data may require the client to demonstrate to the server that the request is from one or more suitably authorized Security Principals.

The different types of Security Principal, the approach taken to control access to signals and the importance of data privacy are described in the sections that follow.

Security Principals

The types of security principal include:

Access Control and Authorization

When a client makes a request to access signal data it is performing the request on behalf of one or more Security Principals, that is, for a particular user and/or vehicle/device.

Access to signals is managed and controlled by the server. The server MAY elect not to enforce access controls on a particular signal or set of signals and to enforce different access controls on other signals.

For each security principal that must be authorised by the server, the client SHALL obtain and pass a security token e.g. an OAuth 2.0 token (see RFC6749) to the server using a message containing an 'authorize' action as defined here.

A server implementation MAY require that a request for a particular signal includes a security token for both the user (e.g. driver of the vehicle) and for the device (e.g. the vehicle) that is hosting the client. A request for a different set of vehicle signals MAY require that only the user is authorized or that only the device is authorized to access particular signals.

WebSocket Channel Authorization

The client MAY send a message with an 'authorize' action to modify the access-control state of the WebSocket channel. The message structure is defined in detail here.

The following diagram illustrates a scenario where the client requests vehicle speed. In this example scenario, this signal is not under access control and so the server returns a message containing the requested data. The client then requests that the server sets the vehicle trunk status to open and the server demands that the client passes access-control credentials before satisfying the request. The steps are shown in more detail in the diagram below:

After receiving a message with an 'authorize' action the server attempts to verify the tokens e.g. by checking with the issuing Security Authority. If all of the tokens that are passed to the server are valid, it returns a success response and all subsequent requests received by the WebSocket instance have elevated access control privileges. Specifically, each of the GET, SET, SUBSCRIBE and UNSUBSCRIBE actions have the access control rights that the server deems to be appropriate for the security principals represented by the token(s).

If the client sends a subsequent 'authorize' message to the server with different token value(s). If one or more of these are invalid, then the server returns an error response and the WebSocket access control status remain unchanged. However, if the new token values are valid, then the server returns a success response and the access control privileges associated with the new token(s) only, applies for all requests from that point.

If the client or the server close the WebSocket connection and a new WebSocket instance is opened, then it is opened without elevated access control privileges.

This server specification defines a standardized, token based approach for access control that includes specific error responses for common user and device access control scenarios. It is important however, that the security model is extensible. Hence, the server MAY implement any type of token that is consistent with this standardized approach and MAY optionally define additional token(s) for other Security Principal type(s). If this is the case, it is expected that the precise type of security tokens that are supported by a particular server implementation, the format of those tokens and all additional error codes and reasons (e.g. to indicate that an additional token type has expired and needs to be renewed) is defined in the Server's documentation.

Use of Encryption

To support a layered security model and to help establish a 'defence in depth', all vehicle signal communications between the client and server MUST be strongly encrypted. This is to make it more difficult for an attacker to eavesdrop or tamper with the security tokens; the request data or the response payload.

One way in which this may be implemented is for the client and the server to use a Public Key Infrastructure (PKI) approach, where the client verifies the server's identity by checking the server's X.509 certificate and the client and the server negotiate to establish a secure Transport Layer Security (TLS) 'tunnel'.

The WebSocket protocol mandates that if a client requests that the server opens a WebSocket connection and the request is received over HTTPS, then the WebSocket is established over TLS, that is, a secure 'wss' connection is created.

Token Renewal

Each security token SHALL have a specified lifetime during which it is valid. If on receiving a request for signals that are subject to access-control, the server determines that the request is unauthorised because the token has expired, the server returns an error response indicating the fact and the client requests a new token from the Security Authority and repeat the request.

If the server returns an error response indicating that the request is forbidden, renewing the security token does not make the request valid. In this case, the client should not repeat the request unless some other change has been made that may mean the request is now valid.

7. Initialisation of the Web Socket

If the client application is an HTML Application running in a web runtime or is a web page running in a browser, the WebSocket instance may either be instantiated natively or be created using a 'standards compliant' WebSocket JavaScript library.

A WebSocket can also be initiated from a native (e.g. C++) Application or from an Application written using a 'Managed Runtime' language like Java or C#. It is assumed that native and managed clients use a suitable standards compliant WebSocket library to request that a WebSocket connection is opened on the server.

A client running on the vehicle is able to connect to the WebSocket Server instance using the hostname 'wwwivi' and uses the default port 443. The hostname 'wwwivi' may locally be mapped to the localhost IP address 127.0.0.1 e.g. by adding an entry to the /etc/hosts file.

The sub-protocol name always is 'wvss' with a version number suffix, e.g. wvss1.0

    var vehicle  = new WebSocket("wss://wwwivi", "wvss1.0");
  

RESTful web services are out of scope for the first revision of this specification, but could be considered for addition in a later version.

To support ‘defence in depth’ and a layered security approach, connections between clients and servers are strongly encrypted. This is to make it more difficult for an attacker that has succeeded in installing malicious code on a vehicle to eavesdrop, hijack security tokens or impersonate valid security principals in order to get and set sensitive vehicle signals.

The client SHALL connect to the server over HTTPS and request that the server opens a WebSocket. All WebSocket communications between the client and server MUST be over ‘wss’. Non encrypted communication is not supported, hence the server MUST refuse ‘ws’ connection requests.

For security reasons, clients are not able to connect directly to ECUs or to CAN, MOST or LIN networks. All access is via WebSocket. This allows the server to securely control access to vehicle signals.

8. Message Structure

The client MUST use the WebSocket send method, defined here, to pass request messages to the server. The message signature SHALL be:

    WebSocket.send(request)
  

The request message MUST be comprised of one the request objects defined in this section. The client SHALL receive responses from the server using the WebSocket onmessage method, as follows:

    WebSocket.onmessage = function(obj){
      // process data
    }
  

The message returned by the server MUST be one of the response objects defined in the table below.

The request and response parameters contain a limited number of attributes, defined in the table below.

Action

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 'action' name/value pair and the value of the 'action' property MUST be one of the values specified in the enumeration:

enum Action {
    "authorize",
    "getVSS",
    "get",
    "set",
    "subscribe",
    "unsubscribe",
    "unsubscribeAll"
};

Authorize

To enable access to signals and data attributes that are under access control, the client MAY optionally pass a message with an 'authorize' action to the server. The structure of the message and the associated success and error responses are defined below.

interface authorizeRequest {
    attribute Action action;
    attribute string tokens;
    attribute string requestId;
};

interface authorizeSuccessResponse {
    attribute Action action;
    attribute int    TTL;
    attribute string requestId;
};

interface authorizeErrorResponse {
    attribute Action action;
    attribute Error  error;
    attribute string requestId;
};

The server SHALL provide support the following security token types and names:

The 'tokens' JSON fragment MAY contain an 'authorization' structure that contains just a single name/value pair, for example, to pass only the user token. Or it may contain only the 'www-vehicle-device' name/value pair to pass the just the vehicle token; alternatively it MAY include name/value pairs for both the 'authorization' and 'www-vehicle-device' tokens. These alternatives are illustrated in the following example:

if(userTokenOnly){
  // Pass user token only
  vehicle.send('{ "action": "authorize",
    "tokens": { "authorization": "<user_token_value>" },
    "requestId": "<some_unique_value>" }');

} else if (deviceTokenOnly) {
  // Pass vehicle/device token only
  vehicle.send('{ "action": "authorize",
    "tokens": { "www-vehicle-device": "<device_token_value>" },
    "requestId": "<some_unique_value>" }');

} else if (userAndDeviceToken) {
  // Pass tokens for user and device
  vehicle.send('{ "action": "authorize",
    "tokens": { "authorization": "<user_token_value>",
      "www-vehicle-device": "<device_token_value>" },
    "requestId": "<some_unique_value>" }');
}

This specification purposely does not define the token structure and the methods to secure tokens. Providers of the server may choose their own preferred formats and security methods. The server may also treat tokens as opaque structures and pass them on to underlying software layers for evaluation.

While this specification does not mandate the token format and structure it SHALL at least contain the following elements to provide meaningful authorization:

It is expected that client and server use the same token format. If a client presents a token using a format that is not understood by the server, ther server rejects the token.

VSS Request

The client MAY use the 'getVSS' action to request metadata describing the potentially available VSS tree. It does this by sending a 'vssRequest' message to the server. If the server is able to return the VSS metadata, then this is returned using a 'vssSuccessResponse' message. If an error occurs, the server returns a 'vssErrorResponse' message to the client.

The client is able to request VSS metadata from any point in the VSS tree, such that only the metadata for the signals within the given branch of the tree is returned. For example, only metadata for the chassis branch of the tree is returned when the chassis path is specified. If the path is not set, the response contains the metadata for the entire VSS tree.

If more than one 'getVSS' call is made with the same 'vssRequest' message content but at different times, the metadata in the 'vssSuccessResponse' SHALL be the same provided the access-control state of the WebSocket channel has not changed.

interface vssRequest {
    attribute Action  action;
    attribute string? path;
};

interface vssSuccessResponse {
    attribute Action action;
    attribute string path;
    attribute object vss;
};

interface vssErrorResponse {
    attribute Action action;
    attribute string path;
    attribute Error  error;
};

The following data flow example shows a request for the signal structure within the Signal.Body branch containing signals related to the vehicle body.

  client -> {
    "action": "getVSS",
    "path": "Signal.Body",
  }
  receive <- {
    "action": "getVSS",
    "path": "Signal.Body",
    "vss": { },
  }
  

Get

The client MAY send a 'getRequest' message to the server to get the value of one or more vehicle signals and data attributes. If the server is able to satisfy the request it SHALL return a 'getSuccessResponse' message. If the server is unable to fulfil the request, e.g. because the client is not authorised to retrieve one or more of the signals, then the server SHALL return a 'getErrorResponse'. The structure of these message objects is defined below:

interface getRequest {
    attribute Action    action;
    attribute DOMString path;
};

interface getSuccessResponse {
    attribute Action       action;
    attribute DOMString    path;
    attribute any          value;
    attribute DOMTimeStamp timestamp;
};

interface getErrorResponse {
    attribute Action       action;
    attribute DOMString    path;
    attribute Error        error;
    attribute DOMTimeStamp timestamp;
};

It is important to note that all examples involving paths are illustrative. Valid path values and the signals and data attributes that correspond to a particular path are defined in the Vehicle Signal Specification.

The example below shows the JSON structure for a 'getRequest' message sent by the client to obtain the engine RPM value and a 'getSuccessResponse' returned by the server.

  client -> {
    "action": "get",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM"
  }

  receive <- {
    "action": "get",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
    "value": 2372,
    "timestamp": <DOMTimeStamp>
  }
  

In the case where the server returns a value that is a complex type, i.e. a value that is not a single basic JavaScript type (e.g. string, number, boolean), the value SHALL be returned as a set of name/value pairs in a JSON object structure. The format MUST be as defined by the Vehicle Signal Specification.

The following shows an example of a 'getRequest' that results in the server returning a 'getSuccessResponse' with a value that is a complex type:

  client -> {
    "action": "get",
    "path": "Signal.Body.Trunk"
  }

  receive <- {
    "action": "get",
    "path": "Signal.Body.Trunk",
    "value": { "Signal.Body.Trunk.IsLocked": false,
      "Signal.Body.Trunk.IsOpen": true },
    "timestamp": <DOMTimeStamp>
  }
  

One or more wildcards (denoted by asterisk '*') MAY be included at any level in the path to specify that all nodes at that level are to be included.

In the example below, the path in the 'getRequest' includes a wildcard at the levels above the leaf (signal) node, in order to request just the 'IsLocked' state for all doors.

  client -> {
    "action": "get",
    "path": "Signal.Cabin.Door.*.IsLocked"
  }

  receive <- {
    "action": "get",
    "path": "Signal.Cabin.Door.*.IsLocked ",
    "value": [ {"Signal.Cabin.Door.Row1.Right.IsLocked" : true },
               {"Signal.Cabin.Door.Row1.Left.IsLocked" : true },
             {"Signal.Cabin.Door.Row2.Right.IsLocked" : false },
             {"Signal.Cabin.Door.Row2.Left.IsLocked" : true } ],
    "timestamp": <DOMTimeStamp>
  }
  

In this example, a complex type with a nested array is returned in response to the Path: "Signal.Cabin.Door.*" which denotes: 'Return all signals and data attributes for all doors'. For simplicity, the example assumes that the VSS definition for each door only has two attributes 'IsLocked' and 'Window.Position'.

  client -> {
    "action": "get",
    "path": "Signal.Cabin.Door.*"
  }

  receive <- {
    "action": "get",
    "path": "Signal.Cabin.Door.*",
    "value": [ {"Signal.Cabin.Door.Row1.Right.IsLocked" : true, "Signal.Cabin.Door.Row1.Right.Window.Position": 50},
               {"Signal.Cabin.Door.Row1.Left.IsLocked" : true, "Signal.Cabin.Door.Row1.Left.Window.Position": 23},
               {"Signal.Cabin.Door.Row2.Right.IsLocked" : false, "Signal.Cabin.Door.Row2.Right.Window.Position": 100 },
               {"Signal.Cabin.Door.Row2.Left.IsLocked": true, "Signal.Cabin.Door.Row2.Left.Window.Position": 0 } ],
    "timestamp": <DOMTimeStamp>
  }
  

The following shows a request for non-existent data

  client -> {
    "action": "get",
    "path": "Body.Flux.Capacitor"
  }

  receive <- {
    "action": "get",
    "path": "Body.Flux.Capacitor",
    "error": { "number":404,
      "reason": "invalid_path",
      "message": "The specified data path does not exist." },
    "timestamp": <DOMTimeStamp>
  }
  

Set

The client may request that the server sets the value of a signal e.g. to lock a door or open a window by sending a 'setRequest' message to the server. If the server is able to satisfy the request it SHALL return a 'setSuccessResponse' message. If an error occurs e.g. because the client is not authorised to set the requested value, or the value is read-only, the server SHALL return a 'setErrorResponse' message.

interface setRequest {
    attribute Action    action;
    attribute DOMString path;
    attribute any       value;
};

interface setSuccessResponse {
    attribute Action       action;
    attribute DOMString    path;
    attribute any          value;
    attribute DOMTimeStamp timestamp;
};

interface setErrorResponse {
    attribute Action       action;
    attribute DOMString    path;
    attribute Error        error;
    attribute DOMTimeStamp timestamp;
};

Successfully set a signal.

  client -> {
    "action": "set",
    "path": "Signal.Cabin.Door.*.IsLocked",
    "value":{ [ {"Row1.Right.IsLocked" : true },
                {"Row1.Left.IsLocked" : true },
            {"Row2.Right.IsLocked" : true },
            {"Row2.Left.IsLocked" : true } ] }
    }

  receive <- {
    "action": "set",
    "path": " Signal.Cabin.Door.*.IsLocked",
    "value":{ [ {"Signal.Cabin.Door.Row1.Right.IsLocked" : true },
                {"Signal.Cabin.Door.Row1.Left.IsLocked" : true },
            {"Signal.Cabin.Door.Row2.Right.IsLocked" : true },
            {"Signal.Cabin.Door.Row2.Left.IsLocked" : true } ] },
    "timestamp": <DOMTimeStamp>
  }
  

Unsuccessful set. The value cannot be set.

  client -> {
    "action": "set",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
    "value": 2000
  }

  receive <- {
    "action": "set",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
    "error": { "number": 403,
      "reason": "device_forbidden",
      "message": "User is not authorised to set this value"},
    "timestamp": <DOMTimeStamp>
    }
  

Unsuccessful set. The value does not exist in the specified path.

  client -> {
    "action": "set",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
    "value": { "locked" : true }
  }

  receive <- {
    "action": "set",
    "path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
    "error": { "number": 400,
      "reason": "bad_request" ,
      "message": "The server is unable to fulfil the client
          request because the request is malformed."},
      "timestamp": <DOMTimeStamp>
    }
  

Subscribe

Vehicle data subscriptions provide data to the client whenever the signal changes on the server, unless otherwise specified using Server Side Filtering. The server MAY reduce the number of notifications sent to the client in order to reduce processing demands, particularly when the client has subscribed to continuously varying signals.

When the client makes a request to the server to create a new subscription, a JSON data object is returned. This object contains the attributes that were passed to the server to make the subscription and a 'subscriptionId' integer handle value which is used to uniquely identify the subscription.

interface subscribeRequest {
    attribute Action    action;
    attribute DOMString path;
    attribute object?   filters;
    attribute string    requestId;
};

interface subscribeSuccessResponse {
    attribute Action       action;
    attribute string       requestId;
    attribute string       subscriptionId;
    attribute DOMTimeStamp timestamp;
};

interface subscribeErrorResponse {
    attribute DOMString    path;
    attribute string       requestId;
    attribute Error        error;
    attribute DOMTimeStamp timestamp;
};

interface subscriptionNotification {
    attribute string       subscriptionId;
    attribute DOMString    path;
    attribute any          value;
    attribute DOMTimeStamp timestamp;
};

interface subscriptionNotificationError {
    attribute string       subscriptionId;
    attribute DOMString    path;
    attribute object       filters;
    attribute Error        error;
    attribute DOMTimeStamp timestamp;
};

  client -> {
    "action": "subscribe",
    "path": "Signal.Drivetrain.Transmission.TripMeter",
    "requestId": 1004
  }

  receive <- {
    "action": "subscribe",
    "requestId": 1004,
    "subscriptionId": 35472,
    "timestamp": <DOMTimeStamp>
  }
  

  receive <- {
    "subscriptionId": 35472,
    "path": "Signal.Drivetrain.Transmission.TripMeter",
    "value": 36912,
    "timestamp": <DOMTimeStamp>
  }
  

The client can use the 'requestId' value to associate the successful subscription response with the original request.

The 'subscriptionId' value is a unique value, created by the server and which is used internally by the server to manage subscriptions on that WebSocket instance.

The subscription id value may be used by the client to unsubscribe from receiving future notifications, by passing the handle value to the server with the unsubscribe action.

To differentiate subscription response from responses for ‘GET’ requests, subscription responses shall additionally include the subscription id value that identifies the subscription that triggered that notification.

The server ensures that a new unique subscription id value is returned for each successful subscription request on a particular WebSocket connection. However the server does not guarantee that subscription handle values are unique between different WebSocket instances.

Once the subscription is successfully registered with the server, the client receives subscription notifications containing the requested data, at a rate defined either by the server or by the server side filter. If there is an error with an existing subscription a subscriptionNotificationError is received by the client. This allows the client to handle the error, such as to reduce the subscription frequency if the server is unable to satisfy the initial demands of the client.

An example of a subscription can be found here.

Unsubscribe

To unsubscribe from a subscription, the client SHALL send an 'unsubscribeRequest' message to the server. This is comprised of a JSON structure which contains an action property set to 'unsubscribe' and a string containing the 'subscriptionId'. If the server is able to satisfy the request it returns an 'unsubscribeSuccessResponse'. If an error occurs, for example because an invalid subscriptionId is passed to the server, an 'unsubscribeErrorResponse' is returned.

The client MAY unsubscribe from all of its subscriptions by sending an 'unsubscribeRequest' with the action property set to 'unsubscribeAll'. This does not require a subscriptionId value.

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 should always unsubscribe from receiving notifications when it is no longer using the data. Over a long vehicle journey, this significantly reduces the processing load on the server and allow the server to free memory. It therefore makes it more likely that the server remains responsive to future requests from the client.

The 'unsubscribe' message structures are defined below:

interface unsubscribeRequest {
    attribute Action  action;
    attribute string? subscriptionId;
    attribute string  requestId;
};

interface unsubscribeSuccessResponse {
    attribute Action       action;
    attribute string?      subscriptionId;
    attribute string       requestId;
    attribute DOMTimeStamp timestamp;
};

interface unsubscribeErrorResponse {
    attribute Action       action;
    attribute string?      subscriptionId;
    attribute Error        error;
    attribute string       requestId;
    attribute DOMTimeStamp timestamp;
};

  client -> {
    "action": "unsubscribe",
    "subscriptionId": 102,
    "requestId": 5264
  }

  receive <- {
    "action": "unsubscribe",
    "subscriptionId": 102,
    "requestId": 5264,
    "timestamp": <DOMTimeStamp>
  }
  

  client -> {
    "action": "unsubscribeAll",
    "requestId": 3468
  }

  receive <- {
    "action": "unsubscribeAll",
    "subscriptionId": null,
    "requestId": 3468,
    "timestamp": <DOMTimeStamp>
  }
  

  client -> {
    "action": "unsubscribe",
    "subscriptionId": 3542,
    "requestId": 7846
  }
  receive <- {
    "action": "unsubscribe",
    "subscriptionId": 3542,
    "error": { "number":404,
      "reason": "invalid_subscriptionId",
      "message": "The specified subscription was not found." },
    "requestId": 7846,  
    "timestamp": <DOMTimeStamp>
  }
  

// send unsubscribe message
vehicle.send('{ "action": "unsubscribe", "subscriptionId": 102, "requestId": 5429 }');

// set handler
vehicle.onmesssage(function(event){
  var msg = JSON.parse(event.data);
  // success case
  if(msg.hasOwnProperty("requestId") && msg.requestId == 5429){
    console.log("Successfully unsubscribed for id " + msg.subscriptionId);
  // error case
  } else if (msg.hasOwnProperty("error")) {
    console.log("Unsuccessful unsubscribe. " + msg.error.message)
  }
});

9. Server Side Filtering

'Filters' may be specified to enable Server side filtering to be used in order to throttle the demands of subscriptions on the server. This may enable the reduction of traffic if the developer has received a 429 - Too Many Requests error message. This can be implementation dependent allowing a number of potential filtering mechanisms, such as ranges, intervals and minimum changes. This can be implemented using the "filters" option.

Filters can only be applied for nodes in the VSS tree, not entire branches. For example, a filter cannot be set on engine.*, however it can be set on engine.rpm.

The subscription currently defaults to sending values to the client only onchange, however this may cause unnecessary processing demands on the vehicle server. A filter object can be included in the subscription request:

        { "action": "subscribe", "path": "<any_path>",
        	"filters": "{ <insert_custom_tags>  }"
        	"requestId": "<some_unique_value>" }
      

Potential tags could include:

• Interval - requests that the server provides a notification every 'n' milliseconds. This allows the client to reduce the load on the server if the client does not need the data more frequently.
• Range - provide a value only when within a given range
• Minimum change - provide data when a value has changed by a specified amount

If the filter is not set, or is unsupported by the server, the notification frequency is determined by the server.

  //client receives data every 100ms
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "interval": 100 },
        	"requestId": "<some_unique_value>" }

  //client receives data when the value is between 100 and 200 (inclusive)
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "range": { "above": 100, "below": 200 } },
        	"requestId": "<some_unique_value>" }

  //client receives data when the value is below 100 (inclusive)
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "range": { "below": 100 } },
        	"requestId": "<some_unique_value>" }

  //client receives data when the value changes by 100 units
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "minChange": 100 },
        	"requestId": "<some_unique_value>" }

  //client receives data when the value changes by 100 units
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "minChange": 100 },
        	"requestId": "<some_unique_value>" }

  //client receives data when the value is above 200 (inclusive)
  //and the value changes by 20 units
  { "action": "subscribe", "path": "<any_path>",
        	"filters": { "range": { "below": 200 }, "minChange": 20},
        	"requestId": "<some_unique_value>" }
      

When the range filter is used a final message is sent when the value returned is outside of the specified range. For example, if the range states { "below": 100 }, a final value may be received at 101 to indicate that the value is now out of range.

The client should not specify a minimum change amount that is smaller than it needs - in order to prevent adding unnecessary load on the server. The server shall return a '429 - Too Many Request' error response if it is unable to fulfil the request made by the client.

The section that follows defines the error responses that shall be supported by the server.

10. Web Socket Closure

The WebSocket may be closed by either the client or the server by invoking the ‘close()’ method on the WebSocket instance.

The following example shows the lifetime of a WebSocket on the client:

// Open the WebSocket
var vehicle  = new WebSocket("wss://localhost:4343", "wvss1.0");

// WebSocket is used to GET, SET, SUBSCRIBE and UNSUBSCRIBE
…

// Close the WebSocket
vehicle.close();

The WebSocket server may terminate the WebSocket connection if it has not received a request for a period determined by the server. It is the client’s responsibility to handle this gracefully and to recover and request new subscriptions, where required.

11. Errors

If there is an error with any of the client’s requests, the server responds with an error number, reason and message.

interface Error {
    attribute int    number;
    attribute string reason;
    attribute string message;
};

For some error codes, for example '401 (Unauthorised)' there can be more than one cause. The error number that is returned is the HTTP Status Code Number e.g. 401. An error reason is also returned, this contains a pre-defined string value that can be used to distinguish between errors that have the same code (e.g. '401 Unauthorized)' but a difference cause. The error message is used to provide message text describing the cause in more detail.

  client -> { "action": "subscribe",
    "filters": { "<filter_expression>" },
    "path": "<any_vss_path>",
    "requestId": "<some_unique_value>" }
  receive on error <- {
    "error":{ "number": "<error_num>",
      "reason": "<error_reason>",
      "message": "<error_message>" },
    "path": "<any_vss_path>",
    "requestId": "<some_unique_value>" }
  

The server implementation supports at least the error numbers and reasons listed in the table below.

The server may optionally return additional error codes. It is expected that if this is the case, they are defined in the Server Documentation. Wherever possible the Server returns a standard HTTP error code where one has been defined for the error condition. See for example RFC7231, RFC7235, and RFC6585.