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.

Introduction

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.

Terminology

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 Overview

VAPI Deployment Scenarios

The software components (SwC) and their possible deployments that are involved in the VAPI context are: Two interface specifications are used in this context: The VCS is not explicitly exposed to the client, VAPI abstracts its details and thus enables different VCS solutions to be used in implementations of VAPI. The VCS can be an OEM proprietary specification, or it can be an open specification like e. g. [[VISS]].
The main deployment combinations of interest in a VAPI context for the two abstraction models are described below.

Deployment in a signal based abstraction model

The figure below shows a typical deployment architecture and messaging flow for client access of vehicle signals.
VAPI signal based deployment.
VAPI signal based deployment.
The signal endpoint, which typically is in a vehicle transducer, is deployed on the southbound side of the vehicle server.
The VCS scope can be limited to support vehicle signals.

Deployment in a service based abstraction model

A service based abstraction model makes the deployment scenario more complex as the service endpoint can be deployed either at the client side or at the server side. A service endpoint implements the actions that the service performs. These actions typically involve accessing vehicle signals, which can be done either through vehicle native interfaces or through a VCS exposed by a signal based server.

Client side service deployment

With the service endpoint deployed at the client side the VCS scope can be limited to support vehicle signals.
VAPI client side service based deployment.
VAPI client side service based deployment.
Client side service deployments do not readily support implementation of a global arbitration of client access to services as one VAPI front-end implementation may not be shared by all clients. This may limit the usefulness of this type of deployment, but it may also be possible to mitigate by adding that functionality on top of all clients. VAPI does not include that functionality.

Server side service deployment

With the service endpoint deployed at the server side the VCS scope must include support for services.
VAPI server side service based deployment.
VAPI server side service based deployment.
It may also support vehicle signal access, allowing a combination of client side and server side service deployments. It could then also be used by service end points to access vehicle signals, if a vehicle server that implements it is also deployed.

VAPI Procedure Grouping

VAPI procedures are characterized as belonging to one of the groups Common, Data, or Service.

Procedure characteristics:

Common Procedures

The common procedures are used for common tasks that are not related specifically to either the data or the service groups.

GetVehicle

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.

Signature

GetVehicle(vehicleGuid: string): GetVehicleOutput

Parameters

  • vehicleGuid (string)
    A globally unique reference to the vehicle.

Returns

GetVehicleOutput
A struct containing the output data from the GetVehicle procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              VehicleId: uint32,
              Protocol: []string
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
VehicleId: The reference to the vehicle that shall be used as input in procedures that require a vehicle id. The scope of this Id is limited to run-time scope of the client calling GetVehicle.
Protocol: A list of supported protocols.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall at least support the error cases:
    • Unknown globally unique vehicle identity.
    • Vehicle connection data not available.
    • Connecting to vehicle failed.
  • The VehicleId and Protocol parameters are invalid if Status is set to FAILED.

ReleaseVehicle

Disconnects communication setup with a vehicle.

This procedure terminates a vehicle communication session for all protocols.

Signature

ReleaseVehicle(vehicleId: uint32): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.

Returns

GeneralOutput
A struct containing the output data from the ReleaseVehicle procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

Connect

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.

Signature

Connect(vehicleId: uint32, protocol: string, clientCredentials: string): ConnectOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • protocol (string)
    If the connectivity solution that is used by the VAPI implementation supports use of multiple transport protocols then this parameter allows the client to select which to use. The names representing the supported protocols must align with the names used by the implemented connectivity solution.
  • clientCredentials (string)
    Access to the vehicle services or data might require that a credential is present, e .g. a certificate. How the client obtains this credential is out-of-scope for this specification, as well as what is required of it to become verified successfully. This information may be available in the context of the implemented connectivity solution. If it is not required then it shall be set to an empty string.

Returns

ConnectOutput
A struct containing the output data from the Connect procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              LtCredential: string
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
LtCredential: Long term credentials that may have a lifetime equal to the vehicle connectivity session. If not used then it is set to an empty string.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall at least support the error cases:
    • Unknown globally unique vehicle identity.
    • Vehicle connection data not available.
    • Connecting to vehicle failed.
  • The LtCredential parameter is invalid if Status is set to FAILED.

Disconnect

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.

Signature

Disconnect(vehicleId: uint32, protocol: string): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • protocol (string)
    The protocol name of an ongoing communication session.

Returns

GeneralOutput
A struct containing the output data from the Disconnect procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

