Introduction: Bridging Hardware and Software in Android Automotive

Android Automotive OS (AAOS) has revolutionized the in-car infotainment experience, bringing the power and flexibility of Android to the vehicle’s cockpit. At its core, AAOS relies on the Vehicle Hardware Abstraction Layer (VHAL) to communicate with the underlying vehicle hardware, providing a standardized interface for accessing sensors, actuators, and other vehicle properties. While VHAL offers a rich set of predefined properties, automotive OEMs and developers often encounter scenarios requiring unique, vehicle-specific functionalities that aren’t covered by the standard. This article will provide an expert-level deep dive into the VHAL architecture and guide you through the process of developing and implementing custom VHAL properties.

Understanding custom VHAL properties is crucial for unlocking the full potential of Android Automotive, enabling integration with bespoke hardware components, proprietary communication buses, or advanced driver-assistance systems (ADAS) that are unique to a specific vehicle platform. By extending VHAL, developers can expose these custom functionalities to the Android framework, allowing applications to interact with them seamlessly.

The Android Automotive VHAL Architecture Explained

The VHAL acts as the crucial interface between vehicle-specific hardware and the Android framework. It’s built upon a client-server model, where CarService (part of the Android framework) acts as the primary client, requesting and subscribing to vehicle properties. The VHAL implementation, typically provided by the SoC vendor or OEM, serves these requests by interacting directly with vehicle ECUs or other hardware via various protocols (CAN bus, Ethernet, etc.).

Key Components:

• CarService: The central service in Android that manages all vehicle-related interactions.
• IVehicleHal: The core interface (historically HIDL, now AIDL) that defines how CarService communicates with the VHAL implementation.
• VHAL Implementation: A vendor-specific module (e.g., a C++ daemon) that implements IVehicleHal and translates Android requests into vehicle hardware commands and vice-versa.
• Vehicle Network: The actual communication bus (e.g., CAN) connecting to various ECUs and sensors.

The standard VHAL properties cover a wide range of functionalities, from basic sensor data like speed and fuel level to control actions like locking doors or adjusting climate. Each property is identified by a unique ID and has associated data types, access permissions, and change modes.

Defining a Custom VHAL Property

The first step in implementing a custom VHAL property is to define it. VHAL properties are defined as 32-bit integers, where specific bit ranges encode information about the property type, area type, and a unique identifier. Custom properties are typically defined in a vendor-specific header file that extends the standard VHAL definitions. For AIDL-based VHAL, this usually involves extending VehicleProperty.aidl or defining custom enums/constants.

Property ID Structure (Example):

// Example for a custom float property in C++ (HIDL-era, but concept applies)uint32_t VEHICLE_PROPERTY_MY_CUSTOM_SENSOR = (uint32_t)VehicleProperty::VENDOR_EXTENSION | // Marks as vendor-specific(uint32_t)VehiclePropertyType::VEHICLE_PROPERTY_TYPE_FLOAT | // Data type is float(uint32_t)VehiclePropertyAreaType::VEHICLE_PROPERTY_AREA_TYPE_GLOBAL | // Applies globally(uint32_t)0x0001; // Vendor-defined unique ID (e.g., 1 for this property)// For AIDL, you might define it in a new .aidl file or extend existing constants.

Let’s break down the example above:

• VEHICLE_PROPERTY_MY_CUSTOM_SENSOR: The unique ID for our custom property.
• VENDOR_EXTENSION: This bit indicates that the property is vendor-specific, reserving a range of IDs to prevent conflicts with standard properties.
• VEHICLE_PROPERTY_TYPE_FLOAT: Specifies that the property’s value will be a floating-point number. Other types include INT32, INT32_VEC, BOOL, STRING, etc.
• VEHICLE_PROPERTY_AREA_TYPE_GLOBAL: Denotes that this property applies to the entire vehicle, not a specific area like a seat or door.
• 0x0001: This is the vendor-defined unique identifier within the vendor extension range. OEMs typically manage a registry of these IDs to avoid internal collisions.

