车辆属性

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

HAL 接口

VHAL 使用以下接口：

  • vehicle_prop_config_t const *(*list_properties)(..., int* num_properties)
    列出 VHAL 所支持的所有属性的配置。车辆网络服务只会使用受支持的属性。
  • (*get)(..., vehicle_prop_value_t *data)
    读取属性的当前值。对于区域属性，每个区域都可能具有不同的值。
  • (*set)(..., const vehicle_prop_value_t *data)
    为属性写入相应值。写入的结果是按属性进行定义。
  • (*subscribe)(..., int32_t prop, float sample_rate, int32_t zones)
    • 开始监视属性值的变化。对于区域属性，订阅适用于请求的区域。Zones = 0 用于请求所有受支持的区域。
    • VHAL 应该在属性值发生变化时（即变化时触发类型）或按一定间隔（即连续类型）调用单独的回调。
  • (*release_memory_from_get)(struct vehicle_hw_device* device, vehicle_prop_value_t *data)
    释放从 get 调用分配的内存。

VHAL 使用以下回调接口：

  • (*vehicle_event_callback_fn)(const vehicle_prop_value_t *event_data)
    通知车辆属性值的变化。应只针对已订阅属性执行。
  • (*vehicle_error_callback_fn)(int32_t error_code, int32_t property, int32_t operation)
    返回全局 VHAL 级错误或每个属性的错误。全局错误会导致 HAL 重新启动，这可能会导致包括应用在内的其他组件重新启动。

车辆属性

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

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

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

区域类型

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
    该属性有问题。

配置属性

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

  • access（r、w、rw）
  • changeMode（表示监视属性的方式：变化模式还是连续模式）
  • areaConfigs（areaId、最小值和最大值）
  • configArray（其他配置参数）
  • configString（以字符串的形式传递的其他信息）
  • minSampleRate、max_sample_rate
  • prop（属性 ID、int）

处理区域属性

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

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

Get 调用

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

示例：获取 HVAC 温度

VHAL get HVAC 示例

图 1. 获取 HVAC 温度（CS = CarService、VNS = VehicleNetworkService、VHAL = 车载 HAL）

Set 调用

set 调用属于异步操作，涉及进行所请求更改之后的事件通知。在典型的操作中，set 调用会导致在车辆网络中发出更改请求。拥有该属性的电子控制单元 (ECU) 执行更改后，更新后的值通过车辆网络返回，而车载 HAL 会将更新后的值作为事件发送给车辆网络服务 (VNS)。

某些 set 调用可能要求准备好初始数据，而这些数据在初始化期间可能尚不可用。在这种情况下，set 调用应该返回 -EAGAIN。某些具有独立的电源开/关的属性应在属性关闭且无法设置时返回 -ESHUTDOWN。

在 set 生效之前，get 不一定会返回所设置的值。

示例：设置 HVAC 温度

VHAL set HVAC 示例

图 2.设置 HVAC 温度（CS = CarService、VNS = VehicleNetworkService、VHAL = 车载 HAL）

处理自定义属性

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

  • 应使用以下字段生成属性 ID：
    • VehiclePropertyGroup:VENDOR
      VENDOR 组仅用于自定义属性。
    • VehicleArea
      选择适当的区域类型。
    • VehiclePropertyType
      选择适当的数据类型。BYTES 类型允许传递原始数据，因此，在大多数情况下是足够的。通过自定义属性频繁发送大数据可能会减缓整个车辆网络的访问速度，因此，在添加大量需要 HAL 处理的数据时要小心谨慎。
    • 属性 ID
      为自定义属性选择一个四位半字节 ID。
  • 通过 CarPropertyManager（适用于 Java 组件）或 Vehicle Network Service API（适用于本机）访问。请勿修改其他汽车 API，因为这样做可能会在将来导致兼容性问题。

处理 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 传感器属性表示真实的传感器数据或策略信息（如驾驶状态）。任何应用都可以不受限制地访问某些传感器信息（如驾驶状态和日间/夜间模式），因为这些数据是构建安全车载应用所必需的。其他传感器信息（如车辆速度）较为敏感，需要获取用户可管理的特定权限才能查看。

支持的传感器属性包括：

  • NIGHT_MODE
    应该支持。确定日间/夜间显示模式。
  • GEAR_SELECTION/CURRENT_GEAR
    驾驶员选择的挡位与实际挡位。
  • VEHICLE_SPEED
    车速。受权限保护。
  • ODOMETER
    当前里程表读数。受权限保护。
  • FUEL_LEVEL
    当前油位 (%)。
  • FUEL_LEVEL_LOW
    油位是否较低（布尔值）。

车载地图服务

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

VMS 仅适用于 Android Automotive 实现；AOSP 不包含发布或订阅 VMS 的默认客户端。

对于 VHAL 中的 VMS 属性，VmsMessageType 枚举中的 VHAL 2.0 中对消息类型和数据结构进行了说明，其中列出了受支持的 VMS 消息的类型。此枚举用作车辆属性整数数组中的第一个整数，并用于确定消息其余部分的解码方式。