Introduction

Android Automotive OS offers a rich, customizable platform for in-vehicle infotainment systems. At its core, the Vehicle Hardware Abstraction Layer (VHAL) provides the standardized interface for Android to communicate with the car’s underlying hardware and sensors. While VHAL covers a wide range of standard vehicle properties, integrating custom or external sensors—such as an advanced air quality monitor, a specialized cabin temperature sensor, or a unique driver biometric device—often requires extending VHAL with custom properties. This expert-level tutorial guides you through the process of defining, implementing, and interacting with custom VHAL properties to seamlessly bridge your bespoke hardware with the Android Automotive framework.

Understanding the Android Automotive VHAL

The VHAL is a critical component of Android Automotive, acting as the bridge between high-level Android services and the vehicle’s hardware. It defines a set of standard properties (e.g., vehicle speed, gear selection, fuel level) that applications and services can query or subscribe to. The VHAL service, typically implemented by the OEM, communicates with the vehicle’s CAN bus, ECUs, and other hardware components, translating raw hardware data into Android-understandable properties and vice-versa. It uses a client-server architecture, where the CarPropertyManager in the Android framework acts as the client, and the VHAL implementation acts as the server exposing the IVehicle HAL interface.

Key concepts of VHAL:

• Properties: Each piece of vehicle data (e.g., speed, engine RPM, door status) is represented as a property.
• Property ID: A unique integer identifier for each property. Defined in types.hal.
• Property Type: Defines the data type (e.g., INT32, FLOAT, BYTE_ARRAY).
• Area ID: Specifies which part of the vehicle the property relates to (e.g., GLOBAL, DRIVER, SEAT).
• Permissions: Access to properties is protected by Android permissions.

The Need for Custom VHAL Properties

While standard VHAL properties are extensive, they cannot anticipate every possible sensor or hardware integration a manufacturer or developer might envision. For instance, if you’re building a unique smart cabin feature that relies on a specialized UV index sensor or a particulate matter sensor, you’ll find no predefined VHAL property for it. In such cases, extending the VHAL with a custom property is the only way to expose this hardware data to the Android Automotive environment in a standardized, maintainable, and secure manner. This allows your Android applications to read, display, and react to data from your custom hardware just as they would with any standard vehicle property.

Designing a Custom VHAL Property

Step 1: Defining the Property in types.hal

The first step is to declare your custom property within the VHAL interface definition. This typically involves modifying the types.hal file corresponding to your Android Automotive version (e.g., hardware/interfaces/automotive/vehicle/2.0/types.hal). You’ll add a new entry to the VehicleProperty enum, ensuring its ID is outside the standard range to avoid conflicts. The general practice is to start custom IDs from a high, unused range (e.g., 0x2000 or higher).

For this example, let’s create a custom property for an ‘External Cabin Air Quality Sensor’ that reports a float value representing PM2.5 levels.

// hardware/interfaces/automotive/vehicle/2.0/types.hal
package [email protected];

enum VehicleProperty : int32 {
    // ... existing properties ...

    // Custom properties start here
    CUSTOM_EXTERNAL_AIR_QUALITY_PM2_5 = 0x2100,
};

// Add property info for the new property
struct VehiclePropertyInfo {
    VehicleProperty prop;
    VehiclePropertyType propType;
    VehicleAreaType vehicleArea;
    int32 access;
    int32 changeMode;
    float minSampleRate;
    float maxSampleRate;
    // ... other fields ...
};

Implementing the Custom Property in VHAL Service

Step 2: Modifying the VHAL Implementation

After defining the property, you need to implement its behavior within the VHAL service. This typically involves modifying the default VHAL implementation (e.g., frameworks/automotive/vehicle/default/impl/vhal/DefaultVehicleHal.cpp or your OEM’s specific VHAL implementation). You’ll need to:

