Developer

Vehicle integration basics

Request Access
Version: 0.5.0

Introduction

This document explains how an integrator can use the Vehicle Integration Library (VIL) to integrate the Automotive Navigation Application (ANA) with a vehicle. It covers setting up the library, using it, and testing the integration.

Note:
This document focuses on using VIL inside a new Android application.
It is also possible to implement a VIL client deeper within Android Automotive OS.

Project setup

  • Install Android Studio if you don’t already have it.
  • To set up VIL, you first need an existing Android project.
  • Ensure that the minimum SDK API level is set to 27 (Android 8.1 "Oreo") or higher.
  • Ensure that the minimum kotlin version used is 1.9.25 or higher.

Configuring project dependencies

Step 1. Add the Artifactory repository URL to the repositories block (settings.gradle.kts):

1dependencyResolutionManagement {
2    repositories {
3        google()
4        mavenCentral()
5        maven {
6            url = uri("https://repositories.tomtom.com/artifactory/automotive-maven-release")
7            credentials {
8                username = "your-username" // Replace with your Artifactory username
9                password = "your-password" // Replace with your Artifactory password
10            }
11        }
12    }
13}

Step 2. Update your app-level Gradle file (for example, app/build.gradle.kts) to include the maven package as a dependency.

1dependencies {
2    implementation("com.tomtom.automotive:vehicle-integration-library:0.5.0")
3    ...
4}

Using VIL

Instantiating a Vehicle Integration API Client

Instantiating VIL is typically done on application initialization, where an Android Context is readily available, such as in the onCreate method of your main application class:

Step 1. If you don't already have an application class, create one (e.g., MyVilApplication) by defining it in a new file named MyVilApplication.kt in your project. Then, initialize VIL as shown below:

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.error.NavAppError
3import com.tomtom.automotive.integration.vehicle.client.api.status.NavAppConnectionStatus
4import com.tomtom.automotive.integration.vehicle.client.api.status.NavAppConnectionStatusType
5import com.tomtom.automotive.integration.vehicle.client.api.status.StatusCallback
6import com.tomtom.automotive.integration.vehicle.client.lib.VehicleIntegrationApiClientFactory
7

8...
9

10class MyVilApplication : Application() {
11    lateinit var vilClient: VehicleIntegrationApiClient
12

13    override fun onCreate() {
14        super.onCreate()
15

16        vilClient = VehicleIntegrationApiClientFactory.create(
17            context = this,
18            statusCallback = object : StatusCallback {
19                override fun onConnectionStatus(connectionStatus: NavAppConnectionStatus) {
20                    if (connectionStatus.connectionStatusType == NavAppConnectionStatusType.CONNECTED) {
21                        // Set parameters
22                    }
23                }
24

25                override fun onError(error: NavAppError) {
26                    // Handle error
27                }
28            }
29        )
30    }
31}

Step 2. Declare your application class in AndroidManifest.xml:

1<application
2    android:name=".MyVilApplication"
3    ...
4      <!-- Other settings -->
5</application>

Once VehicleIntegrationApiClient is created (using the VehicleIntegrationApiClientFactory) and the "connected" callback has been received, you can start calling the API functions. The VIL API reference is available in VIL API Reference.

Setting parameter

For instance, you can set the Vehicle Specifications parameter by using the getVehicleInfoManager() function from the VehicleIntegrationApiClient instance:

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsCallback
3import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsFailure
4import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsParameters
5import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleType
6import com.tomtom.automotive.integration.vehicle.client.lib.VehicleIntegrationApiClientFactory
7import com.tomtom.automotive.integration.vehicle.common.Callback
8import com.tomtom.automotive.integration.vehicle.common.Result
9

10...
11

12vilClient.getVehicleInfoManager().setVehicleSpecs(
13    VehicleSpecsParameters(VehicleType.CAR),
14    object : VehicleSpecsCallback {
15        override fun onResult(result: Result<VehicleSpecsParameters, VehicleSpecsFailure>) {
16            if (result is Result.Failure) {
17                if (result.reason == VehicleSpecsFailure.FAILED_TO_SET_VEHICLE_SPECS) {
18                    // Server-side failure to set vehicle specs
19                } else {
20                    // Unexpected failure reason
21                }
22            } else {
23                // Vehicle specs set successfully
24            }
25        }
26

27        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
28            // Handle functionality unavailable
29            if (reason is Callback.Reason.IncompatibilityError) {
30                // The VIL client is not compatible with the version of the running Navigation Application
31            }
32        }
33    }
34)

Required parameters

This section outlines the required parameters your application should set to successfully start ANA. In case not all required parameters are set, the splash screen remains visible in ANA. To set these parameters, use the respective API functions available in VehicleIntegrationApiClient in the VIL API Reference guide:

  • VehicleSpecsParameters. Represents a generic vehicle specification, such as the type of vehicle. This data is required for ANA to tailor its behavior and is not expected to change during application runtime. Refer to VIL API Reference for more information.
  • OnlineServicesConfigurationParameters Represents Online Services configuration information. Refer to VIL API Reference for more information. Specifies a Fully Qualified Domain Name (FQDN), following the format subdomain.domain.tld. The FQDN is required for ANA to understand how to connect to TomTom Online Services. To learn how to acquire an FQDN, refer to Set up online services.
  • OnlineServicesTokenParameters. Includes an authentication token for Online Services in JSON Web Token (JWT) format. A JWT token is required to authenticate and authorize access to TomTom Online Services. The token is dynamic and changes during the lifetime of the application, depending on the expiry timeout of the token. Refer to VIL API Reference for more information. To learn how to set up a JWT token, refer to Set up online services.
  • ResourcesParameters. Represents platform resources accessible to ANA, such as the path to the folder containing onboard map files, keystore, license, and cache. This is required for ANA to understand where to find files related to the onboard map and where it can store related caches. Refer to VIL API Reference for more information.

Error handling

Your application may receive the following error conditions that must be handled appropriately.

ErrorDescriptionHints
ErrorCallback.NavAppError.SECURITY_ERRORThe VehicleIntegrationClient has insufficient permissions to establish a connection.Ensure that your application has the correct Android permissions to use socket communication.
ErrorCallback.NavAppError.BIND_SERVICE_TIMEOUTThe VehicleIntegrationClient could not establish a connection to the navigation application.Ensure that the navigation application is installed and running.
ErrorCallback.NavAppError.EXCEPTION_WHEN_INVOKE_REQUESTThe VehicleIntegrationClient could not complete a request.This indicates a problem with the navigation application; contact support for assistance.
ErrorCallback.NavAppError.VERSION_MISMATCHThe VehicleIntegrationClient library version is incompatible with your application.Ensure that the correct library version is configured for the navigation app version. Check logs for isVersionMismatch.
ErrorCallback.NavAppError.NO_CONNECTIONThe VehicleIntegrationClient is no longer connected to the navigation application.Ensure that the navigation application is still running.
Result.Failure.UNHANDLEDThe VehicleIntegrationClient library version is incompatible with your application.Ensure that the correct library version is configured for the navigation app version.
Callback.Reason.IncompatibilityErrorThe VehicleIntegrationClient library version is incompatible with your application.Ensure that the correct library version is configured for the navigation app version.