The Vehicle API (VAPI) specification defines an interface for access to vehicle data and services. This access is realized by exposing a procedure-based interface to clients of it. For vehicle services there i a one-to-one mapping between a service and a procedure. For data there are a set of reserved procedure signatures that are used to realize the data access. This specification is agnostic to the connectivity solution that is used in implementations of it. A client may be deployed in-vehicle, but may also be deployed off-vehicle. These details are abstracted in the interface and dealt with in the implementation of the interface.
This specification defines an interface for access to access to vehicle data based both on a signal based abstraction model and a service based abstraction model.
The acronym 'VAPIv1.0' is used to refer to this document, the VAPI version 1.0 specification.
The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification'
which is hosted by COVESA.
The acronym 'HIM' is used to refer to the 'Hierarchical Information Specification'
which is hosted by COVESA.
The acronym 'VISS' is used to refer to the 'Vehicle Information Service Specification'
which is hosted by COVESA.
The acronym 'CVIS' is used to refer to the
'Commercial Vehicle Information Specifications' which is hosted by COVESA.
VAPI procedures are characterized as belonging to one of the groups Common, Data, or Service.
The common procedures are used for common tasks that are not related specifically to either the data or the service groups.
Provides a vehicle reference and connectivity info for a specified vehicle.
This procedure tries to retrieve connectivity data for the vehicle that is associated with the input vehicle globally unique identity. This identity may be a pseudo-VIN that has been derived from the vehicle VIN. How the client has obtained this identity is out-of-scope for this specification. If it succeeds it will return a vehicle Id that shall be used as input in the procedures that require a vehicle Id, and data about which protocols that are available for connecting to it.
GetVehicle(vehicleGuid: string): GetVehicleOutput
GetVehicleOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
VehicleId: uint32,
Protocol: []string
}
Struct member descriptions:Disconnects communication setup with a vehicle.
This procedure terminates a vehicle communication session for all protocols.
ReleaseVehicle(vehicleId: uint32): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:Sets up a connectivity session with a vehicle.
This procedure sets up a connection with the vehicle over the specified protocol. It must be called for any session-based protocol before invoking any service over it.
Connect(vehicleId: uint32, protocol: string, clientCredentials: string): ConnectOutput
ConnectOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
LtCredential: string
}
Struct member descriptions:Disconnects a vehicle communication session.
This procedure terminates a vehicle communication session for a specified protocol. If communication sessions over other protocols are ongoing, these are unaffected by the call.
Disconnect(vehicleId: uint32, protocol: string): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:Selects the default protocol.
This procedure selects which protocol that shall be the default protocol, i. e. the protocol that VAPI procedures that involve sending requests to the vehicle will then use. A successful Connect call for the protocol must have preceeded the SelectProtocol call.
SelectProtocol(vehicleId: uint32, protocol: string): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:Cancels an ongoing service.
This procedure terminates an ongoing service call associated with the provided serviceId. The service is terminated successfully in its current state, unless the underlying vehicle system responds to this state as an error.
CancelService(vehicleId: uint32, serviceId: uint23): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:Inquiry to a vehicle about auxillary services that it supports.
This procedure inquires a vehicle about any auxillary services that it supports. These services can then be called by calling the Invoke procedure.
ServiceInquiry(vehicleId: uint32): ServiceInquiryOutput
ServiceInquiryOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Service: []ServiceSignature
}
Struct member descriptions:Get the vehicle short term credentials.
This procedure is used by the client to obtain the short term credentials that can be used to access vehicle signals/services for a specific use case / purpose.
GetStCredentials(vehicleId: uint32, ltCredentials: string, purpose: string): GetStCredentialsOutput
GetStCredentialsOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
StCredentials: string
}
Struct member descriptions:The Invoke procedure is used to call auxillary services that are not part of the VAPI specification.
If a service that is not part of the VAPI specification has been installed in the vehicle then information about it shall be accessible to the client by calling either the ServiceInquiry or the GetMetadata procedure.
Invoke(vehicleId: uint32, serviceName: string, procedureInput: string, stCredentials: string, callback: *fcn(InvokeOutput): InvokeOutput
{
"parameterName1": "value1",
"parameterName2": "value2"
}
An empty string represents the case with a service having no input parameters.
InvokeOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
ServiceOutput: string,
ServiceId: uint32
}
Struct member descriptions:GetMetadata is used to get the metadata that defines a signal or service.
GetMetadata retrieves the metadata from the subtree with the root node that the input path points to. The subtree can contain either signal metadata or service metadata.
GetMetadata(vehicleId: uint32, path: string, stCredentials: string): GetMetadataOutput
GetMetadataOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Metadata: string
}
Struct member descriptions:The data procedures provide access to vehicle signals using a "service agnostic" API consisting of the procedures:
Get the value of one or more signals.
This procedure retrieves the latest available value with associated timestamp of the signal that is referenced by the input path.
It is possible to reference multiple signals in one call.
This procedure supports multiple execution instances.
Get(vehicleId: uint32, path: string, filter: string, stCredentials: string): GetOutput
GetOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Data: []DataContainer
}
Struct member descriptions:Set the value of a signal.
This procedure changes the state of the actuator so that its associated signal becomes set to the value provided. This change may be instantaneous or it may take an undefined period of time. In the latter case the returned Status only represent the outcome of providing the value to the underlying vehicle system.
Set(vehicleId: uint32, path: string, value: string, stCredentials: string): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:Subscribe to receiving event messages containing one or more signals.
Subscribe initiates a session in which the values of one or more signals are asynchronously returned depending on the event trigger condition.
It is possible to reference multiple signals in one call.
The subscription session will continue until either an Unsubscribe call is issued, or that an error occurs.
Subscribe(vehicleId: uint32, path: string, filter: string, stCredentials: string, callback: *fcn(SubscribeOutput): SubscribeOutput
SubscribeOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Data: []DataContainer,
ServiceId: uint32
}
Struct member descriptions:Unsubscribe to an ongoing subscription session.
This procedure unsubscribes to an ongoing subscription session, leading to the termination of the session.
This procedure supports multiple execution instances.
Unsubscribe(vehicleId: uint32, serviceId: uint32): GeneralOutput
GeneralOutput
{
Status: ProcedureStatus,
Error: *ErrorData
}
Struct member descriptions:The vehicle services are structured into service groups where each group contains services that relates to a vehicle domain. The service groups supported by VAPI are listed below.
The seating service group consists of all services related to the vehicle seating.
Get the available properties for seating in the vehicle.
This procedure retrieves the properties related to the seating service group.
This procedure supports multiple execution instances.
GetPropertiesSeating(vehicleId: uint32): GetPropertiesSeatingOutput
GetPropertiesSeatingOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Properties: RaggedMatrix
}
Struct member descriptions:Performs all supported seat movements.
This procedure performs all supported types of seat movements. It supports "synchronous" movement to any position provided as input to the service, and also "asynchronous" movement where the client terminates the service execution by invokation of CancelService. In the asynchronous scenario the provided input to the service is typically one of the position range end points (zero or hundred percent). Constants are defined to represent movement directions for the different movement types. The service will automatically terminate an ongoing callback session when either the vehicle signal representing the movement reaches the position provided in the input, or if an error occurs.
MoveSeat(vehicleId: uint32, seatId: MatrixId, movementType: string, position: Percentage,
stCredentials: string, callback: *fcn(MoveSeatOutput): MoveSeatOutput
MoveSeatOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
Position: Percentage,
ServiceId: uint32
}
Struct member descriptions:Performs all supported massage types.
This procedure performs all supported types of seat massage. It supports time bound set by the duration provided as input to the service. The client can at any time terminate the service execution by invokation of CancelService.
ActivateMassage(vehicleId: uint32, seatId: MatrixId, massageType: string, intensity: Percentage, duration: uint32,
stCredentials: string, callback: *fcn(MassageOutput): MassageOutput
MassageOutput
{
Status: ProcedureStatus,
Error: *ErrorData,
ServiceId: uint32
}
Struct member descriptions:The HVAC service group consists of all services related to the vehicle HVAC functionality.
xxx
The Exterior lighting service group consists of all services related to the vehicle exterior lighting.
xxx
The Interior lighting service group consists of all services related to the vehicle interior lighting.
xxx
Datatypes that are used by multiple procedures are defined below.
struct {
Code: int32,
Reason: string,
Description: string
}
struct {
Path: string,
SignalData: []DataPoint
}
struct {
Value: string,
Timestamp: string
}
enum: [
ONGOING = 1, // in execution of latest call
SUCCESSFUL = 0, // terminated successfully in latest call
FAILED = -1 // terminated due to failure in latest call
]
float
min = 0
max = 100
struct {
RowName: string,
ColumnName: string
}
SupportData: struct {
Name: string,
Description: string
}
ColumnData: struct {
Name: string,
MovementSupport: []SupportData,
MassageSupport: []SupportData
}
RowDef: struct {
{
RowName: string,
Column: []ColumnData
}
RaggedMatrix: []RowDef
struct {
Name: string,
Description: string
}
If any of the following types of movement are supported then these names and descriptions should be used.
struct {
Name: string,
Input: string,
Output: string
}
const (
LONGITUDINAL = "longitudinal" //Forward-backward direction of the vehicle
VERTICAL = "vertical" // Up-down direction of the vehicle
BACKREST = "backrest" // Seat backrest angular
LUMBAR = "lumbar" // Seat inflate-deflate lumbar
)
const (
FORWARD = 0 //longitudinal movement
BACKWARD = 100 //longitudinal movement
UP = 100 //vertical movement
DOWN = 0 //vertical movement
INFLATE = 100 //lumbar movement
DEFLATE = 0 //lumbar movement
FORWARD_RECLINE = 0 //backrest movement
BACKWARD_RECLINE = 100 //backrest movement
)