Developer

Replace Navigation

Last edit: 2023.07.27

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.

Navigation interface that needs implementing

If you want to provide your own navigation experience you need to provide an implementation for the following list of navigation interfaces. These are interfaces that the TTDC platform is expecting data from.

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, 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, or not. 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.

Get started

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

To set up your environment for building for TTDC, please see our Getting Started guide: Getting started

Note: Instructions about API keys can be ignored, as they are only used for navigation related features.

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).

  1. Start by removing the other examples from the sources.
rm -rf examples/
  1. 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" }
  1. Add the library as a dependency in ./buildSrc/build.gradle.kts:
implementation(libraries.gradlePluginApiProductDefaultsNavStubs)
  1. 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}
  1. 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
  1. 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.

  1. 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}
  1. 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
  1. 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.companionAppGroup,
8        IviAppsuite.hvacGroup,
9        IviAppsuite.mediaGroup,
10        IviAppsuite.messagingGroup,
11        // IviAppsuite.navAppComponentsGroup,  // Remove this line
12        // IviAppsuite.navigationGroup,        // Remove this line
13        IviAppsuite.systemStatusGroup,
14        IviAppsuite.userProfilesGroup,
15        IviAppsuite.vehicleSettingsGroup
16    )
17    exclude(
18        IviAppsuite.navAppComponentsGroup,
19        IviAppsuite.navigationGroup,
20        IviPlatform.navAppComponentsGroup,
21        IviPlatform.navigationGroup
22    )
23}
  1. You can now build a TTDC product without navigation and are ready to start implementing your own.
./gradlew assembleDebug

For instructions on how to create your own Frontends and Services, please see our tutorials on the developer portal: