EV integration

介绍

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

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

前提条件

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

电池相关参数

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

能耗相关参数

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

效率相关参数

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

连接器相关参数

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

辅助电源相关参数

辅助电源：预计行程剩余时间内由空调、信息娱乐系统和照明等系统消耗的平均辅助功率，单位为瓦特。

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

集成步骤

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

步骤 1. 创建 `VehicleIntegrationApiClient` 实例

创建一个 VehicleIntegrationApiClient 实例。您可以在 Quick start 指南中了解更多信息。

步骤 2. 初始化参数

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

1
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Duration
2
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.ElectricCurrent
3
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Energy
4
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Power
5
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Speed
6
import com.tomtom.automotive.integration.vehicle.client.api.model.quantity.Voltage
7
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
8
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.batteryinfo.BatteryInfoParameters
9
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfo
10
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ConnectorInfoParameters
11
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.ElectricityType
12
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.connectorinfo.VehicleConnectorType
13
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.ConsumptionCurveParameters
14
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.consumptioncurve.EvSpeedConsumptionCurve
15
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.evefficiency.EvEfficiencyParameters
16

17
// 电池相关参数
18
private 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
// 能耗相关参数
34
private 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
// 效率相关参数
63
private val _evEfficiencyParameters = EvEfficiencyParameters(
64
    uphillEfficiency = "车辆上坡效率",         // 例如: 0.85
65
    downhillEfficiency = "车辆下坡效率",       // 例如: 1.0
66
    accelerationEfficiency = "车辆加速效率",   // 例如: 0.9
67
    decelerationEfficiency = "车辆减速效率"    // 例如: 0.95
68
)
69

70
// 连接器相关参数
71
private 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
// 辅助电源相关参数
90
private val _auxiliaryPowerParameters = AuxiliaryPowerParameters(
91
    auxiliaryPower = "从车辆接收的辅助电源功率" // 例如: Power.watts(100)
92
)

步骤 3. 发送参数

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

1
import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.VehicleInfoManager
3
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerCallback
4
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerParameters
5
import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.auxiliarypower.AuxiliaryPowerFailure
6
import com.tomtom.automotive.integration.vehicle.common.Callback
7
import com.tomtom.automotive.integration.vehicle.common.Result
8

9
vehicleIntegrationApiClient.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 Routing 指南。

最佳实践

使用 Kotlin Flows 更新应用程序

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

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