Integrate TomTom Digital Cockpit into a Gradle Project

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

1fun RepositoryHandler.tomtomNexus() {
2 // Configure TomTom Digital Cockpit repository.
3 maven("https://repo.tomtom.com/repository/ivi") {
4 credentials {
5 username = extra["nexusUsername"].toString()
6 password = extra["nexusPassword"].toString()
7 }
8 }
9}
10
11pluginManagement {
12 repositories {
13 // Local artifact cache.
14 mavenLocal()
15
16 // External repositories.
17 mavenCentral()
18 google()
19 maven("https://plugins.gradle.org/m2/")
20 }
21}
22
23// Doing it in this way (as opposed to `pluginManagement{repositories{...}}`) allows using the
24// `tomtomNexus` function defined above and avoids duplicating the repository details.
25// The downside is that you can not use plugins in the `settings.gradle.kts` file, if that plugin
26// depends on any of the repositories from this block.
27// See https://docs.gradle.org/current/userguide/upgrading_version_5.html#the_pluginmanagement_block_in_settings_scripts_is_now_isolated
28pluginManagement.repositories {
29 // TomTom's Nexus repository for the Digital Cockpit.
30 tomtomNexus()
31}
32
33dependencyResolutionManagement {
34 repositories {
35 // Local artifact cache.
36 mavenLocal()
37
38 // TomTom's Nexus repository for the Digital Cockpit.
39 tomtomNexus()
40
41 // TomTom's Nexus repository for the Connectivity Agent.
42 maven("https://maven.tomtom.com:8443/nexus/content/repositories/releases/")
43
44 // External repositories.
45 mavenCentral()
46 google()
47 maven("https://plugins.gradle.org/m2/")
48 }
49}

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

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

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 for versioning the APK based on the Git repository information.
8 implementation("com.tomtom.ivi.platform.gradle:api_tools_version:$iviPlatformVersion")
9
10 // Optional: Plugin to use the default frontends and services from the TomTom Digital Cockpit platform
11 // and app suite.
12 implementation("com.tomtom.ivi.product.gradle:api_productdefaults_core:$iviPlatformVersion")
13
14 // Mandatory: For IVI services plugins.
15 implementation(iviDependencies.gradlePluginKsp)
16}

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
10 // Optional: Plugin for versioning the APK based on the Git repository information.
11 id("com.tomtom.ivi.platform.tools.version")
12}

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 includeDefaultGroups() // include all defaults.
8 include(IviAppsuite.alexaGroup) // include explicit opt-in app suite plugin.
9 exclude(IviPlatform.debugGroup) // exclude the default debug group.
10 }
11 frontends {
12 replace(userProfileFrontend, accountFrontend)
13 remove(mediaFrontend)
14 }
15 menuItems {
16 add(myMenuItem)
17 replace(userProfileMenuItem, accountMenuItem to accountFrontend)
18 }
19 }
20 }
21 services {
22 applyGroups {
23 includeDefaultGroups()
24 include(IviAppsuite.alexaGroup)
25 exclude(IviPlatform.debugGroup)
26 }
27 }
28 }
29}

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 excludes the debugGroup for the release build only.

1androidComponents {
2 onVariants { variant ->
3 variant.ivi {
4 application {
5 enabled = true
6 iviInstances {
7 create(IviInstanceIdentifier.default) {
8 applyGroups {
9 includeDefaultGroups() // include all defaults.
10 if (variant.buildType == "release") {
11 exclude(IviPlatform.debugGroup) // exclude the default debug group.
12 }
13 }
14 }
15 }
16 services {
17 applyGroups {
18 includeDefaultGroups()
19 if (variant.buildType == "release") {
20 exclude(IviPlatform.debugGroup) // exclude the default debug group.
21 }
22 }
23 }
24 }
25 }
26 }
27}

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.