Extend VHAL property descriptions in the emulator

The Android Automotive OS (AAOS) contains common VHAL properties that can be viewed in an emulator's VHAL window. As a result, you can view an abundance of information about VHALs including names, descriptions, and the meaning of the values. The information is extracted from the metadata of VHAL properties, which is hard-coded into the QEMU emulator.

When you add your own VHAL properties for exclusive use on your devices, viewing VHAL metadata in the VHAL window requires you to modify the code and build a customized QEMU emulator. To work around this, you can write your own descriptions in JSON format and them to your system image.

Overview

This page details how you can extend VHAL properties descriptions in an AAOS emulator.

Create JSON metadata to extend VHAL properties

The emulator looks for additional metadata in all files ending with -types-meta.json in the Android Virtual Device (AVD) path. JSON files are expected to consist of an array of Enum objects as shown below.

Enum object

The Enum object with the name VehicleProperty is a special case in That you can consider it as a root. Its contents are added to the vehicle properties map. Other Enums (with a name other than VehicleProperty) define maps of the names of the custom values.

Enum: {
  "name" : String,
  "values" : Array of { ValueObject }
}  

ValueObject

ValueObject: {
  "name" : String,
  "value" : Integer,
  "data_enum" : String, VehicleProperty only, optional,
}

For VehicleProperty, the Enum name describes how this property is displayed in the VHAL window of the emulator. The value is the property_id of the property described by the ValueObject. data_enum associates ValueObject with another Enum. This association is used to map a value into a human readable string and exists only for ValueObjects in the Enum for the VehicleProperty. An example of VehicleProperty is shown below:

[
  {
      "name": "VehicleProperty",
      "values": [
          {
              "name": "CURRENT_GEAR",
              "value": 289408001
          }
      ]
  }
]

In this example, a property_id with a value of 289408001 is provided as a name for CURRENT_GEAR. In the emulator, this property is already hard-coded as a name, Current Gear. (You can't reproduce this scenario as this page was authored after removing all the hard-coded properties for demonstration purposes.)

Figure 1. VehicleProperty defined with name and value.

In the emulator's VHAL Properties tab, the name is refreshed to read CURRENT_GEAR as expected.

data_enum

In the above example, the displayed value is 4 when the gear is set to P.

Figure 2. Value displayed as 4.

As intended, on the VHAL Properties tab in the emulator, the name appears as CURRENT_GEAR. This is in contrast to the existing emulator, where it's displayed as P.

enum VehicleGear {
  GEAR_UNKNOWN = 0x0000,
  GEAR_NEUTRAL = 0x0001,
  GEAR_REVERSE = 0x0002,
  GEAR_PARK = 0x0004,
  GEAR_DRIVE = 0x0008,
  GEAR_1 = 0x0010,
  GEAR_2 = 0x0020,
  GEAR_3 = 0x0040,
  GEAR_4 = 0x0080,
  GEAR_5 = 0x0100,
  GEAR_6 = 0x0200,
  GEAR_7 = 0x0400,
  GEAR_8 = 0x0800,
  GEAR_9 = 0x1000,
}

To learn more, see the AIDL definition.

As defined in the AIDL, the value of the Park gear is 4, which means you need to translate the value 4 into P. This is when you use data_enum, which maps this property value to a human readable string in another Enum. The emulator uses this map to translate property values. For example:

[
    {
        "name": "VehicleProperty",
        "values": [
            {
                "name": "CURRENT_GEAR",
                "value": 289408001,
                "data_enum": "VehicleGear"
            }
        ]
    },
    {
        "name": "VehicleGear",
        "values": [
            {
                "name": "GEAR_UNKNOWN",
                "value": 0
            },
            {
                "name": "GEAR_PARK",
                "value": 4
            }
        ]
    }

]

Add "data_enum": "VehicleGear", so the emulator uses an Enum named VehicleGear to translate the property value. Add another Enum named VehicleGear with the value being an array of ValueObject, where the property value (with the value) should be displayed as a name.

Figure 3. Value displayed as GEAR_PARK.

On the VHAL Properties tab for the emulator, the name is refreshed to read CURRENT_GEAR, as expected. The property value of 4 is displayed as GEAR_PARK.

Use JSON metadata to extend VHAL properties

To use JSON metadata to extend your VHAL properties, run this Python script (contained in the Android source) to generate the extended property JSON from information in the AIDL.

Note: Instructions to run the script are contained in the comments of this file.

The resulting JSON includes some redundant values, such as change_mode, access, and unit. Though this information is part of the VHAL property, these JSON values don't affect what's displayed in the emulator's VHAL property window.

Add JSON metadata to the system image

Be mindful that a filename must end with -types-meta.json. If not, the file is ignored.

Add a build target

Add the -types-meta.json file to the PRODUCT_COPY_FILE. For example:

PRODUCT_COPY_FILES += \
    device/generic/car/common/vehicle-types-meta.json:vehicle-types-meta.json

This code copies the file into out/target/product/{your_target_path}/, the root of your built target output.