Integrating Amazon Alexa

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

Additional requirements exist for using Amazon Alexa in your TomTom Digital Cockpit product.

TomTom Digital Cockpit can support the use of multiple voice personal assistants (VPAs) in a single product. The end-user can invoke each one with a separate wake-up-word and then use them one at a time. TomTom Digital Cockpit comes with a pre-integration of Amazon's VPA, Alexa, specifically Alexa Auto.

To be able to use Alexa in your product, you will need to integrate an additional Android APK in your development platform and configure some development account information into your application. This page explains how to do this.

Integrating Amazon Alexa on Hardware

You can skip this section if you are trying to run Amazon Alexa on the TomTom Digital Cockpit emulator or on the TomTom Digital Cockpit reference hardware (Samsung Galaxy S5e WiFi tablet).

Follow these steps to integrate Amazon Alexa on your custom hardware platform:

• Download the Alexa LM app APK:
  • lm-app-en_US-4.1.1.apk
• Sign the Alexa APK with the same key that was used for signing the TomTom Digital Cockpit APK
• Install the signed Alexa APK on your device:
  Copyadb install lm-app-en_US-4.1.1-signed.apk

  adb install lm-app-en_US-4.1.1-signed.apk

• Set the SELinux policy on your device to be permissive:
  Copyadb shell setenforce permissive

  adb shell setenforce permissive

  Alternatively, add the line below to one of your SELinux policy files:
  Copy# Allow platform_app to manage UDS sockets. This is needed both # for Navkit and Alexa Local Voice Controller. allow platform_app app_data_file:sock_file create_file_perms;

  1# Allow platform_app to manage UDS sockets. This is needed both
  2# for Navkit and Alexa Local Voice Controller.
  3allow platform_app app_data_file:sock_file create_file_perms;

Integrating Amazon Alexa in your product

To be able to use Alexa in your TomTom Digital Cockpit-based product, there are some steps that need to be followed:

• Apply the Alexa plugins.
• Register your Alexa product with Amazon.
• Specify your Amazon Alexa IDs.

Apply the Alexa plugins

Declare a reference to the Alexa plugin library in the /build-logic/libraries.versions.toml file:

gradlePluginApiAppsuiteDefaultsAlexa = { module = "com.tomtom.ivi.appsuite.gradle.alexa:api_appsuitedefaults_alexa", version.ref = "iviPlatform" }

Add a dependency on the Alexa plugin library in the /buildSrc/build.gradle.kts file:

1dependencies {
2    ...
3    implementation(libraries.gradlePluginApiAppsuiteDefaultsAlexa)
4    ...
5}

Apply the Alexa plugins in the product's build.gradle.kts file:

1plugins {
2    ...
3    id("com.tomtom.ivi.appsuite.alexa.defaults.alexa")
4    id("com.tomtom.ivi.appsuite.alexa.defaults.config")
5}

Explicitly include the Alexa group (this is an opt-in group) in the product's iviInstances and services in the build.gradle.kts file.

1ivi {
2    application {
3        enabled = true
4        iviInstances {
5            create(IviInstanceIdentifier.default) {
6                applyGroups {
7                    ...
8                    include(
9                        IviAppsuite.alexaGroup // explicit opt-in group.
10                    )
11                    ...
12                }
13            }
14        }
15        services {
16            applyGroups {
17                ...
18                include(
19                    IviAppsuite.alexaGroup // explicit opt-in group.
20                )
21                ...
22            }
23        }
24    }
25}

These plugins will add the Alexa TomTom Digital Cockpit application to your product and will provide a simple way to configure the Alexa application.

Register your Alexa product with Amazon

In order to use Amazon Alexa as part of your TomTom Digital Cockpit-based product, some information is needed from Amazon's developer site.

A list of the prerequisites is provided below:

• An Amazon Developer Account. If you are reading this document, then you or your company will already have communication or a business relationship with Amazon, who will have made Alexa Auto dependencies and non-public documentation available to you. Your Amazon contact can assist you with any issues relating to Amazon accounts. TomTom has no control over your Amazon Developer Account.
• Within your Amazon Developer Account, an Alexa Voice Service product and security profile should have been set up. See Amazon's instructions or speak to your Amazon contact to understand how to do this.
• You will need your product's Product ID and Client ID which can be obtained from the Amazon Voice Service console which you can access from within your Amazon Developer Account.

Specify your Amazon Alexa IDs

Now that you have your Product ID and Client ID ready, you can configure the product so that they can be used with the TomTom Digital Cockpit SDK.

The Amazon Alexa IDs can be configured in various ways depending on your development and production needs:

• Via local.properties or Gradle properties.
• By overriding the static configuration values in Android resources.
• With a static configuration provider.

Via local.properties or Gradle properties

The Product ID and Client ID are specified by the properties named alexaDeviceInfoProductId and alexaDeviceInfoClientId respectively.

The easiest way is to set the two properties via the top-level local.properties file or as Gradle properties.

This option is preferred if you do not want to add the ID to your SCM (such as Git). In this case you can configure the IDs in the local.properties file (which is not supposed to be added to an SCM) or configure the key in the gradle.properties file in the Gradle user home directory. The latter option makes the IDs available in any Gradle project.

By overriding the static configuration values in Android resources

You can override static configuration values in Android resources.

For example in the alexa_ids.xml file:

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<resources>
3    <!--The client ID used to authorize the client with AVS.-->
4    <string name="alexaDeviceInfoClientIdConfigKey">my-client-id-from-Amazon-developer-site</string>
5    <!--The product ID used to authorize the client with AVS.-->
6    <string name="alexaDeviceInfoProductIdConfigKey">MyProductId</string>
7</resources>

Disable the build-time check by setting the disableAlexaDeviceIdBuildTimeCheck property to true in the top-level gradle.properties file:

disableAlexaDeviceIdBuildTimeCheck=true

or by not applying the com.tomtom.ivi.appsuite.alexa.defaults.config Gradle plugin in the build.gradle.kts file.

This option is preferred if you want to simplify the project setup. However, it requires the IDs to be added to your SCM.

With a static configuration provider

Last but not least is to configure a static configuration provider in the Android Application class that provides the key. For this you can use an AlexaDeviceInfoStaticConfigurationProvider instance. The ExampleApplication class contains an example explaining how to configure it.

Disable the build-time check by setting the disableAlexaDeviceIdBuildTimeCheck property to true in the top-level gradle.properties file:

disableAlexaDeviceIdBuildTimeCheck=true

or by not applying the com.tomtom.ivi.appsuite.alexa.defaults.config Gradle plugin.

This option is preferred if you want to obtain and configure the IDs at runtime.

Configuring Alexa

Static configuration

Setting up your Amazon Alexa IDs allows your product to access Alexa so that your end-users can use the voice assistant. There are additional parameters, however, which can be set to give Alexa more information about the product and vehicle in which it is running. These additional parameters can be configured by overriding the static configuration values in Android resources or using a static configuration provider.

The additional parameters correspond to the configuration values which Amazon have documented in their VehicleConfiguration reference page and are also listed in the table below:

Dynamic configuration

The VpaMediatorSettingsService defines a set of VPA-related settings that the service clients are able to change at runtime. The default values of these settings for the Alexa VPA are defined by a DynamicConfigurationProvider, but, if necessary, they can be overriden by providing a custom dynamic configuration. More information on dynamic configurations is available in the configuration framework page. The dynamic configuration values are listed in the table below: