The Vehicle Hardware Abstraction Layer (VHAL) interface defines the properties OEMs can implement and contains property metadata (for example, whether the property is an int and which change modes are allowed). The VHAL interface is based on accessing (read, write, subscribe) a property, which is an abstraction for a specific function.
The VHAL uses the following interfaces:
List the configuration of all properties supported by the VHAL. CarService uses supported properties only.
(StatusCode status,vec<VehiclePropConfig> propConfigs);
Return the configuration of selected properties.
Write a value to property. Result of write is defined per property.
subscribe(IVehicleCallback callback, vec<SubscribeOptions> options)generates
Start monitoring a property value change. For zoned property,
unsubscribe(IVehicleCallback callback, int32_t propId)generates
The VHAL uses the following callback interfaces:
Notifies vehicle property's value change. Should be done only for subscribed properties.
oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
Return global VHAL level error or error per property. Global error causes the HAL to restart, which can lead to restarting other components (including applications).
Properties can be read-only, write-only (used to pass information to VHAL
level), or read and write (support of most properties is optional). Each
property is uniquely identified by an int32 key and has a predefined type
A zoned property may have more than one value, based on the number of zones supported by the property.
The VHAL defines multiple area types:
||This property is a singleton and does not have multiple areas.|
||Area based on windows, uses
||Area based on mirrors, uses
||Area based on seats, uses
||Area based on doors, uses
||Area based on wheels, uses
Each zoned property must use a pre-defined area type. Each area type has a set
of bit flags defined in an enum for the area type. For example, the
ROW_1_LEFT = 0x0001
ROW_1_CENTER = 0x0002
ROW_1_RIGHT = 0x0004
ROW_2_LEFT = 0x0010
ROW_2_CENTER = 0x0020
ROW_2_RIGHT = 0x0040
ROW_3_LEFT = 0x0100
Zoned properties are addressed through Area IDs. Each zoned property may support
one or more Area IDs. An Area ID is composed of one or more flags from its
respective enum. For example, a property using
might use the following Area IDs:
||The Area ID applies to both front seats.|
||Applies only to the rear left seat.|
||Applies only to the rear right seat.|
Every property value comes with a
This indicates the current status for the property:
||Property is available and the value is valid.|
||Property value is currently unavailable. Used for transiently disabled features for a supported property.|
||Something is wrong with this property.|
Configuring a property
VehiclePropConfig to provide configuration information for each
property. Information includes:
||Represents how a property is monitored, on change versus continuous.|
||Additional configuration parameters.|
||Additional information passed as a string.|
||Property ID, int|
Handling zone properties
A zoned property is equivalent to a collection of multiple properties where each sub-property can be accessed with the specified Area ID value.
getcall for zoned property always includes the Area ID in the request. Therefore, only the current value for the requested Area ID is returned. If the property is a global, then Area ID is 0.
setcall for zoned property always includes the Area ID in the request. Therefore, only the requested Area ID is changed.
subscribecall generates events for all Area IDs for the property.
During initialization, the value for the property may not be available yet as
the matching vehicle network message has not yet been received. In such cases,
get call should return
-EAGAIN. Some properties
(such as HVAC) have separate on/off power property. Calling
such a property (when powered off) should return a
status rather than returning an error. For example, get HVAC Temperature
Figure 1. Get HVAC temperature (CS = CarService, VHAL = Vehicle HAL)
set call is an asynchronous operation involving event
notification after a requested change is made. In a typical operation, a
set call leads to making a change request across vehicle network.
set calls may require initial data to be ready but during
initialization, such data may not be available yet. In such cases, the
set call should return
-EAGAIN. Some properties with
separate power on /off should return
-ESHUTDOWN when the property
is powered off and set cannot be done. Until
set is made effective,
get does not necessarily return the same value as what is set. For
set HVAC Temperature.
Figure 2. Set HVAC temperature (CS = CarService, VHAL = Vehicle HAL)
Handling custom properties
To support partner-specific needs, the VHAL allows custom properties that are restricted to system apps. Use the following guidelines when working with custom properties:
- Property ID should be generated using the following fields:
VENDORgroup is used only for custom properties.
Select an appropriate Area Type.
Select the proper data type.
BYTEStype allows the passing of raw data which is sufficient in most cases. Sending big data frequently through custom properties can slow down entire vehicle network access — be careful when adding a big payload.
Choose a four nibble ID for the custom property.
- To prevent ecosystem fragmentation, custom properties must not be used to replicate vehicle properties that already exist in the (VehiclePropertyIds SDK).
- Fill in
VehiclePropConfig.configStringwith a short description of the custom property. This allows sanity check tools to flag the accidental replication of existing vehicle properties. For example, "hazard light state."
- Access through
CarPropertyManager(for Java components) or through the Vehicle Network Service API (for native). Do not modify other car APIs as doing so can lead to future compatibility issues.
- After implementing vendor properties, selectonly the permissions list in
VehicleVendorPermissionenum for vendor properties. Mapping vendor permissions to system properties will break the CTS and VTS.
Handling HVAC properties
You can use the VHAL to control HVAC by setting HVAC-related properties. Most HVAC properties are zoned properties, although several are non-zoned (global) properties. Sample defined properties include:
||Set temperature per zone.|
||Control recirculation per zone.|
To see a complete list of HVAC properties, search for
types.hal. When the HVAC property uses
VehicleAreaSeat, additional rules
for mapping a zoned HVAC property to Area IDs apply. Each available seat in the car must be part
of an Area ID in the Area ID array.
Example One. A car has two front seats (
and three back seats (
ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). The car
has two temperature control units: the driver side and passenger side.
- A valid mapping set of Area IDs for
ROW_1_LEFT | ROW_2_LEFT
ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
- An alternative mapping for the same hardware configuration is:
ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
ROW_1_RIGHT | ROW_2_RIGHT
Example Two. A car has three seat rows with two seats in the front row
ROW_1_LEFT, ROW_1_RIGHT), three seats in the second
ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT), and three in the third rows
ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). The car has three
temperature control units: driver side, passenger side, and rear. A reasonable way to
HVAC_TEMPERATURE_SET to Area IDs is as a three element array:
ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT
Handling sensor properties
VHAL sensor properties represent real sensor data or policy information such as driving status. Some sensor information (such as driving status and day/night mode) is accessible by any app without restriction as the data is mandatory to build a safe vehicle application. Other sensor information (such as vehicle speed) is more sensitive and requires specific permissions that users can manage.
See the supported sensor properties in (types.hal).
Vehicle Map Service
The Vehicle Map Service (VMS) provides a mechanism to exchange map data between clients through a pub/sub interface to support common vehicle features, such as Advanced Driver Assistance Systems (ADAS). Clients can include vehicle systems interfacing through the VMS property in the VHAL or privileged Android applications. Data shared on VMS are intended to be limited to map data for use by vehicle systems and supporting apps.
VMS is intended for use only in Android Automotive implementations; AOSP does not contain default clients that publish or subscribe to VMS. For the VMS property in the VHAL, the message types and data structures are described in VHAL 2.0 in the VmsMessageType enum, which lists the types of supported VMS messages. This enum is used as the first integer in the vehicle property integers array and determines how the rest of the message is decoded.