Integrating Deftpower

In order to make use of the Deftpower integration offered by TomTom Digital Cockpit, your company needs to contact Deftpower for access to their service.

Deftpower is an e-mobility service provider (eMSP) which streamlines the end-to-end electric vehicle (EV) charging process. In the context of TomTom Digital Cockpit (TTDC), Deftpower provides the backend that allows EV drivers to start charging at a charging station and pay for charging all from within the in-vehicle system without using a dedicated app on their phone.

TomTom Digital Cockpit's application suite contains an IVI service plugin which provides access to Deftpower's APIs to allow the product to support most of the typical end-to-end charging flow that an EV driver will go through to charge their vehicle and to pay for charging. To complete the end-to-end flow, the car maker needs to configure the built-in Deftpower service plugin and to implement the parts specific to their product. This guide explains how to do this.

Prerequisites

The Deftpower plugin in TomTom Digital Cockpit makes calls to Deftpower's API which is hosted on Deftpower's backend. Access to this needs to be granted by Deftpower, therefore, prior to starting this integration, it is necessary to contact Deftpower to organize access to their API.

The rest of this guide assumes that this has been done and that the reader or the reader's organization has a contact within Deftpower who can provide them with suitable access.

Architectural overview

TomTom Digital Cockpit provides an IVI service as part of its appsuite which abstracts away direct access to Deftpower's API. The TomTom Digital Cockpit AppSuite includes a frontend with an end-to-end UI for the entire vehicle charging process. In order for this frontend to be used in a vehicle, some configuration and additional development needs to be done by the car maker. These are the parts that are typically car maker-specific and relates to company or product-specific API keys, authentication mechanisms and cloud-to-vehicle communication mechanisms.

This component diagram describes the architecture of the Deftpower integration within TomTom Digital Cockpit:

The components prefixed with "CarMaker" are not provided as part of TomTom Digital Cockpit.

These are:

• CarMakerProductConfigurationGradlePlugin: The Deftpower IVI service provided by TomTom Digital Cockpit's platform needs to be configured by the car maker. Values such as the API key to use and other parameters need to be specified.
• CarMakerEvChargingLoginFrontend: User account management is not provided as part of TomTom Digital Cockpit. Deftpower is also a white label brand and not intended to be end-user facing. Therefore the car maker needs to brand the charging service that it offers and, for example, combine the login to the charging service with the login for its general driver account or offer it as a separate service. To give the car maker the flexibility to decide how its customers should identify themselves with the service, the car maker needs to create a UI that allows its end-users to log in. TomTom provides APIs to aid this. For more information on how to create a UI frontend, see Create a frontend plugin
• CarMakerSessionMonitorService: TomTom Digital Cockpit enables the driver to start and stop charging their vehicle using their IVI system. However, the driver can in reality also do this using a mobile application or using the charging station terminal itself. They may also do this after switching off their vehicle (and hence the IVI system) and so the vehicle needs to be informed if charging was started or stopped from outside of its IVI system. Something needs to push this state to TomTom Digital Cockpit and this component needs to be able to send the right information to the right vehicle. To do this, an online component needs to be written and hosted by the car maker. This component needs to get (or be notified of) the latest vehicle charging state and then push this state to TomTom Digital Cockpit when needed. Please speak to your Deftpower contact person to learn about how to get this information from their service. TODO(IVI-9982): # (Update this section when the technical solution is known.)

Integrating Deftpower into your product

To be able to use Deftpower in your TomTom Digital Cockpit product, the following main steps need to be followed:

• Apply the Deftpower plugins.
• Configure the Deftpower plugins.
• Implement the login and logout UI.
• Implement the session monitor

Each of these steps is now described in detail.

Apply the Deftpower plugins

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

gradlePluginApiAppsuiteDefaultsDeftpower = { module = "com.tomtom.ivi.appsuite.gradle.deftpower:api_appsuitedefaults_deftpower", version.ref = "iviPlatform" }

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

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

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

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

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

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

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

Configure the Deftpower plugins

Some parameters need to be specified to configure the built-in Deftpower plugin that is provided as part of the TomTom Digital Cockpit platform.

These parameters are used to:

• Set up authentication features in the plugin so that the driver can log in to Deftpower.
• Allow access to the Deftpower API.
• Specify which countries Deftpower should be used in.

Some of the values of these should be obtained from your contact at Deftpower.

These parameters are configured by using Gradle properties, overriding the static configuration values in Android resources or using a static configuration provider.

The static configuration keys are:

Using Gradle properties

The easiest way is to set the values of properties via the top-level local.properties file or as Gradle properties. The available properties are shown in the example below:

For example:

1deftpowerApiKeyConfigKey=my-api-key
2deftpowerClientId=my-organizations-id
3deftpowerOAuthRedirectUri=my-oauth-redirect-uri
4deftpowerOpenIdConnectIssuerUri=my-open-id-connect-issuer-uri
5deftpowerOpenIdAuthorizationScope=my-scope-string
6deftpowerOperationalCountries=US,GB,DE,IT,NL
7...

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 using the Configuration Framework.

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<resources>
3    <!--The Deftpower client ID.-->
4    <string name="deftpowerClientIdConfigKey">my-organizations-client-id-from-Deftpower</string>
5    <!--The Deftpower API key.-->
6    <string name="deftpowerApiKeyConfigKey">my-Deftpower-api-key</string>
7    <!--The countries in which I want my product to use Deftpower as a comma delimited list of 2-letter ISO 3166 alpha country codes.-->
8    <string name="deftpowerOperationalCountriesConfigKey">US,GB,DE,NL,IT</string>
9</resources>

