Create a Custom In-Vehicle Charging Service

Last edit: 2024.02.08

The TomTom Digital Cockpit platform allows carmakers to implement custom services to extend the In-Vehicle Charging feature to support multiple different eMSPs (e-Mobility Service Providers).

In this guide, you will learn how to create a custom In-Vehicle Charging service to support a new eMSP.

How to create a custom In-Vehicle Charging service

The following sections describe how to create a custom In-Vehicle Charging service implementation.

Example code illustrating how to implement the concepts described in this document can be found in examples/evcharging/service.

Service module setup

To create an In-Vehicle Charging service, add an AndroidManifest.xml file to your module. In this file your custom service has to be declared so it can be seen by the system. This XML file could also contain the package name together with some permissions:

Add a src/main/AndroidManifest.xml file:


Add a dependency to the EvChargingService and LifecycleService in your build.gradle.kts file:

1dependencies {
2 implementation(libraries.iviPlatformEvchargingApiCommonEvcharging)
3 implementation(libraries.iviPlatformEvchargingApiServiceEvcharging)

The dependency to the EvChargingService is necessary as it is used as the base class for the custom service. The dependency to the the common evcharging module is necessary as its classes are used between the service and the mediator.

Service configuration

To configure an In-Vehicle Charging service to use your custom implementation, define a service host configuration class that inherits from the IviServiceHostConfig class. This class should be placed in the application Gradle build file.


1val exampleEvChargingServiceHost by extra {
2 IviServiceHostConfig(
3 serviceHostBuilderName = "ExampleEvChargingServiceHostBuilder",
4 implementationModule = ExampleModuleReference("examples_evcharging_service"),
5 interfaces = listOf(
6 IviServiceInterfaceConfig(
7 serviceName = "EvChargingService",
8 serviceId = "com.example.ivi.example.evcharging.service",
9 serviceApiModule = IviPlatformModuleReference("platform_evcharging_api_service_evcharging")
10 )
11 )
12 )

In this configuration, the examples_evcharging_service module defines the implementation for the platform_evcharging_api_service_evcharging interface.

In order to create the service host configuration named ExampleEvChargingServiceHostBuilder, the IVI platform needs a service host builder class with the specific name ExampleEvChargingServiceHostBuilder.


1class ExampleEvChargingServiceHostBuilder : SimpleIviServiceHostBuilder() {
3 override fun createIviServices(iviServiceHostContext: IviServiceHostContext)
4 : Collection<AnyIviServiceBase> =
5 listOf(
6 ExampleEvChargingService(iviServiceHostContext) {
7 getDiscoverableServiceId(it)
8 }
9 )
11 companion object

Note: Every service host configuration needs to be registered in your application. This is so that the platform knows which service should be started with which implementation when a client requires the access to a service api.

To register this configuration, add the service host to your application Gradle file:


1val exampleEvChargingServiceHost: IviServiceHostConfig by project.extra
3ivi {
4 application {
5 enabled = true
7 iviInstances {
8 create(IviInstanceIdentifier.default) {
9 applyGroups {
10 includeDefaultPlatformGroups()
11 includeDefaultAppsuiteGroups()
12 include(
13 IviAppsuite.evChargingGroup // Will add the EvCharging frontend.
14 )
15 }
16 }
17 }
18 services {
19 applyGroups {
20 includeDefaultPlatformGroups()
21 includeDefaultAppsuiteGroups()
22 include(
23 IviPlatform.evChargingGroup, // Will add the EvChargingMediatorService
24 IviPlatform.evChargingStationGroup, // Will add the EvChargingStationService
25 )
26 }
27 addHost(exampleEvChargingServiceHost)
28 }
29 }

Service definition

In order to create an In-Vehicle Charging service implementation you need to create a class that inherits from the EvChargingServiceBase base class.


1internal class ExampleEvChargingService(
2 iviServiceHostContext: IviServiceHostContext,
3 serviceIdProvider: IviDiscoverableServiceIdProvider,
4) : EvChargingServiceBase(iviServiceHostContext, serviceIdProvider) {

In this example, the In-Vehicle Charging service has no implementation. This example only shows how to create a custom service. The implementation of the service is up to the carmaker, since the implementation will depend on the eMSP.

Service lifecycle

To manage the initialization and destruction of the service, override the onCreate and onDestroy methods.

When the service is created:


1 override fun onCreate() {
2 super.onCreate()
4 emspServiceInfo = EMSP_INFO
5 emspAuthenticationStatus = NotAuthenticated
6 serviceReady = true
7 }

then the EvChargingService properties all need to be initialized. The emspServiceInfo property is used to provide information about the eMSP. The emspAuthenticationStatus property is used to provide information about the authentication status of the eMSP. The serviceReady property is used to provide information about the service readiness.

When the service is destroyed:


1override fun onDestroy() {
2 // Put here cleaning code if necessary.
3 super.onDestroy()