Introduction: The Evolving Landscape of Android Automotive VHAL

The Vehicle Hardware Abstraction Layer (VHAL) is the backbone of Android Automotive, providing a standardized interface for interacting with various vehicle systems and sensors. While VHAL offers a rich set of predefined properties for common vehicle data (like speed, gear, or engine RPM), real-world automotive applications often demand more sophisticated data exchange. What happens when your ECU delivers a complex struct containing multiple sensor readings, or a dynamically sized array of diagnostics codes? Traditional VHAL properties, primarily designed for scalar types or fixed-size enums, fall short. This article delves into expert-level techniques for extending VHAL to handle complex data structures and array properties, focusing on the powerful yet often underutilized BYTES property type.

The Limitations of Standard VHAL Properties

VHAL properties are defined by their IDs, types, and access modes. Standard types include INT32, FLOAT, BOOL, and basic arrays of these types (e.g., INT32_VEC for a fixed-size integer array). While these cover many scenarios, they struggle with:

• Arbitrary Structures: A custom data packet containing a timestamp, multiple sensor values, and an error flag.
• Dynamic Arrays: A list of detected objects from a camera, where the number of objects varies.
• Complex Enums/Bitmasks: More intricate state representations than simple integers.

Attempting to map such data to multiple individual VHAL properties can lead to property sprawl, synchronization issues, and increased overhead. The solution lies in serialization and the flexible BYTES property type.

Leveraging `BYTES` Properties for Custom Data

The BYTES property type allows VHAL to transmit an arbitrary sequence of bytes. This opens the door to sending any complex data structure, provided it can be serialized into a byte array and deserialized back into its original form. Protocol Buffers (protobuf) are an excellent choice for this, offering efficient serialization, language-agnostic data definitions, and backward/forward compatibility.

Step 1: Defining Your Custom Data Structure with Protocol Buffers

First, define your complex data structure using a .proto file. Let’s imagine we need to transmit a structure representing a fused sensor reading, including multiple IMU values and a timestamp.

