Replace Navigation
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.IviServiceHostConfig23import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.activeRouteInformationStubServiceHost4import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.guidanceInstructionsStubServiceHost5import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.tripStubServiceHost6import com.tomtom.ivi.product.gradle.api.productdefaults.navstubs.vehicleDrivingStateStubServiceHost7import 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 vehicleLocationStubServiceHost7)
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 theapplyGroups{}
statement:
1ivi {2 application {3 enabled = true4 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 theexclude()
statement in the next step.
1import com.tomtom.ivi.platform.gradle.api.common.iviapplication.config.IviPlatform2import com.tomtom.ivi.platform.gradle.api.defaults.config.navigationGroup3import 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 line11 // IviAppsuite.navigationGroup, // Remove this line12 IviAppsuite.systemStatusGroup,13 IviAppsuite.userProfilesGroup,14 IviAppsuite.vehicleSettingsGroup15 )16 exclude(17 IviAppsuite.navAppComponentsGroup,18 IviAppsuite.navigationGroup,19 IviPlatform.navAppComponentsGroup,20 IviPlatform.navigationGroup21 )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
.