車両プロパティ

Vehicle Hardware Abstraction Layer（VHAL）インターフェースは 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 は、それぞれの列挙値からの 1 つ以上のフラグで構成されます。たとえば、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、min、max の値）
  • 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 による HVAC 取得の例

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

set 呼び出し

set 呼び出しは、リクエストによる変更が行われた後のイベント通知に関わる非同期処理です。一般的な処理において、set 呼び出しは車両ネットワーク全体での変更リクエストにつながります。プロパティを持つ電子制御ユニット（ECU）により変更が実行されると、更新された値が車両ネットワーク経由で返され、車両 HAL は更新された値をイベントとして車両ネットワーク サービス（VNS）に送信します。

一部の set 呼び出しでは初期データの用意が必要な場合もありますが、初期化中はこうしたデータが利用できないこともあります。このような場合、set 呼び出しは -EAGAIN を返します。個別の電源オン / オフを持つ一部のプロパティでは、プロパティの電源がオフになっていて設定できない場合に -ESHUTDOWN が返されます。

set が有効になるまで、get からは設定された値と同じ値が返されない場合もあります。

例: HVAC の温度の設定

VHAL による HVAC の設定の例

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

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

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

  • 次のフィールドを使用して、プロパティ ID を生成する必要があります。
    • VehiclePropertyGroup:VENDOR
      VENDOR グループは、カスタム プロパティにのみ使用します。
    • VehicleArea
      適切なエリアタイプを選択します。
    • VehiclePropertyType
      適切なデータタイプを選択します。BYTES タイプは元データを渡すことができるため、通常はこれで十分です。カスタム プロパティを介してビッグデータを頻繁に送信すると車両ネットワーク全体のアクセス速度が低下する可能性があるため、容量の大きなペイロードを追加する場合は注意が必要です。
    • プロパティ ID
      カスタム プロパティの 4 つのニブル 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 を使用する場合、エリア 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 のセンサー プロパティは、実際のセンサーデータや運転状況などのポリシー情報を表します。一部のセンサー情報（運転状態や日中モードまたは夜間モードなど）については、安全な車両アプリを構築するために不可欠なデータであることから、あらゆるアプリが制限なしでアクセスできるようになっています。その他のセンサー情報（車速など）については機密性が高いため、特定の権限（ユーザーが管理可能）が必要になります。

サポートされるセンサー プロパティは次のとおりです。

  • NIGHT_MODE
    サポートが必要。ディスプレイの日中モードまたは夜間モード。
  • GEAR_SELECTION/CURRENT_GEAR
    運転者が選択したギアと実際のギア。
  • VEHICLE_SPEED
    車速。権限により保護されています。
  • ODOMETER
    現在の走行距離。権限により保護されています。
  • FUEL_LEVEL
    現在の燃料残量（%）。
  • FUEL_LEVEL_LOW
    燃料残量の不足（ブール値）。

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 で説明されています。この列挙値は、車両プロパティにおいて整数配列の最初の整数として使用され、メッセージの残りの部分のデコード方法を指定します。