Vehicle

VERSION 0.28.2

The Navigation SDK for iOS is only available upon request. Contact us to get started.

The Vehicle module offers a VehicleProvider. This interface gets the current vehicle state, then listens for changes. With this, the integrator can provide their implementation and inject it into other TomTom modules, like Navigation. TomTom also offers the thread-safe implementation of a VehicleProviderInterface. The DefaultVehicleProvider helps the integrator monitor the vehicle’s current state. With DefaultVehicleProvider the integrator can:

set the initial vehicle state.
update the vehicle state.
listen for vehicle state changes.

Once created, DefaultVehicleProvider returns an empty non-commercial car as the current’s vehicle snapshot.

Setting the initial vehicle profile, then switching to a different vehicle

The following code snippet shows how to set the initial profile as an electric engine car and later switch to a bicycle, another vehicle type.

1let chargeLevel = try ChargeLevel(
2    currentCharge: Measurement.tt.kilowattHours(30.0),
3    maxCharge: Measurement.tt.kilowattHours(60.0)
4)
5let electricEngine = ElectricEngine(chargeLevel: chargeLevel)
6let electricCar = Car(electricEngine: electricEngine)
7let defaultVehicleProvider = DefaultVehicleProvider(vehicle: electricCar)
8
9// Switch to a bicycle
10let bicycle = Bicycle()
11defaultVehicleProvider.vehicle = bicycle

Updating the vehicle profile

This updates the listed VehicleParameters in the current vehicle profile. If a parameter, which is not .maxSpeed or .commercialVehicle, was not previously set, it will throw an VehicleError.invalidVehicleParameter. .maxSpeed can be updated for every vehicle type. .commercialVehicle can be updated for a motorized vehicle type.

1let updatedCurrentChargeParameter = Measurement.tt.kilowattHours(25.0)
2let updatedElectricEngineParameters: [ElectricEngineParameter] = [.currentCharge(updatedCurrentChargeParameter)]
3let updatedVehicleParameters = VehicleParameter.electricEngine(updatedElectricEngineParameters)
4
5try defaultVehicleProvider.updateVehicleState(with: [updatedVehicleParameters])

Snapshot of the current vehicle profile

The following code snippet shows how to get the snapshot of the current vehicle’s state:

let currentVehicleSnapshot = defaultVehicleProvider.vehicleSnapshot

Listening to vehicle updates

The integrator can listen for the specific changes of the VehicleParameters or every vehicle state change. If the integrator attempts to add the same observer twice, the VehicleError.alreadyRegisteredObserver is thrown, regardless of how it was added.

All changes

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

1class MyVehicleUpdateObserver: VehicleUpdateObserver {
2    func onVehicleUpdate(_ vehicle: Vehicle) {
3        // YOUR CODE GOES HERE
4    }
5}
6let myVehicleUpdateObserver = MyVehicleUpdateObserver()
7try defaultVehicleProvider.addObserver(myVehicleUpdateObserver)

Specific change

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

1class MyVehicleUpdateObserver: VehicleUpdateObserver {
2    func onVehicleUpdate(_ vehicle: Vehicle) {
3        // YOUR CODE GOES HERE
4    }
5}
6
7let myVehicleUpdateObserver = MyVehicleUpdateObserver()
8let vehicleOptionsToBeTracked = [VehicleUpdateOption.currentCharge]
9
10try defaultVehicleProvider.addObserver(
11    myVehicleUpdateObserver,
12    for: vehicleOptionsToBeTracked
13)

By setting the CombustionEngineParameter or ElectricEngineParameter, the observer is notified of any change to combustion or electric engine parameters, respectively.

Next step

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