车辆参数设置

功能介绍

车辆参数用于驱动 SDK 的路线约束、道路可通行性判断以及部分导航行为（例如货车限行、隧道限制、危险品规避、EV 相关能力）。

SDK 支持以下 3 类车辆类型的参数配置能力：

乘用车（PV）
房车（RV）
商用车（Truck），并细分为：
- 厢式货车
- 重卡（牵引车/半挂）

时序图

车辆参数支持两种配置方式：可在 SDK 初始化时一次性配置，也可在运行过程中按需动态更新，满足不同业务阶段的车辆信息管理需求。

车辆参数设置时序图

核心接口

1) 初始化阶段（推荐）

VehicleInfoConfig.Builder
- setVehicleCategory(...)
- setVehicleDimensions(...)
- setDrivetrainType(...)
- setEnergyProfile(...)
- setEnergyLevel(...)
- setAxleProfile(...)
- setHazardousMaterialTypes(...)
- setTunnelRestrictionCode(...)
- setTrailerCount(...)

用于在 SDK.initialize(...) 前构建初始车辆参数，适合 HMI 已有稳定车辆档案的场景。当前该 Builder 未提供 setTractorType(...)，重卡牵引车类型请在初始化成功后通过 vehicleInfoProvider.setTractorType(...) 设置。

2) 运行时阶段（动态更新）

SDK.getInstance().vehicleInfoProvider
- 通用：setModelName、setDimensions、setDrivetrainType、setVehicleStatus
- 能源：setEnergyProfile、setEnergyLevel、setEvChargePortConnectionStatus、setEvChargeStatus
- 货车扩展：setAxleProfile、setHazardousMaterialTypes、setTunnelRestrictionCode、setTrailerCount、setTractorType

适合挂车状态变化、载重变化、能源状态变化等实时场景。
基于实际应用场景，vehicleCategory 通常在初始化阶段通过 VehicleInfoConfig.Builder.setVehicleCategory(...) 完成设置；运行时更适合更新尺寸、挂车、能源状态等动态参数。

关键参数（按车型）

乘用车（PV）

建议最少设置：

vehicleCategory = VehicleCategory.AUTO

按业务能力可选设置：

驱动形式（drivetrainType）：
- 两驱（DrivetrainType.TWO_WHEEL_DRIVE）
- 四驱（DrivetrainType.FOUR_WHEEL_DRIVE，四驱车型建议设置）
EV 相关参数：
- 能源画像（energyProfile）
- 当前能源水平（energyLevel）
- 能源类型（energyType）支持：详见枚举取值总览（按参数）
dimensions 通常不作为 PV 场景的重点约束参数

房车（RV）

建议最少设置：

vehicleCategory = VehicleCategory.RV
dimensions：建议完整设置以下字段：
- 长度（length）
- 宽度（width）
- 高度（height）
- 重量（weight）

按业务能力可选设置：

驱动形式（drivetrainType）：
- 两驱（DrivetrainType.TWO_WHEEL_DRIVE）
- 四驱（DrivetrainType.FOUR_WHEEL_DRIVE，若车型支持四驱请设置；否则设置为 TWO_WHEEL_DRIVE）
隧道限制等级（tunnelRestrictionCode，详见枚举取值总览（按参数））
危险品类型（hazardousMaterialTypes，详见枚举取值总览（按参数））

商用车（Truck）

1) 厢式货车（可支持拖车）

建议最少设置：

车辆类别（vehicleCategory = VehicleCategory.TRUCK）
车辆尺寸与质量（dimensions）：
- 长度（length）
- 宽度（width）
- 高度（height）
- 重量（weight）
- 最大允许总质量（grossVehicleMass / GVM，建议同时设置）。GVM/GVW/MAM 的口径可参考英国政府对车辆重量术语的说明（官方链接：GOV.UK Vehicle weights explained）。

建议补充设置：

车轴画像（axleProfile）：
- 最大单轴载重（maxWeightPerAxle）
- 最大轴距（maxDistanceBetweenAxles）
- 轴总数（amountOfAxles）
- 轴组（axleGroups）
隧道限制等级（tunnelRestrictionCode，详见枚举取值总览（按参数））
危险品类型（hazardousMaterialTypes，如有危险品运输，详见枚举取值总览（按参数））
挂车数量（trailerCount，如有拖车请按实际挂接数量设置）
如为新能源厢式货车，SDK 支持 EV 算路；请补充设置 EV 相关参数（energyProfile、energyLevel）

2) 重卡（牵引车/半挂）

建议最少设置：

车辆类别（vehicleCategory = VehicleCategory.TRUCK）
车辆尺寸与质量（dimensions）：
- 长度（length）
- 宽度（width）
- 高度（height）
- 重量（weight）
- 最大允许总质量（grossVehicleMass / GVM，建议同时设置）。
车轴画像（axleProfile）：
- 最大单轴载重（maxWeightPerAxle）
- 最大轴距（maxDistanceBetweenAxles）
- 轴总数（amountOfAxles）
- 轴组（axleGroups）
牵引车类型（tractorType）：
- 牵引车（TractorType.TRACTOR）
- 带标准半挂（TractorType.WITH_SEMI_TRAILER）
- 带冷藏半挂（TractorType.WITH_REFRIGERATED_SEMI_TRAILER）
挂车数量（trailerCount）

建议补充设置：

隧道限制等级（tunnelRestrictionCode，详见枚举取值总览（按参数））
危险品类型（hazardousMaterialTypes，详见枚举取值总览（按参数））

挂车相关参数口径说明（dimensions）：

length：如果挂车通过球铰接（可转向）连接，填写“最长单体”的长度；否则填写“整车总长度”。
width：填写主车与挂车中最宽部分。
height：填写主车与挂车中最高部分。
weight：应包含主车与已挂接挂车的总重量。
grossVehicleMass / GVM：填写车辆制造商标定的最大允许总质量，通常用于判断道路、桥梁、牌照和车型法规限制。

枚举取值总览（按参数）

车辆类别（vehicleCategory）：
- VehicleCategory.UNKNOWN：未知或未设置车型。仅建议在无法确认车型时使用，实际算路可能按默认车辆处理。
- VehicleCategory.AUTO：普通乘用车。适用于轿车、SUV、MPV 等非商用重型车辆。
- VehicleCategory.RV：房车/休旅车。适用于需要考虑车高、车长、露营车通行限制的车辆。
- VehicleCategory.TRUCK：货车/商用车。适用于需要考虑限高、限宽、限重、轴重、危险品等约束的车辆。
驱动形式（drivetrainType）：
- DrivetrainType.UNKNOWN：未知或未设置驱动形式。
- DrivetrainType.TWO_WHEEL_DRIVE：两驱车辆，通常用于普通公路通行场景。
- DrivetrainType.FOUR_WHEEL_DRIVE：四驱车辆，可用于越野、低附着路面或需要区分通行能力的场景。
能源类型（energyType）：
- EnergyType.UNKNOWN：未知或未设置能源类型。
- EnergyType.DIESEL：柴油车。常见于货车、客车等商用车型。
- EnergyType.GASOLINE：汽油车。常见于普通乘用车。
- EnergyType.ELECTRIC：纯电动车。可用于后续结合充电、续航、限行等电动车相关能力。
牵引车类型（tractorType）：
- TractorType.TRACTOR：牵引车头或单独牵引车配置。
- TractorType.WITH_SEMI_TRAILER：牵引车带标准半挂车。尺寸、重量应按组合车辆填写。
- TractorType.WITH_REFRIGERATED_SEMI_TRAILER：牵引车带冷藏半挂车。适用于冷链运输等可能有额外车辆属性的场景。
隧道限制等级（tunnelRestrictionCode）：
- TunnelRestrictionCode.NO_LOAD_CODE_APPLICABLE：未装载适用隧道限制的危险品，或当前货物不适用隧道限制代码。
- TunnelRestrictionCode.TUNNEL_RESTRICTION_CODE_B：限制等级 B。通常代表最高风险限制，装载物可能导致非常大规模爆炸，限制范围最宽。
- TunnelRestrictionCode.TUNNEL_RESTRICTION_CODE_C：限制等级 C。通常覆盖非常大规模爆炸、大规模爆炸或大量有毒物质释放风险。
- TunnelRestrictionCode.TUNNEL_RESTRICTION_CODE_D：限制等级 D。通常覆盖爆炸、有毒释放以及大规模火灾风险。
- TunnelRestrictionCode.TUNNEL_RESTRICTION_CODE_E：限制等级 E。通常表示仅限制进入 E 类隧道，是 ADR 隧道限制代码中相对较低的限制。
隧道限制等级可参考 UNECE ADR 规范：ADR 2023 Volume 2 的 Chapter 8.6 “Road tunnel restrictions for the passage of vehicles carrying dangerous goods” 定义了危险品车辆通过道路隧道的限制代码与通行规则（官方链接：UNECE ADR 2023 Volume 2）。实际业务中应以当地法规、道路标识和项目数据配置为准。
危险品类型（hazardousMaterialTypes）：
- HazardousMaterialType.EXPLOSIVE：爆炸品，如烟花、爆破材料等。
- HazardousMaterialType.GAS：气体类危险品，如压缩气体、液化气体等。
- HazardousMaterialType.FLAMMABLE：易燃品，通常指易燃液体或易燃物质。
- HazardousMaterialType.COMBUSTIBLE：可燃品，燃点相对较高但仍有燃烧风险。
- HazardousMaterialType.ORGANIC：有机危险品，如有机过氧化物等需特殊管控的物质。
- HazardousMaterialType.POISON：有毒物质，接触、摄入或泄漏可能造成中毒风险。
- HazardousMaterialType.RADIOACTIVE：放射性物质。
- HazardousMaterialType.CORROSIVE：腐蚀性物质，如强酸、强碱等。
- HazardousMaterialType.POISONOUS_INHALATION：吸入性有毒物质，泄漏后经呼吸道造成高风险。
- HazardousMaterialType.HARMFUL_FOR_WATER：对水体有害物质，泄漏后可能造成水环境污染。
- HazardousMaterialType.OTHER：其他危险品类型，无法归入上述分类时使用。
危险品/有害物质分类可参考 UNECE ADR 规范：ADR 2023 Volume 1 的 Part 2 “Classification” 定义了道路危险品运输中的 Class 1 爆炸品、Class 2 气体、Class 3 易燃液体、Class 7 放射性物质、Class 8 腐蚀性物质等分类体系（官方链接：UNECE ADR 2023 Volume 1）。项目实现中应以 SDK 枚举、客户车型配置和当地法规要求为准。
轴组类型（axleGroup.type）：
- AxleGroupType.SINGLE：单轴组。
- AxleGroupType.TANDEM：双联轴组。
- AxleGroupType.TRIPLE：三联轴组。
- AxleGroupType.QUAD：四联轴组。
- AxleGroupType.QUINT：五联轴组。
每侧每轴轮胎数（axleGroup.wheelsPerAxle）：
- WheelsPerAxle.SINGLE：每侧单胎。
- WheelsPerAxle.DUAL：每侧双胎，常见于重型货车后轴。
- WheelsPerAxle.TRIPLE：每侧三胎。
- WheelsPerAxle.QUAD：每侧四胎。
- WheelsPerAxle.QUINT：每侧五胎。

示例代码

1) SDK 初始化时设置车辆参数

import com.telenav.sdk.SDK
import com.telenav.sdk.common.model.*
import com.telenav.sdk.options.NavSDKOptions
import com.telenav.sdk.options.SDKOptions

val vehicleDimensions = VehicleDimensions.Builder()
    .setLength(680)          // cm
    .setWidth(255)           // cm
    .setHeight(390)          // cm
    .setWeight(12000)        // kg
    .setGrossVehicleMass(18000)
    .build()

val axleGroup = AxleGroupProfile.Builder()
    .setType(AxleGroupType.TANDEM)
    .setWeightForAxleGroup(24000)
    .setWheelsPerAxle(WheelsPerAxle.DUAL)
    .build()

val axleProfile = AxleProfile.Builder()
    .setMaxWeightPerAxle(12000)
    .setMaxDistanceBetweenAxles(450)  // cm
    .setAmountOfAxles(4)
    .setAxleGroups(arrayListOf(axleGroup))
    .build()

val vehicleInfoConfig = VehicleInfoConfig.Builder()
    .setVehicleCategory(VehicleCategory.TRUCK)
    .setVehicleDimensions(vehicleDimensions)
    .setAxleProfile(axleProfile)
    .setTunnelRestrictionCode(TunnelRestrictionCode.NO_LOAD_CODE_APPLICABLE)
    .setTrailerCount(1)
    .build()

val sdkOptions = SDKOptions.builder()
    .setApiKey("<YOUR_API_KEY>")
    .setApiSecret("<YOUR_API_SECRET>")
    .setCloudEndPoint("<YOUR_CLOUD_ENDPOINT>")
    .setRegion("<YOUR_REGION>")
    .build()

val navOptions = NavSDKOptions.builder(sdkOptions, vehicleInfoConfig).build()
SDK.getInstance().initialize(context, navOptions)

2) 运行时更新车辆参数

import com.telenav.sdk.SDK
import com.telenav.sdk.common.model.*

val provider = SDK.getInstance().vehicleInfoProvider

fun updateCommonRuntimeParams() {
    provider.setDrivetrainType(DrivetrainType.FOUR_WHEEL_DRIVE)
    val rvDimensions = VehicleDimensions.Builder()
        .setLength(780)
        .setWidth(250)
        .setHeight(320)
        .setWeight(5500)
        .setGrossVehicleMass(7500)
        .build()
    provider.setDimensions(rvDimensions)
}

fun updateTruckRuntimeParams() {
    val vanDimensions = VehicleDimensions.Builder()
        .setLength(720)
        .setWidth(245)
        .setHeight(310)
        .setWeight(8000)
        .setGrossVehicleMass(12000)
        .build()
    provider.setDimensions(vanDimensions)
    provider.setTrailerCount(0)
}

fun updateHeavyTruckRuntimeParams() {
    provider.setTractorType(TractorType.WITH_SEMI_TRAILER)
    provider.setTrailerCount(1)
    provider.setTunnelRestrictionCode(TunnelRestrictionCode.NO_LOAD_CODE_APPLICABLE)
    provider.setHazardousMaterialTypes(
        listOf(HazardousMaterialType.EXPLOSIVE, HazardousMaterialType.FLAMMABLE)
    )
}

注意事项

建议在创建 NavigationService 或发起首个算路任务前完成关键车辆参数设置；缺失关键参数可能导致初始化阶段行为不符合预期。
TruckInfoProvider 相关参数（轴组、危险品、隧道码、挂车数等）在导航进行中修改，通常不会影响当前导航行为；需要停止并重新开始导航，或重新发起算路任务后生效。
当挂车数量或挂车形态发生变化时，建议同步更新 trailerCount 与 dimensions（length/width/height/weight），避免路线约束判断与实际车辆状态不一致。
Android VehicleInfoProvider 不提供 setVehicleCategory(...)；如需从 AUTO/RV/TRUCK 切换车型，请在初始化阶段通过 VehicleInfoConfig.Builder.setVehicleCategory(...) 重新配置。
参数有默认值：如 vehicleCategory=Unknown、尺寸/重量默认 0。未设置时等价于“未知”，可能弱化或关闭对应约束能力。
EV 场景下若 energyType 为电动，必须提供有效电量（EnergyLevel.evBatteryPercent），否则部分 EV 功能可能不可用。
VehicleInfoProvider 的变更通知是“值变化触发”：重复设置同值不会重复通知监听器。
setVehicleStatus 只会对空调状态和驻车加热状态变化触发通知，温度字段变化不会触发对应 listener 回调。