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.

The concepts of Brand, Model, and Variant

The diagram below illustrates the relationship.

Brand, Model, and Variant relationship diagram

Brand

A brand name distinguishes one manufacturer’s vehicles from others. A brand consists of a group of models.

Model

A model is a group of variants sharing the same OEM-assigned name. Models organize vehicles into collections.

Models do not restrict variants based on any parameter. A model can include types such as CAR and VAN, various engine types, etc. Integrators determine which variants to add. This flexibility exists because combustion and hybrid electric engines may be offered within the same model, and manufacturers may reuse the same platform for electric models under the same name.

Variant

A variant is a vehicle type characterized by specific attributes: brand, model, variant name, and vehicle specifications. These attributes define unique features and characteristics, enabling differentiation within the vehicle lineup.

What defines a new variant?

A new variant is defined by changes in parameters that significantly impact consumption, charging, or range. This includes modifications that alter WLTP (Worldwide Harmonised Light Vehicle Test), NEDC (New European Driving Cycle), or EPA (Environmental Protection Agency) standards, including physical characteristics such as size and weight.

Less critical information can also play a role:

• Production start date: If unspecified, the vehicle may be a prototype
• Production stop date: If unspecified, the vehicle may still be in production
• New brand or model names: For example, variations between Opel and Vauxhall

Any parameter affecting consumption or charging time should be treated as a basis for creating a new variant entry.

Examples

Disclaimer: The brands, models, and manufacturers listed in this table are provided for illustrative purposes only. We do not claim any rights to these names or logos. All data included in this table is based on publicly available information.

Vehicle registration

TomTom currently supports manual vehicle registration via Thru service. If you haven’t been onboarded, send a request to ev-integration-support@tomtom.com to register a vehicle.

Once onboarded, you can access the service to send vehicle data for registration.

After onboarding, TomTom will send you an Excel sheet to complete and return via Thru service. Encrypt each Excel sheet using the built-in password protection feature. Attach the file using Thru email service, and share the password in the encrypted private message box.

After registering the new vehicle, TomTom will send you the unique modelId for the registered vehicle variant. This modelId can then be used for LDEV route planning via Navigation SDK.

The parameters to be filled in the Excel sheet are described in detail below.

Vehicle parameters

Battery Charging Curve

Provide charging curve as a list of “State of Energy” and “Max power” pairs. Include 2 to 20 pairs for interpolation using a piecewise-linear function. If a single curve is insufficient, provide individual charging curves for each connector and omit this global curve.

Validation rules for the curve:

• first pair must have “State of charge” equal to 0.0
• “Max power” must be greater than 0.0
• no duplicated values for “State of Energy”
• order pairs by “State of Energy” ascending

Connectors

Battery Charging Curves for Connectors

Each vehicle must have at least one connector. Multiple connectors can represent different charging capabilities. Each connector can have its own battery charging curve instead of using a single vehicle charging curve. Connector charging curves follow the same rules as the general battery charging curve. A connector can use its maximum power without defining a curve. To use maximum connector power, omit the charging curve for the connector and explicitly state this in the table.

This is a list of 2 up to 20 pairs.

Applying changes to variants

Variant entries are treated as unchangeable objects to keep data consistent and reliable.

Changes affecting consumption or charging can lead to variations in service quality and less accurate consumption predictions. Consider the impact of updates carefully to maintain prediction quality.

These fields can be changed without affecting consumption predictions:

• Brand name
• Model name
• Produced from
• Produced to

To change other parameters, create a new vehicle entry:

1. Register a new variant entry with updated parameters. Specify which variant to replace. The new version will be associated with the selected variant.
2. Use the new variant in Navigation SDK.

This approach maintains vehicle history integrity while allowing necessary modifications.

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:

1
val modelId = "" // Fill with received Model ID of registered vehicle
2
val electricEngine = ElectricEngine(
3
    chargeLevel = ChargeLevel(
4
        currentCharge = Energy.kilowattHours(10),
5
        maxCharge = Energy.kilowattHours(50)
6
    )
7
)
8
val vehicle = Vehicle.Car(
9
    electricEngine = electricEngine,
10
    modelId = modelId
11
)
12
VehicleProvider.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:

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

1
FeatureToggleController.enable(RedesignedTelemetryFeature)
2
Telemetry.userConsent = Consent.Personalized
3
FeatureToggleController.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 subsequent vehicle changes through the vehicle provider using the appropriate property:

1
val numberOfOpenWindows = NumberOfOpenWindowsProperty(2)
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:

1
val customAttributes = ConsumptionModelCustomAttributesProperty(
2
      mapOf("attribute1" to 0.75)
3
)
4

5
VehicleProvider.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 advantageous. 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:

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

8
VehicleProvider.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.