Vehicle

VERSION 1.22.0

The Vehicle module offers a VehicleProvider interface that is responsible for the control, access, and listening to changes in the vehicle state.

The integrator can choose to provide its implementation of the VehicleProvider or use the TomTom default thread-safe implementation.

The TomTom implementation can be obtained via the VehicleProviderFactory.

VehicleProviderFactory allows the user to pass a custom vehicle object for initialization of the VehicleProvider. If no vehicle object is provided, a non-commercial car with a combustion engine is used by default.

When an instance of VehicleProvider is created, it can be injected into other TomTom modules that depend on it, e.g., Navigation.

Project setup

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

implementation("com.tomtom.sdk.vehicle:vehicle-provider:1.22.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 =
5    Vehicle.Car(
6        electricEngine =
7            ElectricEngine(
8                chargeLevel =
9                    ChargeLevel(
10                        currentCharge,
11                        maxCharge,
12                    ),
13            ),
14    )
15vehicleProvider = VehicleProviderFactory.create(electricCar)
16
17// Switch to the bicycle
18vehicleProvider.vehicle = Vehicle.Bicycle()

If using 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 torn apart into VehicleProperties which offers the integrator a simpler way of updating the current state of the vehicle. If a property, which is not MaxSpeed or CommercialVehicle, was not previously set or the update would lead to vehicle’s state being inconsistent, it will throw an IllegalArgumentException. 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 =
3    ElectricEngineProperties(
4        listOf(updatedCurrentCharge),
5    )
6val updatedVehicleProperties = listOf(updatedElectricEngineProperties)
7
8vehicleProvider.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 the specific changes of the VehicleProperties or every change of the vehicle’s state. If the integrator tries to add the same listener twice then the IllegalArgumentException is thrown, regardless of the way it was added.

All changes

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

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

Specific change

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

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

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

Next steps

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