The Vehicle Information Service Specification (VISS) is a service for accessing vehicle information, including signals from sensors on control units within a vehicle's network. This information is exposed through a hierarchical, tree-like taxonomy as defined in the COVESA Vehicle Signal Specification (VSS), and is provided in JSON format. The VISS service may be hosted within the vehicle or on external servers, using data that has already been off-boarded.

VISS enables a broad range of use cases, including predictive maintenance, usage-based insurance, fleet management, and real-time driver assistance services. In the context of artificial intelligence, VISS serves as a critical data access layer, providing high-quality, real-time vehicle data that can be utilized by AI algorithms for tasks such as anomaly detection, driver behavior analysis, energy optimization, and contextual decision-making.

This specification describes the third version of VISS, which has been implemented and deployed in production vehicles. The first version of VISS supported only WebSocket as a transport protocol, the second version is generalized to work across different protocols as some are better suited for different use cases. The second version added support for the HTTP and MQTT transport protocols, improved subscription capabilities and added an access control mechanism.

There are three parts to this specification, [[CORE]], [[TRANSPORT]], and PAYLOAD ENCODING. This document, the VISS version 3.0 PAYLOAD ENCODING specification, describes the VISSv3.0 payload encodings that is used in some cases. The companion specifications [[CORE]] describes the messaging layer, and [[TRANSPORT]] describes the deviations form the CORE specification that are used by some transport protocols.

Introduction

This specification describes the payload encodings used by some transport protocols.

Terminology

The acronym 'VISSv3.0' is used to refer to this document, the VISS version 3.0 specification. The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification' which is hosted by COVESA. The term 'WebSocket' when used in this specification, is as defined in the W3C WebSocket API and [[RFC6455]], the WebSocket Protocol.

Transport Payload

The payload primary format is JSON. This means that the payloads received by a client SHALL have the JSON format, unless an implementation deliberately deviates from this. Refer to the [[CORE]] specification for the JSON payload format of the messages for the different transport protocols.

Protobuf encoding

Protocol Buffers (Protobuf) is a language-neutral, platform-neutral, extensible mechanism for serializing structured data, developed by Google. This encoding method is particularly beneficial for efficient data serialization and deserialization, ensuring low latency and reduced payload size, which are crucial for vehicle information services.

The Vehicle Information Service Specification (VISS) defines a standard protocol for accessing vehicle data in a standardized manner. As vehicles become more connected and data-driven, the need for efficient data exchange methods becomes paramount. Protobuf encoding serves as an optimal solution within VISS due to its compact binary format and schema evolution capabilities.

In this section, we outline the integration of Protobuf encoding with VISS version 3.0, providing comprehensive details on schema definitions, encoding and decoding processes, and practical examples. This will enable seamless implementation and interoperability across different systems and platforms within the automotive ecosystem.

Protobuf Schema Definition

