Vehicle HAL (VHAL)

The Gateway to the Car: Vehicle HAL (VHAL)

The Vehicle Hardware Abstraction Layer (VHAL) is arguably the most critical component unique to Android Automotive OS. It serves as the single, standardized gateway between the upper Android framework (specifically CarService) and the deeply embedded vehicle network (CAN, LIN, FlexRay, or Automotive Ethernet).

Without the VHAL, AAOS is just a tablet OS. With the VHAL, it becomes an integrated vehicle component capable of reading wheel speed, adjusting HVAC, and responding to physical steering wheel buttons.

The IVehicle AIDL Interface

Historically defined in HIDL, the VHAL is now defined using Stable AIDL. The interface (android.hardware.automotive.vehicle.IVehicle) is surprisingly simple, primarily exposing methods to get, set, and subscribe to vehicle properties.

// Simplified representation of IVehicle.aidl
package android.hardware.automotive.vehicle;

import android.hardware.automotive.vehicle.VehiclePropValue;

@VintfStability
interface IVehicle {
    // Read a property value
    VehiclePropValue get(in VehiclePropValue requestedPropValue);
    
    // Write a property value
    void set(in VehiclePropValue propValue);
    
    // Subscribe to property changes
    void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options);
    
    // Unsubscribe
    void unsubscribe(in IVehicleCallback callback, in int[] propIds);
}

The power of the VHAL lies not in complex method signatures, but in the standardized data model passed through VehiclePropValue.

Vehicle Properties: The VehicleProperty Enum

Every piece of data exchanged through the VHAL is defined as a Property. Google defines hundreds of standardized properties in the VehicleProperty enum, categorizing them by type and purpose.

Properties are identified by an integer ID and are defined with specific attributes:

• Type: Boolean, Integer, Float, Int32Vec, String, etc.
• Change Mode: STATIC (never changes, e.g., number of doors), ON_CHANGE (updates only when the value changes, e.g., gear selection), or CONTINUOUS (updates constantly at a specific frequency, e.g., vehicle speed).
• Access: Read/Write, Read-Only, Write-Only.

// Example: Setting a property value in C++ VHAL implementation
VehiclePropValue value;
value.prop = toInt(VehicleProperty::HVAC_TEMPERATURE_SET);
value.areaId = toInt(VehicleAreaSeat::ROW_1_LEFT); // Driver side
value.value.floatValues.resize(1);
value.value.floatValues[0] = 22.5f; // 22.5 Celsius

auto status = mVehicle->set(value);

Vendor Specific Properties

OEMs frequently need to support hardware features not covered by standard properties (e.g., a proprietary massage seat pattern). The VHAL allows the definition of Vendor properties by utilizing a specific ID range masked with VehiclePropertyGroup::VENDOR.

Integrating with the Vehicle Bus (CAN)

The VHAL itself does not speak CAN or LIN. The reference implementation provided by AOSP acts as a mock layer. In a production environment, the OEM must replace or extend this reference implementation to communicate with their specific MCU (Microcontroller Unit) or Gateway.

The typical data flow looks like this:

1. App: Sets HVAC temperature via CarPropertyManager.
2. Framework: CarService routes the request to VHAL via AIDL.
3. VHAL implementation (C++): Translates the standard Android property into an OEM specific payload.
4. IPC / Socket: The VHAL sends the payload over a local socket, SPI, or PCIe to a dedicated Vehicle Network Service or directly to the MCU.
5. MCU: The MCU translates the payload into a physical CAN frame and transmits it onto the vehicle bus.

Testing with the VHAL Emulator

Developing automotive apps without a physical car is possible thanks to the VHAL emulator. When running an AAOS emulator, the reference VHAL is connected to a local socket.

Developers can use the dumpsys utility or the graphical Android Emulator Extended Controls to inject property changes.

# Example: Injecting a gear change (Drive) via adb
adb shell dumpsys android.hardware.automotive.vehicle.IVehicle/default --set 289408000 -i 4

Note: 289408000 is the integer representation of VehicleProperty::GEAR_SELECTION and 4 represents VehicleGear::GEAR_DRIVE.

By thoroughly understanding the VHAL, platform engineers can effectively bridge the gap between high level Android applications and low level embedded vehicle networks.