SelectProtocol

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.

Signature

SelectProtocol(vehicleId: uint32, protocol: string): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • protocol (string)
    The protocol name. This was typically obtained in a previous GetVehicle call.

Returns

GeneralOutput
A struct containing the output data from the SelectProtocol procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

CancelService

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.

Signature

CancelService(vehicleId: uint32, serviceId: uint23): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle call.
  • serviceId (uint32)
    The serviceId was received in a previous response from a service call.

Returns

GeneralOutput
A struct containing the output data from the CancelService procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

ServiceInquiry

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.

Signature

ServiceInquiry(vehicleId: uint32): ServiceInquiryOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.

Returns

ServiceInquiryOutput
A struct containing the output data from the ServiceInquiry procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Service: []ServiceSignature
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Service: An array of structs describing the service signature.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall at least support the error cases:
    • Unknown globally unique vehicle identity.
    • Vehicle connection data not available.
    • Connecting to vehicle failed.
  • The Service parameter is invalid if Status is set to FAILED.

GetStCredentials

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.

Signature

GetStCredentials(vehicleId: uint32, ltCredentials: string, purpose: string): GetStCredentialsOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • LtCredential (string)
    The long term credentials that was obtained in a previous GetVehicle. If it is not required then it shall be set to an empty string.
  • purpose (string)
    A description of the use case / purpose for the client access to the signals/service. If not required it shall be set to an empty string. The string representing the purpose must align with the purposes supported by the ecosystem around the implemented connectivity solution.

Returns

GetStCredentialsOutput
A struct containing the output data from the GetStCredentials procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              StCredentials: string
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
StCredentials: Short term credentials that have a lifetime less than or equal to the vehicle connectivity session. If not required for the client to get access then it shall be set to an empty string.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall at least support the error cases:
    • Unknown globally unique vehicle identity.
    • Vehicle connection data not available.
    • Connecting to vehicle failed.
  • The StCredentials parameter is invalid if Status is set to FAILED.

Invoke

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.

Signature

