TomTom LogoDocs
Products
Resources
Pricing
Sign in
Automotive Navigation Application
English
中文

EV integration

Request access

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.

import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Duration
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.ElectricCurrent
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Energy
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Power
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Speed
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Voltage
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.batteryinfo.BatteryInfoParameters
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfo
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfoParameters
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ElectricityType
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.VehicleConnectorType
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.ConsumptionCurveParameters
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.EvSpeedConsumptionCurve
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.evefficiency.EvEfficiencyParameters


// Battery-related parameters
private val _batteryInfoParameters = BatteryInfoParameters(
    currentBatteryCapacity = "capacity received from the vehicle", // For example: Energy.kilowattHours(80)
    stateOfEnergy = "SoE received from the vehicle",               // For example: Energy.kilowattHours(40)
    stateOfCharge = "SoC received from the vehicle",               // For example: 68.9
    batteryChargeCurve = "battery charging curve supported by the vehicle", // For example:
        listOf(
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(0), power = Power.kilowatts(75)),
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(8), power = Power.kilowatts(150)),
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(40), power = Power.kilowatts(112)),
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(64), power = Power.kilowatts(52)),
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(72), power = Power.kilowatts(30)),
            BatteryInfoParameters.Point(energy = Energy.kilowattHours(80), power = Power.kilowatts(0))
        )
)


// Consumption-related parameters
private val _speedConsumptionCurve = ConsumptionCurveParameters(
    speedConsumptionCurve = EvSpeedConsumptionCurve(
        consumptionCurve = "the vehicle's energy consumption at a given speed", // For example:
            listOf(
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(10), energy = Energy.wattHours(114.1)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(20), energy = Energy.wattHours(91.7)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(30), energy = Energy.wattHours(87.7)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(40), energy = Energy.wattHours(89.5)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(50), energy = Energy.wattHours(94.8)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(60), energy = Energy.wattHours(102.6)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(70), energy = Energy.wattHours(112.6)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(80), energy = Energy.wattHours(124.6)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(90), energy = Energy.wattHours(138.5)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(100), energy = Energy.wattHours(154.3)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(110), energy = Energy.wattHours(171.9)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(120), energy = Energy.wattHours(191.3)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(130), energy = Energy.wattHours(212.5)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(140), energy = Energy.wattHours(235.5)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(150), energy = Energy.wattHours(260.2)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(160), energy = Energy.wattHours(286.6)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(170), energy = Energy.wattHours(314.8)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(180), energy = Energy.wattHours(344.8)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(190), energy = Energy.wattHours(376.5)),
                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(200), energy = Energy.wattHours(409.9))
            )
    )
)


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


// Connector-related parameters
private val _connectorInfoParameters = ConnectorInfoParameters(
    vehicleConnectors = "connectors supported by the vehicle", // For example:
        listOf(
            ConnectorInfo(
                vehicleConnectorType = VehicleConnectorType.TYPE2_CCS,
                electricityType = ElectricityType.DC,
                maxVoltage = Voltage.volts(800),
                maxCurrent = ElectricCurrent.amperes(500),
                maxPower = Power.kilowatts(350),
                baseLoad = Power.watts(0),
                efficiency = 0.98
            )
        ),
    connectorChargingAdapters = "adapters supported by the vehicle",         // For example: emptyList()
    preSelectedChargingAdapters = "adapters to be pre-selected by the application", // For example: emptyList()
    chargingTimeOffset = "estimated amount of time between reaching a charging station and actual charging start" // For example: Duration.seconds(300)
)


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

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:

import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.VehicleInfoManager
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerCallback
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerFailure
import com.tomtom.automotive.integration.vehicle.common.Callback
import com.tomtom.automotive.integration.vehicle.common.Result


vehicleIntegrationApiClient.vehicleInfoManager.setAuxiliaryPower(
    _auxiliaryPowerParameters,
    object : AuxiliaryPowerCallback {
        override fun onResult(result: Result<Unit, out AuxiliaryPowerFailure>) {
            when (result) {
                is Result.Success<*> -> {
                    // Handle success if required
                }
                is Result.Failure<*> -> {
                    // Handle failure
                }
            }
        }


        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
            // Handle error
        }
    }
)

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.