EV integration

介绍

本教程将指导您如何使用 Vehicle Integration Library (VIL) 将电动汽车（EV）特定的数据集成到您的应用程序中。您应用程序的 EV 导航功能的成功依赖于与车辆系统（如电池管理系统（BMS））的无缝集成。此集成能够实现沿途准确的能耗预测、到达时的电量状态（SoC）估算、在地图上显示剩余可达续航里程，并自动包含途中必要的充电停靠点。

在本指南中，我们将探讨如何利用 com.tomtom.automotive.integration.vehicle.client.api 包实现与车辆的有效集成。

前提条件

要成功将导航应用集成到电动汽车中，以下参数是必需的。有关这些参数及其相互关系的详细说明，请参阅EV 路由指南。

电池相关参数

当前电池容量：电池当前可用的能量容量，单位为瓦时（考虑老化和健康状态后）。
电量状态（SoE）：电池当前剩余能量，单位为瓦时。
电荷状态（SoC）：电池当前电量百分比。
充电曲线：一组点，将不同的 SoE（瓦时）映射到对应的最大充电功率（瓦特）。

能耗相关参数

速度能耗曲线：一组点，将不同车辆速度（公里/小时）映射到能耗（瓦时/公里）。

效率相关参数

上坡效率：车辆上坡时将电能转换为势能的效率因子，取值范围 0.0 到 1.0。
下坡效率：车辆下坡时将电能转换为势能的效率因子，取值范围 0.0 到 1.0。
加速效率：车辆加速时将电能转换为动能的效率因子，取值范围 0.0 到 1.0。
减速效率：车辆减速时将电能转换为动能的效率因子，取值范围 0.0 到 1.0。

连接器相关参数

连接器：车辆支持的充电连接器类型列表：
- 适配器：车辆配备的充电适配器列表。
- 预选适配器：默认使用的充电适配器列表。
- 充电时间偏移：从到达充电站到实际开始充电的估计时间间隔，单位为秒。

辅助电源相关参数

辅助电源：预计行程剩余时间内平均的辅助功率，单位为瓦特，用于气候控制、信息娱乐和照明等系统。

信息
当前车辆重量固定为 2000 公斤，无法修改。请注意，任何依赖车辆重量的计算或功能均基于此固定值运行。

集成步骤

为提供前提条件部分列出的参数，请执行以下步骤。

步骤 1. 创建 `VehicleIntegrationApiClient` 实例

创建一个 VehicleIntegrationApiClient 实例。您可以在快速入门指南中了解更多信息。

步骤 2. 初始化参数

在将参数发送到应用程序之前，必须使用可用的 vehicleinfo 数据类初始化它们。

