Developer

EV integration

Request Access
Version: 0.5.0

介绍

本教程将指导您如何使用 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 公斤，无法修改。请注意，任何依赖车辆重量的计算或功能均基于此固定值运行。

集成步骤

为提供前述前提条件中的参数，请执行以下步骤。

步骤 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 Routing 指南。

最佳实践

使用 Kotlin Flows 更新应用

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

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