You would typically add this definition to a file like packages/services/Car/VehicleHal/aidl/default/include/VehicleHalProperties.h or a similar vendor-specific location if you’re working with an AIDL VHAL implementation, or [email protected]/default/impl/VehicleProperty.h for HIDL.

Defining Property Metadata: Access and Change Mode

Beyond the ID, each property needs metadata:

• VehiclePropertyAccess: Defines if the property is readable (READ), writable (WRITE), or both (READ_WRITE).
• VehiclePropertyChangeMode: Specifies how the property changes. STATIC for properties that don’t change, ON_CHANGE for properties that change infrequently (VHAL only notifies clients when the value changes), and CONTINUOUS for frequently changing properties (e.g., speed, requiring clients to specify a sampling rate).

Implementing the VHAL Interface for Custom Properties

Once defined, the custom property needs to be integrated into the VHAL implementation. This involves modifying the VHAL daemon to recognize and handle your new property. The core of this implementation lies in extending the IVehicleHal interface methods.

1. Declare Support for the Custom Property

The VHAL implementation must inform CarService which properties it supports. This is typically done in a method that returns a list of supported properties. You’ll add your custom property ID to this list.

// Example in C++ (simplified)std::vector<VehiclePropConfig> MyVehicleHal::get);SupportedProperties() {    std::vector<VehiclePropConfig> properties;    // ... add standard properties ...    VehiclePropConfig myCustomSensorConfig;    myCustomSensorConfig.prop = VEHICLE_PROPERTY_MY_CUSTOM_SENSOR;    myCustomSensorConfig.access = VehiclePropertyAccess::READ_WRITE;    myCustomSensorConfig.changeMode = VehiclePropertyChangeMode::CONTINUOUS;    // For continuous properties, define min/max sample rates    myCustomSensorConfig.minSampleRate = 1.0f; // 1 Hz    myCustomSensorConfig.maxSampleRate = 100.0f; // 100 Hz    properties.push_back(myCustomSensorConfig);    return properties;}

2. Handle Property Read Requests (onGetProperty)

When a client (e.g., CarService) requests the value of your custom property, the VHAL implementation’s onGetProperty method will be invoked. Here, you’ll identify your custom property ID and return its current value.

// Example in C++ (simplified)Result MyVehicleHal::onGetProperty(const VehiclePropValue& requestedValue, VehiclePropValue* outValue) {    if (requestedValue.prop == VEHICLE_PROPERTY_MY_CUSTOM_SENSOR) {        // Simulate reading from hardware or a sensor        float sensorValue = getMyCustomSensorDataFromHardware(); // Your hardware-specific function        outValue->prop = VEHICLE_PROPERTY_MY_CUSTOM_SENSOR;        outValue->areaId = requestedValue.areaId;        outValue->timestamp = elapsedRealtimeNano();        outValue->value.floatValues.push_back(sensorValue);        return Result::OK;    }    // Handle other properties or return NOT_AVAILABLE/INVALID_ARG    return Result::NOT_AVAILABLE;}

3. Handle Property Write Requests (onSetProperty)

If your custom property is writable (READ_WRITE access), you’ll need to implement logic in the onSetProperty method to process incoming values and apply them to the hardware.

// Example in C++ (simplified)Result MyVehicleHal::onSetProperty(const VehiclePropValue& requestedValue) {    if (requestedValue.prop == VEHICLE_PROPERTY_MY_CUSTOM_SENSOR) {        if (requestedValue.value.floatValues.empty()) {            return Result::INVALID_ARG;        }        float newValue = requestedValue.value.floatValues[0];        setMyCustomSensorThresholdInHardware(newValue); // Your hardware-specific function        return Result::OK;    }    // Handle other properties or return NOT_AVAILABLE/INVALID_ARG    return Result::NOT_AVAILABLE;}

4. Sending Asynchronous Property Events (onPropertyEvent)

For properties with ON_CHANGE or CONTINUOUS change modes, the VHAL implementation is responsible for actively monitoring the hardware and pushing updates to CarService. This is typically done by calling a callback provided by CarService, often named onPropertyEvent or similar, within your VHAL implementation.

