特別なプロパティ

ベンダープロパティ

パートナー固有のニーズをサポートするため、VHAL ではシステム API を通じてのみアクセスされるベンダープロパティが許可されています。ベンダープロパティを設定する場合は、次のガイドラインを使用します。

必ず最初にシステムプロパティの使用を試してください。ベンダープロパティは、どのシステムプロパティも要件を満たさない場合の最後の手段として使用する必要があります。
エコシステムの断片化を防ぐため、SDK VehiclePropertyIds にある既存の車両プロパティを、ベンダープロパティを使用して複製しないでください。詳しくは、CDD のセクション 2.5 Android Automotive の要件をご覧ください。
以下のフィールドを使用してプロパティ ID を生成します。
- VehiclePropertyGroup:VENDOR VENDOR グループはベンダープロパティにのみ使用されます。
- VehicleArea 適切なエリアタイプを選択します。
- VehiclePropertyType 適切なデータタイプを選択します。BYTES タイプを使用すると、生データを渡すことができます（ほとんどの場合、これで十分です）。ベンダープロパティを介して大量のデータを頻繁に送信すると車両ネットワーク全体のアクセス速度が低下する可能性があります。容量の大きなペイロードを追加する場合は注意が必要です。
- Property ID ベンダープロパティの一意の 2 バイトの ID を選択します（例: 0x1234）。
VehiclePropConfig.configString に、ベンダープロパティの簡単な説明を入力します。これにより、妥当性チェックツールは既存の車両プロパティの偶発的なレプリケーションを報告できます（例: 「XYZ のカスタムプロパティ」）。
CarPropertyManager（Java コンポーネントの場合）または libvhalclient（ネイティブの場合）を介してアクセスします。互換性に関する問題が発生する可能性があるため、他の自動車 API は変更しないでください。

ベンダープロパティ権限

定義されたベンダープロパティに対するデフォルトの権限は、android.car.Car.PERMISSION_VENDOR_EXTENSION です。権限をより細かく制御するには、SUPPORT_CUSTOMIZE_VENDOR_PERMISSION プロパティをサポートします。この STATIC プロパティは読み取り専用であり、config 配列でベンダープロパティの権限を指定します。configArray は以下のように設定します（i は 0 以上の整数）。

configArray[3 * i] propId、ベンダープロパティのプロパティ ID。
configArray[3 * i + 1] プロパティの値の読み取り権限を示す VehicleVendorPermission.aidl の列挙型。
configArray[3 * i + 2] プロパティの値の書き込み権限を示す VehicleVendorPermission.aidl の列挙型。

たとえば、以下の config 配列は、2 つのベンダープロパティ（vendor_prop_1 と vendor_prop_2）が権限を持つように設定します。

vendor_prop_1 は、読み取るために android.car.hardware.property.VehicleVendorPermission.PERMISSION_GET_CAR_VENDOR_CATEGORY_SEAT、書き込むために android.car.hardware.property.VehicleVendorPermission.PERMISSION_SET_CAR_VENDOR_CATEGORY_SEAT が必要です。
vendor_prop-2 は、読み取るために android.car.hardware.property.VehicleVendorPermission.PERMISSION_GET_CAR_VENDOR_CATEGORY_INFO が必要です。Android アプリでは書き込めません。

configArray = {
  PERMISSION_SET_VENDOR_CATEGORY_SEAT
    vendor_prop_2, PERMISSION_GET_VENDOR_CATEGORY_INFO, PERMISSION_NOT_ACCESSIBLE
}

この配列にないベンダープロパティは、デフォルトのベンダー権限を取ります。PERMISSION_NOT_ACCESSIBLE が選択されている場合、Android アプリはプロパティにアクセスできません。この例では、Android アプリは vendor_prop_2 の値を書き込めません。このプロパティに書き込めるのは、ネイティブの VHAL クライアントのみです。

先進運転支援システム（ADAS）

ADAS 車両のプロパティをご覧ください。

SEAT と STEERING

座席とハンドルのプロパティをご覧ください。

暖房換気空調システム

VHAL を使用して HVAC を制御するには、HVAC 関連のプロパティを設定します。大半の HVAC プロパティは車両内の特定エリアと関連付けられていますが、グローバルプロパティもいくつかあります。定義済みのプロパティの例は次のとおりです。

プロパティ	目的
`HVAC_TEMPERATURE_SET`	エリア ID ごとに温度を設定します。
`HVAC_POWER_ON`	エリア ID ごとの HVAC システムの電源状態。

HVAC システムの電源状態に依存する HVAC プロパティについては、HVAC_POWER_ON config 配列にリストする必要があります。HVAC プロパティの完全なリストを表示するには、VehicleProperty.aidl で HVAC_* を検索し、サポートされているシステムプロパティのプロパティをご覧ください。

非 GLOBAL VehicleArea タイプの HVAC プロパティを AreaID にマッピングする場合のルール: プロパティの影響を受ける特定の VehicleArea タイプのすべての「エリア」を、そのプロパティのエリア ID に含む必要があります。温度コントローラは「最も影響が大きい」座席に割り当てられますが、影響を受ける座席はすべて 1 回含む必要があります。中央後部座席を左または右の AreaID に割り当てることは恣意的に思われるかもしれませんが、影響を受けるすべての座席を 1 つの AreaID のみに含めることで、車内の座席がすべて表現され、各座席に影響を与える適切な方法が利用可能であることが保証されます。

例 1

