Vehicle Data

The purpose of this guide is to explain how vehicle data items can be exposed to app developers through the HMI.

Vehicle data can be exposed to app developers by creating a VehicleInfo component within your HMI. To communicate with this component, you will first need to register it with the message broker and respond to the VehicleInfo.IsReady message from SDL (see the Component Readiness Requests section for more information).

RPCs

Below are descriptions for the primary RPCs used by the VehicleInfo component of SDL. More information regarding this component is available in the VehicleInfo section of the HMI Documentation.

VehicleInfo.GetVehicleData

Description:

A request from Core to retrieve specific vehicle data items from the system.

Example Request:

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "VehicleInfo.GetVehicleData",
    "params" : {
        "speed" : true
    }
}

Example Response:

{
    "id": 123,
    "jsonrpc": "2.0",
    "result" : {
        "speed" : 100
    }
}

VehicleInfo.SubscribeVehicleData

Description:

A request from Core to receive periodic updates for specific vehicle data items from the system.

Example Request:

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "VehicleInfo.SubscribeVehicleData",
    "params" : {
        "speed" : true
    }
}

Example Response:

{
    "id": 123,
    "jsonrpc": "2.0",
    "result" : {
        "speed" : {
            "dataType" : "VEHICLEDATA_SPEED",
            "resultCode" : "SUCCESS"
        }
    }
}

VehicleInfo.UnsubscribeVehicleData

Description:

A request from Core to stop receiving periodic updates for specific vehicle data items from the system.

Example Request:

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "VehicleInfo.UnsubscribeVehicleData",
    "params" : {
        "speed" : true
    }
}

Example Response:

{
    "id": 123,
    "jsonrpc": "2.0",
    "result" : {
        "speed" : {
            "dataType" : "VEHICLEDATA_SPEED",
            "resultCode" : "SUCCESS"
        }
    }
}

VehicleInfo.OnVehicleData

Description:

A notification from the HMI indicating that one or more of the subscribed vehicle data items were updated.

Example Notification:

{
    "jsonrpc": "2.0",
    "method": "VehicleInfo.OnVehicleData",
    "result" : {
        "speed" : 100
    }
}

Available Vehicle Data Items

Below is a list of all of the vehicle data items which are available via SDL as of Release 6.1.0 of SDL Core. New vehicle data items are proposed regularly via the SDL Evolution process.

Custom Vehicle Data Items

Starting with SDL Core version 6.0.0, custom vehicle data items can be defined via the policy table. See SDL-0173 for the full proposal details. These items are structured in a similar manner to the Mobile API and contained in the vehicle_data section of the policy table.

In addition to custom items, this feature can be used to expose other vehicle data items that were introduced to the project in later versions. This can be useful when the software version on the head unit cannot be updated easily. If a vehicle data item is added into the project, the definition of this item will be included in the policy table by default. Any vehicle data items which are defined in Core's local Mobile API will be ignored from the policy table, but newer items will be interpreted as custom items. This allows apps to use these data items normally if they are exposed by the head unit, even when they were not initially supported.

Example Entry

"vehicle_data": {
    "schema_version": "1.0.0",
    "schema_items": [
        ...
        {
            "name": "customString",
            "key": "KEY_CUSTOM_STRING",
            "minlength": 0,
            "maxlength": 100,
            "type": "String",
            "mandatory": false
        },
        {
            "name": "customInt",
            "key": "KEY_CUSTOM_INT",
            "minvalue": 0,
            "maxvalue": 100,
            "type": "Integer",
            "mandatory": false
        },
        {
            "name": "customFloat",
            "key": "KEY_CUSTOM_FLOAT",
            "minvalue": 0.0,
            "maxvalue": 100.0,
            "type": "Float",
            "mandatory": false
        },
        {
            "name": "customBool",
            "key": "KEY_CUSTOM_BOOL",
            "type": "Boolean",
            "mandatory": false
        },
        {
            "name": "customArray",
            "key": "KEY_CUSTOM_ARRAY",
            "type": "String",
            "array": true,
            "minsize": 0,
            "maxsize": 100,
            "mandatory": false
        },
        {
            "name": "customStruct",
            "params": [
                {
                    "name": "customStructVal",
                    "key": "KEY_CUSTOM_STRUCT_VAL",
                    "type": "String",
                    "mandatory": true
                },
                {
                    "name": "customStructVal2",
                    "key": "KEY_CUSTOM_STRUCT_VAL2",
                    "minvalue": 0,
                    "maxvalue": 100,
                    "type": "Integer",
                    "mandatory": true
                },
                {
                    "name": "customDeprecatedVal",
                    "key": "KEY_CUSTOM_DEPRECATED_VAL",
                    "minvalue": 0,
                    "maxvalue": 100,
                    "type": "Integer",
                    "mandatory": true,
                    "until": "7.0"
                },
                {
                    "name": "customDeprecatedVal",
                    "key": "KEY_CUSTOM_DEPRECATED_VAL",
                    "minvalue": 0,
                    "maxvalue": 100,
                    "type": "Integer",
                    "mandatory": true,
                    "deprecated": true,
                    "since": "7.0"
                }
            ],
            "key": "KEY_CUSTOM_STRUCT",
            "type": "Struct",
            "mandatory": false
        }
    ]
}