1. Add the property to the list of supported properties: In DefaultVehicleHal::initProperties(), you define the property’s characteristics.
2. Handle read requests: Implement logic in DefaultVehicleHal::onGetProperty() to return the current value of your custom sensor.
3. Handle write requests (if applicable): Implement logic in DefaultVehicleHal::onSetProperty() if the property can be written to. For a sensor reading, it’s usually read-only.

Let’s assume our external sensor provides its data by writing to a specific file (e.g., /sys/class/custom_sensors/air_quality_pm2_5) or through a serial interface. For simplicity, we’ll simulate reading from a file.

// frameworks/automotive/vehicle/default/impl/vhal/DefaultVehicleHal.cpp

using namespace std::chrono_literals;

// Inside DefaultVehicleHal::initProperties()
void DefaultVehicleHal::initProperties() {
    // ... existing properties ...

    // Add our custom property
    VehiclePropertyInfo info;
    info.prop = toInt(VehicleProperty::CUSTOM_EXTERNAL_AIR_QUALITY_PM2_5);
    info.propType = VehiclePropertyType::FLOAT;
    info.vehicleArea = VehicleAreaType::VEHICLE_AREA_TYPE_GLOBAL;
    info.access = VehiclePropertyAccess::READ;
    info.changeMode = VehiclePropertyChangeMode::ON_CHANGE;
    info.minSampleRate = 0.5f; // Sample twice per second
    info.maxSampleRate = 2.0f; // Max two samples per second
    addProperty(info);
}

// Inside DefaultVehicleHal::onGetProperty()
void DefaultVehicleHal::onGetProperty(const VehicleProp& request, 
                                        GetPropertyCallback callback) {
    if (request.prop == toInt(VehicleProperty::CUSTOM_EXTERNAL_AIR_QUALITY_PM2_5)) {
        VehicleProp prop = request;
        prop.status = VehiclePropertyStatus::AVAILABLE;

        // Simulate reading from a sensor device file
        // In a real scenario, this would involve reading from a hardware interface
        std::ifstream sensorFile("/sys/class/custom_sensors/air_quality_pm2_5");
        std::string line;
        float pm25Value = 0.0f;
        if (sensorFile.is_open()) {
            std::getline(sensorFile, line);
            try {
                pm25Value = std::stof(line);
            } catch (const std::exception& e) {
                ALOGE("Failed to parse PM2.5 value: %s", e.what());
            }
            sensorFile.close();
        } else {
            ALOGW("Could not open custom air quality sensor file.");
            // Return a default/error value or indicate UNAVAILABLE
            prop.status = VehiclePropertyStatus::ERROR;
        }

        prop.value.floatValues = {pm25Value};
        callback(prop);
        return;
    }
    // ... handle other properties ...
}

// onSetProperty is generally not needed for read-only sensor data.
// If your sensor has configurable parameters, you would implement it here.

Important Considerations:

• Permissions: Ensure the VHAL service has the necessary kernel permissions to access your hardware device files (e.g., `/dev/your_sensor` or `/sys/class/custom_sensors/`). This might involve SELinux policy modifications.
• Error Handling: Robustly handle cases where the sensor is unavailable or returns invalid data.
• Asynchronous Data: For `ON_CHANGE` or `CONTINUOUS` properties, the VHAL implementation should proactively send property events using sendPropertyEvent when the sensor data changes.

Interacting from an Android Application

Step 3: Creating an Automotive Application

Finally, you’ll need an Android application to interact with your custom VHAL property. This involves using the CarPropertyManager to read the property’s value.

1. Add Permissions to AndroidManifest.xml:

<!-- AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.automotiveairquality">

    <uses-permission android:name="android.car.permission.CAR_PROPERTY_ACCESS" />
    <uses-feature android:name="android.hardware.type.automotive" android:required="true" />

    <application ...>
        <activity ...>
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

2. Interact with CarPropertyManager in your Activity:

// src/main/java/com/example/automotiveairquality/MainActivity.java
package com.example.automotiveairquality;

import android.car.Car;
import android.car.CarNotConnectedException;
import android.car.hardware.CarPropertyConfig;
import android.car.hardware.CarPropertyValue;
import android.car.hardware.CarPropertyManager;
import android.os.Bundle;
import android.util.Log;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;