前部に 2 席（ROW_1_LEFT、ROW_1_RIGHT）、後部に 3 席（ROW_2_LEFT、ROW_2_CENTER、ROW_2_RIGHT）ある車。温度制御装置は 2 つあります（運転席側、助手席側）。HVAC_TEMPERATURE_SET の AreaID に対する有効なマッピングセットは次の 2 つの要素からなる配列になります。

ROW_1_LEFT | ROW_2_LEFT
ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT

同じハードウェア構成で、次のようなマッピングもあります。

ROW_1_LEFT | ROW_2_CENTER | ROW_2_LEFT
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_RIGH）あります。運転席側、助手席側、後部座席に合計 3 つの温度制御装置があります。HVAC_TEMPERATURE_SET を AreaID にマッピングするには、次のような 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

例 3

前部に 2 席（ROW_1_LEFT、ROW_1_RIGHT）、後部に 3 席（ROW_2_LEFT、ROW_2_CENTER、ROW_2_RIGHT）ある車。前部 2 席でのみ HVAC_AUTO_ON をサポートしているとします。HVAC_AUTO_ON の AreaID に対する有効なマッピングセットは、次の 1 つの要素からなる配列になります。

ROW_1_LEFT | ROW_1_RIGHT

HVAC_AUTO_ON が運転席側と助手席側で異なる 2 つの制御装置を有する場合、次の 2 つの要素からなる配列でのマッピングもあります。

ROW_1_LEFT
ROW_1_RIGHT

INFO_EXTERIOR_DIMENSIONS

車両の外寸は、図 1 で示されるようにミリメートルで測定されます。

この表に記載されているプロパティを使用して、車両の外寸を定義します。

車両のプロパティ	VHAL フィールド	説明
高さ	`int32Values[0]`	地面と車両最高部の間の垂直距離。この距離は、工場出荷時の正規空気圧の車輪を前提としています。
長さ	`int32Values[1]`	車両の前後の最も外側となる部分の間の水平距離。
幅（ミラーを除く）	`int32Values[2]`	車両の両側の最も外側となる部分の間の水平距離（サイドミラーを除く）。
幅（ミラーを含む）	`int32Values[3]`	車両の両側の最も外側となる部分の間の水平距離（サイドミラーを含む）。
ホイールベース	`int32Values[4]`	車両の前輪と後輪の中心間の距離。
トレッド幅（フロント）	`int32Values[5]`	前輪間の距離（一方のタイヤトレッドの中心線から反対側のタイヤトレッドの中心線までを測定）。
トレッド幅（リア）	`int32Values[6]`	後輪間の距離（一方のタイヤトレッドの中心線から反対側のタイヤトレッドの中心線までを測定）
車輪回転直径	`int32Values[7]`	ハンドルを最大にきって一回転したときの車両の外側の車輪が描く円の直径。

欧州連合一般安全規則への準拠

車両が Android を通じて欧州連合一般安全規制（GSR）要件に準拠する必要がある場合、プロパティ GENERAL_SAFETY_REGULATION_COMPLIANCE_REQUIREMENT をサポートする必要があります。ユースケース例は、EU 規則 2019/2144 で定義されている GSR-ISA（インテリジェントスピードアシスト）です。このプロパティは Android 13 から AIDL VHAL に追加されましたが、Android 12 のリリース以降カーサービスでサポートされています。このプロパティは読み取り専用の静的グローバル整数プロパティとして定義され、取り得る値は GsrComplianceRequirementType 列挙型で定義されます。

名前	値	説明
`GSR_COMPLIANCE_NOT_REQUIRED`	0	GSR に準拠する必要はありません。
`GSR_COMPLIANCE_REQUIRED_V1`	1	GSR に準拠する必要があります。要件ソリューションバージョンは 1 です。

Android 12 の HIDL VHAL でこのプロパティをサポートする場合、ベンダーはプロパティ ID をハードコードする必要があります。たとえば、次のスニペットはリファレンス HIDL VHAL DefaultConfig.h でのサポート方法を示しています。

{
  .config =
      {
          // GENERAL_SAFETY_REGULATION_COMPLIANCE_REQUIREMENT
          .prop = 0x11400F47,
          .access = VehiclePropertyAccess::READ,
          .changeMode = VehiclePropertyChangeMode::STATIC,
      },
  // GsrComplianceRequirementType::GSR_COMPLIANCE_REQUIRED_V1
  .initialValue = {.int32Values = {1}},
}

Android 13 以降の AIDL VHAL でこのプロパティをサポートする場合、ベンダーは VehicleProperty.h のプロパティ ID と GsrComplianceRequirementType.h の列挙型を使用できます。たとえば、リファレンス AIDL VHAL DefaultProperties.json のようにできます。

{
  "property": "VehicleProperty::GENERAL_SAFETY_REGULATION_COMPLIANCE_REQUIREMENT",
  "defaultValue": {
    "int32Values": [
      "GsrComplianceRequirementType::GSR_COMPLIANCE_REQUIRED_V1"
    ]
  }
}

Android アプリでこのプロパティを読み取る場合、CarPropertyManager.getIntProperty を使用します。

Android 13 以降では VehiclePropertyIds.GENERAL_SAFETY_REGULATION_COMPLIANCE をプロパティ ID として使用します。
Android 12 では、ハードコードされた 0x11400F47 の値をプロパティ ID として使用します。このプロパティは権限 Car#PERMISSION_CAR_INFO が必要です。