Hardware capabilities in AAOS

Car properties that can be accessed by the AAOS

Given below is the architecture of the android automotive in car

• Electronic control units (ECUs) are embedded systems responsible for controlling one or more electrical systems in automobiles. Various sensors feed data to these ECUs.

• A Vehicle Hardware Abstraction Layer (VHAL) acts as a bridge between vehicle hardware and Android software. It translates signals from the vehicle bus into vehicle properties so that they can be accessed by the operating system. Its main purpose is to provide a standardized and adaptable way for system services to communicate with car-specific hardware and functionalities.

• The Car Service builds upon these vehicle properties and enriches them with additional information from other sources, creating a set of useful services for applications. Applications don’t directly call the Car Service; instead, they interact with the Car Manager library, which implements the android.car.* packages.

The vehicle manufacturers make use of HAL files, which define the interface between a hardware device and the Android operating system. HAL files are written in the Hardware Interface Description Language (HIDL) for Android 12 and lower, and Android Interface Definition Language (AIDL) for Android 13 and above. This interface is used by vehicle manufacturers (OEM or Original Equipment Manufacturer) to define which hardware properties and features are exposed to apps and the Android framework

While implementing these properties, the specified property configuration structure is followed which will contain fields such as :

• propertyId

• access mode such as READ, WRITE or READ_WRITE

• changeMode such as STATIC, ON_CHANGE or CONTINUOUS

• configArray an optional array to contain property specific configuration which can be empty.

• configString an optional string to contain property specific configuration which can be empty.

• minSampleRate and maxSampleRate The minimum and maximum supported sample rate for continuous property

• PropertyType like STRING, BOOLEAN, INT32, INT64, FLOAT, BYTE, MIXED

• areaId

Currently there are around 160 system properties that are supported by the VHAL . These are defined as constants in VehiclePropertyId. Here is the list 👇

VehiclePropertyIds  |  Android DevelopersAndroid Developers

Each vehicle property has been associated with some permission, such as properties like IGNITION_STATE and CURRENT_GEAR requiring 'android.car.permission.CAR_POWERTRAIN,' and properties such as ENGINE_OIL_TEMP and ENGINE_RPM falling under the signature permission 'android.car.permission.CAR_ENGINE_DETAILED.' We may need to add these permissions to our manifest file to access those properties. However, there is a catch: only permissions that are not marked as signature/privileged can be added to the manifest and used.

Signature / Privileged permission:

Since the VHAL can provide very sensitive information about the car, the associated permissions are marked as signature permissions and are not available to regular developers.

How can apps be granted these signature permissions?

• The preinstalled apps developed by car manufacturers will have these signature permissions granted.

• Other developers need to sign the app with the privileged key, which will be granted by the car manufacturer or the AAOS team only to trusted developers.

Properties that are not entitled with signature permission:

Currently only 9 permission can be easily added by third party developers. Below is the list of those permissions and its associated properties:

1. android.car.permission.CAR_INFO :

• INFO_DRIVER_SEAT

• INFO_EV_BATTERY_CAPACITY

• INFO_EV_CONNECTOR_TYPE

• INFO_EV_PORT_LOCATION

• INFO_EXTERIOR_DIMENSIONS

• INFO_FUEL_CAPACITY

• INFO_FUEL_DOOR_LOCATION

• INFO_FUEL_TYPE

• INFO_MAKE

• INFO_MODEL

• INFO_MODEL_YEAR

• INFO_MULTI_EV_PORT_LOCATIONS

• INFO_VIN

• ELECTRONIC_TOLL_COLLECTION_CARD_STATUS

• ELECTRONIC_TOLL_COLLECTION_CARD_TYPE

1. android.car.permission.CAR_ENERGY

• EV_BATTERY_INSTANTANEOUS_CHARGE_RATE

• EV_BATTERY_LEVEL

• FUEL_LEVEL

