Developer

EV integration

Request Access
Version: 0.5.0

Introduction

This tutorial will guide you through integrating electric vehicle (EV)-specific data into your application using the Vehicle Integration Library (VIL). The success of your application's EV navigation features relies on seamless integration with vehicle systems, such as the Battery Management System (BMS). This integration enables accurate energy consumption predictions along the route, estimation of the State of Charge (SoC) upon arrival, display the remaining reachable range on a map, and automatically include necessary charging stops along the way.

In this guide, we will explore how to utilize the com.tomtom.automotive.integration.vehicle.client.api package to achieve effective integration with the vehicle.

Prerequisites

To successfully integrate your navigation application in an electric vehicle, the following parameters are essential. For a more detailed explanation of these parameters and their interrelations, please refer to the EV Routing guide.

Battery-related parameters

  • Current battery capacity: the current usable energy capacity of the battery in Watt-hour (after accounting for aging and considering state of health).
  • StateOfEnergy (SoE): the current remaining energy in the battery in Watt-hour.
  • StateOfCharge (SoC): the current battery level as a percentage.
  • Charge curve: a list of points mapping various SoE’s in Watt-hour to corresponding maximum charging powers in Watt for that SoE.

Consumption-related parameters

  • Speed consumption curve: a list of points mapping various vehicle speeds in km/h to an energy consumption in Watt-hour/km.

Efficiency-related parameters

  • Uphill efficiency: efficiency factor of converting electric energy to potential energy when the vehicle gains elevation; fractional value between 0.0 and 1.0.
  • Downhill efficiency: efficiency factor of converting electric energy to potential energy when the vehicle loses elevation; fractional value between 0.0 and 1.0.
  • Acceleration efficiency: efficiency factor of converting electric energy to kinetic energy when the vehicle accelerates; fractional value between 0.0 and 1.0.
  • Deceleration efficiency: efficiency factor of converting electric energy to kinetic energy when the vehicle decelerates; fractional value between 0.0 and 1.0.

Connector-related parameters

  • Connectors: a list of charging connector types supported by the vehicle:
  • Adapters: a list of charging adapters available with the vehicle.
  • Pre-selected adapters: a list of charging adapters that are the default used.
  • Charging time offset: the estimated time interval between arriving at a charging station and the start of the actual charging process in seconds.

Auxiliary power-related parameters

  • Auxiliary power: the expected average auxiliary power in Watt for the remainder of the trip, consumed by systems like climate control, infotainment and lighting.

Information
Currently, the vehicle weight is fixed at 2000 kg and cannot be modified. Please note that any calculations or functionalities dependent on vehicle weight will operate under this fixed value

Integration steps

To supply the parameters outlined in the prerequisites section, perform the following steps.

Step 1. Create the VehicleIntegrationApiClient instance

Create an instance of VehicleIntegrationApiClient. You can read more about that in the Quick start guide.

Step 2. Initialize the parameters

Before sending the parameters to the application, they must be initialized using the available vehicleinfo data classes.

1import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Duration
2import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.ElectricCurrent
3import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Energy
4import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Power
5import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Speed
6import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Voltage
7import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
8import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.batteryinfo.BatteryInfoParameters
9import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfo
10import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfoParameters
11import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ElectricityType
12import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.VehicleConnectorType
13import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.ConsumptionCurveParameters
14import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.EvSpeedConsumptionCurve
15import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.evefficiency.EvEfficiencyParameters
16

17// Battery-related parameters
18private val _batteryInfoParameters = BatteryInfoParameters(
19    currentBatteryCapacity = "capacity received from the vehicle", // For example: Energy.kilowattHours(80)
20    stateOfEnergy = "SoE received from the vehicle",               // For example: Energy.kilowattHours(40)
21    stateOfCharge = "SoC received from the vehicle",               // For example: 68.9
22    batteryChargeCurve = "battery charging curve supported by the vehicle", // For example:
23        listOf(
24            BatteryInfoParameters.Point(energy = Energy.kilowattHours(0), power = Power.kilowatts(75)),
25            BatteryInfoParameters.Point(energy = Energy.kilowattHours(8), power = Power.kilowatts(150)),
26            BatteryInfoParameters.Point(energy = Energy.kilowattHours(40), power = Power.kilowatts(112)),
27            BatteryInfoParameters.Point(energy = Energy.kilowattHours(64), power = Power.kilowatts(52)),
28            BatteryInfoParameters.Point(energy = Energy.kilowattHours(72), power = Power.kilowatts(30)),
29            BatteryInfoParameters.Point(energy = Energy.kilowattHours(80), power = Power.kilowatts(0))
30        )
31)
32

