Developer

Replace Navigation

Last edit: 2024.05.31
Important note:

The TomTom Digital Cockpit SDK is not available for general use. Please contact us for more information.

The TomTom Digital Cockpit (TTDC) platform contains the TomTom Automotive UI for navigation. This can be replaced by a customer’s own navigation experience. However, some of the platform and applications have dependencies on some of the navigation data. This means that a number of public interfaces need an implementation in the replacement for TomTom's Automotive UI.

Note: To set up your build environment for TTDC, please see our Getting Started guide: Getting started. Instructions about API keys can be ignored as they are only used for TomTom navigation-related features.

First download the sources for our example application from GitHub (you should have received instructions on how to access this, after signing the license agreement):

git clone https://github.com/tomtom-international/tomtom-digital-cockpit-sdk-examples.git

Note: The example sources consist of several different example applications, one of which is the template app. This example only contains what is needed to include the TTDC platform core experience (and no additional examples).

Getting started with a clean template project.

  • Start by removing the other examples from the sources.
rm -rf examples/
  • Add the plugin containing the stubbed service hosts.

Open ./build-logic/libraries.versions.toml and add the api_productdefaults_navstubs plugin:

gradlePluginApiProductDefaultsNavStubs = { module = "com.tomtom.ivi.product.gradle:api_productdefaults_navstubs", version.ref = "iviPlatform" }
  • Add the library as a dependency in ./buildSrc/build.gradle.kts:
implementation(libraries.gradlePluginApiProductDefaultsNavStubs)
  • Update the template app build file. Open ./template/app/build.gradle.kts and add the navstubs plugin after the core one:
1plugins {
2    id("com.tomtom.ivi.product.defaults.core")
3    id("com.tomtom.ivi.product.defaults.navstubs") 
4}
  • Add the following imports to ./template/app/build.gradle.kts:
1import com.tomtom.ivi.platform.gradle.api.common.iviapplication.config.IviServiceHostConfig
2

3import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.activeRouteInformationStubServiceHost
4import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.guidanceInstructionsStubServiceHost
5import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.tripStubServiceHost
6import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.vehicleDrivingStateStubServiceHost
7import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.vehicleLocationStubServiceHost
  • Create a list of the stubbed ServiceHosts in ./template/app/build.gradle.kts.

This can be used to replace the existing services whilst you develop your own replacements.

1private val navigationStubServiceHosts: List<IviServiceHostConfig> = listOf(
2    activeRouteInformationStubServiceHost,
3    guidanceInstructionsStubServiceHost,
4    tripStubServiceHost,
5    vehicleDrivingStateStubServiceHost,
6    vehicleLocationStubServiceHost
7)

Note: When you later add your own implementations for these, you need to remove the corresponding ServiceHost from this list.

  • Add the navigationStubServiceHosts list to the IVI build configuration in the services section, after the applyGroups{} statement:
1ivi {
2    application {
3        enabled = true
4        iviInstances {
5            create(IviInstanceIdentifier.default) {
6                applyGroups {
7                    selectGroups()
8                }
9            }
10        }
11        services {
12            applyGroups {
13                selectGroups()
14            }
15            addHosts(navigationStubServiceHosts)
16        }
17    }
18}
  • Add the following imports to ./template/app/build.gradle.kts to be able to use them in the exclude() statement in the next step.
1import com.tomtom.ivi.platform.gradle.api.common.iviapplication.config.IviPlatform
2import com.tomtom.ivi.platform.gradle.api.defaults.config.navigationGroup
3import com.tomtom.ivi.platform.gradle.api.defaults.navappcomponents.navAppComponentsGroup
  • Exclude navigation related features from the build.

Remove the navigation related groups from the include() and add the following exclude() statement:

1fun IviDefaultsGroupsSelectionConfigurator.selectGroups() {
2    includeDefaultPlatformGroups()
3    include(
4        IviAppsuite.appStoreGroup,
5        IviAppsuite.bluetoothGroup,
6        IviAppsuite.communicationsGroup,
7        IviAppsuite.hvacGroup,
8        IviAppsuite.mediaGroup,
9        IviAppsuite.messagingGroup,
10        // IviAppsuite.navAppComponentsGroup,  // Remove this line
11        // IviAppsuite.navigationGroup,        // Remove this line
12        IviAppsuite.systemStatusGroup,
13        IviAppsuite.userProfilesGroup,
14        IviAppsuite.vehicleSettingsGroup
15    )
16    exclude(
17        IviAppsuite.navAppComponentsGroup,
18        IviAppsuite.navigationGroup,
19        IviPlatform.navAppComponentsGroup,
20        IviPlatform.navigationGroup
21    )
22}
  • You can now build a TTDC product without navigation and are ready to start implementing your own.
./gradlew assembleDebug

Adding your own map

To show a map provided by your own navigation component, you need to create a frontend plugin that adds a HomePanel which exposes a fragment containing your map. For instructions on how to create your own frontend plugin, please see our tutorials on the developer portal: Create a frontend plugin.

Implementing a navigation interface

If you want to provide your own navigation experience you need to provide an implementation for the following list of navigation interfaces. For instructions on how to create your own Services, please see our tutorials on the developer portal: Create an IVI service.

These are the interfaces from which the TTDC platform expects data and needs to be implemented.

ActiveRouteInformationService

This interface provides information about an active route, for example:

  • Estimated Time of Arrival
  • Remaining duration
  • Remaining distance
  • Traffic delays
  • etc...

See the complete API documentation: ActiveRouteInformationService.

GuidanceInstructionsService

This interface provides information about the next guidance instruction. Clients can also subscribe to receive events to know when to display next instruction cues to the user.

See the complete API documentation: GuidanceInstructionsService.

TripService

This provides an interface to perform operations on a Trip, for example:

  • Planning a trip
  • Trip planning complete callbacks
  • Cancelling a trip

See the complete API documentation: TripService.

VehicleDrivingStateService

Provides information about the driving state of the vehicle (either driving or not driving). For example, this is used by the safety lock feature in the platform. For more information, please see: Safety lock.

See the complete API documentation: VehicleDrivingStateService.

VehicleLocationService

VehicleLocationService exposes information related to the current driving situation and to the current location, regardless of whether a trip is planned. For example:

  • Last known location (in latitude/longitude).
  • Which source was used for the location (saved or live from the platform).

See the complete API documentation: VehicleLocationService.