Vehicle

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:

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

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.

1
val currentCharge = Energy.kilowattHours(30.0)
2
val maxCharge = Energy.kilowattHours(60.0)
3

4
val electricCar = Vehicle.Car(
5
    electricEngine = ElectricEngine(
6
        chargeLevel = ChargeLevel(currentCharge, maxCharge),
7
    ),
8
)
9
VehicleProvider.vehicle = electricCar
10

11
// Switch to the bicycle
12
VehicleProvider.vehicle = Vehicle.Bicycle()

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:

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

8
VehicleProvider.updateVehicleProperties(updatedVehicleProperties)

Current vehicle

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

1
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:

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

6
VehicleProvider.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:

1
val vehicleOptionToBeTracked = PropertyId.CurrentCharge
2

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

10
VehicleProvider.addVehicleUpdatedListener(listener)

Next steps

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

• Planning a route
• Calculating a reachable range