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)

See ADAS Vehicle Properties.

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:

Property Purpose
HVAC_TEMPERATURE_SET Set temperature per area ID.
HVAC_POWER_ON The power state of the HVAC system per area ID.

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.

Figure 1. Vehicle exterior dimensions, front view.
Figure 2. Vehicle exterior dimensions, side view.

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

Vehicle property VHAL field Description
Height int32Values[0] Vertical distance between the ground and the highest point on the vehicle. This presumes normally inflated factory wheels.
Length int32Values[1] Horizontal distance between the outermost points of the front and rear of the vehicle.
Width, excluding mirrors int32Values[2] Horizontal distance between the two outermost points on each side of the vehicle, excluding the side mirrors.
Width, including mirrors int32Values[3] Horizontal distance between the two outermost points on each side of the vehicle, including the side mirrors.
Wheel base int32Values[4] Distance between the vehicle's center of the front and rear wheels.
Track width, front int32Values[5] Distance between the front wheel, measured from the center line of one tire tread to the center line of the opposite tire tread.
Track width, rear int32Values[6] Distance between the rear wheel, measured from the center line of one tire tread to the center line of the opposite tire tread.
Curb-to-curb turning diameter int32Values[7] The diameter of the circle made by the outer wheels of the vehicle when making a complete turn with a fully-locked steering wheel.

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:

Name Value Description
GSR_COMPLIANCE_NOT_REQUIRED 0 GSR compliance is not required
GSR_COMPLIANCE_REQUIRED_V1 1 GSR compliance is required and the requirement solution version is 1.

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.