1import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Duration
2import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.ElectricCurrent
3import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Energy
4import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Power
5import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Speed
6import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Voltage
7import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
8import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.batteryinfo.BatteryInfoParameters
9import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfo
10import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfoParameters
11import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ElectricityType
12import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.VehicleConnectorType
13import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.ConsumptionCurveParameters
14import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.EvSpeedConsumptionCurve
15import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.evefficiency.EvEfficiencyParameters
16
17// 电池相关参数
18private val _batteryInfoParameters = BatteryInfoParameters(
19    currentBatteryCapacity = "从车辆接收的容量", // 例如：Energy.kilowattHours(80)
20    stateOfEnergy = "从车辆接收的 SoE",          // 例如：Energy.kilowattHours(40)
21    stateOfCharge = "从车辆接收的 SoC",          // 例如：68.9
22    batteryChargeCurve = "车辆支持的电池充电曲线", // 例如：
23        listOf(
24            BatteryInfoParameters.Point(energy = Energy.kilowattHours(0), power = Power.kilowatts(75)),
25            BatteryInfoParameters.Point(energy = Energy.kilowattHours(8), power = Power.kilowatts(150)),
26            BatteryInfoParameters.Point(energy = Energy.kilowattHours(40), power = Power.kilowatts(112)),
27            BatteryInfoParameters.Point(energy = Energy.kilowattHours(64), power = Power.kilowatts(52)),
28            BatteryInfoParameters.Point(energy = Energy.kilowattHours(72), power = Power.kilowatts(30)),
29            BatteryInfoParameters.Point(energy = Energy.kilowattHours(80), power = Power.kilowatts(0))
30        )
31)
32
33// 能耗相关参数
34private val _speedConsumptionCurve = ConsumptionCurveParameters(
35    speedConsumptionCurve = EvSpeedConsumptionCurve(
36        consumptionCurve = "车辆在特定速度下的能耗", // 例如：
37            listOf(
38                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(10), energy = Energy.wattHours(114.1)),
39                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(20), energy = Energy.wattHours(91.7)),
40                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(30), energy = Energy.wattHours(87.7)),
41                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(40), energy = Energy.wattHours(89.5)),
42                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(50), energy = Energy.wattHours(94.8)),
43                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(60), energy = Energy.wattHours(102.6)),
44                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(70), energy = Energy.wattHours(112.6)),
45                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(80), energy = Energy.wattHours(124.6)),
46                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(90), energy = Energy.wattHours(138.5)),
47                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(100), energy = Energy.wattHours(154.3)),
48                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(110), energy = Energy.wattHours(171.9)),
49                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(120), energy = Energy.wattHours(191.3)),
50                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(130), energy = Energy.wattHours(212.5)),
51                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(140), energy = Energy.wattHours(235.5)),
52                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(150), energy = Energy.wattHours(260.2)),
53                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(160), energy = Energy.wattHours(286.6)),
54                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(170), energy = Energy.wattHours(314.8)),
55                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(180), energy = Energy.wattHours(344.8)),
56                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(190), energy = Energy.wattHours(376.5)),
57                EvSpeedConsumptionCurve.Point(speed = Speed.kilometersPerHour(200), energy = Energy.wattHours(409.9))
58            )
59    )
60)
61
62// 效率相关参数
63private val _evEfficiencyParameters = EvEfficiencyParameters(
64    uphillEfficiency = "车辆上坡效率",         // 例如：0.85
65    downhillEfficiency = "车辆下坡效率",       // 例如：1.0
66    accelerationEfficiency = "车辆加速效率",   // 例如：0.9
67    decelerationEfficiency = "车辆减速效率"    // 例如：0.95
68)
69
70// 连接器相关参数
71private val _connectorInfoParameters = ConnectorInfoParameters(
72    vehicleConnectors = "车辆支持的连接器", // 例如：
73        listOf(
74            ConnectorInfo(
75                vehicleConnectorType = VehicleConnectorType.TYPE2_CCS,
76                electricityType = ElectricityType.DC,
77                maxVoltage = Voltage.volts(800),
78                maxCurrent = ElectricCurrent.amperes(500),
79                maxPower = Power.kilowatts(350),
80                baseLoad = Power.watts(0),
81                efficiency = 0.98
82            )
83        ),
84    connectorChargingAdapters = "车辆支持的适配器",         // 例如：emptyList()
85    preSelectedChargingAdapters = "应用预选的适配器",      // 例如：emptyList()
86    chargingTimeOffset = "到达充电站与实际开始充电之间的估计时间" // 例如：Duration.seconds(300)
87)
88
89// 辅助电源相关参数
90private val _auxiliaryPowerParameters = AuxiliaryPowerParameters(
91    auxiliaryPower = "从车辆接收的辅助功率" // 例如：Power.watts(100)
92)

步骤 3. 发送参数

参数初始化完成后，您可以使用 VehicleInfoManager 将它们发送到应用程序。例如，发送辅助电源参数：

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.VehicleInfoManager
3import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerCallback
4import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
5import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerFailure
6import com.tomtom.automotive.integration.vehicle.common.Callback
7import com.tomtom.automotive.integration.vehicle.common.Result
8
9vehicleIntegrationApiClient.vehicleInfoManager.setAuxiliaryPower(
10    _auxiliaryPowerParameters,
11    object : AuxiliaryPowerCallback {
12        override fun onResult(result: Result<Unit, out AuxiliaryPowerFailure>) {
13            when (result) {
14                is Result.Success<*> -> {
15                    // 如有需要，处理成功
16                }
17                is Result.Failure<*> -> {
18                    // 处理失败
19                }
20            }
21        }
22
23        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
24            // 处理错误
25        }
26    }
27)

步骤 4. 确认集成成功

参数成功发送后，您的应用应能利用 EV 导航功能，包括长距离 EV 路由。要验证这些功能，请规划一个超过车辆续航里程的目的地路线。应用应自动生成包含必要充电停靠点的路线。

有关如何在应用中规划长距离 EV 路线的更多信息，请参阅EV 路由指南。

最佳实践

使用 Kotlin Flows 更新应用程序

Kotlin flows 提供了一个强大的响应式编程模型，用于管理异步数据流。通过使用 MutableStateFlow 来处理来自车辆的数据，您可以实现一个动态且响应迅速的系统，当车辆底层数据（如 SoE 或 SoC）发生变化时，能够自动更新 VehicleIntegrationApiClient。

注意
及时响应车辆数据变化并更新应用程序，对于提供可靠且可信赖的 EV 导航体验至关重要。