Developer

Integrate TomTom Digital Cockpit into a Gradle Project

Last edit: 2024.02.23

This pages contains the steps required to integrate the TomTom Digital Cockpit platform into an existing Android Gradle project. If you are new to TomTom Digital Cockpit, our recommendation is to use the examples as a starting point, as these already cover the steps described on this page. Use the steps on this page as a reference to integrate the TomTom Digital Cockpit platform into an existing / newly created Android Gradle project. These steps assume a basic level of experience with setting up Gradle build files using Kotlin.

Maven repositories

Gradle will need to be able to download TomTom Digital Cockpit platform dependencies from TomTom's Maven repositories, for which login credentials are required. These can be obtained from TomTom.

Access to these repositories can be configured in Gradle as follows:

build-logic/repositories.gradle.kts

1

2fun RepositoryHandler.tomtomArtifactory() {
3    val repoName = artifactoryRepo ?: "ivi"
4    maven("https://repository.tomtom.com/artifactory/$repoName") {
5        credentials {
6            username = extra["artifactoryEdgeUser"].toString()
7            password = extra["artifactoryEdgeToken"].toString()
8        }
9        content {
10            includeGroupByRegex("com\\.tomtom\\..+")
11            includeGroup("com.tomtom")
12            includeGroup("com.amazon.alexa.aace")
13        }
14    }
15}
16

17pluginManagement.repositories {
18    // Local artifact cache.
19    mavenLocal()
20    
21    tomtomArtifactory()
22

23    // External repositories.
24    mavenCentral()
25    google()
26    maven("https://plugins.gradle.org/m2/")
27}
28

29dependencyResolutionManagement {
30    repositories {
31        // Local artifact cache.
32        mavenLocal()
33        
34        tomtomArtifactory()
35

36        // External repositories.
37        mavenCentral()
38        google()
39        maven("https://plugins.gradle.org/m2/")
40    }
41}

The above needs to be applied to buildscript, buildSrc and to all projects. As such, apply this file in the Gradle settings files.

settings.gradle.kts

apply(from = "build-logic/repositories.gradle.kts")

buildSrc/settings.gradle.kts

apply(from = "../build-logic/repositories.gradle.kts")

Dependency management

The TomTom Digital Cockpit platform publishes a version catalog which you can use to ensure your product uses the same versions as used by the TomTom Digital Cockpit platform.

build-logic/ividependencies.versioncatalog.gradle.kts

1dependencyResolutionManagement {
2    versionCatalogs {
3        create("iviDependencies") {
4            val group = "com.tomtom.ivi.platform"
5            val artifact = "dependencies-catalog"
6            val version = "<TOMTOM-DIGITAL-COCKPIT-VERSION>"
7            from("${group}:${artifact}:${version}")
8        }
9    }
10}

Replace the <TOMTOM-DIGITAL-COCKPIT-VERSION> with the TomTom Digital Cockpit version you want to use, in format x.y.z.

Next, apply this file in the top-level settings.gradle.kts file and buildSrc/settings.gradle.kts files.

BuildSrc dependencies

The TomTom Digital Cockpit platform provides Gradle plugins for the build-time configuration of the TomTom Digital Cockpit platform. This allows you to, for example, include all of Digital Cockpit's default frontends in your product. To allow these Gradle plugins to be used in the Gradle projects, it is required to add them as implementation dependencies to the buildSrc. The following adds these dependencies:

buildSrc/build.gradle.kts

1dependencies {
2    val iviPlatformVersion = "<TOMTOM-DIGITAL-COCKPIT-VERSION>"
3

4    // Mandatory: Plugin to configure the IVI application at build-time.
5    implementation("com.tomtom.ivi.platform.gradle:api_framework_config:$iviPlatformVersion")
6

7    // Optional: Plugin to use the default frontends and services from the TomTom Digital Cockpit platform
8    // and app suite.
9    implementation("com.tomtom.ivi.product.gradle:api_productdefaults_core:$iviPlatformVersion")
10

11    // Mandatory: For IVI services plugins.
12    implementation(iviDependencies.gradlePluginKsp)
13}

Root project configuration