// In a separate thread or hardware monitoring loopvoid MyVehicleHal::monitorCustomSensor() {    while (running) {        float currentSensorValue = getMyCustomSensorDataFromHardware();        if (currentSensorValue != lastReportedSensorValue ||            VEHICLE_PROPERTY_MY_CUSTOM_SENSOR is continuous) {            VehiclePropValue eventValue;            eventValue.prop = VEHICLE_PROPERTY_MY_CUSTOM_SENSOR;            eventValue.areaId = 0; // Global            eventValue.timestamp = elapsedRealtimeNano();            eventValue.value.floatValues.push_back(currentSensorValue);            // Call the callback provided by CarService            mVehicleHalCallback->onPropertyEvent({eventValue});            lastReportedSensorValue = currentSensorValue;        }        std::this_thread::sleep_for(std::chrono::milliseconds(100)); // Sample rate    }}

Building and Deploying the Custom VHAL

After modifying the VHAL implementation, you’ll need to recompile the Android Automotive OS and flash it onto your target device or emulator. The exact build steps depend on your Android version and build system, but generally involve:

1. Syncing the Android source code: repo init -u <URL> -b <BRANCH> && repo sync
2. Applying your VHAL changes in the relevant vendor/hardware directories.
3. Setting up the build environment: source build/envsetup.sh
4. Choosing your target device: lunch <TARGET> (e.g., aosp_car_x86_64-userdebug)
5. Building the entire Android image: m -j$(nproc)
6. Flashing the image to your device (e.g., using fastboot flashall).

Testing Your Custom VHAL Property

Once deployed, you can verify your custom property using adb shell commands or by developing a simple Android application.

Using adb shell for inspection:

adb shell cmd car_service dump

This command will dump all registered vehicle properties, including your custom one if it’s correctly exposed by the VHAL. Look for your custom property ID and its associated metadata.

Interacting with a custom app:

A simple Android app can use CarPropertyManager to interact with your custom property:

// Java/Kotlin example in an Android Automotive AppCarPropertyManager carPropertyManager = (CarPropertyManager) getSystemService(Context.CAR_PROPERTY_SERVICE);int MY_CUSTOM_SENSOR_PROPERTY_ID = 0x21000000 | 0x0001; // Reconstruct your property IDCarPropertyConfig<Float> config = carPropertyManager.getCarPropertyConfig(MY_CUSTOM_SENSOR_PROPERTY_ID);if (config != null) {    Log.d("VHAL_TEST", "Custom sensor config: " + config.toString());    // Read the property    CarPropertyValue<Float> value = carPropertyManager.getProperty(Float.class, MY_CUSTOM_SENSOR_PROPERTY_ID, 0);    if (value != null) {        Log.d("VHAL_TEST", "Custom sensor value: " + value.getValue());    }    // Write to the property (if READ_WRITE)    // carPropertyManager.setProperty(Float.class, MY_CUSTOM_SENSOR_PROPERTY_ID, 0, 123.45f);    // Register for updates    carPropertyManager.registerCallback(new CarPropertyManager.CarPropertyEventCallback() {        @Override        public void onChangeEvent(CarPropertyValue value) {            if (value.getPropertyId() == MY_CUSTOM_SENSOR_PROPERTY_ID) {                Log.d("VHAL_TEST", "Custom sensor changed: " + value.getValue());            }        }        @Override        public void onErrorEvent(int propId, int area, int errorCode) {            Log.e("VHAL_TEST", "Error on property " + propId);        }    }, MY_CUSTOM_SENSOR_PROPERTY_ID, CarPropertyManager.SENSOR_RATE_FAST);} else {    Log.e("VHAL_TEST", "Custom sensor property not found.");}

Conclusion

Implementing custom VHAL properties is a powerful technique for extending Android Automotive OS to support unique vehicle hardware and functionalities. By carefully defining property IDs, implementing the IVehicleHal interface, and correctly handling read/write/event logic, OEMs and developers can seamlessly integrate proprietary systems into the Android ecosystem. This deep dive has provided a foundational understanding and practical guidance for developing your own custom VHAL properties, paving the way for highly customized and innovative in-car experiences.