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)
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 = {
}
WebSocket.onmessage = function(obj){
}
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.
Term
Definitions
|
Attribute
|
Type
|
Description
|
|
action
|
Action
|
The
type
of
action
that
the
server
is
requested
to
perform.
by
the
client
or
delivered
by
the
server.
|
|
path
|
DOMString
String
|
The
path
to
the
desired
vehicle
signal(s),
as
defined
by
the
Vehicle
Signal
Specification
(VSS)
.
|
|
requestId
|
DOMString
String
|
Unique
id
value
specified
by
the
client.
Returned
by
the
server
in
the
response
and
used
by
client
to
link
the
request
and
response
messages.
The
value
MAY
be
an
integer
or
a
Universally
Unique
Identifier
(UUID).
|
|
subscriptionId
|
DOMString
String
|
Value
returned
by
the
server
to
uniquely
identify
each
subscription.
The
value
MAY
be
an
integer
or
a
Universally
Unique
Identifier
(UUID).
|
|
tokens
|
object
|
Structure
containing
one
or
more
security
token
(e.g
OAuth2)
name/value
pairs.
|
|
timestamp
|
DOMTimestamp
integer
|
The
Coordinated
Universal
Time
(UTC)
time
that
the
server
returned
the
response
(expressed
as
number
of
milliseconds).
|
|
value
|
any
|
The
data
value
returned
by
the
server.
This
could
either
be
a
basic
type,
or
a
complex
type
comprised
of
nested
name/value
pairs
in
JSON
format.
|
|
TTL
|
int
integer
|
Returns
the
time
to
live
of
the
authentication
authorization
token
in
milliseconds.
seconds.
|
|
filters
|
object
|
Provides
a
filtering
mechanism
to
reduce
the
demands
of
a
subscription
on
the
server.
|
error
metadata
|
object
|
Metadata
describing
the
potentially
available
signal
tree.
|
error
Error
|
Error
|
Returns
an
error
code,
reason
and
message.
|
JSON
Schema
Definitions
The
definitions
within
this
section
describe
the
datatypes
referenced
within
the
JSON
Schema
VISS
interfaces.
{
"definitions": { "action": { "enum": [ "authorize", "getMetadata", "get", "set", "subscribe", "subscription", "unsubscribe", "unsubscribeAll"], "description": "The type of action requested by the client or delivered by the server",
},
"requestId": { "description": "Returned by the server in the response and used by the client to link the request and response messages.", "type": "string"
},
"path": { "description": "The path to the desired vehicle signal(s), as defined by the metadata schema.", "type": "string"
},
"value": { "description": "The data value returned by the server. This could either be a basic type, or a complex type comprised of nested name/value pairs in JSON format.", "type": "string"
},
"timestamp": { "description": "The Coordinated Universal Time (UTC) time that the server returned the response (expressed as number of milliseconds).", "type": "integer"
},
"filters": { "description": "May be specified in order to throttle the demands of subscriptions on the server.", "type": ["object", "null"], "properties": { "interval": { "description": "The server is requested to provide notifications with a period equal to this field's value.", "type": "integer"
},
"range": { "description": "The server is requested to provide notifications only whilst a value is within a given range.", "type": "object", "properties":{ "below": { "description": "The server is requested to provide notifications when the value is less than or equal to this field's value.", "type": "integer"
},
"above": { "description": "The server is requested to provide notifications when the value is greater than or equal to this field's value.", "type": "integer"
}
}
},
"minChange": { "description": "The subscription will provide notifications when a value has changed by the amount specified in this field.", "type": "integer"
}
}
},
"subscriptionId":{ "description": "Integer handle value which is used to uniquely identify the subscription.", "type": "string"
},
"metadata":{ "description": "Metadata describing the potentially available signal tree.", "type": "object"
},
"error": { "description": "Server response for error cases", "type": "object", "properties": { "number": { "description": "HTTP Status Code Number", "type": "integer"
},
"reason": { "description": "Pre-defined string value that can be used to distinguish between errors that have the same code", "type": "string"
},
"message": { "description": "Message text describing the cause in more detail", "type": "string"
}
}
}
}
}
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:
{
"",
"",
"",
"",
"",
"",
""
};
Enumeration
description
-
authorize
-
Enables
client
to
pass
security
tokens
for
Security
Principals
to
the
server
to
support
access-control.
-
getVSS
getMetadata
-
Allows
the
client
to
request
metadata
describing
signals
and
data
attributes
that
are
potentially
accessible.
-
get
-
Enables
the
client
to
get
a
value
one
or
more
values
once.
-
set
-
Enables
the
client
to
set
a
value
one
or
more
values
once.
-
subscribe
-
Enables
the
client
to
receive
a
notification
request
notifications
containing
a
JSON
data
structure
with
values
for
one
or
more
vehicle
signals
and/or
data
attributes.
The
client
requests
that
it
is
notified
when
the
signal
changes
on
the
server.
-
subscription
-
Enables
the
server
to
send
notifications
to
the
client
containing
a
JSON
data
structure
with
values
for
one
or
more
vehicle
signals
and/or
data
attributes.
-
unsubscribe
-
Allows
the
client
to
notify
the
server
that
it
should
no
longer
receive
notifications
based
on
that
subscription.
-
unsubscribeAll
-
Allows
the
client
to
notify
the
server
that
it
should
no
longer
receive
notifications
for
any
active
subscription.
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.
{
};
Authorize
Request
Properties
The
properties
and
schema
for
an
authorizeRequest
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Authorize Request", "description": "Enables the user to set access controls for the vehicle signals", "type": "object", "required": ["action", "tokens", "requestId"], "properties": { "action": { "enum": [ "authorize" ], "description": "The identifier for the authorize request"
},
"tokens": { "description": "Extensible key-value pair token mechanism used for access control", "type": "object", "properties": { "authorization": { "description": "The user token, for the user that the client is making requests on behalf of", "type": "string"
},
"www-vehicle-device": { "description": "The device token for the originating device that is making the request to the server", "type": "string"
}
}
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
an
authorizeSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Authorize Success Response", "description": "The response sent from the server upon a successful authorization request", "type": "object", "required": ["action", "TTL", "requestId"], "properties": { "action": { "enum": [ "authorize" ], "description": "The identifier for the authorize request",
},
"TTL": { "description": "The time to live of the authorization token", "type": "integer"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
an
authorizeErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Authorize Error Response", "description": "The response sent from the server upon an unsuccessful authorization request", "type": "object", "required": ["action", "error", "requestId"], "properties": { "action": { "enum": [ "authorize" ], "description": "The identifier for the authorize request",
},
"error": { "$ref": "#/definitions/error"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
server
SHALL
provide
support
the
following
security
token
types
and
names:
|
Security Principal
|
Token
Name
|
Description
|
|
User
|
authorization
|
The
user
that
the
client
is
making
requests
on
behalf
of.
This
MAY
be
a
person
e.g.
driver
or
passenger,
it
MAY
be
an
organisation
e.g.
Emergency
Services
or
MAY
be
any
other
legal
entity.
|
|
Device
|
www-vehicle-device
|
The
originating
device
that
is
making
the
request
to
the
server.
This
MAY
be
an
ECU
in
the
vehicle
that
is
hosting
the
WebSocket
VIS
Server
or
MAY
be
a
device
that
is
connected
to
the
vehicle
via
a
WiFi
hotspot
or
MAY
be
any
other
device.
|
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:
Example
3
4
(userTokenOnly){
// Pass user token only
vehicle.send('{ "action": "authorize",
"tokens": { "authorization": "<user_token_value>" },
"requestId": "<some_unique_value>" }');
if(userTokenOnly){
// Pass user token only
vehicle.send('{ "action": "authorize",
"tokens": { "authorization": "<user_token_value>" },
"requestId": "<some_unique_value>" }');
} (deviceTokenOnly) {
// Pass vehicle/device token only
vehicle.send('{ "action": "authorize",
"tokens": { "www-vehicle-device": "<device_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>" }');
} (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>" }');
} 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.
obtain
token(s).
Providers
of
the
server
implementation
may
choose
select
their
own
preferred
formats
token
format
and
security
methods.
method
for
verifying
the
authenticity
of
token(s)
passed
to
the
server.
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:
Element
Description
Path
The
signal
path
(defined
here
)
the
token
authorizes.
The
path
may
be
a
branch
name
or
contain
wildcards
to
authorize
entire
branches.
Actions
List
of
actions
that
the
token
authorizes
for
the
path.
The
list
contains
at
least
one
of
the
actions
getVSS
,
get
,
set
,
subscribe
and
unsubscribe
.
Valid
From
Timestamp
in
UTC
indicating
the
date
and
time
from
which
on
the
token
is
valid.
Valid
Until
Tmestamp
in
UTC
indicating
the
date
and
time
until
which
the
token
is
valid.
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
the
server
rejects
the
token.
VSS
In
order
to
make
dictionary
attacks
more
difficult,
authentication
will
be
denied
after
a
number
of
failed
authentication
requests.
A
401
(Unauthorized)
too_many_requests
error
will
be
sent
by
the
server
in
response
to
any
subsequent
authentication
requests.
The
number
of
failed
requests
and
the
period
of
time
during
which
attempts
will
be
denied
is
to
be
determined
by
the
implementation.
The
client
MAY
use
the
'getVSS'
'getMetadata'
action
to
request
metadata
describing
the
potentially
available
signal
schema,
for
example
the
VSS
tree.
It
does
this
by
sending
a
'vssRequest'
'metadataRequest'
message
to
the
server.
If
the
server
is
able
to
return
the
VSS
metadata,
then
this
is
returned
using
a
'vssSuccessResponse'
'metadataSuccessResponse'
message.
If
an
error
occurs,
the
server
returns
a
'vssErrorResponse'
'metadataErrorResponse'
message
to
the
client.
The
client
is
able
to
request
VSS
metadata
from
any
point
in
the
VSS
signal
tree,
such
that
only
the
metadata
for
the
signals
within
the
given
branch
of
the
tree
schema's
hierachy
is
returned.
For
example,
only
metadata
for
the
chassis
branch
of
the
VSS
tree
is
returned
when
the
chassis
path
is
specified.
If
the
path
is
not
set,
the
response
contains
the
metadata
for
the
entire
VSS
signal
tree.
If
more
than
one
'getVSS'
'getMetadata'
call
is
made
with
the
same
'vssRequest'
'metadataRequest'
message
content
but
at
different
times,
the
metadata
in
the
'vssSuccessResponse'
'metadataSuccessResponse'
SHALL
be
the
same
provided
the
access-control
state
of
the
WebSocket
channel
has
not
changed.
{
};
The
Vehicle
Signal
Server
(VSS)
specification
allows
branches
to
be
defined
as
either
public
or
private.
The
VIS
server
will
satisfy
a
request
for
metadata
in
a
public
branch
regardless
of
the
access
control
permissions
associated
with
the
client
making
the
request.
This
means
that
a
user
could
see
that
a
particular
signal
in
a
public
branch
is
available
but
they
may
not
be
currently
authorised
to
Get,
Set,
or
Subscribe
to
that
signal.
If
a
branch
is
defined
to
be
'private',
only
suitably
authorised
clients
will
be
able
to
retrieve
metadata
for
that
branch.
This
is
to
enable
vehicle
manufacturers
to
apply
access
controls
to
metadata
for
commercially
sensitive
signals
and
data.
If
a
signal
is
requested
to
which
the
client
has
no
access
then
the
server
will
reject
the
request
as
detailed
by
the
Get,
Set,
and
Subscribe
sections
of
this
specification.
The
server
shall
only
return
metadata
for
the
branches
and
nodes
which
are
classified
as
"Private"
branch
unless
the
client
has
appropriate
access
permissions.
Other
data
models
may
also
operate
similar
mechanisms.
The
properties
and
schema
for
a
metadataRequest
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Metadata Request", "description": "Request metadata describing the potentially available signals", "type": "object", "required": ["action", "path", "requestId"], "properties": { "action": { "enum": [ "getMetadata" ], "description": "The identifier for the getMetadata request"
},
"path": { "$ref": "#/definitions/path"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
a
metadataSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Metadata Success Response", "description": "The response sent from the server upon a successful getMetadata request", "type": "object", "required": ["action", "requestId", "metadata", "timestamp"], "properties": { "action": { "enum": [ "getMetadata" ], "description": "The identifier for the getMetadata request"
},
"requestId": { "$ref": "#/definitions/requestId"
},
"metadata": { "$ref": "#/definitions/metadata"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
metadataErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Metadata Error Response", "description": "The response sent from the server upon an unsuccessful getMetadata request", "type": "object", "required": ["action", "requestId", "error", "timestamp"], "properties": { "action": { "enum": [ "getMetadata" ], "description": "The identifier for the getMetadata request"
},
"requestId": { "$ref": "#/definitions/requestId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Examples
The
following
data
flow
example
shows
a
request
for
the
signal
structure
within
the
Signal.Body
Signal.Drivetrain.InternalCombustionEngine.RPM
branch
containing
signals
related
to
the
vehicle
body.
RPM
signal,
where
the
metadata
is
defined
using
a
VSS
tree.
A
leaf
node
has
been
chosen
in
this
example
for
brevity,
however
entire
VSS
branches
and
other
schemas
can
also
be
requested
using
the
getMetadata
interface.
client -> {
,
,
"action": "getMetadata",
"path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
"requestId": "3874"
}
receive <- {
,
,
: { },
"action": "getMetadata",
"requestId": "3874",
"metadata": { "Signal": {
"description": "All signals that can dynamically be updated by the vehicle",
"type": "branch",
"children": {
"Drivetrain": {
"description": "Drivetrain data for internal combustion engines, transmissions, electric motors, etc.",
"type": "branch",
"children": {
"InternalCombustionEngine": {
"description": "Engine-specific data, stopping at the bell housing.",
"type": "branch",
"children": {
"RPM": {
"description": "Engine speed measured as rotations per minute.",
"min": 0,
"max": 20000,
"type": "UInt16",
"id": 54,
"unit": "rpm"
}
}
}
}
}
}
}
},
"timestamp": 1496087968995
}
The
following
data
flow
example
shows
a
request
for
the
VSS
structure
within
the
Attribute.Body
branch
of
the
VSS.
The
example
assumes
the
VSS
contains
two
leaf
nodes
within
the
Attribute.Body
branch.
client -> {
"action": "getMetadata", "path": "Attribute.Body", "requestId": "3875"
}
receive <- {
"action": "getMetadata", "requestId": "3875", "metadata": { "Attribute": { "description": "Attribute signals that do not change during the power cycle of a vehicle.", "type": "branch", "children": { "Body": { "description": "All body components", "type": "branch", "children": { "BodyType": { "description": "Body type code as defined by ISO 3779", "type": "string"
},
"RefuelPosition": { "description": "Location of the fuel cap or charge port", "type": "string", "enum": ["front_left", "front_right", "middle_left", "middle_right", "rear_left", "rear_right"]
}
}
}
}
}
},
"timestamp": 1489985044000
}
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
authorized
to
retrieve
one
or
more
of
the
signals,
then
the
server
SHALL
return
a
'getErrorResponse'.
The
structure
of
these
message
objects
is
defined
below:
{
};
Get
Request
Properties
The
properties
and
schema
for
a
getRequest
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Get Request", "description": "Get the value of one or more vehicle signals and data attributes", "type": "object", "required": ["action", "path", "requestId"], "properties": { "action": { "enum": [ "get" ], "description": "The identifier for the get request",
},
"path": { "$ref": "#/definitions/path"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
a
getSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Get Success Response", "description": "The response sent from the server upon a successful get request", "type": "object", "required": ["action", "requestId", "value", "timestamp"], "properties": { "action": { "enum": [ "get" ], "description": "The identifier for the get request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"value": { "$ref": "#/definitions/value"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
getErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Get Error Response", "description": "The response sent from the server upon an unsuccessful get request", "type": "object", "required": ["action", "requestId", "error", "timestamp"], "properties": { "action": { "enum": [ "get" ], "description": "The identifier for the get request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Examples
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 -> {
,
}
client -> {
"action": "get", "path": "Signal.Drivetrain.InternalCombustionEngine.RPM", "requestId": "8756"
}
receive <- {
,
,
,
}
receive <- {
"action": "get", "requestId": "8756", "value": 2372, "timestamp": 1489985044000
}
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),
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
version
of
the
Vehicle
Signal
Specification.
Specification
that
is
associated
with
the
WebSocket
sub-protocol
value
specified
when
the
WebSocket
is
created.
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 -> {
,
}
client -> {
"action": "get", "path": "Signal.Body.Trunk", "requestId": "9078"
}
receive <- {
,
,
,
},
}
receive <- {
"action": "get", "requestId": "9078", "value": { "Signal.Body.Trunk.IsLocked": false, "Signal.Body.Trunk.IsOpen": true }, "timestamp": 1489985044000
}
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 -> {
,
}
client -> {
"action": "get", "path": "Signal.Cabin.Door.*.IsLocked", "requestId": "4523"
}
receive <- {
,
,
},
{ },
{ },
{ } ],
}
receive <- {
"action": "get", "requestId": "4523", "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": 1489985044000
}
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 -> {
,
}
client -> {
"action": "get", "path": "Signal.Cabin.Door.*", "requestId": "6745"
}
receive <- {
,
,
},
{},
{ },
{ } ],
}
receive <- {
"action": "get", "requestId": "6745", "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": 1489985044000
}
The
following
shows
a
request
for
non-existent
data
client -> {
,
}
client -> {
"action": "get", "path": "Body.Flux.Capacitor", "requestId": "1245"
}
receive <- {
,
,
,
,
},
}
receive <- {
"action": "get", "requestId": "1245", "error": { "number":404, "reason": "invalid_path", "message": "The specified data path does not exist." }, "timestamp": 1489985044000
}
Set
The
client
may
request
that
the
server
sets
the
value
of
a
signal
one
or
more
signals
e.g.
to
lock
a
door
one
or
more
doors
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
authorized
to
set
the
requested
value,
or
the
value
is
read-only,
the
server
SHALL
return
a
'setErrorResponse'
message.
{
};
The
properties
and
schema
for
a
setRequest
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Set Request", "description": "Enables the client to set one or more values once.", "type": "object", "required": ["action", "path", "value", "requestId"], "properties": { "action": { "enum": [ "set" ], "description": "The identifier for the set request",
},
"path": { "$ref": "#/definitions/path"
},
"value": { "$ref": "#/definitions/value"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
a
setSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Set Success Response", "description": "The response sent from the server upon a successful set request", "type": "object", "required": ["action", "requestId", "timestamp"], "properties": { "action": { "enum": [ "set" ], "description": "The identifier for the set request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
setErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Set Error Response", "description": "The response sent from the server upon an unsuccessful set request", "type": "object", "required": ["action", "requestId", "error", "timestamp"], "properties": { "action": { "enum": [ "set" ], "description": "The identifier for the set request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Examples
Successfully
set
a
signal.
client -> {
,
,
},
{ },
{ },
{ } ] }
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 } ],
"requestId": "5689"
}
receive <- {
,
,
},
{ },
{ },
{ } ] },
}
receive <- {
"action": "set", "requestId": "5689", "timestamp": 1489985044000
}
Unsuccessful
set.
The
value
cannot
be
set.
client -> {
,
,
}
client -> {
"action": "set", "path": "Signal.Drivetrain.InternalCombustionEngine.RPM", "value": 2000, "requestId": "8912"
}
receive <- {
,
,
,
,
},
receive <- {
"action": "set", "requestId": "8912", "error": { "number": 401, "reason": "read_only", "message": "The desired signal cannot be set since it is a read only signal"}, "timestamp": 1489985044000
}
Unsuccessful
set.
The
value
does
not
exist
in
the
specified
path.
client -> {
,
,
}
}
receive <- {
,
,
,
,
"The server is unable to fulfil the client
request because the request is malformed."},
client -> {
"action": "set",
"path": "Signal.Drivetrain.InternalCombustionEngine.RPM",
"value": { "locked" : true }
"requestId": "2311"
}
receive <- {
"action": "set",
"requestId": "2311",
"error": { "number": 400,
"reason": "bad_request" ,
"message": "The server is unable to fulfil the client
request because the request is malformed."},
"timestamp": 1489985044000
}
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.
{
};
Subscribe
Request
Properties
The
properties
and
schema
for
a
subscribeRequest
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Subscribe Request", "description": "Allows the client to subscribe to time-varying signal notifications on the server.", "type": "object", "required": ["action", "path", "requestId"], "properties": { "action": { "enum": [ "subscribe" ], "description": "The identifier for the subscription request"
},
"path": { "$ref": "#/definitions/path"
},
"filters": { "$ref": "#/definitions/filters"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
The
properties
and
schema
for
a
subscribeSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Subscribe Success Response", "description": "The response sent from the server upon a successful subscription request", "type": "object", "required": ["action", "requestId", "subscriptionId", "timestamp"], "properties": { "action": { "enum": [ "subscribe" ], "description": "The identifier for the subscription request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
subscribeErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Subscribe Error Response", "description": "The response sent from the server upon an unsuccessful subscribe request", "type": "object", "required": ["action", "requestId", "error", "timestamp"], "properties": { "action": { "enum": [ "subscribe" ], "description": "The identifier for the subscription request",
},
"requestId": { "$ref": "#/definitions/requestId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
subscriptionNotification
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Subscription Notification", "description": "Notification sent from the server to provide the requested data to the client", "type": "object", "required": ["action", "subscriptionId", "value", "timestamp"], "properties": { "action": { "enum": [ "subscription" ], "description": "The identifier for the subscription notification",
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"value": { "$ref": "#/definitions/value"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
The
properties
and
schema
for
a
subscriptionNotificationError
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Subscription Notification Error", "description": "Error message sent by the server when there is an error with an existing subscription", "type": "object", "required": ["action", "subscriptionId", "error", "timestamp"], "properties": { "action": { "enum": [ "subscription" ], "description": "The identifier for the subscription notification",
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Examples
For
example
when
a
client
need
wishes
to
subscribe
to
continuously
receive
"Signal.Drivetrain.Transmission.TripMeter"
information
from
the
server,
it
can
use
the
"subscribe"
action
with
the
target
path
property
like
below.
client -> {
,
,
}
set
as
follows:
client -> {
"action": "subscribe", "path": "Signal.Drivetrain.Transmission.TripMeter", "requestId": "1004"
}
receive <- {
,
,
,
}
receive <- {
"action": "subscribe", "requestId": "1004", "subscriptionId": "35472", "timestamp": 1489985044000
}
When
this
This
example
is
for
illustrative
purposes
only,
it
MAY
or
MAY
NOT
be
the
case
that
the
version
of
the
Vehicle
Server
Specification
implemented
by
the
VIS
Server
includes
the
example
path
'Signal.Drivetrain.Transmission.TripMeter'.
If
the
"subscribe"
request
has
been
successed,
client
is
successful
the
server
will
receive
return
a
notificaton
with
changing
value
continuously
subscribeSuccessResponse
as
below
JSON
structure.
receive <- {
,
,
,
}
The
client
can
use
shown
in
the
'requestId'
value
to
associate
example
above,
and
the
successful
client
will
then
start
to
receive
subscription
response
with
notifications
like
the
original
request.
one
illustrated
in
the
following
JSON
structure:
receive <- {
"action": "subscription", "subscriptionId": "35472", "value": 36912, "timestamp": 1489985044000
}
The
'subscriptionId'
value
is
a
unique
value,
created
by
the
server
and
which
is
may
be
used
internally
by
the
server
to
manage
subscriptions
on
that
WebSocket
instance.
The
subscription
id
subscriptionId
value
may
also
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
subscriptionId
value
that
identifies
the
subscription
that
triggered
that
notification.
The
server
ensures
that
a
new
unique
subscription
id
subscriptionId
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
SHALL
be
sent
to
the
client.
This
allows
the
client
to
handle
the
error,
such
as
for
example
by
modifying
the
filter
condition
to
reduce
the
requested
notification
frequency.
If
the
authentication
token
expires
whilst
a
subscription
frequency
if
is
active,
the
server
will
send
a
subscriptionNotificationError
for
each
subscription
that
can
no
longer
be
fulfilled.
The
client
is
unable
then
responsible
for
communicating
with
the
relevant
Security
Authority
to
satisfy
renew
the
initial
demands
authentication
token.
After
the
client
authentication
token
has
expired,
the
server
MAY
continue
to
send
notifications
for
data
that
is
not
subject
to
access
control
restrictions.
The
client
will
NOT
receive
notifications
for
subscriptions
that
require
a
valid
authentication
token
until
the
client
sends
a
renewed
authentication
token
to
the
server.
If
a
new
authentication
token
is
presented
by
the
client
to
the
server
in
a
timely
manner,
all
existing
subscriptions
will
continue
to
cause
notifications
to
be
sent
from
the
server,
provided
the
security
principal(s)
have
not
changed.
The
time
window
during
which
the
client
MAY
re-authenticate
and
subscriptions
continue
WILL
be
implementation
dependent.
If
the
server
has
terminated
any
subscriptions,
it
is
the
responsibility
of
the
client
to
renew
them.
At
any
time
the
server
MUST
only
send
subscription
notifications
for
data
that
the
client
is
authorized
to
access.
The
server
MAY
close
the
WebSocket
connection
at
any
time
and
in
so
doing,
terminate
all
subscriptions
for
the
client.
The
client
is
then
responsible
for
renewing
subscriptions.
The
client
MUST
close
the
WebSocket
connection
if
the
server
data
is
no
longer
required.
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.
It
is
not
possible
to
unsubscribe
from
a
subset
of
signals
within
a
subscription.
The
client
must
unsubscribe
and
set
up
a
new
subscription
to
receive
notifications
for
the
desired
signals.
For
example,
if
there
is
an
active
subscription
for
all
lights,
using
the
path
Signal.Body.Lights.*,
and
the
client
requires
information
for
only
Signal.Body.Lights.IsLowBeamOn,
the
client
will
have
to
unsubscribe
from
the
Signal.Body.Lights.*
subscription
and
re-subscribe
to
Signal.Body.Lights.IsLowBeamOn.
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
will
remain
responsive
to
future
requests
from
the
client.
Unsubscribe
Request
Properties
The
'unsubscribe'
message
structures
are
defined
below:
properties
and
schema
for
a
unsubscribeRequest
is:
{
};
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Unsubscribe Request", "description": "Allows the client to unsubscribe to time-varying signal notifications on the server.", "type": "object", "required": ["action", "subscriptionId", "requestId"], "properties": { "action": { "enum": [ "unsubscribe" ], "description": "The identifier for the unsubscribe request"
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"requestId": { "$ref": "#/definitions/requestId"
}
}
}
Unsubscribe
from
The
properties
and
schema
for
a
single
subscription.
client -> {
,
,
}
unsubscribeSuccessResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Unsubscribe Success Response", "description": "The response sent from the server upon a successful unsubscribe request", "type": "object", "required": ["action", "subscriptionId", "requestId", "timestamp"], "properties": { "action": { "enum": [ "unsubscribe" ], "description": "The identifier for the unsubscribe request"
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"requestId": { "$ref": "#/definitions/requestId"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Unsubscribe
The
properties
and
schema
for
a
unsubscribeErrorResponse
is:
{
"$schema": "http://json-schema.org/draft-04/schema#", "title": "Unsubscribe Error Response", "description": "The response sent from the server upon an unsuccessful unsubscribe request", "type": "object", "required": ["action", "subscriptionId", "requestId", "error", "timestamp"], "properties": { "action": { "enum": [ "unsubscribe" ], "description": "The identifier for the subscription request"
},
"subscriptionId": { "$ref": "#/definitions/subscriptionId"
},
"requestId": { "$ref": "#/definitions/requestId"
},
"error": { "$ref": "#/definitions/error"
},
"timestamp": { "$ref": "#/definitions/timestamp"
}
}
}
Examples
The
example
below
shows
the
JSON
message
structure
for
a
'unsubscribeRequest'
and
'unsubscribeSuccessResponse'
to
unsubscribe
from
all
subscriptions.
client -> {
,
}
a
single
subscription.
client -> {
"action": "unsubscribe", "subscriptionId": "102", "requestId": "5264"
}
receive <- {
,
,
,
}
receive <- {
"action": "unsubscribe", "subscriptionId": "102", "requestId": "5264", "timestamp": 1489985044000
}
Error
The
following
shows
an
example
of
error
case
-
with
invalid
ID
client -> {
,
,
}
receive <- {
,
,
,
,
},
,
}
susbscriptionId.
client -> {
"action": "unsubscribe", "subscriptionId": "3542", "requestId": "7846"
}
receive <- {
"action": "unsubscribe", "subscriptionId": "3542", "requestId": "7846", "error": { "number":404, "reason": "invalid_subscriptionId", "message": "The specified subscription was not found." }, "timestamp": 1489985044000
}
Example
4
5
vehicle.send();
vehicle.send('{ "action": "unsubscribe", "subscriptionId": "102", "requestId": "5429" }');
vehicle.onmesssage(function(event){
.parse(event.data);
){
+ msg.subscriptionId);
} )) {
+ msg.error.message)
}
var msg = JSON.parse(event.data);
if(msg.hasOwnProperty("requestId") && msg.requestId == "5429"){
console.log("Successfully unsubscribed for id " + msg.subscriptionId);
} else if (msg.hasOwnProperty("error")) {
console.log("Unsuccessful unsubscribe. " + msg.error.message)
}
});
