Vehicle Properties

The vehicle HAL 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 vehicle HAL interface is based on accessing (read, write, subscribe) a property, which is an abstraction for a specific function.

HAL interfaces

The vehicle HAL uses the following interfaces:

  • vehicle_prop_config_t const *(*list_properties)(..., int* num_properties)
    List configuration of all properties supported by the vehicle HAL. Only supported properties are used by vehicle network service.
  • (*get)(..., vehicle_prop_value_t *data)
    Read the current value of the property. For zoned property, each zone may have different value.
  • (*set)(..., const vehicle_prop_value_t *data)
    Write a value to property. Result of write is defined per property.
  • (*subscribe)(..., int32_t prop, float sample_rate, int32_t zones)
    • Start monitoring a property value change. For zoned property, subscription applies to requested zones. Zones = 0 is used to request all zones supported.
    • Vehicle HAL should call separate callback when the property's value changes (=on change) or in const interval (=continuous type).
  • (*release_memory_from_get)(struct vehicle_hw_device* device, vehicle_prop_value_t *data)
    Release memory allocated from get call.

The vehicle HAL uses the following callback interfaces:

  • (*vehicle_event_callback_fn)(const vehicle_prop_value_t *event_data)
    Notifies vehicle property's value change. Should be done only for subscribed properties.
  • (*vehicle_error_callback_fn)(int32_t error_code, int32_t property, int32_t operation)
    Return global vehicle HAL level error or error per property. Global error causes HAL restart, which can lead to restarting other components (including applications).

Vehicle properties

Properties can be read-only, write-only (used to pass information to vehicle HAL 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 (value_type):

  • BYTES
  • BOOLEAN
  • FLOAT
  • FLOAT[]
  • INT32
  • INT32[]
  • INT64
  • INT64[]
  • STRING

A zoned property may have more than one value, based on the number of zones supported by the property.

Area types

The vehicle HAL defines multiple area types:

  • GLOBAL
    This property is a singleton and does not have multiple areas.
  • WINDOW
    Area based on windows, uses VehicleAreaWindow enum.
  • MIRROR
    Area based on mirrors, uses VehicleAreaMirror enum.
  • SEAT
    Area based on seats, uses VehicleAreaSeat enum.
  • DOOR
    Area based on doors, uses VehicleAreaDoor enum.
  • WHEEL
    Area based on wheels, uses VehicleAreaWheel enum.

Each zoned property must use pre-defined area type. Each area type has a set of bit flags defined in an enum for the area type. For example, the SEAT area defines VehicleAreaSeat enums:

  • 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
  • ...

Area IDs

Zoned properties are addressed via 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 VehicleAreaSeat might use the following Area IDs:

  • ROW_1_LEFT | ROW_1_RIGHT
    The Area ID applies to both front seats.
  • ROW_2_LEFT
    Only applies to rear left seat.
  • ROW_2_RIGHT
    Only applies to rear right seat.

Property Status

Every property value comes with a VehiclePropertyStatus value. This indicates the current status for the property:

  • AVAILABLE
    Property is available and the value is valid.
  • UNAVAILABLE
    Property value is currently unavailable. This is used for transiently disabled features for a supported property.
  • ERROR
    Something is wrong with this property.

Configuring a property

Use vehicle_prop_config_t to provide configuration information for each property. Information includes:

  • access (r, w, rw)
  • changeMode (represents how property is monitored: on change vs continuous)
  • areaConfigs (areaId, min, and max values)
  • configArray (additional configuration parameters)
  • configString (additional information passed as a string)
  • minSampleRate, max_sample_rate
  • prop (Property ID, int)

Handling zone properties

A zoned property is equivalent to a collection of multiple properties where each sub property is accessible by specified Area ID value.

  • get call for zoned property always includes the Area ID in the request, so only the current value for the requested Area ID is returned. If the property is a global, then Area ID is 0.
  • set call for zoned property always includes the Area ID in the request, so only the requested Area ID is changed.
  • subscribe call will generate events for all Area IDs for the property.

Get calls

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, the get call should return -EAGAIN. Some properties (such as HVAC) have separate on/off power property. Calling get for such a property (when powered off) should return a UNAVAILABLE status rather than returning an error.

Example: get HVAC Temperature

Vehicle HAL get HVAC example

Figure 1. Get HVAC temperature (CS = CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)

Set calls

A 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. When the change is performed by the electronic control unit (ECU) owning the property, the updated value is returned through vehicle network and the vehicle HAL sends an updated value as an event to vehicle network service (VNS).

Some 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.

Example: set HVAC Temperature

Vehicle HAL set HVAC example

Figure 2. Set HVAC temperature (CD = CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)

Handling custom properties

To support partner-specific needs, the vehicle HAL 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:
    • VehiclePropertyGroup:VENDOR
      The VENDOR group is used only for custom properties.
    • VehicleArea
      Select an appropriate Area Type.
    • VehiclePropertyType
      Select the proper data type. BYTES type allows passing raw data, so this is enough in most cases. Sending big data frequently through custom properties can slow down the whole vehicle network access, so be careful when you add a big payload.
    • Property ID
      Choose a four nibble ID for the custom property.
  • Access via CarPropertyManager (for Java components) or via Vehicle Network Service API (for native). Do not modify other car APIs as it can lead to compatibility issues in the future.

Handling HVAC properties

You can use the vehicle HAL to control HVAC by setting HVAC-related properties. Most HVAC properties are zoned properties, but a few are non-zoned (global) properties. Example properties defined include:

  • VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET
    Set temperature per zone.
  • VEHICLE_PROPERTY_HVAC_RECIRC_ON
    Control recirculation per zone).

For a full list of HVAC properties, search for VEHICLE_PROPERTY_HVAC_* in types.hal.

There are additional rules for mapping a zoned HVAC property to Area IDs when the HVAC property uses VehicleAreaSeat. Every available seat in the car must be part of an Area ID in the Area ID array.

Example 1: A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three back seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). There are two temperature control units: driver side and passenger side.

  • A valid mapping set of Area IDs for HVAC_TEMPERATURE SET is:
    • 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 2: A car has three seat rows with two seats in the front row (ROW_1_LEFT, ROW_1_RIGHT) and three seats in the second (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) and third rows (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). There are three temperature control units: driver side, passenger side, and rear. A reasonable way to map HVAC_TEMPERATURE_SET to Area IDs is a three element array:

  • ROW_1_LEFT
  • ROW_1_RIGHT
  • ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT

Handling sensor properties

Vehicle HAL 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.

Supported sensor properties include:

  • NIGHT_MODE
    Should support. Determines day/night mode of display.
  • GEAR_SELECTION/CURRENT_GEAR
    Gear selected by driver vs. actual gear.
  • VEHICLE_SPEED
    Vehicle speed. Protected with permission.
  • ODOMETER
    Current odometer reading. Protected with permission.
  • FUEL_LEVEL
    Current fuel level in %.
  • FUEL_LEVEL_LOW
    Fuel level is low or not (boolean).

Vehicle Mapping Service (VMS)

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 (ADAS). Clients may include vehicle systems interfacing through the VMS property in the Vehicle HAL 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 Vehicle HAL, the message types and data structures are described in Vehicle HAL 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.