Develop with the SDK

Last edit: 2024.06.19

Follow all instructions on this page to build your own Digital Cockpit application using the SDK source code.

Download the SDK source code

The SDK source code is available on GitHub. You can clone the sources with the following command:

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

Install the Java Development Kit

TomTom Digital Cockpit requires OpenJDK 17, which is a free and open-source implementation of the Java platform.

Linux

To install it, run the following command in a terminal:

sudo apt install openjdk-17-jdk

You might already have other versions of JDK installed. Verify this by running:

sudo update-java-alternatives -l

If you see the following output, then you only have OpenJDK and you are all set:

java-1.17.0-openjdk-amd64      1711       /usr/lib/jvm/java-1.17.0-openjdk-amd64

If you see multiple Java versions in the output, you need to make sure you have the correct one set as the default:

sudo update-java-alternatives -s java-1.17.0-openjdk-amd64

Then you can verify that the correct Java version is in use by running:

java --version

You should see output similar to this:

1openjdk version "17.0.7" 2023-04-18
2OpenJDK Runtime Environment (build 17.0.7+7-Ubuntu-0ubuntu122.04.2)
3OpenJDK 64-Bit Server VM (build 17.0.7+7-Ubuntu-0ubuntu122.04.2, mixed mode, sharing)

If you still see the old one, you might need to log out and back in.

Mac

Adoptium Temurin JDK Java version 17 can easily be installed on Mac using Homebrew:

1brew tap homebrew/cask-versions
2brew info temurin17
3brew install temurin17

Then you can verify that the correct Java version is in use by running:

java --version

You should see output similar to this:

1openjdk 17.0.7 2023-04-18
2OpenJDK Runtime Environment Temurin-17.0.7+7 (build 17.0.7+7)
3OpenJDK 64-Bit Server VM Temurin-17.0.7+7 (build 17.0.7+7, mixed mode)

Windows

Navigate to the Adoptium Temurin JDK website.

Select Windows, your CPU architecture, and JDK 17 - LTS from the dropdown menu.

Download and run the .msi installer.

Enable the Set JAVA_HOME variable if you intend to build from the command-line.

Then you can verify that the correct Java version is in use by running:

java -version

You should see output similar to this:

1openjdk version "17.0.7" 2023-04-18
2OpenJDK Runtime Environment Temurin-17.0.7+7 (build 17.0.7+7)
3OpenJDK 64-Bit Server VM Temurin-17.0.7+7 (build 17.0.7+7, mixed mode, sharing)

Configure Android Studio

Custom configuration of Android Studio is required to work with the Digital Cockpit SDK.

Install Android Studio

The minimum required version of Android Studio is Koala | 2024.1.1.

Download Android Studio and follow the installation instructions.
Start Android Studio and open the SDK Examples project you cloned earlier.

Android Studio will try to sync the project, but you need to configure credentials first for it to succeed.

Install Android SDK

Digital Cockpit runs on Android 12L. The Android 12L SDK needs to be installed from the SDK Manager in Android Studio.

Navigate to Tools > SDK Manager.
Navigate to the SDK Platforms tab.
Find Android 12L (Sv2).
Check the box next to that version.
Click Apply.

The Android 12L SDK will now be installed.

Configure the JDK

Android Studio needs to use the JDK you installed earlier.

Linux and Windows

Navigate to File > Settings > Build, Execution, Deployment > Build Tools > Gradle.
From the dropdown menu next to Gradle JDK select the OpenJDK version you installed earlier.
Click Apply.

Mac

Navigate to Android Studio > Preferences > Build, Execution, Deployment > Build Tools > Gradle
From the dropdown menu next to Gradle JDK select the OpenJDK version you installed earlier.
Click Apply.

Configure your credentials

If you haven't created an Artifactory identity token yet, please follow these instructions.

You must configure your company domain email address and Artifactory identity token so that binaries can be retrieved while building the project.

Linux and Mac

Navigate to your system's Gradle directory:

cd ~/.gradle

Create a gradle.properties file:

touch gradle.properties

Edit the gradle.properties file and add your credentials:

artifactoryEdgeUser=<your-company-email-address>
artifactoryEdgeToken=<your-Artifactory-identity-token>

Windows

Navigate to your system's Gradle directory:

cd %USERPROFILE%\.gradle

Create a gradle.properties file:

notepad gradle.properties

Edit the gradle.properties file and add your credentials:

artifactoryEdgeUser=<your-company-email-address>
artifactoryEdgeToken=<your-Artifactory-identity-token>

Build the template application

Now you can build your own APK from the SDK source files.

Linux and Mac

Run the following command from the root of the project:

./gradlew template_app:assembleRelease

You will find the generated APK in the following directory:

tomtom-digital-cockpit-sdk-examples/template/app/build/outputs/apk/release

Windows

Run the following command from the root of the project:

set ANDROID_HOME=C:\Users\you\AppData\Local\Android\Sdk
.\gradlew.bat template_app:assembleRelease

You will find the generated APK in the following directory:

tomtom-digital-cockpit-sdk-examples\template\app\build\outputs\apk\release

Avoid the green hammer icon in Android Studio as this will build the entire project, so including all example apps and the template app.

Run the application

You can run the APK you just generated on an emulator or on the reference tablet:

Have a look at the tutorials to explore what the Digital Cockpit SDK example code has to offer.