車輛屬性

車輛硬體抽象層 (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。因此，系統只會傳回要求區域 ID 目前的值。如果屬性是全域，則區域 ID 為 0。
  • set 呼叫區域屬性時，要求中一律會包含區域 ID。因此，系統只會變更要求的 Area ID。
  • subscribe 呼叫會為資源的所有區域 ID 產生事件。

接聽來電

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

VHAL 取得空調範例

圖 1. 確認空調溫度 (CS = CarService，VHAL = 車輛 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 中 VMS 屬性所面對的車輛系統，或是具有特殊權限的 Android 應用程式。在 VMS 上共用的資料僅限於車輛系統和支援應用程式使用的地圖資料。

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