Installing TomTom Digital Cockpit on Hardware

For installation on hardware and enabling all the functionality, you need to sign the application, install it on the system partition, and do some additional configurations as explained below.

The TomTom Digital Cockpit SDK comes with a prebuilt emulator image and a prebuilt image for our reference hardware (Samsung Galaxy S5E tablet), based on version 19.1 of LineageOS, which in turn is based on Android 12.

Read through the following information to use TomTom Digital Cockpit on your hardware.

Platform requirements

Automotive vs. plain Android

In principle, TomTom Digital Cockpit can run on any Android device with a TomTom Digital Cockpit-supported CPU architecture, but the experience will be poorer. If using non-automotive Android, for example, Bluetooth will not behave as expected. This is because standard Android uses Headset and Handsfree server profiles, as the mobile phone is the audio source that goes to for example a Bluetooth headset. Android Automotive instead enables the client profile, as the car head unit connects to a mobile phone instead, and streams from it. Therefore, do not use Bluetooth features such as calling, companion app integration, or media streaming.

Also, support for secondary displays like a cluster display and air conditioning controls is missing.

Android Automotive will support all car-related functionality such as calling, media streaming, and air conditioning controls.

More limitations are present in certain domains. Read below for more information.

System signature vs. Root access

To enable some features, especially regarding media, the application needs to be signed and installed on the system partition. You can read more about privileged and system permissions here.

In particular, it is necessary to re-sign the TomTom Digital Cockpit APK with the same key that was used to sign the system apps on your Android platform, for it to be granted all the necessary system permissions. If this is not possible, there will be some limitations; those are explained later in this page.

Sign the TomTom Digital Cockpit APK with the same key that was used for signing the system image

The TomTom Digital Cockpit platform debug key and password files (used for the pre-created tablet and emulator images) are in the keystore directory in the example source.

If you're not using the pre-created tablet or emulator images, but instead have a custom AOSP-based build, you can simply replace these with your own platform keys and rebuild. By default, all the signing keys used by the AOSP build system can be found in the build/target/product/security/ directory of the AOSP source tree. To re-sign the TomTom Digital Cockpit APK with your own platform key, run this command from the root of the AOSP source tree:

java -Djava.library.path=out/host/linux-x86/lib64 -jar out/host/linux-x86/framework/signapk.jar build/target/product/security/platform.x509.pem build/target/product/security/platform.pk8 ttdc.apk ttdc-signed.apk

For actual development work, it is recommended to create a new Android keystore file out of the platform keys, so that APKs can be built then directly signed using the platform keys. A shell script such as keytool-importkeypair can be used to make an Android keystore file out of AOSP certificates.

Push the signed APK to the system partition

• Remount the system partition to be writeable.
• Copy the privapp-permissions-tomtom-ivi.xml file from the permissions directory to /system/etc/permissions on the device. Don't forget to change the package name when installing your own Digital Cockpit app.
• Install the Digital Cockpit APK that you have built, into the /system/priv-app directory on the device.

1$ adb remount
2$ adb push privapp-permissions-tomtom-ivi.xml /system/etc/permissions/
3$ adb shell mkdir /system/priv-app/MyDigitalCockpitApp
4$ adb push MyDigitalCockpitApp.apk /system/priv-app/MyDigitalCockpitApp/

Verify signatures

To ensure that signing of the final application is correct, retrieve the signature of the platform:

$ adb shell dumpsys package android | grep signatures
signatures=PackageSignatures{efb5875 version:3, signatures:[e977ab68], past signatures:[]}

The signature: hash in square brackets, here [e977ab68], is the platform signature's hash.

Then retrieve the signature of the package of the installed APK (if unknown, check with adb shell pm list packages):

$ adb shell dumpsys package $PACKAGE_NAME_HERE | grep signatures
signatures=PackageSignatures{33fffff version:3, signatures:[e977ab68], past signatures:[]}

If the signature: hashes in square brackets match, the app is signed correctly.

When platform signing is not possible

If it's not possible to sign the APK with the system signature, there will be the following limitations (note that you should still follow the two other steps):

• Media being played by the system will not be visible in the main process panel, nor will it be possible to control it.
• The media source Spotify will never work: TomTom Digital Cockpit needs to be signed with platform keys for Spotify to communicate with it.

To work around the first problem, enable media notification access. This fixes access to all media sources except Spotify.

$ adb root
$ adb shell cmd notification allow_listener com.example.mydigitalcockpitapp/com.tomtom.ivi.appsuite.media.plugin.service.media.MediaNotificationListener

Spotify only communicates with system apps signed with the platform signature, so if your APK is unsigned or not a system app, this command will only allow you to control Spotify playback started with the default AOSP media player, but not to browse Spotify content from within TomTom Digital Cockpit.

Debug builds and startup issues

Normally release builds will be installed and compiled ahead of time for speed optimization. However, by default on hardware platforms, debug builds are not compiled for speed optimization at installation. This results in a slower start up of the application and may even cause it to time out, because the compilation is done just in time when the application starts and will happen for each of its processes.

To avoid this, you can manually compile the application for speed optimization at installation by executing the following command after installation (replacing com.example.mydigitalcockpitapp with your own application package name):

$ adb root
$ adb shell cmd package compile -m speed -f com.example.mydigitalcockpitapp

The images for the Emulator and the Reference Tablet already support ahead of time compilation for debug builds. There is no need to run the above command on these images.

If you create your own image and want to enable ahead of time compilation for installation of debug builds, you can apply this patch.

Domain-specific notes

Text-To-Speech

Since Android Automotive doesn't come with a TTS engine by default, you will need to install a TTS engine APK for Messaging TTS and Navigation voice instructions to work.

There are many TTS engines available for Android, our reference hardware currently uses the Google Text-to-Speech application.

Multimedia sources

TomTom Digital Cockpit supports any Android Automotive media source that can also be found in the Android Automotive Play Store.

By default TomTom Digital Cockpit does not support advanced functionality, such as custom actions. These add capabilities unique for a single source, such as liking a song. Support for them can be added via a TomTom Digital Cockpit plugin.

If a multimedia app requires a sign in, a modal panel allowing you to do so will open when selecting the app.

If the hardware and AOSP build both support Radio (FM/AM/DAB), the radio multimedia source in TomTom Digital Cockpit should also work (albeit with a confusing user interface, as no specialization work for radio has yet been made).

Phone

To automatically configure TomTom Digital Cockpit as the default dialer app, set TomTom Digital Cockpit as the default dialer in system settings (Settings > Apps & Notifications > Default apps).

Pair a phone with Bluetooth and ensure that all necessary profiles (such as Phone calls, Media audio, Text messages and Contact Sharing) are enabled by tapping on the phone name in settings. You should thereafter be able to use this phone from TomTom Digital Cockpit.