Special properties

Vendor properties

To support partner-specific needs, the VHAL allows vendor properties that are accessed only through system APIs. Use the following guidelines when working with vendor properties:

• Always try to use system properties first, vendor properties should be used as a last resort when none of the system properties feeds your requirement.
• To prevent ecosystem fragmentation, vendor properties must not be used to replicate vehicle properties that already exist in the SDK VehiclePropertyIds. To learn more, see Section 2.5, Automotive Requirements in the CDD.
• Use the following fields to generate the Property ID:
  • VehiclePropertyGroup:VENDOR VENDOR group is used only for vendor properties.
  • VehicleArea Select an appropriate Area Type.
  • VehiclePropertyType Select the proper data type. BYTES type allows passing raw data, which is sufficient in most cases. Sending big data frequently through vendor properties can slow down entire vehicle network access. Be careful when adding a big payload.
  • Property ID Choose a unique two-byte ID for vendor property. For example, 0x1234.
• Fill in VehiclePropConfig.configString with a short description of the vendor property. This allows validity check tools to flag the accidental replication of existing vehicle properties. For example, "My custom property for XYZ."
• Access through CarPropertyManager (for Java components) or through the libvhalclient (for native). Do not modify other car APIs as doing so can lead to future compatibility issues.

Vendor properties permission

The default permission for any defined vendor properties is android.car.Car.PERMISSION_VENDOR_EXTENSION. For finer granularity of permission control, support the SUPPORT_CUSTOMIZE_VENDOR_PERMISSION property. This STATIC property is read-only, for which its config array specifies the permissions for vendor properties. The configArray is set as follows (i is an integer starts from 0):

• configArray[3 * i] propId, the property ID for the vendor property.
• configArray[3 * i + 1] An enum in VehicleVendorPermission.aidl to indicate permission to read the property value.
• configArray[3 * i + 2] An enum in VehicleVendorPermission.aidl to indicate permission to write the property value.

For example, the following config array configures two vendor properties, vendor_prop_1 and vendor_prop_2, to have the permissions:

• vendor_prop_1 requires android.car.hardware.property.VehicleVendorPermission.PERMISSION_GET_CAR_VENDOR_CATEGORY_SEAT to read, android.car.hardware.property.VehicleVendorPermission.PERMISSION_SET_CAR_VENDOR_CATEGORY_SEAT to write.
• vendor_prop-2 requires android.car.hardware.property.VehicleVendorPermission.PERMISSION_GET_CAR_VENDOR_CATEGORY_INFO to read, and is not writable for Android apps.

configArray = {
  PERMISSION_SET_VENDOR_CATEGORY_SEAT
    vendor_prop_2, PERMISSION_GET_VENDOR_CATEGORY_INFO, PERMISSION_NOT_ACCESSIBLE
}

Vendor properties not in this array take the default vendor permission. When PERMISSION_NOT_ACCESSIBLE is selected, Android apps can't access the property. In the example, Android apps can't write a value for vendor_prop_2. Only native VHAL clients can write to this property.

Advanced driver assistance systems (ADAS)

SEAT and STEERING

See Seat and Steering Wheel Properties.

HVAC

You can use the VHAL to control HVAC by setting HVAC-related properties. Most HVAC properties are associated with particular areas in the vehicle, although several are global properties. Sample defined properties include:

For HVAC properties that are dependent on the power state of the HVAC system, they must be listed in the HVAC_POWER_ON config array. To see a complete list of HVAC properties, search for HVAC_* in VehicleProperty.aidl, see Supported System Properties. properties.

Rules for mapping non-GLOBAL VehicleArea type HVAC properties to AreaIDs: Every “area” for a specific VehicleArea type that is affected by the property, must be included in an area ID for that property. The temperature controllers are assigned to the seats that they "most influence," but every affected seat must be included exactly once. The assignment of the center rear seat to the left or right AreaID might seem arbitrary, but the inclusion of every affected seat in exactly one AreaID ensures that the seats in the car are all expressed and that a reasonable way to affect each seat is available.

Example 1

A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three back seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). There are two temperature control units, one each For the driver side and the passenger side. A valid mapping set of AreaIDs for HVAC_TEMPERATURE_SET would be a two-element array:

• ROW_1_LEFT | ROW_2_LEFT
• ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT

An alternative mapping for the same hardware configuration would be:

• ROW_1_LEFT | ROW_2_CENTER | ROW_2_LEFT
• ROW_1_RIGHT | ROW_2_RIGHT

Example 2

A car has three seat rows with two seats in the front row (ROW_1_LEFT, ROW_1_RIGHT) and three seats in the second (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) and third rows (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). There are three temperature control units, one each for the driver side, the passenger side, and the rear. A reasonable way to map HVAC_TEMPERATURE_SET to AreaIDs is a three element array:

• ROW_1_LEFT
• ROW_1_RIGHT
• ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT

Example 3

A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three back seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). Suppose the car supports HVAC_AUTO_ON for just the two front seats. A valid mapping set of AreaIDs for HVAC_AUTO_ON would be a single element array:

• ROW_1_LEFT | ROW_1_RIGHT

If HVAC_AUTO_ON had two separate control units for the driver side and passenger side, an alternative mapping would be a two elements array:

• ROW_1_LEFT
• ROW_1_RIGHT

INFO_EXTERIOR_DIMENSIONS

A vehicle's exterior dimensions are measured in millimeters, as illustrated in Figure 1.

Use the properties described in this table to define a vehicle's exterior dimensions.

European Union general safety regulation compliance

If the vehicle must comply with European Union General Safety Regulation (GSR) requirements through Android, the property GENERAL_SAFETY_REGULATION_COMPLIANCE_REQUIREMENT must be supported. An example use case is GSR-ISA (Intelligent Speed Assist) as defined in EU Regulation 2019/2144. This property is added in AIDL VHAL from Android 13, however, it is supported in Car Service since the release of Android 12. This property is defined as a read-only static global integer property, with possible values defined by GsrComplianceRequirementType enum:

To support this property in HIDL VHAL (in Android 12), vendors must hard-code the property ID. For example, the following snippet shows how this is supported in the reference 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}},
}

To support this property in AIDL VHAL (from Android 13), vendors can use the property ID from VehicleProperty.h and enum from GsrComplianceRequirementType.h. For example, as in reference AIDL VHAL DefaultProperties.json:

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

To read this property from an Android app, use CarPropertyManager.getIntProperty.

• In Android 13 and higher, use VehiclePropertyIds.GENERAL_SAFETY_REGULATION_COMPLIANCE as the property ID.
• In Android 12, use the hard-coded value of 0x11400F47 as property ID. This property requires the permission, Car#PERMISSION_CAR_INFO.