Invoke(vehicleId: uint32, serviceName: string, procedureInput: string, stCredentials: string, callback: *fcn(InvokeOutput): InvokeOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • serviceName (string)
    • The name of the auxillary service.
  • procedureInput (string)
    The input parameters of the service to be called are supplied as a JSON object. The syntax shall be as follows with both parameter names and values represented as strings (two input parameters in the example). 
    
              {
                  "parameterName1": "value1",
                  "parameterName2": "value2"
              }
    An empty string represents the case with a service having no input parameters.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.
  • callback (*fcn(InvokeOutput))
    A pointer to a callback function that is called if an event message gets issued by the service. If set to nil callbacks will not be issued.

Returns

InvokeOutput
A struct containing the output data from the Invoke procedure. This shall be returned both synchronously on the procedure call and asynchronously on event trigger conditions. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              ServiceOutput: string,
              ServiceId: uint32
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
ServiceOutput: The service output parameters is a JSON object following the same syntax as used for the input parameters.
ServiceId: A reference to the service session that the client may use to call CancelService. It may be set to zero in which case it is invalid.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The ServiceOutput and ServiceId parameters are invalid if Status is set to FAILED.

GetMetadata

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.

Signature

GetMetadata(vehicleId: uint32, path: string, stCredentials: string): GetMetadataOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • path (string)
    The path must follow the syntax described in HIM. It may address any node in the HIM defined tree.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.

Returns

GetMetadataOutput
A struct containing the output data from the GetMetadata procedure. This shall be returned both synchronously on the procedure call and asynchronously on event trigger conditions. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Metadata: string
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Metadata: A JSON object containing the metadata from the signals or services in the subtree.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The Metadata parameter is invalid if Status is set to FAILED.

Data Procedures

The data procedures provide access to vehicle signals using a "service agnostic" API consisting of the procedures:

Get

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.

Signature

Get(vehicleId: uint32, path: string, filter: string, stCredentials: string): GetOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • path (string)
    The path must follow the syntax described in HIM. It must address a leaf node in the HIM defined tree, unless there is also an input filter parameter.
  • filter (string)
    If the path addresses a branch node in the HIM defined tree, then a filter must be used to extend it to one or more leaf nodes. The filter expression must follow the syntax as described in the implemented connectivity solution.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.

Returns

GetOutput
A struct containing the output data from the Get procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Data: []DataContainer
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Data: The requested data.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The Data parameter is invalid if Status is set to FAILED.

Set

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.

Signature

Set(vehicleId: uint32, path: string, value: string, stCredentials: string): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • path (string)
    The path must follow the syntax described in HIM. It must address a leaf node in the HIM defined tree, unless there is also an input filter parameter.
  • value (string)
    The value that the signal shall become set to. Regardless of datatype the value is represented in string format.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.

Returns

GeneralOutput
A struct containing the output data from the Set procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.

Subscribe

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.

Signature

Subscribe(vehicleId: uint32, path: string, filter: string, stCredentials: string, callback: *fcn(SubscribeOutput): SubscribeOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle call.
  • path (string)
    The path must follow the syntax described in HIM. It must address a leaf node in the HIM defined tree, unless there is also an input filter parameter.
  • filter (string)
    If the path addresses a branch node in the HIM defined tree, then a filter must be used to extend it to one or more leaf nodes. The filter expression must follow the syntax as described in [[VISS]].
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.
  • callback (*fcn(SubscribeOutput))
    A pointer to a callback function that is called if an event message gets issued by the service. If set to nil callbacks will not be issued.

Returns

SubscribeOutput
A struct containing the output data from the Subscribe procedure. This shall be returned both synchronously on the procedure call and asynchronously on event trigger conditions. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Data: []DataContainer,
              ServiceId: uint32
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Data: The requested data.
ServiceId: A reference to the service session that the client may use to call CancelService. It may be set to zero in which case it is invalid.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The Data and ServiceId parameters are invalid if Status is set to FAILED.

Unsubscribe

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.

Signature

Unsubscribe(vehicleId: uint32, serviceId: uint32): GeneralOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • serviceId (uint32)
    The serviceId was received in the previous Subscribe response.

Returns

GeneralOutput
A struct containing the output data from the Unsubscribe procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.

Service Procedures

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.

Seating Service Group

The seating service group consists of all services related to the vehicle seating.

GetPropertiesSeating

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.

Signature

GetPropertiesSeating(vehicleId: uint32): GetPropertiesSeatingOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.

Returns

GetPropertiesSeatingOutput
A struct containing the output data from the GetPropertiesSeating procedure. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Properties: RaggedMatrix
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Properties: A ragged matrix of seat identities and available properties per seat.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The Properties parameter is invalid if Status is set to FAILED.

MoveSeat

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.

Signature

MoveSeat(vehicleId: uint32, seatId: MatrixId, movementType: string, position: Percentage,
          stCredentials: string, callback: *fcn(MoveSeatOutput): MoveSeatOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • seatId (MatrixId)
    The seat Id identifies one of the seats in the vehicle.
  • movementType (string)
    The seat movement type must be one of the MovementSupport elements retrieved by GetPropertiesSeating.
  • position (Percentage)
    The seat movement regardless of type is expressed in a percentage where zero (0) is one end position and hundred (100) is the other end position.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.
  • callback (*fcn(MoveSeatOutput))
    A pointer to a callback function that is called if an event message gets issued by the service. If set to nil callbacks will not be issued.

Returns

MoveSeatOutput
A struct containing the output data from the MoveSeat procedure. This shall be returned both synchronously on the procedure call and asynchronously on event trigger conditions. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              Position: Percentage,
              ServiceId: uint32
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
Position: The current position of the seat movement.
ServiceId: A reference to the service session that the client may use to call CancelService. It may be set to zero in which case it is invalid.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The Position and ServiceId parameters are invalid if Status is set to FAILED.

ActivateMassage

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.

Signature

ActivateMassage(vehicleId: uint32, seatId: MatrixId, massageType: string, intensity: Percentage, duration: uint32,
          stCredentials: string, callback: *fcn(MassageOutput): MassageOutput

Parameters

  • vehicleId (uint32)
    A reference to the vehicle that was obtained in a previous GetVehicle.
  • seatId (MatrixId)
    The seat Id identifies one of the seats in the vehicle.
  • massageType (string)
    The massage type type must be one of the MassageSupport elements retrieved by GetPropertiesSeating.
  • intensity (Percentage)
    The massage intensity is expressed in a percentage where zero (0) is the minimum level and hundred (100) is the maximum level.
  • duration (uint32)
    The massage duration is expressed in seconds. It is limited to a maximum duration of 24 hours. If set to zero then the duration becomes set to 24 hours.
  • stCredentials (string)
    The short term credentials that was obtained by a call to GetStCredentials.
  • callback (*fcn(MassageOutput))
    A pointer to a callback function that is called if an event message gets issued by the service. If set to nil callbacks will not be issued.

Returns

MassageOutput
A struct containing the output data from the ActivateMassage procedure. This shall be returned both synchronously on the procedure call and asynchronously on event trigger conditions. 

            {
              Status: ProcedureStatus,
              Error: *ErrorData,
              ServiceId: uint32
            }
Struct member descriptions:
Status: The status of the latest service call to it.
Error: Error information for the latest service call, if error occurred.
ServiceId: A reference to the service session that the client may use to call CancelService. It may be set to zero in which case it is invalid.

Error

  • If Status is set to FAILED then Error must be available and populated with error data, else the pointer to Error shall be set to nil.
  • Error data shall conform to the error data definitions in [[VISS]] for signals.
  • The ServiceId parameter is invalid if Status is set to FAILED.

HVAC Service Group

The HVAC service group consists of all services related to the vehicle HVAC functionality.

xxx Procedure

xxx

Exterior Lighting Service Group

The Exterior lighting service group consists of all services related to the vehicle exterior lighting.

xxx Procedure

xxx

Interior Lighting Service Group

The Interior lighting service group consists of all services related to the vehicle interior lighting.

xxx Procedure

xxx

Datatype Definitions

Datatypes that are used by multiple procedures are defined below.

ErrorData

A struct containing the error data related to a failed procedure call.
The Code shall conform to the status codes defined in [[RFC2616]].
The Reason shall be the associated reason phrase from the referenced RFC document.
The Description shall provide more context of the failure. 

        struct {
            Code: int32,
            Reason: string,
            Description: string
        }

DataContainer

A struct containing the path of a signal and one or more data points of the signal. 

        struct {
            Path: string,
            SignalData: []DataPoint
        }

DataPoint

A struct containing one data point. A data point contains a signal value and its associated timestamp. The value has string format which is used to represent the value for any of the datatypes supported by HIM. 

        struct {
            Value: string,
            Timestamp: string
        }

ProcedureStatus

An enumeration of int8 values representing the current state of a procedure execution. If set to FAILED then associated ErrorData is available. 

        enum: [
            ONGOING = 1,     // in execution of latest call
            SUCCESSFUL = 0,  // terminated successfully in latest call
            FAILED = -1      // terminated due to failure in latest call
        ]

Supported protocols

A string array containing names of the supported protocols. The first on the list is set as default, which can be changed by SelectProtocol if multiple protocolsa are supported. Protocol naming should be "MainProtocolName-SubProtocolName", e. g. "VISSv3.0-grpc".

Percentage

A float value ranging from zero to one hundred. This represents the percentage of the current value within a range calculated as current value / (max range value - min range value). The semantics of max and min range values shall be defined in the context of the range being addressed. 

        float
        min = 0
        max = 100

MatrixId

A struct containing the Id of one element of a two-dimensional matrix. 

        struct {
            RowName: string,
            ColumnName: string
        }

RaggedMatrix

A two-dimensional matrix in which the number of elements may vary in the different rows. The matrix is represented as an array of RowDef elements. The Rowdef datatype is a struct with one element representing the name of the row, and the other is a string array containing the elements of that row, each containing the column name and the available properties. 

        SupportData: struct {
            Name: string,
            Description: string
        }

        ColumnData: struct {
            Name: string,
            MovementSupport: []SupportData,
            MassageSupport: []SupportData
        }

        RowDef: struct {
        {
            RowName: string,
            Column: []ColumnData
        }

        RaggedMatrix: []RowDef

SeatMovementType

A struct containing the name and description of seat movement types in the vehicle. 

        struct {
            Name: string,
            Description: string
        }
If any of the following types of movement are supported then these names and descriptions should be used. Movement types not covered by the list may be added in an implementation.

ServiceSignature

A struct describing the procedure signature of an auxillary service.
The Name member shall be used as the serviceName input parameter when calling Invoke to perform a call of this service.
The Input member is a JSON object describing the input parameters of the auxillary service. The format described shall be used procedureInput input parameter in the Invoke call.
The Output member is a JSON object describing the output parameters of the auxillary service. This can be helpful when decoding the JSON object that is received in the response (and events if issued) from the service call. 

        struct {
            Name: string,
            Input: string,
            Output: string
        }

Constants

Movement Types


	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
	)

Movement Directions


	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
	)