Navigation SDK

Seamless vehicle integration with LDEVR

To seamlessly integrate a new vehicle with Long Distance EV Routing in Navigation SDK, use com.tomtom.sdk.vehicle.VehicleMetadataProvider and com.tomtom.sdk.vehicle.Motorized::modelId.

With this approach, OEMs provide only essential static vehicle information during registration, not detailed consumption parameters. TomTom derives initial consumption parameters based on the provided vehicle data.

TomTom continuously improves energy consumption predictions and range estimates for each registered vehicle using advanced data analytics. The system refines predictions based on real-world driving patterns, environmental factors, and vehicle performance metrics, ensuring drivers receive reliable information about vehicle energy efficiency and range.

Each vehicle model variant receives a unique identifier for use in LDEV route planning via Navigation SDK.

Vehicle registration is a foundational step that enables future innovations in energy consumption prediction and optimization.

Electric vehicle registration is described briefly on the following page: Electric Vehicle Registration

Using newly registered vehicles in LDEVR

The Variant ID provided to Navigation SDK should be easily changeable (e.g., through Over-The-Air updates) while the vehicle is in production and use. This flexibility enables smooth implementation of necessary variant changes.

Online-only scenario

Every registered vehicle variant has a unique ID to provide in RoutePlanningOptions::Vehicle::Car::modelId.

This code creates a vehicle of type Car with an electric engine and provides the variant ID:

1val variantId = "" // Fill with received Variant ID of a registered vehicle
2val electricEngine = ElectricEngine(
3    chargeLevel = ChargeLevel(
4        currentCharge = Energy.kilowattHours(10),
5        maxCharge = Energy.kilowattHours(50)
6    )
7)
8val vehicle = Vehicle.Car(
9    electricEngine = electricEngine,
10    modelId = variantId
11)
12VehicleProvider.vehicle = vehicle // Set vehicle to VehicleProvider

Consumption and charging parameters cannot be provided separately. These details were submitted during vehicle registration, and TomTom maintains and optimizes consumption values using AI-powered EV consumption prediction.

Online-first scenario

For an online-first scenario with offline fallback, create the vehicle as follows:

1val context = ContextProvider.getApplicationContext()
2val apiKey = "<Your-Api-Key>"
3val variantId = VehicleMetadataId(UUID.fromString("")) // Fill with received Variant ID of a registered vehicle
4val metadataProvider = VehicleMetadataProvider(
5    context = context,
6    apiKey = apiKey,
7    cacheDirectory = CacheDirectory.DefaultDirectory,
8)
9val vehicle = metadataProvider.createVehicle(
10    CreateVehicleOptions.CreateElectricVehicleOptions(
11        id = variantId,
12        chargeLevel = ChargeLevel(
13            maxCharge = 18.8.kilowattHours,
14            currentCharge = 2.kilowattHours,
15        ),
16        vehicleType = VehicleType.Car,
17    ),
18).value()
19VehicleProvider.vehicle = vehicle // Assign vehicle to VehicleProvider

Enhancing State of Energy predictions

Integrating vehicles into Navigation SDK's Vehicle Metadata Provider and LDEVR simplifies determining detailed consumption parameters.

TomTom-generated consumption parameters are sufficient to start experimenting with EV Routing calls and prototyping. To fully benefit from TomTom smart EV consumption prediction, provide additional dynamic vehicle signals. These signals and custom attributes enable the system to learn vehicle-specific characteristics and automatically refine consumption predictions over time. Navigation SDK's telemetry module transmits this data. All collected data is linked to the vehicle variant ID in the Vehicle object.

Before sending signals or attributes, enable RedesignedTelemetryFeature and provide consent for telemetry data:

1FeatureToggleController.enable(RedesignedTelemetryFeature)
2Telemetry.userConsent = Consent.Personalized
3FeatureToggleController.enable(VehicleDataCollectionFeature)

Providing dynamic vehicle signals

To send additional vehicle signals or custom consumption attributes, create a Navigation SDK vehicle and assign it to the VehicleProvider singleton. Make all further vehicle changes through the vehicle provider using the appropriate property:

val numberOfOpenWindows = NumberOfOpenWindowsProperty(2)
VehicleProvider.updateVehicleProperties(listOf(numberOfOpenWindows))

VehicleProvider updates the dynamic vehicle signals in the VehicleSignals class within the managed Vehicle. TomTom smart EV consumption prediction model automatically extracts signals from VehicleSignals when creating RoutePlanningOptions.

Vehicle signals parameters

Use these vehicle signals and property names in the VehicleProvider.updateVehicleProperties(...) method:

Providing custom consumption attributes

Integrators may identify other attributes important for consumption modeling beyond the vehicle signals above. Provide custom consumption attributes even if TomTom does not know their exact semantic definitions. Detailed, vehicle-specific information can significantly improve consumption prediction accuracy.

Each custom consumption attribute must have a unique name for setting the attribute in Navigation SDK. Keep this name consistent during and across trips to ensure meaningful usage in TomTom smart EV consumption prediction.

Provide custom consumption attributes via VehicleProvider using ConsumptionModelCustomAttributesProperty:

1val customAttributes = ConsumptionModelCustomAttributesProperty(
2      mapOf("attribute1" to 0.75)
3)
4
5VehicleProvider.updateVehicleProperties(listOf(customAttributes))

Examples of custom consumption attributes

As outlined in Consumption model integration, the navigation system should receive current battery capacity and State of Energy (SoE) projected to equilibrium conditions (corrected for thermal effects). Additionally, providing battery capacity and SoE based on current thermal conditions is useful. This supplementary data enhances TomTom smart EV consumption prediction by better accounting for environmental impact on vehicle consumption. Supply these attributes to Navigation SDK via VehicleProvider for automatic telemetry collection and smart EV consumption prediction:

1val customAttributes = ConsumptionModelCustomAttributesProperty(
2    mapOf(
3        "capacity_at_battery_temp_kwh" to 74.3,
4        "soe_at_battery_temp_kwh" to 25.75
5    )
6)
7
8VehicleProvider.updateVehicleProperties(listOf(customAttributes))

Another custom consumption attribute example is State of Charge (SoC) as displayed in the IVI cluster. While SoC is not required for EV routing in Navigation SDK (Navigation SDK focuses on energy consumption), it is a valuable signal for smart EV consumption prediction. SoC helps the model learn how the vehicle maps State of Energy (SoE) to the SoC visible to the driver.