import java.util.List;

public class MainActivity extends AppCompatActivity {

    private static final String TAG = "AirQualityApp";
    // Define the custom property ID. This must match the ID in types.hal
    private static final int CUSTOM_AIR_QUALITY_PM2_5 = 0x2100; 

    private Car mCar;
    private CarPropertyManager mCarPropertyManager;
    private TextView mAirQualityTextView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main); // Assuming you have a layout with a TextView
        mAirQualityTextView = findViewById(R.id.air_quality_value);

        // Connect to Car service
        mCar = Car.createCar(this, null);
        try {
            mCar.connect();
            mCarPropertyManager = (CarPropertyManager) mCar.getManager(Car.PROPERTY_SERVICE);
            if (mCarPropertyManager != null) {
                registerAirQualityListener();
                // Optionally, read initial value
                CarPropertyValue<Float> initialValue = mCarPropertyManager.getProperty(Float.class, CUSTOM_AIR_QUALITY_PM2_5, 0);
                if (initialValue != null) {
                    updateAirQuality(initialValue.getValue());
                } else {
                    Log.w(TAG, "Initial PM2.5 value not available.");
                    mAirQualityTextView.setText("N/A");
                }
            } else {
                Log.e(TAG, "CarPropertyManager is null");
            }
        } catch (CarNotConnectedException e) {
            Log.e(TAG, "Car not connected", e);
        }
    }

    private void registerAirQualityListener() {
        List<CarPropertyConfig> configs = mCarPropertyManager.getPropertyList();
        boolean propertyFound = false;
        for (CarPropertyConfig config : configs) {
            if (config.getPropertyId() == CUSTOM_AIR_QUALITY_PM2_5) {
                propertyFound = true;
                mCarPropertyManager.registerCallback(new CarPropertyManager.CarPropertyEventCallback() {
                    @Override
                    public void onChangeEvent(CarPropertyValue value) {
                        if (value.getPropertyId() == CUSTOM_AIR_QUALITY_PM2_5) {
                            updateAirQuality((Float) value.getValue());
                        }
                    }

                    @Override
                    public void onErrorEvent(int propId, int zone) {
                        Log.e(TAG, "Error event for PM2.5 property: " + propId);
                        mAirQualityTextView.setText("Error");
                    }
                }, CUSTOM_AIR_QUALITY_PM2_5, CarPropertyManager.SENSOR_RATE_ONCHANGE);
                Log.i(TAG, "Registered listener for custom air quality sensor.");
                break;
            }
        }
        if (!propertyFound) {
            Log.e(TAG, "Custom Air Quality PM2.5 property (0x2100) not found in VHAL.");
        }
    }

    private void updateAirQuality(float pm25Value) {
        runOnUiThread(() -> {
            mAirQualityTextView.setText(String.format("PM2.5: %.2f µg/m³", pm25Value));
        });
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (mCar != null && mCar.isConnected()) {
            mCar.disconnect();
        }
    }
}

Building, Flashing, and Testing

Step 4: AOSP Build and Deployment

1. Build AOSP: After making the changes to types.hal and DefaultVehicleHal.cpp, you need to rebuild your Android Automotive OS image. This is typically done with commands like:

   $ source build/envsetup.sh
   $ lunch <your_target> # e.g., lunch aosp_car_x86-userdebug
   $ make -j$(nproc)

2. Flash the Device: Once the build is complete, flash the new image onto your Automotive device or emulator.

   $ adb reboot bootloader
   $ fastboot flash all

3. Install and Run the App: After the device reboots, install your Android application via ADB:

   $ adb install path/to/your/app.apk

   Run the app and observe if it correctly displays the air quality data from your simulated or real sensor. You can simulate sensor data by writing values to the `/sys/class/custom_sensors/air_quality_pm2_5` file on the device (e.g., `echo

   Android Mobile Specs & Compare Directory

   Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!

   Compare Devices Specs →