車両プロパティ

Vehicle Hardware Abstraction Layer（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 は、それぞれの列挙値からの 1 つ以上のフラグで構成されます。たとえば、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 が常に含まれるため、リクエストされたエリア ID のみが変更されます。
  • subscribe 呼び出しは、プロパティのすべてのエリア ID のイベントを生成します。

get 呼び出し

初期化中はプロパティの値を利用できない場合があります。これは、一致する車両ネットワーク メッセージをまだ受信していないからです。このような場合、get 呼び出しは -EAGAIN を返します。HVAC などの一部のプロパティは、電源のオン / オフのプロパティを個別に持ちます。このようなプロパティに対して get が呼び出されると（電源がオフの場合）、エラーではなく UNAVAILABLE ステータスが返されます。たとえば、HVAC の温度を取得するとします。

VHAL による HVAC 取得の例

図 1. HVAC の温度の取得（CS = CarService、VHAL = Vehicle HAL）

set 呼び出し

一般的な処理において、set 呼び出しは車両ネットワーク全体での変更リクエストにつながります。set 呼び出しは、できるだけ早く値を返す非同期処理であることが理想ですが、同期にすることもできます。一部の set 呼び出しでは初期データの用意が必要な場合もありますが、初期化中はこうしたデータが利用できないこともあります。このような場合、set 呼び出しは StatusCode#TRY_AGAIN を返します。個別の電源オン / オフを持つ一部のプロパティでは、プロパティの電源がオフになっていて set を実行できない場合に StatusCode#NOT_AVAILABLE または StatusCode#NOT_AVAILABLE_DISABLED が返されます。set が有効になるまで、get からは設定された値と同じ値が返されない場合もあります。例: set HVAC Temperature。

VHAL による HVAC の設定の例

図 2. HVAC の温度の設定（CS = CarService、VHAL = Vehicle HAL）

カスタム プロパティの処理

パートナー固有のニーズをサポートするため、VHAL ではシステムアプリに限定されたカスタム プロパティが許可されています。カスタム プロパティを設定する場合は、次のガイドラインを使用します。

  • 次のフィールドを使用して、プロパティ ID を生成する必要があります。
    • VehiclePropertyGroup:VENDOR
      VENDOR グループは、カスタム プロパティにのみ使用されます。
    • VehicleArea
      適切なエリアタイプを選択します。
    • VehiclePropertyType
      適切なデータタイプを選択します。BYTES タイプを使用すると、生データを渡すことができます（ほとんどの場合、これで十分です）。カスタム プロパティを介して大量のデータを頻繁に送信すると車両ネットワーク全体のアクセス速度が低下する可能性があるため、容量の大きなペイロードを追加する場合は注意が必要です。
    • Property ID
      カスタム プロパティの 4 つのニブル ID を選択します。
  • エコシステムの断片化を防ぐため、（VehiclePropertyIds SDK）にある既存の車両プロパティを、カスタム プロパティを使用して複製しないでください。
  • VehiclePropConfig.configString に、カスタム プロパティの簡単な説明を入力します。これにより、サニティ チェック ツールは既存の車両プロパティの偶発的なレプリケーション、たとえば「ハザードライトの状態」などをレポートできます。
  • CarPropertyManager（Java コンポーネントの場合）または車両ネットワーク サービス API（ネイティブの場合）を介してアクセスします。互換性に関する問題が発生する可能性があるため、他の自動車 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 を使用する場合、エリア ID にゾーン HVAC プロパティをマッピングするための追加のルールがあります。車内の利用可能な座席はすべて、エリア ID 配列内のエリア ID の一部である必要があります。

例 1: 座席が 2 列の車。前部に 2 席（ROW_1_LEFT, ROW_1_RIGHT）、後部に 3 席（ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT）あります。運転席側と助手席側に合計 2 つの温度制御ユニットがあります。

  • 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: 座席が 3 列の車。1 列目に 2 席（ROW_1_LEFT, ROW_1_RIGHT）、2 列目に 3 席（ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT）、3 列目に 3 席（ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT）あります。運転席側、助手席側、後部座席に合計 3 つの温度制御ユニットがあります。HVAC_TEMPERATURE_SET をエリア ID にマッピングするには、次のような 3 つの要素を使用した配列が適切です。

  • 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）。

Vehicle Map Service

Vehicle Map Service（VMS）は、Pub/Sub インターフェースを介してクライアント間でマップデータを交換するメカニズムを提供し、先進運転支援システム（ADAS）などの一般的な車両機能をサポートします。クライアントには、VHAL または Android の特権アプリの VMS プロパティを介してインターフェースを提供する車両システムが含まれている場合があります。VMS で共有されるデータは、車両システムやサポートアプリで使用するマップデータに限られます。

VMS は Android Automotive の実装で使用することのみを目的としており、VMS を公開またはサブスクライブするデフォルトのクライアントは AOSP には含まれていません。VHAL の VMS プロパティについて、メッセージ タイプとデータ構造は、サポートされる VMS メッセージのタイプをリストする VmsMessageType 列挙値の VHAL 2.0 で説明されています。この列挙値は、車両プロパティにおいて整数配列の最初の整数として使用され、メッセージの残りの部分のデコード方法を指定します。