The following protobuf schema defines the VISS message payloads. When saved in a file (e.g., named "viss.proto"), the Protobuf compiler (protoc) can be used to create helper functions that can be called to encode and decode between the JSON and Protobuf formats. The protobuf schema below also contains a "service" clause that the protoc compiler uses to create a gRPC based communication framework.

              syntax = "proto3";
              package grpcProtobufMessages;
              
              enum ResponseStatus {
                  SUCCESS = 0;
                  ERROR = 1;
              }
              
              enum SubscribeResponseType {
                  RESPONSE = 0;
                  EVENT = 1;
              }
              
              service VISS {
                rpc GetRequest (GetRequestMessage) returns (GetResponseMessage);
              
                rpc SetRequest (SetRequestMessage) returns (SetResponseMessage);
              
                rpc SubscribeRequest (SubscribeRequestMessage) returns (stream SubscribeStreamMessage);
              
                rpc UnsubscribeRequest (UnsubscribeRequestMessage) returns (UnsubscribeResponseMessage);
              }
              
              message ErrorResponseMessage {
                  string Number = 1;
                  string Reason = 2;
                  string Description = 3;
              }
              
              message FilterExpressions {
                message FilterExpression {
                  enum FilterVariant {
                      PATHS = 0;
                      TIMEBASED = 1;
                      RANGE = 2;
                      CHANGE = 3;
                      CURVELOG = 4;
                      HISTORY = 5;
                      METADATA = 6;
                  }
                  FilterVariant Variant = 1;
              
                  message FilterValue {
                      message PathsValue {
                          repeated string RelativePath = 1;
                      }
                      optional PathsValue ValuePaths = 1;
              
                      message TimebasedValue {
                          string Period = 1;
                      }
                      optional TimebasedValue ValueTimebased = 2;
              
                      message RangeValue {
                          string LogicOperator = 1;
                          string Boundary = 2;
                      }
                      repeated RangeValue ValueRange = 3;
              
                      message ChangeValue {
                          string LogicOperator = 1;
                          string Diff = 2;
                      }
                      optional ChangeValue ValueChange = 4;
              
                      message CurvelogValue {
                          string MaxErr = 1;
                          string BufSize = 2;
                      }
                      optional CurvelogValue ValueCurvelog = 5;
              
                      message HistoryValue {
                          string TimePeriod = 1;  //ISO8601 period expression
                      }
                      optional HistoryValue ValueHistory = 6;
              
                      message MetadataValue {
                          string Tree = 1;
                      }
                      optional MetadataValue ValueMetadata = 7;
                  }
                  FilterValue Value = 2;
                }
                repeated FilterExpression FilterExp = 1;
              }
              
              message DataPackages {
                  message DataPackage {
                      string Path = 1;
              
                      message DataPoint {
                          string Value = 1;
                          string Ts = 2;
                      }
                      repeated DataPoint Dp = 2;
                  }
                  repeated DataPackage Data = 1;
              }
              
              message GetRequestMessage {
                      string Path = 1;
                      optional FilterExpressions Filter = 2;
                      optional string Authorization = 3;
                      optional string DataCompression = 4;
                      optional string RequestId = 5;
              }
              
              message GetResponseMessage {
                      ResponseStatus Status = 1;
                      message SuccessResponseMessage {
                          optional DataPackages DataPack = 1;
                          optional string Metadata = 2; // replaces DataPack in metadata variant
                      }
                      optional SuccessResponseMessage SuccessResponse = 2;
                      optional ErrorResponseMessage ErrorResponse = 3;
                      optional string RequestId = 4;
                      string Ts = 5;
                      optional string Authorization = 6;
              }
              
              message SetRequestMessage {
                      string Path = 1;
                      string Value = 2;
                      optional string Authorization = 3;
                      optional string RequestId = 4;
              }
              
              message SetResponseMessage {
                      ResponseStatus Status = 1;
                      optional ErrorResponseMessage ErrorResponse = 2;
                      optional string RequestId = 3;
                      string Ts = 4;
                      optional string Authorization = 5;
              }
              
              message SubscribeRequestMessage {
                      string Path = 1;
                      optional FilterExpressions Filter = 2;
                      optional string Authorization = 3;
                      optional string DataCompression = 4;
                      string RequestId = 5;
              }
              
              message SubscribeStreamMessage {
                  SubscribeResponseType MType = 1;
                  ResponseStatus Status = 2;
              
                  message SubscribeResponseMessage {
                      optional ErrorResponseMessage ErrorResponse = 1;
                      optional string SubscriptionId = 2;
                      string RequestId = 3;
                      string Ts = 4;
                      optional string Authorization = 5;
                  }
                  optional SubscribeResponseMessage Response = 3;
              
                  message SubscribeEventMessage {
                      string SubscriptionId = 1;
                      message SuccessResponseMessage {
                          DataPackages DataPack = 1;
                      }
                      optional SuccessResponseMessage SuccessResponse = 2;
                      optional ErrorResponseMessage ErrorResponse = 3;
                      string Ts = 4;
                  }
                  optional SubscribeEventMessage Event = 4;
              }
              
              message UnsubscribeRequestMessage {
                      string SubscriptionId = 1;
                      optional string RequestId = 2;
              }
              
              message UnsubscribeResponseMessage {
                      ResponseStatus Status = 1;
                      optional ErrorResponseMessage ErrorResponse = 2;
                      optional string RequestId = 3;
                      string Ts = 4;
              }
            
Protobuf schema file for VISS version 3.0

Transport Protocol Realizations

This part outlines how Protobuf encoding is realized across various transport protocols, including gRPC, WebSocket, and MQTT.

gRPC Realization

The 'service' clause in the Protobuf schema is used by the Protobuf compiler(protoc) to automatically generate code for gRPC-based communication. This generated code simplifies the development of server and client interactions by abstracting the network communication layer, allowing developers to focus on the application logic.

Websocket Realization

If a server supports protobuf payload encoding over the Websocket protocol, it SHALL be shown in the server capabilities data how the client configures this. Two mechanisms are defined:

  • Separate port number. The recommended port number is 6444.
  • A sub-protocol MUST be specified when connecting to the server, The recommended sub-protocol name is "VISS-protoenc".

MQTT Realization

If a server supports protobuf payload encoding over the MQTT protocol, it SHALL be shown in the server capabilities data which topic name that the server uses to listen for clients that want to issue requests with protobuf encoded payloads. The recommended topic name is the topic name used for the unencoded payload channel appended with the string "/protobuf".

Encoding and Decoding with Protobuf

The protobuf compiler uses the protobuf schema to generate an API to helper functions that can be used to implement the encoding and decoding between JSON and the protobuf format for the various VISS messages. The implementation of the encoding and the decoding is out-of-scope for this specification.

JSON schema based encoding

Several Interface Definition Languages (IDLs), such as OpenAPI and AsyncAPI, can utilize a JSON Schema representation as input. The JSON scheme representation of the VISSv3.0 interface in the [[CORE]] specification can be used for such a purpose.