Apply the following plugins to the root Gradle project:

build.gradle.kts

1plugins {
2    `kotlin-dsl`
3    ...
4    // Mandatory: For IVI service plugins.
5    id("com.google.devtools.ksp") apply false
6

7    // Mandatory: For configuring the IVI application at build-time.
8    id("com.tomtom.ivi.platform.framework.config")
9}

In the same file, configure the TomTom Digital Cockpit platform dependency source.

build.gradle.kts

1ivi {
2    dependencySource =
3        IviDependencySource.ArtifactRepository(libraries.versions.iviPlatform.get())
4}

Integrating TomTom Digital Cockpit platform into the APK

To integrate the TomTom Digital Cockpit platform into an APK, you can add the following to the build file of the project that builds the APK:

my_project/build.gradle.kts

1plugins {
2    // Optional: To use the default frontends and services from the TomTom Digital Cockpit platform
3    // and app suite.
4    id("com.tomtom.ivi.product.defaults.core")
5    // Optional: Add a non-default frontend.
6    id("com.tomtom.ivi.appsuite.alexa.defaults.alexa")
7}
8

9ivi {
10    application {
11        enabled = true
12    }
13}

The Gradle plugin applied in this example id("com.tomtom.ivi.product.defaults.core") configures all the default frontends, frontend extensions, menu items and IVI service hosts from the TomTom Digital Cockpit platform and app suite for the default runtime deployment. Unless defined otherwise all default components are enabled in the ivi application.

If you only want to apply defaults from the TomTom Digital Cockpit platform without the appsuite default, you can achieve this by only applying the platform Gradle plugin: id("com.tomtom.ivi.platform.defaults.core").

Furthermore, you can add specific non-default platform or appsuite plugins, such as id("com.tomtom.ivi.appsuite.alexa.defaults.alexa"). However, any non-default plugin components need to be enabled explicitly in the ivi application.

Configuring the IVI application

The ivi application contains three important blocks. The iviInstances, the services and the runtime. If any of these blocks are not specified, defaults will apply. However, by using the blocks, one can have control over how the platform is integrated.

This can be achieved in a fine-grained way by specifically adding, removing or replacing components such as frontends, or in a more coarse-grained way by including or excluding groups.

my_project/build.gradle.kts

1ivi {
2    application {
3        enabled = true
4        iviInstances {
5            create(IviInstanceIdentifier.default) {
6                applyGroups {
7                    includeDefaultPlatformGroups() // Include everything from TTDC platform.
8                    includeDefaultAppsuiteGroups() // Include everything from TTDC appsuite.
9                    include(IviAppsuite.alexaGroup) // Include explicit opt-in app suite plugin.
10                    exclude(IviPlatform.debugGroup) // Exclude the default debug group.
11                }
12                frontends {
13                    replace(userProfileFrontend, accountFrontend)
14                    remove(mediaFrontend)
15                }
16                menuItems {
17                    add(myMenuItem)
18                    replace(userProfileMenuItem, accountMenuItem to accountFrontend)
19                }
20            }
21        }
22        services {
23            applyGroups {
24                includeDefaultPlatformGroups()
25                includeDefaultAppsuiteGroups()
26                include(IviAppsuite.alexaGroup)
27                exclude(IviPlatform.debugGroup)
28            }
29        }
30    }
31}

Applying groups can be particularly useful for long term stable integration. For instance, in the above example, the alexaGroup is an opt-in group. Instead of adding the specific frontend and menu items specifically, the entire group is added. This is robust against future changes, which may add or remove frontends or menu items. If the fine-grained method is used, it would require changes to the build.gradle.kts, but using groups this is not needed.

Similarly, if a default group needs to be excluded, this can be achieved by excluding all components individually (frontends, menu items, services), or simply by excluding its group. The example below includes the appStoreGroup for the minimal product flavor.

1

2androidApplication {
3    // Define the `default` and `minimal` product flavors:
4    flavorDimensions.add("iviapplication")
5    productFlavors {
6        create("default") {
7            dimension = "iviapplication"
8            isDefault = true
9        }
10        create("minimal") {
11            dimension = "iviapplication"
12        }
13    }
14}
15