syntax = "proto3";package com.example.automotive.vhal;option java_package = "com.example.automotive.vhal.proto";option java_outer_classname = "VehicleSensorProto";message FusedSensorData {  int64 timestamp_ms = 1;  float accelerometer_x = 2;  float accelerometer_y = 3;  float accelerometer_z = 4;  float gyroscope_x = 5;  float gyroscope_y = 6;  float gyroscope_z = 7;  repeated string detected_objects = 8; // Example of an array within the struct}

This .proto file defines FusedSensorData, including a repeated string field to demonstrate an array of strings within the structure itself.

Step 2: Generating Language-Specific Code

Compile your .proto file to generate C++ and Java classes. These generated classes provide methods for serializing your data to bytes and deserializing bytes back into your data structure.

# For C++:protoc --cpp_out=. FusedSensorData.proto# For Java (Android):protoc --java_out=java/src/main FusedSensorData.proto

Step 3: Defining the Custom VHAL Property

Next, define a new VHAL property using a unique ID in your VHAL implementation. This can be done in types.hal if you are modifying the core VHAL definitions, or in a custom enum in your Java/C++ VHAL service implementation if you’re working with an emulated or custom hardware abstraction.

For Android Automotive, you’ll typically define custom properties in an extension of VehiclePropertyIds, often within your car service implementation:

// In your custom VHAL service (e.g., EmulatedVehicleConnector.java)public static final int CUSTOM_FUSED_SENSOR_DATA = 0x22100001; // Example custom property ID// Or in a .hal file:type VehicleProperty: int {  CUSTOM_FUSED_SENSOR_DATA = 0x22100001,}// Property configuration:addProperty(CUSTOM_FUSED_SENSOR_DATA, VehiclePropertyType.BYTES, VehicleArea.GLOBAL, VehiclePropertyAccess.READ_WRITE, VehiclePropertyChangeMode.ON_CHANGE);

Note the VehiclePropertyType.BYTES. This is crucial.

Step 4: Implementing Serialization/Deserialization in VHAL Service

Now, integrate the protobuf generated classes into your VHAL service. When a client requests data (get) or sends data (set), your VHAL service will handle the serialization and deserialization.

VHAL Service (Java Example – typically an emulated or mock VHAL)

import com.google.protobuf.InvalidProtocolBufferException;import com.example.automotive.vhal.proto.VehicleSensorProto.FusedSensorData;import android.car.hardware.property.CarPropertyManager;import android.car.hardware.property.CarPropertyConfig;import android.car.hardware.property.CarPropertyValue;import android.hardware.automotive.vehicle.V2_0.VehiclePropertyType;import android.hardware.automotive.vehicle.V2_0.VehicleArea;import android.hardware.automotive.vehicle.V2_0.VehiclePropertyAccess;import android.hardware.automotive.vehicle.V2_0.VehiclePropertyChangeMode;// ... inside your VHAL service class (e.g., EmulatedVehicleConnector)private FusedSensorData currentFusedSensorData; // Internal state representation// Method to handle property 'get' requests@Overridepublic CarPropertyValue onGetProperty(CarPropertyConfig config, VehiclePropValue requestedPropValue) {    if (config.getPropertyId() == CUSTOM_FUSED_SENSOR_DATA) {        if (currentFusedSensorData != null) {            byte[] serializedData = currentFusedSensorData.toByteArray();            return new CarPropertyValue(config.getPropertyId(), requestedPropValue.areaId, serializedData);        }    }    return super.onGetProperty(config, requestedPropValue);}// Method to handle property 'set' requests@Overridepublic int onSetProperty(VehiclePropValue propValue) {    if (propValue.prop == CUSTOM_FUSED_SENSOR_DATA) {        try {            currentFusedSensorData = FusedSensorData.parseFrom(propValue.bytes);            // Process the received data, e.g., update internal state, notify other components            Log.d(TAG, "Received FusedSensorData: " + currentFusedSensorData.toString());            return VehicleHalStatusCode.OK;        } catch (InvalidProtocolBufferException e) {            Log.e(TAG, "Failed to parse FusedSensorData from bytes", e);            return VehicleHalStatusCode.BAD_VALUE;        }    }    return super.onSetProperty(propValue);}

VHAL Service (C++ Example – for native VHAL implementation)

// In IVehicleHal.cpp or your custom hardware module implementation#include "FusedSensorData.pb.h"// ... within getProperty or setProperty methods// For getProperty(const VehiclePropValue& requestedPropValue, VehiclePropValue* outValue)// if requestedPropValue.prop == CUSTOM_FUSED_SENSOR_DATA {  // Assuming mCurrentFusedSensorData is a member variable of type FusedSensorData  if (mCurrentFusedSensorData) {    std::string serializedData;    mCurrentFusedSensorData->SerializeToString(&serializedData);    outValue->bytes.insert(outValue->bytes.end(), serializedData.begin(), serializedData.end());    return OK;  }}// For setProperty(const VehiclePropValue& propValue)// if propValue.prop == CUSTOM_FUSED_SENSOR_DATA {  FusedSensorData receivedData;  if (receivedData.ParseFromArray(propValue.bytes.data(), propValue.bytes.size())) {    // Process the received data    mCurrentFusedSensorData = std::make_unique(receivedData);    return OK;  } else {    return BAD_VALUE;  }}

Step 5: Client Application Interaction

On the Android client side, you interact with the custom property via CarPropertyManager. The key is to handle the byte[] return type and perform the same serialization/deserialization logic.

import com.example.automotive.vhal.proto.VehicleSensorProto.FusedSensorData;import android.car.Car;import android.car.CarNotConnectedException;import android.car.hardware.property.CarPropertyManager;import android.car.hardware.property.CarPropertyValue;import android.os.Bundle;import android.util.Log;import androidx.appcompat.app.AppCompatActivity;public class VhalClientActivity extends AppCompatActivity {    private static final String TAG = "VhalClientActivity";    public static final int CUSTOM_FUSED_SENSOR_DATA = 0x22100001;    private CarPropertyManager mCarPropertyManager;    @Override    protected void onCreate(Bundle savedInstanceState) {        super.onCreate(savedInstanceState);        // Assume Car instance is already obtained        Car car = Car.createCar(this, null);        try {            mCarPropertyManager = (CarPropertyManager) car.getCarManager(Car.PROPERTY_SERVICE);            // Register listener for updates            mCarPropertyManager.registerCallback(new CarPropertyManager.CarPropertyEventCallback() {                @Override                public void onChangeEvent(CarPropertyValue value) {                    if (value.getPropertyId() == CUSTOM_FUSED_SENSOR_DATA) {                        try {                            byte[] bytes = (byte[]) value.getValue();                            FusedSensorData data = FusedSensorData.parseFrom(bytes);                            Log.d(TAG, "Received updated FusedSensorData: " + data.toString());                        } catch (Exception e) {                            Log.e(TAG, "Error parsing FusedSensorData from VHAL", e);                        }                    }                }                @Override                public void onErrorEvent(int propId, int zone) {                    Log.e(TAG, "Property error: " + propId);                }            }, CUSTOM_FUSED_SENSOR_DATA, CarPropertyManager.PROPERTY_EVENT_RATE_ONCHANGE);            // Example: Get current value            byte[] currentBytes = (byte[]) mCarPropertyManager.getProperty(CUSTOM_FUSED_SENSOR_DATA, 0).getValue();            if (currentBytes != null) {                FusedSensorData currentData = FusedSensorData.parseFrom(currentBytes);                Log.d(TAG, "Current FusedSensorData: " + currentData.toString());            }            // Example: Set a new value            FusedSensorData newData = FusedSensorData.newBuilder()                .setTimestampMs(System.currentTimeMillis())                .setAccelerometerX(0.1f).setAccelerometerY(0.2f).setAccelerometerZ(9.8f)                .setGyroscopeX(0.01f).setGyroscopeY(0.02f).setGyroscopeZ(0.03f)                .addDetectedObjects("car").addDetectedObjects("pedestrian")                .build();            mCarPropertyManager.setProperty(CUSTOM_FUSED_SENSOR_DATA, 0, newData.toByteArray());        } catch (CarNotConnectedException e) {            Log.e(TAG, "Car not connected", e);        }    }}

Handling Array Properties

As demonstrated in the FusedSensorData example, protobuf’s repeated keyword is the natural way to handle arrays within complex structures. When the entire property represents an array (e.g., a list of diagnostic trouble codes), you can define a protobuf message containing just that repeated field:

// diagnostics.protopackage com.example.automotive.vhal;option java_package = "com.example.automotive.vhal.proto";option java_outer_classname = "VehicleDiagnosticsProto";message DiagnosticCodes {  repeated string dtc_codes = 1;}

This DiagnosticCodes message would then be serialized into a BYTES VHAL property, allowing you to transmit a dynamically sized array of strings. The implementation steps for VHAL service and client remain identical to those for complex structures.

Best Practices and Considerations

• Performance: Serialization and deserialization add overhead. For high-frequency, small, simple data, consider if multiple scalar properties are more efficient. For larger or less frequent updates of complex data, BYTES + protobuf is often superior.
• Version Compatibility: Protocol Buffers are excellent for maintaining compatibility across different versions of your data structure definition, which is critical in long-lived automotive systems.
• Error Handling: Always implement robust error handling for InvalidProtocolBufferException when deserializing. Malformed data could lead to crashes or incorrect system behavior.
• Security: Ensure that any sensitive data transmitted via custom BYTES properties is appropriately secured (e.g., encrypted if crossing untrusted boundaries).
• Documentation: Clearly document your custom VHAL properties and their underlying protobuf schemas to ensure maintainability and ease of integration for other developers.
• Property Change Mode: For data that changes frequently, use ON_CHANGE. For data that changes rarely or requires explicit polling, use STATIC or ON_CHANGE with a suitable sample rate.

Conclusion

Extending Android Automotive VHAL beyond its basic property types is a powerful capability for building sophisticated in-car systems. By effectively using the BYTES property type in conjunction with robust serialization frameworks like Protocol Buffers, developers can transmit complex data structures and dynamic arrays seamlessly between vehicle hardware and the Android application layer. This approach not only provides flexibility but also promotes a clean, maintainable, and version-compatible VHAL interface, essential for the demanding environment of automotive software development.