• FUEL_LEVEL_LOW

• RANGE_REMAINING

1. android.car.permission.CAR_ENERGY_PORTS

• EV_CHARGE_PORT_CONNECTED

• EV_CHARGE_PORT_OPEN

• FUEL_DOOR_OPEN

1. android.car.permission.CAR_POWERTRAIN

• CURRENT_GEAR

• GEAR_SELECTION

• IGNITION_STATE

• PARKING_BRAKE_AUTO_APPLY

• PARKING_BRAKE_ON

1. android.car.permission.READ_CAR_DISPLAY_UNITS

• DISTANCE_DISPLAY_UNITS

• EV_BATTERY_DISPLAY_UNITS

• FUEL_CONSUMPTION_UNITS_DISTANCE_OVER_VOLUME

• FUEL_VOLUME_DISPLAY_UNITS

• TIRE_PRESSURE_DISPLAY_UNITS

• TIRE_PRESSURE_DISPLAY_UNITS

1. android.car.permission.CAR_EXTERIOR_ENVIRONMENT

• ENV_OUTSIDE_TEMPERATURE

• NIGHT_MODE

1. android.car.permission.CAR_SPEED

• PERF_VEHICLE_SPEED

• PERF_VEHICLE_SPEED_DISPLAY

• WHEEL_TICK

1. android.car.permission.READ_CAR_INTERIOR_LIGHTS

• CABIN_LIGHTS_STATE

• READING_LIGHTS_STATE

1. android.car.permission.CONTROL_CAR_INTERIOR_LIGHTS

• CABIN_LIGHTS_SWITCH

• READING_LIGHTS_SWITCH

1. android.car.permission.READ_CAR_STEERING

• PERF_REAR_STEERING_ANGLE

• PERF_STEERING_ANGLE

These properties can be accessed using CarPropertyManager class which provides the application interface for interacting with vehicle specific properties and its associated API Car.PROPERTY_SERVICE. Below is the example 👇

// Creating instance of CarPropertyManager with appropriate API
var carPropertyManager = Car.createCar(carContext).getCarManager(Car.PROPERTY_SERVICE) as CarPropertyManager

println(carPropertyManager.getFloatProperty(VehiclePropertyIds.EV_BATTERY_LEVEL,0))

The above code will print the EV battery level in watt-hours (Wh).

The second parameter in the getFloatProperty() is called areaId.

What is areaId and its use :

The structure of the car is split into different area types, namely: GLOBAL, WINDOW, MIRROR, SEAT, DOOR, WHEEL. Some vehicle properties, such as climate control or seat settings, can have different values for various zones within the area. In that case, areaId specifies which zone a property value applies to. Each area type has a set of bit flags defined for its zones in an enum

For example, the SEAT area defines VehicleAreaSeat enums:

• ROW_1_LEFT

• ROW_1_RIGHT

• ROW_2_LEFT

• ROW_2_CENTER

• ROW_2_RIGHT

The areaId can be used when we want to get information or execute a task in a specific zone of that area. For example, if we want to adjust the fan only for the front rows, areaId comes in handy. Properties that are independent of any area and are global are represented by 0.

We can also register to a specific property so that we can get notified when that property value has been changed.

carPropertyManager.registerCallback(object : CarPropertyManager.CarPropertyEventCallback {
        override fun onChangeEvent(value: CarPropertyValue<*>) {
                Log.d("TAG", "SPEED: onChangeEvent(" + value.value + ")");
        }

        override fun onErrorEvent(propId: Int, zone: Int) {
                Log.d("TAG", "SPEED: onErrorEvent($propId, $zone)");
        }
  }, VehiclePropertyIds.PERF_VEHICLE_SPEED, CarPropertyManager.SENSOR_RATE_NORMAL)

Overview  |  Android Open Source ProjectAndroid Open Source Project

VHAL

Android Automotive: Unleashing the Power of Android OS on the RoadMedium