33// Consumption-related parameters
34private val _speedConsumptionCurve = ConsumptionCurveParameters(
35    speedConsumptionCurve = EvSpeedConsumptionCurve(
36        consumptionCurve = "the vehicle's energy consumption at a given speed", // For example:
37            listOf(
38                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(10), energy = Energy.wattHours(114.1)),
39                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(20), energy = Energy.wattHours(91.7)),
40                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(30), energy = Energy.wattHours(87.7)),
41                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(40), energy = Energy.wattHours(89.5)),
42                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(50), energy = Energy.wattHours(94.8)),
43                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(60), energy = Energy.wattHours(102.6)),
44                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(70), energy = Energy.wattHours(112.6)),
45                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(80), energy = Energy.wattHours(124.6)),
46                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(90), energy = Energy.wattHours(138.5)),
47                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(100), energy = Energy.wattHours(154.3)),
48                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(110), energy = Energy.wattHours(171.9)),
49                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(120), energy = Energy.wattHours(191.3)),
50                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(130), energy = Energy.wattHours(212.5)),
51                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(140), energy = Energy.wattHours(235.5)),
52                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(150), energy = Energy.wattHours(260.2)),
53                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(160), energy = Energy.wattHours(286.6)),
54                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(170), energy = Energy.wattHours(314.8)),
55                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(180), energy = Energy.wattHours(344.8)),
56                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(190), energy = Energy.wattHours(376.5)),
57                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(200), energy = Energy.wattHours(409.9))
58            )
59    )
60)
61

62// Efficiency-related parameters
63private val _evEfficiencyParameters = EvEfficiencyParameters(
64    uphillEfficiency = "uphill efficiency of the vehicle",         // For example: 0.85
65    downhillEfficiency = "downhill efficiency of the vehicle",     // For example: 1.0
66    accelerationEfficiency = "acceleration efficiency of the vehicle", // For example: 0.9
67    decelerationEfficiency = "deceleration efficiency of the vehicle"  // For example: 0.95
68)
69

70// Connector-related parameters
71private val _connectorInfoParameters = ConnectorInfoParameters(
72    vehicleConnectors = "connectors supported by the vehicle", // For example:
73        listOf(
74            ConnectorInfo(
75                vehicleConnectorType = VehicleConnectorType.TYPE2_CCS,
76                electricityType = ElectricityType.DC,
77                maxVoltage = Voltage.volts(800),
78                maxCurrent = ElectricCurrent.amperes(500),
79                maxPower = Power.kilowatts(350),
80                baseLoad = Power.watts(0),
81                efficiency = 0.98
82            )
83        ),
84    connectorChargingAdapters = "adapters supported by the vehicle",         // For example: emptyList()
85    preSelectedChargingAdapters = "adapters to be pre-selected by the application", // For example: emptyList()
86    chargingTimeOffset = "estimated amount of time between reaching a charging station and actual charging start" // For example: Duration.seconds(300)
87)
88

89// Auxiliary power-related parameters
90private val _auxiliaryPowerParameters = AuxiliaryPowerParameters(
91    auxiliaryPower = "auxiliary power received from the vehicle" // For example: Power.watts(100)
92)

Step 3. Send the parameters

Once the parameters have been initialized, you can send them to the application using the VehicleInfoManager. For example, to send the auxiliary power parameters:

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.VehicleInfoManager
3import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerCallback
4import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
5import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerFailure
6import com.tomtom.automotive.integration.vehicle.common.Callback
7import com.tomtom.automotive.integration.vehicle.common.Result
8

9vehicleIntegrationApiClient.vehicleInfoManager.setAuxiliaryPower(
10    _auxiliaryPowerParameters,
11    object : AuxiliaryPowerCallback {
12        override fun onResult(result: Result<Unit, out AuxiliaryPowerFailure>) {
13            when (result) {
14                is Result.Success<*> -> {
15                    // Handle success if required
16                }
17                is Result.Failure<*> -> {
18                    // Handle failure
19                }
20            }
21        }
22

23        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
24            // Handle error
25        }
26    }
27)

Step 4. Confirm that the integration is successful

Once the parameters have been successfully sent, your application should leverage EV navigation capabilities, including Long Distance EV Routing. To verify these features, plan a route to a destination that exceeds your vehicle's range. The application should automatically generate a route that incorporates necessary charging stops along the way.

For more information on how to plan a long-distance EV Route in your application, refer to the EV Routing guide.

Best practices

Use Kotlin Flows to update the application

Kotlin flows offer a robust reactive programming model for managing asynchronous data streams. By utilizing MutableStateFlow for data sourced from the vehicle, you can achieve a dynamic and responsive system that automatically updates the VehicleIntegrationApiClient whenever there are changes in the vehicle's underlying data, such as SoE or SoC.

Note
Timely updates to your application in response to changes in vehicle data are essential for delivering a reliable and trustworthy EV navigation experience.