Skip to content

Alexa Auto Car Control

The Alexa Auto Car Control library is an Android library for the Alexa Auto App to run car control commands in cars that are based on Android Automotive OS. A car control command is run by the AACS Core Service each time the user tries to voice-control a vehicle component.

Table of Contents

Overview

The Alexa Auto Car Control Library allows user utterances to be directly applied to Android Automotive OS car control APIs and then to the Hardware Abstraction Layer to complete the car control workflow. The library translates between Auto SDK Car Control events and Android Automotive CarPropertyManager API calls, which controls various car features, such as air conditioning and fan settings. For information about CarPropertyManager, see the Android documentation on CarPropertyManager.

The library works with Android Car API and CarPropertyManager API. These APIs are only available at Android API level 29 and up.

Understanding Library Components

The following list describes the purposes of the major components of the library:

  • The AACS Car Control Broadcast Receiver:

    • Receiving AASB AdjustControllerValue or SetControllerValue messages from the AACS Core Service.
    • Instantiating the Car Control Handler to call specific controller operations. The exact operations supported depend on the controller type, which can be Power, Toggle, Mode, or Range.

  • The AACS Car Control platform implementation (CarControlHandler):

    • Instantiating the Android Car object to be called in the set and adjust methods for each controller type.
    • Defining the get and set methods for each controller type.
    • Defining the adjust methods for the Range or Power Controller.

  • The AACS Car Control Helper/Util:

    • Providing translation between [endpointID, controllerType, controllerID, value] in the AASB Car Control message from the Auto SDK Engine to [propertyId, areaId, value] used in the Android Automotive API call.
    • Getting or saving the current Mode setting for the Mode Controller.
    • Enabling you to parse an external configuration file if you want to use a customized CarControlEndpointMapping.json file.

  • Car Control Endpoint Mapping configuration file maps [endpointID, controllerType, controllerID, value] from the Auto SDK Car Control Asset to [propertyId, areaId, value] used in the Android Automotive API call.

    A default CarControlEndpointMapping.json file is provided in the assets directory. Be sure to review CarControlEndpointMapping.json to verify that it contains values consistent with the ones specified in the CarControlConfig.json file in the Car Control module. For example, if you have changed an endpointId in CarControlConfig.json from "default.light" to "default.roof.light", the CarControlEndpointMapping.json file must contain the same endpoint mapping information.

Before Using the Alexa Auto Car Control Library

Before using the library, follow these major steps:

  1. Install your application as a system privileged app on Android Automotive OS.
  2. Provide permission in your app's Android Manifest.
  3. Ensure that the intent target specified in the library is used.

Including Alexa Auto Car Control Library in a System Application

For the Alexa Auto App to enable the permission namespace android.car.permission, it must run in a system privileged app. To install your application as a system privileged app, place it in the /system/priv-app/ directory.

Providing Permission in Android Manifest

For security reasons, for your application to send intents to or receive intents from the Alexa Auto Car Control Library, follow these steps:

1) In privapp-permissions-com.amazon.alexaautoclientservice.xml, specify android.car.permission. The following example file shows how to specify permissions for using intents for various car control operations.

    <?xml version="1.0" encoding="utf-8"?>
    <permissions>
        <privapp-permissions package="com.amazon.alexaautoclientservice">
        <permission name="android.car.permission.CONTROL_CAR_EXTERIOR_LIGHTS" />
        <permission name="android.car.permission.CONTROL_CAR_DOORS" />
        <permission name="android.car.permission.CONTROL_CAR_CLIMATE" />
        <permission name="android.car.permission.CONTROL_CAR_SEATS" />
        <permission name="android.car.permission.CAR_EXTERIOR_ENVIRONMENT" />
        <permission name="android.car.permission.CAR_ENERGY_PORTS" />
        <permission name="android.car.permission.CONTROL_CAR_MIRRORS" />
        <permission name="android.car.permission.READ_CAR_DISPLAY_UNITS" />
        <permission name="android.car.permission.CONTROL_CAR_WINDOWS" />
        <permission name="android.car.permission.CAR_CONTROL_AUDIO_VOLUME" />
        <permission name="android.car.permission.CAR_DISPLAY_IN_CLUSTER" />
        <permission name="android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL" />
        <permission name="android.car.permission.CAR_EXTERIOR_LIGHTS" />
        <permission name="android.car.permission.CONTROL_CAR_INTERIOR_LIGHTS" />
        <permission name="android.car.permission.READ_CAR_INTERIOR_LIGHTS" />
        <permission name="android.car.permission.CAR_DYNAMICS_STATE" />
        <permission name="android.car.permission.CONTROL_CAR_DISPLAY_UNITS" />
        <permission name="android.permission.INTERNET" />
        <permission name="android.permission.RECORD_AUDIO" />
        <permission name="android.permission.ACCESS_FINE_LOCATION" />
        <permission name="android.permission.ACCESS_NETWORK_STATE" />
        <permission name="android.permission.ACCESS_WIFI_STATE" />
        <permission name="android.permission.RECEIVE_BOOT_COMPLETED" />
        <permission name="android.permission.CONTROL_INCALL_EXPERIENCE"/>   
        <permission name="android.permission.CAPTURE_AUDIO_OUTPUT"/>
        <permission name="android.permission.INTERACT_ACROSS_USERS"/>
        </privapp-permissions>
    </permissions>

2) Include privapp-permissions-com.amazon.alexaautoclientservice.xml in the /etc/permissions/ directory.

Ensuring Intent Target Specified in the Library is Used

The AACS Car Control Broadcast Receiver listens to intents from the AACS Core Service with the CarControl topic. The intent filter in the Alexa Auto App Car Control Library already defines the intent target for CarControl. For the intent filter in the library to take effect, be sure to clear the intent target defined for CarControl in the Alexa Auto App configuration as follows. Otherwise, the target specification in the Alexa Auto App configuration overrides the intent filter in the library.

    "CarControl" : {
        "type": [],
        "package": [],   
        "class": []
    }

Sequence Diagrams

The following diagram illustrates the flow when an utterance asks Alexa to set fan speed to 3. Set Fan Speed

The following diagram illustrates the flow after the set value is finished at the hardware layer. Set Reply

How the Alexa Auto Car Control Library Works

When the user issues an utterance, the Engine receives a car control event from Alexa, which the Engine passes to the Alexa Auto App through an AASB message.

The AASB message received by the Alexa Auto App has the following attributes:

  • Action is com.amazon.aacs.aasb.AdjustControllerValue or com.amazon.aacs.aasb.SetControllerValue.
  • Category is com.amazon.aacs.aasb.CarControl.

  • Extras is payload.

    The payload object includes detailed information about the action, which is specified in the messageDescription field of the AASB message. The following list describes the payload for each action:

    • For SetControllerValue, the payload has the following schema: 
      "payload" : {
    "controllerType" : "POWER",
    "endpointId" : "{{String}}",
    "turnOn" : {{Boolean}}
}
    • For AdjustControllerValue, the payload has the following schema: 
      "payload" : {
    "controllerType" : "TOGGLE",
    "endpointId" : "{{String}}",
    "controllerId" : "{{String}}",
    "turnOn" : {{Boolean}}
}
    • For SetModeController, the payload has the following schema: 
      "payload" : {
    "controllerType" : "MODE",
    "endpointId" : "{{String}}",
    "controllerId" : "{{String}}",
    "value" : "{{String}}"
}
    • For SetRangeController, the payload has the following schema: 
      "payload" : {
    "controllerType" : "RANGE",
    "endpointId" : "{{String}}",
    "controllerId" : "{{String}}",
    "value" : {{Double}}
}
    • For AdjustModeController, the payload has the following schema: 
      "payload" : {
    "controllerType" : "MODE",
    "endpointId" : "{{String}}",
    "controllerId" : "{{String}}",
    "delta" : {{Integer}}
}
    • For AdjustRangeController, the payload has the following schema: 
      "payload" : {
    "controllerType" : "RANGE",
    "endpointId" : "{{String}}",
    "controllerId" : "{{String}}",
    "delta" : {{Double}}
}

After receiving the intent, the AACS Car Control Broadcast Receiver parses the payload and calls for the Car Control Handler to perform specific car control operations.

Back to top