If this mechanism is used to override static configuration values, then a build-time check that ensures that values have been defined for these keys needs to be disabled (since they are now defined in code). This build-time check has been put in place to ensure that car makers do not forget to specify their Deftpower Client ID, API key and other values as these are mandatory for using the Deftpower API.

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

disableDeftpowerPropertiesBuildTimeCheck=true

or by not applying the com.tomtom.ivi.appsuite.deftpower.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

It is also possible to configure a static configuration provider in the Android Application class that provides the key. For this you can use an DeftpowerStaticConfigurationProvider instance. Static configurations are created with the configuration generator. See the API reference documentation of IviConfigurationGeneratorConfig.

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

disableDeftpowerPropertiesBuildTimeCheck =true

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

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

Implement the login and logout UI

Deftpower's API maintains driver and vehicle information in user accounts. An EV driver therefore needs to log in to use the service. Deftpower supports OpenID as the authentication mechanism and this needs to be configured by the car maker in their product, for example, by specifying the relevant endpoints.

TomTom Digital Cockpit does not provide a user interface to manage user accounts and leaves it up to the car maker to provide a custom UI for this process. However, APIs to facilitate the OpenID login process are provided.

This gives the car maker the flexibility of offering its end-users a login experience that is consistent with the rest of its product and to customize the Deftpower service so that it is consistent with the car maker's own branding.

Background information

The implementation of the Deftpower authentication process within the TomTom Digital Cockpit platform makes use of the Android AppAuth library which provides APIs for communicating with OpenID providers. The platform abstracts away some of the lower level details needed to work with OpenID such as the retrieval of tokens. The Android AppAuth documentation describes how the library works.

Prerequisites

This guide assumes some familiarity of OpenID as a login mechanism. More information on this can be found on the official OpenID site.

Furthermore, some OpenID configuration parameters need to be configured into your product. The section Configure the Deftpower plugins describes the configuration parameters in more detail.

The login process

The Architectural Overview diagram shows that a component called the CarMakerEvChargingLoginFrontend needs to be implemented by the car maker to provide a login interface for the end-user.

This UI uses APIs from the EvChargingMediatorService which is part of the TomTom Digital Cockpit platform. This section explains which APIs are relevant for the implementation of this UI and when they need to be called as the end-user logs in.

The following diagram describes the sequence of events which occurs to complete the login flow.

When the driver interacts with the UI to login, the EvChargingMediatorService.logIn should be called to indicate to the TomTom Digital Cockpit platform that the user has requested that the login process should be started. This API returns a result indicating whether the API call itself was successful or not. This call can fail because there is no internet connection as the system needs to be online to be able to reach the Deftpower cloud. See the EvChargingMediatorService.logIn for all the possible error values that can be returned.

This request is passed on to the relevant eMSP, in this case Deftpower. The Deftpower plugin (StockDeftpowerService) handles that request and assuming that the OpenID configuration parameters have been specified correctly (see section Configure the Deftpower plugins), then the result is a change in the EvChargingMediatorService.emspAuthenticationStatus to EmspAuthenticationStatus.AuthenticationRequested.

An authorization request Intent is also returned by the EvChargingMediatorService. This Intent can be launched and will typically open a webpage which allows the user to enter their username and password to login. However, the exact behavior depends on the OpenID configuration.

The actual login process is therefore handed over to the web browser and the result is an authorization result Intent which is returned as an Activity result.

This result needs to be passed back to the TomTom Digital Cockpit platform using EvChargingMediatorService.provideOpenIdAuthenticationResult which can extract the necessary information from it to know whether login succeeded or failed. If the user abandons the login process, for example, by closing the UI containing the login page, then it is also necessary to inform the TomTom Digital Cockpit platform using EvChargingMediatorService.provideOpenIdAuthenticationResult so that it can reset its internal state.

The CarMakerEvChargingLoginFrontend should be observing the EvChargingMediatorService.emspAuthenticationStatus property to get updated on changes to the authentication status. A change in value to EmspAuthenticationStatus.Authenticated indicates that login was successful. A change to EmspAuthenticationStatus.NotAuthenticated indicates that the user did not login successfully.

The logout process

When the driver interacts with the UI to log out of Deftpower, then the frontend should call EvChargingMediatorService.logOut.

The following diagram describes the sequence of events which occurs to complete the logout flow.

Since the login process is handed over to a web browser, the browser also holds cookies that maintains the logged in state. The frontend should ensure that those cookies are also cleared on a successful return of EvChargingMediatorService.logOut.

EvChargingMediatorService.logOut can fail, for example, if the API was called but the user was not logged in. This invalid state usually indicates that there is a logical error in the frontend.

Implement the session monitor

An EV driver can start, stop and monitor the charging process from within their in-vehicle infotainment system running TomTom Digital Cockpit. However, they can usually also do this through a companion mobile app or by interacting with the physical charging station itself (by using their physical charging card, for example). This means that the charging state can change outside of TomTom Digital Cockpit.

The driver will likely also switch off and then leave their vehicle if they plan to charge it for a long time. This means that TomTom Digital Cockpit needs to be told about changes in the charging state of the vehicle, if they were initiated from outside of it.

The car maker needs to provide a way to inject these changes in state to TomTom Digital Cockpit.