Vehicle

VERSION 2.2.0

The Vehicle module offers a VehicleProvider object that is responsible for controlling, accessing, and listening to changes in the vehicle state.

Project setup

You have to add the Vehicle module dependency to the build.gradle.kts file of your application module and synchronize the project:

implementation("com.tomtom.sdk.vehicle:vehicle-provider:2.2.0")

Setting initial vehicle’s state and switching to another vehicle

The following code snippet shows how to set the profile for an electric engine car and later switch to bicycle, which is another vehicle type.

1val currentCharge = Energy.kilowattHours(30.0)
2val maxCharge = Energy.kilowattHours(60.0)
3
4val electricCar = Vehicle.Car(
5    electricEngine = ElectricEngine(
6        chargeLevel = ChargeLevel(currentCharge, maxCharge),
7    ),
8)
9VehicleProvider.vehicle = electricCar
10
11// Switch to the bicycle
12VehicleProvider.vehicle = Vehicle.Bicycle()

If you are using an electric vehicle, make sure that the latest state of charge is set before navigation is started or resumed, in order to avoid unnecessary route updates.

Updating the vehicle’s state

Vehicle data classes' properties are separated into VehicleProperties, which offer the integrator a simpler way to update the current state of the vehicle. If a property—other than MaxSpeed or CommercialVehicle—was not previously set, or if the update would lead to an inconsistent vehicle state, an IllegalArgumentException will be thrown. MaxSpeed can be updated for every vehicle type. CommercialVehicle can be updated for a motorized vehicle type. This updates the listed VehicleProperties in the current vehicle profile:

1val updatedCurrentCharge = CurrentChargeProperty(Energy.kilowattHours(25.0))
2val updatedElectricEngineProperties = ElectricEngineProperties(
3    listOf(updatedCurrentCharge),
4)
5val updatedVehicleProperties = listOf(updatedElectricEngineProperties)
6
7VehicleProvider.updateVehicleProperties(updatedVehicleProperties)

Current vehicle

The following code snippet shows how to get the currently set vehicle.

val vehicle = VehicleProvider.vehicle

Listening to vehicle updates

The integrator can listen for specific changes of the VehicleProperties or for every change in the vehicle’s state. If the integrator tries to add the same listener twice, an IllegalArgumentException is thrown, regardless of how it was added.

All changes

The following code snippet shows how to add a listener whose method will be called whenever the vehicle’s state changes:

1val listener = VehicleUpdatedListener { vehicle, updatedProperties ->
2    // YOUR CODE GOES HERE
3}
4
5VehicleProvider.addVehicleUpdatedListener(listener)

Specific change

If the integrator only wants to listen to changes in specific VehicleProperties, this can be done by specifying their corresponding PropertyId. The following code snippet shows how to listen for changes in the current state of charge:

By setting the CombustionEngineId or ElectricEngineId, the listener will be notified of any changes to the combustion or electric engine’s properties.

1val vehicleOptionToBeTracked = PropertyId.CurrentCharge
2
3val listener = VehicleUpdatedListener { vehicle, updatedProperties ->
4    if (vehicleOptionToBeTracked in updatedProperties) {
5        // YOUR CODE GOES HERE
6    }
7}
8
9VehicleProvider.addVehicleUpdatedListener(listener)

Next steps

Since you have learned how to set up a vehicle provider, here are recommendations for the next steps: