车辆属性

车载硬件抽象层 (VHAL) 接口会定义原始设备制造商 (OEM) 可以实现的属性，并会包含属性元数据（例如，属性是否为整数以及允许使用哪些更改模式）。VHAL 接口以对属性的访问（读取、写入、订阅）为基础，属性即为一个特定函数的抽象。

HAL 接口

VHAL 使用以下接口：

  • getAllPropConfigs() 会生成 (vec<VehiclePropConfig>propConfigs)
    列出 VHAL 所支持的所有属性的配置。CarService 仅使用支持的属性。
  • getPropConfigs(vec<int32_t> props) 会生成 (StatusCode status,vec<VehiclePropConfig> propConfigs);
    返回所选属性的配置。
  • set(VehiclePropValue propValue) 会生成 (StatusCodestatus);
    向属性写入一个值。写入的结果是按属性进行定义的。
  • subscribe(IVehicleCallback callback, vec<SubscribeOptions> options) 会生成 (StatusCode status);
    开始监视属性值的变化。对于区域属性，unsubscribe(IVehicleCallback callback, int32_t propId) 会生成 (StatusCode status);

VHAL 使用以下回调接口：

  • oneway onPropertyEvent(vec<VehiclePropValue>propValues);
    通知车辆属性值的变化。应只针对已订阅属性执行。
  • oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
    返回全局 VHAL 级错误或每个属性的错误。全局错误会导致 HAL 重新启动，这可能会导致包括应用在内的其他组件重新启动。

车辆属性

属性可以为只读、只写（用于将信息传递到 VHAL 一级），也可以为读写（对大多数属性而言对读写的支持是可选的）。每个属性都由一个 int32 键唯一标识，且具有一个预定义的类型 (value_type)：

  • BYTES
  • BOOLEAN
  • EPOCH_TIME
  • FLOAT
  • FLOAT[]
  • INT32
  • INT32[]
  • INT64
  • INT64[]
  • STRING
  • MIXED

区域属性可能具有多个值，具体取决于属性所支持的区域数量。

区域类型

VHAL 定义了多种区域类型：

区域类型 说明
GLOBAL 此属性是一个单例，不具备多个区域。
WINDOW 基于车窗的区域，使用 VehicleAreaWindow 枚举。
MIRROR 基于车镜的区域，使用 VehicleAreaMirror 枚举。
SEAT 基于座椅的区域，使用 VehicleAreaSeat 枚举。
DOOR 基于车门的区域，使用 VehicleAreaDoor 枚举。
WHEEL 基于车轮的区域，使用 VehicleAreaWheel 枚举。

每个区域属性都必须使用一个预定义的区域类型。每种区域类型都有一组在区域类型的枚举中定义的位标志。例如，SEAT 区域定义了 VehicleAreaSeat 枚举：

  • ROW_1_LEFT = 0x0001
  • ROW_1_CENTER = 0x0002
  • ROW_1_RIGHT = 0x0004
  • ROW_2_LEFT = 0x0010
  • ROW_2_CENTER = 0x0020
  • ROW_2_RIGHT = 0x0040
  • ROW_3_LEFT = 0x0100
  • …

区域 ID

区域属性通过区域 ID 进行寻址。每个区域属性都可以支持一个或多个区域 ID。区域 ID 由其各自枚举中的一个或多个标志组成。例如，使用 VehicleAreaSeat 的属性可能会使用以下区域 ID：

项目 说明
ROW_1_LEFT | ROW_1_RIGHT 区域 ID 适用于两个前排座椅。
ROW_2_LEFT 仅适用于后排左侧座位。
ROW_2_RIGHT 仅适用于后排右侧座位。

属性状态

每个属性值都有一个 VehiclePropertyStatus 值。该值指示相应属性的当前状态：

项目 说明
AVAILABLE 属性可用，且值有效。
UNAVAILABLE 属性值目前不可用。用于某个受支持属性的被暂时停用的功能。
ERROR 该属性有问题。

配置属性

使用 VehiclePropConfig 为每个属性提供配置信息。具体信息包括：

变量 说明
access r、w、rw
changeMode 表示监视属性的方式：变化时监视或持续监视。
areaConfigs areaId、min 和 max 值。
configArray 额外配置参数。
configString 以字符串形式传递的额外信息。
minSampleRate maxSampleRate
prop 属性 ID，整数

处理区域属性

区域属性相当于多个属性的集合，其中每个子属性都可使用指定的区域 ID 值来访问。

  • 区域属性的 get 调用始终在请求中包含区域 ID。因此，系统只返回所请求的区域 ID 的当前值。如果属性是全局属性，那么区域 ID 为 0。
  • 区域属性的 set 调用始终在请求中包含区域 ID。因此，只有请求的区域 ID 会发生改变。
  • subscribe 调用为属性的所有区域 ID 生成事件。

Get 调用

在初始化期间，由于尚未收到匹配的车辆网络消息，属性的值可能不可用。在这种情况下，get 调用应返回 -EAGAIN。一些属性（例如 HVAC）具有独立的电源开/关属性。对此类属性调用 get（关闭电源时）应返回 UNAVAILABLE 状态，而不是返回错误。例如，get HVAC 温度

VHAL get HVAC 示例

图 1. Get HVAC 温度（CS = CarService、VHAL = 车载 HAL）

Set 调用

在通常的操作中，set 调用会导致在车辆网络中发出更改请求。set 调用最好是异步操作，能够尽快返回，但也可以是同步操作。某些 set 调用可能要求准备好初始数据，而这些数据在初始化期间可能尚不可用。在这种情况下，set 调用应返回 StatusCode#TRY_AGAIN。某些具有独立电源开/关的属性应在属性关闭且无法完成 set 时返回 StatusCode#NOT_AVAILABLE 或 StatusCode#NOT_AVAILABLE_DISABLED。在 set 生效之前，get 不一定会返回所设置的值。例如 set HVAC Temperature。

VHAL set HVAC 示例

图 2. Set HVAC 温度（CS = CarService、VHAL = 车载 HAL）

处理自定义属性

为了满足合作伙伴的特定需求，VHAL 允许使用仅限用于系统应用的自定义属性。在使用自定义属性时，请遵循以下指南：

  • 应使用以下字段生成属性 ID：
    • VehiclePropertyGroup:VENDOR
      VENDOR 组仅用于自定义属性。
    • VehicleArea
      选择适当的区域类型。
    • VehiclePropertyType
      选择适当的数据类型。BYTES 类型允许传递原始数据（在大多数情况下，这就足够了）。频繁地通过自定义属性发送大数据可能会减缓整个车辆网络的访问速度，因此，在添加大量数据时应谨慎。
    • Property ID
      为自定义属性选择一个四位半字节 ID。
  • 为了防止生态系统碎片化，不得使用自定义属性复制 (VehiclePropertyIds SDK) 中已有的车辆属性。
  • 在 VehiclePropConfig.configString 中填写自定义属性的简短说明。这样一来，在已有车辆属性发生意外复制时，健全性检查工具就可以对其进行标记。例如，“危险警示灯的状态”。
  • 通过 CarPropertyManager（适用于 Java 组件）或 Vehicle Network Service API（适用于本机）进行访问。请勿修改其他 Car API，以免日后出现兼容性问题。
  • 实现供应商属性后，请仅在 VehicleVendorPermission 枚举中为供应商属性选择权限列表。将供应商权限映射到系统属性会破坏 CTS 和 VTS。

处理 HVAC 属性

您可以使用 VHAL 控制 HVAC，具体方法是设置与 HVAC 相关的属性。大多数 HVAC 属性均为区域属性，但也有一些为非区域（全局）属性。定义的属性示例包括：

属性 用途
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET 按区域设置温度。
VEHICLE_PROPERTY_HVAC_RECIRC_ON 按区域控制再循环。

如需查看完整的 HVAC 属性列表，请在 types.hal 中搜索 VEHICLE_PROPERTY_HVAC_*。当 HVAC 属性使用 VehicleAreaSeat 时，需遵守将区域 HVAC 属性映射到区域 ID 的额外规则。汽车中的每个可用座椅都必须是区域 ID 数组中某个区域 ID 的一部分。

示例 1：某辆汽车有两个前排座椅 (ROW_1_LEFT, ROW_1_RIGHT) 和三个后排座椅 (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT)，并具有两个温度控制单元，分别位于驾驶员侧和乘客侧。

  • HVAC_TEMPERATURE SET 的区域 ID 的有效映射集如下：
    • ROW_1_LEFT | ROW_2_LEFT
    • ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
  • 同一硬件配置的替代映射如下：
    • ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
    • ROW_1_RIGHT | ROW_2_RIGHT

示例 2：某辆汽车有三排座位，第一排两个座椅 (ROW_1_LEFT, ROW_1_RIGHT)、第二排三个座椅 (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT)，第三排三个座椅 (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT)。这辆汽车具有三个温度控制单元，分别位于驾驶员侧、乘客侧和车厢后部。将 HVAC_TEMPERATURE_SET 映射到区域 ID 的合理方法是使用三个元素数组：

  • ROW_1_LEFT
  • ROW_1_RIGHT
  • ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT

处理传感器属性

VHAL 传感器属性表示真实的传感器数据或政策信息（例如行驶状态）。某些传感器信息（例如行驶状态和日间/夜间模式）可供任何应用不受限制地访问，因为这些数据是构建安全车载应用所必需的。其他传感器信息（例如车辆速度）更为敏感，需要用户可以管理的特定权限。

请参阅支持的传感器属性（在 types.hal 中）。

车载地图服务

车载地图服务 (VMS) 提供一种可通过 Pub/Sub 接口在客户端之间交换地图数据的机制，旨在支持常见的车辆功能，例如高级驾驶辅助系统 (ADAS)。客户端可能包括通过 VHAL 或 Android 特权应用中的 VMS 属性进行连接的车载系统。在 VMS 上共享的数据仅限于供车载系统和支持应用使用的地图数据。

VMS 仅适用于 Android Automotive 实现；AOSP 不包含发布或订阅 VMS 的默认客户端。对于 VHAL 中的 VMS 属性，VHAL 2.0 在 VmsMessageType 枚举内对消息类型和数据结构进行了说明，其中列出了受支持的 VMS 消息的类型。此枚举用作车辆属性整数数组中的第一个整数，并用于确定消息其余部分的解码方式。