Custom Data Fields

• name : Is the vehicle data item in question. e.g. gps, speed etc. SDL core would use this as the vehicle data param for requests from the app and to validate policies permissions.
• type : Is the return data type of the vehicle data item. It can either be a generic SDL data type (Integer, String, Float, Boolean, Struct) or an enumeration defined in Mobile API XML. For a vehicle data item that has sub-params, this would be Struct.
• key : Is a reference for the OEM Network Mapping table which defines signal attributes for this vehicle data items. OEMs may use this table to differentiate between various vehicle and SW configurations. SDL core will pass along this reference to HMI, and then HMI would be responsible to resolve this reference using the Vehicle Data Mapping table (see Vehicle Data Mapping File).
• array : A boolean value used to specify if the vehicle data item/param response is an array, rather than a single value of the given type.
• mandatory : A boolean value used to specify if the vehicle data param is mandatory to be included in response for the overall vehicle data item.
• params : A recursive list of sub-params for a vehicle data item, see example above (customStruct) for structure definition.
• since, until : String values related to API versioning which are optional per vehicle data item.
• removed, deprecated : Boolean values related to API versioning which are optional per vehicle data item.
• minvalue, maxvalue : Integer/Float values which are used for controlling the bounds of number values (Integer, Float).
• minsize, maxsize : Integer values which are used for controlling the bounds of array values (where array is true).
• minlength, maxlength : Integer values which are used for controlling the bounds of String values.

Note

• name is required for top level vehicle data items while type, key & mandatory are required fields for vehicle data & sub-params. However array can be omitted, in which case array defaults to false.
• Custom/OEM Specific vehicle data parameters that are not a part of the rpc spec should not have any version related tags included (since, until, removed, deprecated). These vehicle data parameters would not be able to have the same versioning system as the rpc spec, since any version number supplied would not be the version associated with any known public rpc spec.

Custom Vehicle Data Requests

Custom vehicle data requests have a separate structure to normal vehicle data requests. While normal vehicle data items are requested using the key structure of "<name>: true", custom items are constructed using the key field and can have a nested structure (when requesting Struct items). For example, when requesting all of the vehicle data items which are defined above, the HMI would receive the following message:

{
    "id" : 139,
    "jsonrpc" : "2.0",
    "method" : "VehicleInfo.GetVehicleData",
    "params" : {
        "KEY_CUSTOM_STRING": true,
        "KEY_CUSTOM_INT": true,
        "KEY_CUSTOM_FLOAT": true,
        "KEY_CUSTOM_BOOL": true,
        "KEY_CUSTOM_ARRAY": true,
        "KEY_CUSTOM_STRUCT": {
            "KEY_CUSTOM_STRUCT_VAL": true,
            "KEY_CUSTOM_STRUCT_VAL2": true,
            "KEY_CUSTOM_DEPRECATED_VAL": true
        }
    }
}

Vehicle Data Mapping File

Since these keys may not be immediately known by the HMI, a vehicle data mapping file can be used to connect these keys to actual readable values from the vehicle. The HMI primarily uses this file to convert CAN data values into an SDL-compatible format. The location where this file is hosted can be specified in the policy table in the module_config.endpoints.custom_vehicle_data_mapping field (see Policy Endpoints). The format of this file is OEM-defined.

Example Format

{
    "version":"0.0.1",
    "date":"01-01-2020",
    "vehicleDataTable": [
        {
            "CGEA1.3c":{
                "defaultPowertrain": {
                    "vehicleData": [
                    ]
                },
                "PHEV":{
                    "vehicleData":[
                        {
                            "key":"OEM_REF_FUELLEVEL",
                            "type":"Integer",
                            "minFrequency":200,
                            "maxLatency":10,
                            "messageName":"Cluster_Info3",
                            "messageID":"0x434",
                            "signalName":"FuelLvl_Pc_Dsply",
                            "transportChannel":"HS3",
                            "resolution":0.109,
                            "offset":-5.2174
                        }
                    ]
                }
            }
        }
    ]
}

Note

In order for the HMI to determine when this file needs to be updated, this file can be assigned a version via the module_config.endpoint_properties.custom_vehicle_data_mapping.version field. The HMI can retrieve this field using the SDL.GetPolicyConfigurationData RPC.

Reading Raw CAN Data

In addition to complex vehicle data items, the vehicle data mapping file can also be used to make some CAN values directly readable via a String value:

Policy Definition

{
    "name":"messageName",
    "type":"String",
    "key":"OEM_REF_MSG",
    "array":true,
    "mandatory":false,
    "since":"X.x",
    "maxsize":100,
    "params":[]
}

HMI Response

{
    "messageName": "AB 04 D1 9E 84 5C B8 22"
}