車輛屬性

車輛硬體抽象層 (VHAL) 介面定義了原始設備製造商 (OEM) 可實作的屬性，並包含屬性中繼資料 (例如屬性是否為 int，以及允許哪些變更模式)。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，int

處理可用區屬性

區塊資源等同於多個資源的集合，可透過指定的區域 ID 值存取每個子資源。

  • 區域屬性的 get 呼叫一律會在要求中加入區域 ID。因此，系統只會傳回要求的 Area ID 目前的值。如果屬性是全域，則區域 ID 為 0。
  • set 呼叫區域屬性時，要求中一律會包含區域 ID。因此，系統只會變更要求的 Area ID。
  • subscribe 呼叫會為資源的所有區域 ID 產生事件。

接聽來電

在初始化期間，由於尚未收到相符的車輛網路訊息，因此可能無法使用資源值。在這種情況下，get 呼叫應傳回 -EAGAIN。部分房源 (例如空調設備) 有獨立的開/關電源屬性。針對此類屬性 (在關閉時) 呼叫 get 時，應傳回 UNAVAILABLE 狀態，而非傳回錯誤。例如取得空調溫度

VHAL 取得空調系統範例

圖 1. 取得空調溫度 (CS = CarService、VHAL = Vehicle HAL)

設定通話

在一般作業中，set 呼叫會導致在車輛網路中提出變更要求。set 呼叫的理想情況是盡快傳回的非同步作業，但也可以是同步作業。某些 set 呼叫可能需要初始資料，但在初始化期間，這類資料可能尚未可用。在這種情況下，set 呼叫應傳回 StatusCode#TRY_AGAIN。部分具有獨立開關的房源，在關閉電源且無法執行 set 時，應傳回 StatusCode#NOT_AVAILABLE 或 StatusCode#NOT_AVAILABLE_DISABLED。在 set 生效之前，get 不一定會傳回與設定值相同的值。例如：set HVAC Temperature。

VHAL 設定空調系統範例

圖 2. 設定空調系統溫度 (CS = CarService，VHAL = 車輛 HAL)

處理自訂屬性

為支援合作夥伴的特定需求，VHAL 允許自訂屬性，但僅限於系統應用程式。使用自訂資源時，請遵守下列規範：

  • 產生房源 ID 時，請使用下列欄位：
    • VehiclePropertyGroup:VENDOR
      VENDOR 群組僅適用於自訂資源。
    • VehicleArea
      選取適當的區域類型。
    • VehiclePropertyType
      選取適當的資料類型。BYTES 類型可傳遞原始資料，在大多數情況下都足以應付。經常透過自訂屬性傳送大量資料可能會降低整個車輛網路的存取速度，因此請謹慎新增大型酬載。
    • Property ID
      為自訂屬性選擇四個位元組 ID。
  • 為避免生態系統分散，請勿使用自訂屬性複製 (VehiclePropertyIds SDK) 中已存在的車輛屬性。
  • 在 VehiclePropConfig.configString 中填入自訂資源的簡短說明。這樣一來，健全性檢查工具就能標示意外複製現有車輛屬性。例如「hazard light state」。
  • 透過 CarPropertyManager (適用於 Java 元件) 或 Vehicle Network Service API (適用於原生) 存取。請勿修改其他車輛 API，否則可能會導致日後的相容性問題。
  • 實作供應商屬性後，請僅 選取供應商屬性的 VehicleVendorPermission 列舉中的權限清單。將供應商權限對應至系統屬性會導致 CTS 和 VTS 發生問題。

處理空調屬性

您可以使用 VHAL 設定 HVAC 相關的屬性，藉此控管 HVAC。大部分的空調設備資源都是區域資源，但也有幾個是非區域 (全域) 資源。定義的屬性範例包括：

資源 目的
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET 設定每個區域的溫度。
VEHICLE_PROPERTY_HVAC_RECIRC_ON 控管各區域的回風循環。

如要查看完整的 HVAC 屬性清單，請在 types.hal 中搜尋 VEHICLE_PROPERTY_HVAC_*。如果空調系統屬性使用 VehicleAreaSeat，系統會套用其他規則，將區分區的空調系統屬性對應至區域 ID。車輛中的每個可用座位都必須是 Area ID 陣列中的 Area ID 的一部分。

示例一：車輛有兩個前座 (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

第二個範例。車輛有三排座椅，前排有兩個座位 (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) 提供一種機制，可透過發布/訂閱介面在用戶端之間交換地圖資料，以支援常見的車輛功能，例如先進駕駛輔助系統 (ADAS)。用戶端可透過 VHAL 或特權 Android 應用程式中的 VMS 屬性，加入車輛系統介面。在 VMS 上共用的資料僅限於車輛系統和支援應用程式使用的地圖資料。

VMS 僅適用於 Android Automotive 實作；AOSP 不包含發布或訂閱 VMS 的預設用戶端。針對 VHAL 中的 VMS 屬性，訊息類型和資料結構已在 VHAL 2.0 的 VmsMessageType 列舉中說明，其中列出支援的 VMS 訊息類型。這個列舉會用於車輛屬性整數陣列中的首個整數，並決定如何解碼訊息的其餘部分。