Run the Application on a Reference Tablet

Last edit: 2023.09.25

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

If you are using Nexus, please see the Artifactory migration instructions.

Tablet specification

The tablet we are using for this tutorial is the Samsung Galaxy Tab S5e WiFi (SM-T720). There are two variants available:

4GB RAM and 64GB internal storage.
6GB RAM and 128GB internal storage.

Both variants will work with our OTA image, but we recommend using the 6GB RAM variant with 128GB internal storage. This variant allows you to run the TomTom Digital Cockpit app on multiple screens without memory issues.

Installation guide

If the tablet has already been flashed with the LineageOS image, it can be upgraded by following the instructions in Upgrade Tablet.

The subsequent instructions aim to provide a comprehensive guide for successfully unlocking the bootloader, flashing the reference hardware, and installing LineageOS on your Android tablet.

The instructions are based on the official LineageOS installation instructions.

Downloading the required files

TomTom takes no responsibility for any damages that may occur from installing or using the freely available third-party tools and files mentioned on this page.

Download the following files:

Odin (Samsung flashing tool).
vbmeta.tar.
The latest img.tar file from TWRP (Team Win Recovery Project).

The reference tablet image

Download the latest release of the OTA image (file ending with -ota.zip) from Artifactory using your company domain email address and password.

Setup

Install the Odin tool on a Windows machine.
Install the adb tool on any machine, it does not have to be the above-mentioned Windows machine.

Preparing for bootloader unlock

Enabling developer options

Connect the tablet to a WiFi network to enable the OEM unlock option.
Open the Settings app and go to About tablet > Software Information.
Tap on Build number seven times to enable Developer Options.

Enabling OEM unlock

In Settings > Developer Options, enable OEM unlocking and USB debugging.
If either option is not visible, ensure a working WiFi connection and reopen Developer Options.

Bootloader unlock

Entering bootloader mode

Power off the tablet by pressing and holding the Power and Volume Down buttons, then selecting Power off.
Connect the tablet to the machine with adb installed using a USB cable.
Press and hold the Power, Volume Up, and Volume Down buttons simultaneously.
The tablet should display a blue screen with the bootloader unlock option.

Unlocking the bootloader

Long press the Volume Up button to select the Device unlock mode page.
Press the Volume Up button again to unlock the bootloader.
The device will perform a factory reset and restart into Android.

Factory reset

Verifying OEM unlock and connectivity

Verify that the OEM Unlocking option is still enabled in the Developer Options menu. Otherwise go through preparing for bootloader unlock section.
Ensure the tablet is connected to WiFi and that the OEM unlocking option is visible.

Entering download mode

In Settings > Developer Options, enable USB debugging.
Allow the machine to access the tablet's data, by selecting Allow on all of the pop-up windows.
Enter the download mode using the following command:
```
adb reboot download
```

Performing factory reset

Connect your tablet to the Windows machine with Odin installed. If you have adb and Odin installed on the same machine you do not need to do anything.
Launch the Odin tool installed on the Windows machine.
Check for a connected device in the top left corner of the Odin window, for example COM1.
Check the box next to the AP button and click it.
A pop-up dialog will appear. Select the previously downloaded vbmeta.tar file, then press the Start button, which should reboot the device.
The device will fail to restart and present several options: Try again, Factory data reset and View recovery logs.
Use the Volume Down button to select Factory data reset and press Power to make the selection.
Confirm factory reset by pressing Volume Down and Power buttons.

Flashing TWRP recovery

Reboot into TWRP tool

Go through the factory reset section until you reach the pop-up dialog prompting file selection in Odin. Select the previously downloaded TWRP file instead of the vbmeta.tar.
Press the Start button in Odin, while holding Volume Up button on the tablet until flashing is complete.
The tablet should now reboot into TWRP recovery.

Installing LineageOS

TWRP recovery options

The recovery tool will ask whether to keep System Read Only.
Check the "Never show this screen during boot again" box.
Swipe the bottom bar to allow system modifications.

Wiping data

Select Wipe in the recovery menu.
Select Format Data and continue with the formatting process.
This will remove encryption and delete all files stored in the internal storage.

Wiping cache and system

Return to the previous menu and select Advanced Wipe.
Select the Cache and System partitions.
Swipe to Wipe.

Upgrade tablet

Connect the tablet to the machine with adb installed. If the tablet has already been flashed with the LineageOS image, it can be upgraded with any machine that has adb installed, using the following command:
```
1adb root
2adb push lineageos-gts4lvwifi-<version>-ota.zip /data/lineageos-gts4lvwifi-ota.zip && \
3adb shell "echo --update_package=/data/lineageos-gts4lvwifi-ota.zip > /cache/recovery/command" && \
4adb reboot recovery
```

Installing TomTom Digital Cockpit on the reference tablet

Download the template application APK

If you have not been granted access yet, please follow these instructions.

Download the template app APK (use your company's email address and password):

template-app-arm64-v8a

This section of the tutorial will guide you through the process of installing TomTom Digital Cockpit on the reference tablet. By following these steps, you will be able to install the application on the data partition, and configure it to enable all the functionality.

Install the APK on the tablet

Make sure your tablet is connected to the machine with adb installed.
Install the Digital Cockpit APK on the data partition.
```
adb install template-app-arm64-v8a-debug.apk.apk
```

The Digital Cockpit app should now appear in the All apps menu.

Reflashing the tablet

If the tablet is taking a long time to boot after a Restart or Power off, follow these steps:

Connect the tablet to the machine with adb installed.
Run the following command:
```
adb reboot recovery
```
Select Apply update > Apply from ADB.
Run the following command:
```
adb sideload lineageos-gts4lvwifi-<version>-ota.zip
```
After the sideload is complete, select Reboot system now.