16androidComponents {
17    // Configure each variant (defaultDebug, defaultRelease, minimalDebug, minimalRelease):
18    onVariants { variant ->
19        variant.ivi {
20            application {
21                enabled = true
22                iviInstances {
23                    create(IviInstanceIdentifier.default) {
24                        applyGroups {
25                            includeDefaultPlatformGroups() // Include everything from TTDC platform.
26                            includeDefaultAppsuiteGroups() // Include everything from TTDC appsuite.
27                            if (variant.flavorName == "minimal") {
28                                exclude(IviAppsuite.appStoreGroup) // Exclude the app store.
29                            }
30                        }
31                    }
32                }
33                services {
34                    applyGroups {
35                        includeDefaultPlatformGroups()
36                        includeDefaultAppsuiteGroups()
37                        if (variant.flavorName == "minimal") {
38                            exclude(IviAppsuite.appStoreGroup)
39                        }
40                    }
41                }
42            }
43        }
44    }
45}

Customization of TomTom Digital Cockpit platform and appsuite default frontends and services

The Gradle plugin applied in the example above id("com.tomtom.ivi.product.defaults.core") enables all the default frontends, frontend extensions, menu items and IVI service hosts from the TomTom Digital Cockpit platform and app suite for default runtime deployment.

If you only want to apply defaults from the TomTom Digital Cockpit platform without the appsuite default, you can achieve this by only applying the id("com.tomtom.ivi.platform.defaults.core") Gradle plugin. Additionally, if you want to include a selection of the TomTom Digital Cockpit Applications, you can apply the Gradle plugin for each individual TomTom Digital Cockpit Application.

To allow these Gradle plugins to be used in the Gradle projects, it is required to add them as implementation dependencies to the buildSrc. The following adds these dependencies:

1dependencies {
2    val iviPlatformVersion = "<TOMTOM-DIGITAL-COCKPIT-VERSION>"
3

4    // Optional: Plugin to configure in the default frontends and services from the TomTom Digital Cockpit platform.
5    implementation("com.tomtom.ivi.platform.gradle:api_defaults_core:$iviPlatformVersion")
6

7    // Optional: Plugin to configure in the defaults from Media TomTom Digital Cockpit Application.
8    implementation("com.tomtom.ivi.appsuite.gradle.media:api_appsuitedefaults_media:$iviPlatformVersion")
9    // Optional: Plugin to configure in the defaults from Communications TomTom Digital Cockpit Application.
10    implementation("com.tomtom.ivi.appsuite.gradle.communications:api_appsuitedefaults_communications:$iviPlatformVersion")
11    // Optional: Plugin to configure in the defaults from User Profiles TomTom Digital Cockpit Application.
12    implementation("com.tomtom.ivi.appsuite.gradle.userprofiles:api_appsuitedefaults_userprofiles:$iviPlatformVersion")
13    // Optional: Plugin to configure in the defaults from Vehicle Settings TomTom Digital Cockpit Application.
14    implementation("com.tomtom.ivi.appsuite.gradle.vehiclesettings:api_appsuitedefaults_vehiclesettings:$iviPlatformVersion")
15

16    // Optional: Plugin to configure in the defaults from App Store TomTom Digital Cockpit Application.
17    implementation("com.tomtom.ivi.appsuite.gradle.appstore:api_appsuitedefaults_appstore:$iviPlatformVersion")
18    // Optional: Plugin to configure in the defaults from Bluetooth TomTom Digital Cockpit Application.
19    implementation("com.tomtom.ivi.appsuite.gradle.bluetooth:api_appsuitedefaults_bluetooth:$iviPlatformVersion")
20    // Optional: Plugin to configure in the defaults from Companion TomTom Digital Cockpit Application.
21    implementation("com.tomtom.ivi.appsuite.gradle.companionapp:api_appsuitedefaults_companionapp:$iviPlatformVersion")
22    // Optional: Plugin to configure in the defaults from Hvac TomTom Digital Cockpit Application.
23    implementation("com.tomtom.ivi.appsuite.gradle.hvac:api_appsuitedefaults_hvac:$iviPlatformVersion")
24    // Optional: Plugin to configure in the defaults from Messaging TomTom Digital Cockpit Application.
25    implementation("com.tomtom.ivi.appsuite.gradle.messaging:api_appsuitedefaults_messaging:$iviPlatformVersion")
26    // Optional: Plugin to configure in the defaults from Navigation TomTom Digital Cockpit Application.
27    implementation("com.tomtom.ivi.appsuite.gradle.navigation:api_appsuitedefaults_navigation:$iviPlatformVersion")
28    // Optional: Plugin to configure in the defaults from System Status TomTom Digital Cockpit Application.
29    implementation("com.tomtom.ivi.appsuite.gradle.systemstatus:api_appsuitedefaults_systemstatus2:$iviPlatformVersion")
30    // Optional: Plugin to configure in the defaults from Vpa TomTom Digital Cockpit Application.
31    implementation("com.tomtom.ivi.appsuite.gradle.vpa:api_appsuitedefaults_vpa:$iviPlatformVersion")
32}

And then, apply necessary plugins in the build.gradle.kts of the project that builds the APK:

1plugins {
2    // Optional: To use the default frontends and services from the TomTom Digital Cockpit platform only.
3    // This plugin should be always applied first, before the rest of the `defaults` plugins.
4    id("com.tomtom.ivi.platform.defaults.core")
5

6    // Optional: To configure in the defaults from Media TomTom Digital Cockpit Application.
7    id("com.tomtom.ivi.appsuite.media.defaults.media")
8    // Optional: To configure in the defaults from Communications TomTom Digital Cockpit Application.
9    id("com.tomtom.ivi.appsuite.communications.defaults.communications")
10    // Optional: To configure in the defaults from User Profiles TomTom Digital Cockpit Application.
11    id("com.tomtom.ivi.appsuite.userprofiles.defaults.userprofiles")
12    // Optional: To configure in the defaults from Vehicle Settings TomTom Digital Cockpit Application.
13    id("com.tomtom.ivi.appsuite.vehiclesettings.defaults.vehiclesettings")
14

15    // Optional: To configure in the defaults from App Store TomTom Digital Cockpit Application.
16    id("com.tomtom.ivi.appsuite.appstore.defaults.appstore")
17    // Optional: To configure in the defaults from Bluetooth TomTom Digital Cockpit Application.
18    id("com.tomtom.ivi.appsuite.bluetooth.defaults.bluetooth")
19    // Optional: To configure in the defaults from Companion App TomTom Digital Cockpit Application.
20    id("com.tomtom.ivi.appsuite.companionapp.defaults.companionapp")
21    // Optional: To configure in the defaults from Hvac TomTom Digital Cockpit Application.
22    id("com.tomtom.ivi.appsuite.hvac.defaults.hvac")
23    // Optional: To configure in the defaults from Messaging TomTom Digital Cockpit Application.
24    id("com.tomtom.ivi.appsuite.messaging.defaults.messaging")
25    // Optional: To configure in the defaults from Navigation TomTom Digital Cockpit Application.
26    id("com.tomtom.ivi.appsuite.navigation.defaults.navigation")
27    // Optional: To configure in the defaults from System Status TomTom Digital Cockpit Application.
28    id("com.tomtom.ivi.appsuite.systemstatus.defaults.systemstatus")
29    // Optional: To configure in the defaults from Vpa TomTom Digital Cockpit Application.
30    id("com.tomtom.ivi.appsuite.vpa.defaults.vpa")
31}

Note: Some of these Gradle plugins add menu items. The order in which these plugins are applied, defines the order of the menu items in the main menu frontend.

Module references

Before adding frontends or IVI service hosts, our recommendation is to implement the ModuleReference class.

The ModuleReference implementation class can be used in the build configurations of the frontend and IVI service host later on. It will be used to refer to modules that implement the frontend or IVI service host, and also to resolve the full-qualified package names.

Create the ModuleReference implementation class <ProjectName>ModuleReference in buildSrc. You can use ExampleModuleReference.kt in buildSrc/src/main/kotlin/com/tomtom/ivi/buildsrc/dependencies/ as an example.