Skip to content
3.3
Switch branches/tags
Code

Latest commit

The Alexa Auto SDK is for automotive OEMs to integrate Alexa directly into vehicles.

**v3.3.0**

* v3.3.0 released on 2021-09-30

**Enhancements**
* Added the `DeviceUsage` platform interface to provide the Alexa application network usage data to the Auto SDK Engine. The Auto SDK Engine emits this data as a metric to Amazon if Auto SDK is built with the `Device Client Metrics` extension. For more information, see the Core module README for [C++](./modules/core/README.md#providing-network-usage-data-to-auto-sdk) or [Android](./platforms/android/modules/core/README.md#providing-network-usage-data-to-auto-sdk).

* Extended the features of the `Local Navigation` module for the `Local Voice Control (LVC)` extension. The `LocalSearchProvider` platform interface now enables you to provide customers with offline navigation to street addresses, cities, and neighborhoods in addition to the existing support for local search and navigation to points of interest. See the Local Navigation module README for information about integrating the features.
  >**Note:** There are updates to the `LocalSearchProvider` APIs. See the [Migration Guide](./MIGRATION.md) for details.

* Added a new generic `DEFAULT` media source to the list of sources supported by the `LocalMediaSource` platform interface. The DEFAULT source can be used for voice playback control of any arbitrary media sources on the infotainment system outside of deep-linked MACC applications using the `ExternalMediaAdapter` interface and existing sources supported by name through the `LocalMediaSource` interface. For details about integrating a default media source, see the Alexa module README for [C++](./modules/alexa/README.md) or [Android](./platforms/android/modules/alexa/README.md).

* Added offline LVC support for tuning to station names on terrestrial radio and SiriusXM. E.g., “Play CNN on Sirius XM” and “Play KISS FM”. This feature is already available in online mode.

* Enhancements for AACS:

    * Added an app component called `alexa-auto-carcontrol` that deeply integrates Auto SDK car control features into the Android Automotive OS. For more information about AACS deep integration to Car Control, please refer to this [README](./platforms/android/app-components/alexa-auto-carcontrol/README.md).

    * Added an enhancement in which AACS can automatically sync Alexa’s timezone and locale properties with the device system settings when you set the `syncSystemPropertyChange` field to true in your AACS configuration file. If you set the field to false or omit it, you still have flexibility to change the properties in your own implementation.

* Enhancements for AACS Sample App:

    * Added a location sharing consent screen in Alexa setup and settings wherein the user has the option to enable or disable location sharing.

    * Added support for rendering for `TemplateRuntime` display cards for the weather domain.

    * Added support for rendering `Amazon Presentation Language (APL)` documents.

    * Added media player transport control improvements. For example, shuffle and loop transport controls are added, and disabled transport controls are displayed.

    * Added support for setup and setting menu specific to the Alexa Custom Assistant extension.

**Resolved Issues**
* Android 11 requires the attribute `android:foregroundServiceType` to be defined in services that require permissions such as microphone and location. This is added to the AACS Android Manifest file. Also, the `compileSdkVersion` and `targetSdkVersion` to are updated to 30 in `build.gradle`.

* Added a `UserIdentity` value in AACS `AuthStatus` when the user finishes CBL login.

* Made the 'stateOrRegion' field optional in the AACS `StartNavigation` directive JSON parser.

* Implemented the AASB `SetUserProfile` message in the CBL module to ensure the user email and username will be sent to the client application after user login when `enableUserProfile` is set to true.

* Fixed an issue that blocked a valid transition from the `THINKING` to `LISTENING` `AlexaClient` dialog states.

* Updated the `PhoneCallControllerCapabilityAgent` to include context in `PhoneCallController` events per the `PhoneCallController` API specification.

* Fixed a memory leak observed during Engine shutdown in the `Local Voice Control` extension.

* Fixed a rare deadlock issue during Engine stop and start when using the `AuthProvider` interface.

* Fixed an issue in which the Engine erroneously allowed 3,000 coordinates in the "shapes" array of navigation state queried via `Navigation::getNavigationState()`. The limit is updated to 100 coordinates.

**Known Issues**
* General
    * If the "locales" field of the "deviceSettings" node of the Alexa module configuration JSON is not specified, the Engine automatically declares support for the following locale combinations:
        ["en-US", "es-US"],
        ["es-US", "en-US"],
        ["en-IN", "hi-IN"],
        ["hi-IN", "en-IN"],
        ["fr-CA", "en-CA"],
        ["en-CA", "fr-CA"].

      The Engine does not declare support for locale combinations if the "locales" field is assigned an empty value.

    * The `wakewordEnabled` property is not persistent across device reboots. If you use AACS, however, this issue does not occur.

    * For Linux platforms, if your hardware does not use AVX2 instructions, the wake word library initialization causes an illegal instruction error.

    * When using LVC and calling Engine::stop(), the AlexaClient connection status remains CONNECTED because the connection to LVC is not disabled. Your implementation should not accept user utterances while the Engine is stopped despite the connection status showing CONNECTED.

    * The [automotive HMI guidelines](https://developer.amazon.com/en-US/docs/alexa/alexa-auto/display-cards.html#dismiss-display-cards) for display cards state that actionable display cards should be dismissed automatically after 30 seconds, and non-actionable display cards should be dismissed automatically after 8 seconds. This guideline is not descriptive enough since it does not clarify what is actionable and non-actionable content. The UX team is working on correcting the guideline to specify specific template types. The current automatic dismissal time for all Template Runtime display cards is 8 seconds.

* Car Control
    * If you configure the Auto SDK Engine and connect to Alexa using a set of endpoint configurations, you cannot delete any endpoint in a set in the cloud. For example, after you configure set A with endpoints 1, 2, and 3, if you change your car control configuration during development to set B with endpoints 2, 3, and 4, endpoint 1 from set A remains in the cloud and might interfere with resolving the correct endpoint ID for your utterances. However, any endpoint configurations with matching IDs override previous configurations. For example, the configuration of endpoint 2 in set B replaces endpoint 2 in set A. During development, limit configuration changes to create only supersets of previous endpoint configurations. Work with your Solutions Architect or Partner Manager to produce the correct configuration on the first try.

* Communications

    * DTMF utterances that include the letters "A", "B", "C", or "D" (for example "press A" or "dial 3*#B") are ignored.

    * Calling numbers such as 1-800-xxx-xxxx by using utterances such as “Alexa call one eight double oh...” may return unexpected results. Similarly, when you call numbers by using utterances that include "triple," "hundred," and "thousand," or press special characters such as # or * by saying "Alexa press *#", you may experience unexpected results. We recommend that your client application ignore special characters, dots, and non-numeric characters when requesting Alexa to call or press digits.

    * A user playing any skill with extended multi-turn dialogs (such as Jeopardy or Skyrim) cannot use voice to accept or reject incoming Alexa-to-Alexa calls.

* Entertainment
    * A user playing notifications while music is playing hears the music for a split second between the end of one notification and the start of the next.

    * The word, "line-in," in an utterance is sometimes misinterpreted as "line" or other words. For example, if the user says, "Switch to line-in," the misinterpretation of "line-in" might cause an incorrect response.

    * When an external player authorization is in progress at the exact moment of shutdown, a very rare race condition might occur, causing the Engine to crash.

    * If your application displays the NowPlaying `TemplateRuntime` display card when Alexa plays media, the card might be erroneously dismissed by the Auto SDK Engine with a call to `TemplateRuntime::clearPlayerInfo()` if your application calls `AlexaClient::stopForegroundActivity()` to cancel an Alexa interaction. For example, the user might initiate an Alexa interaction during music playback and then cancel it by pressing a cancel button while Alexa is listening, thinking, or speaking. The media display card should not be dismissed in this scenario.

    * The generic `DEFAULT` `LocalMediaSource` type is not supported offline with LVC. If user gives a generic playback control request like "Alexa, play" when the Alexa application is operating in the offline mode with LVC, Alexa responds "Sorry, something went wrong". Other named players like USB work as expected in the offline mode.

* Authentication
    * The CBL module uses a backoff when refreshing the access token after expiry. If the internet is disconnected when the refresh is attempted, it could take up to a minute to refresh the token when the internet connection is restored.

* Local Search and Navigation
    * When using LVC in offline mode, after requesting a list of POIs (e.g., "find Starbucks nearby"), Alexa does not recognize utterances like "select the first one" and does not display or read detailed information about the requested selection.

* AACS

    * For some platform interface APIs in the Core module, when an application fails to handle a directive, there is no way to report the failure to the Engine. This is because AASB assumes that the application always handles messages correctly. When AASB incorrectly reports how the application handles the message, the Engine state might become inconsistent with the application state. For example, suppose the Engine sends a directive to the application to set the audio volume but the application fails to make the change. AASB does not report the failure to the Engine. As a result, the Engine's and the application's settings become out of sync. The following list shows the affected APIs:
        * `AudioInput`:
            * `startAudioInput()`
        * `AudioOutput`:
            * `setPosition(int64_t position)`
            * `volumeChanged(float volume)`
            * `mutedStateChanged(MutedState state)`

    * If you are not using the default audio output implementation (i.e. your application handles `AudioOutput` AASB messages) and even though you are playing the Alexa pushed media content, `Stop` message would not be sent from AACS when AACS shuts down. e.g. If you are playing an audio stream for AmazonMusic, if AACS is stopped, [AASB `AudioOutput.Stop` message](extensions/aasb/docs/AudioOutput/StopMessage.html) would not be received. As a result, the media playing from your application would not be stopped. This issue will be fixed in the next release. As a workaround, your application can listen to `[AASB.StopService](`extensions/aasb/docs/AASB/StopServiceMessage.html`)` message or adopt `AACSPinger` (See [README](platforms/android/alexa-auto-client-service/README.md#checking-aacs-connection-state)) to listen to the `STOPPED` state of AACS and stop the media accordingly.

[Read the SDK Docs](https://alexa.github.io/alexa-auto-sdk/)
2607c7b

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Overview of the Alexa Auto SDK

The Alexa Auto SDK contains essential client-side software required to integrate Alexa into the automobile. The Auto SDK provides libraries that connect to Alexa and expose C++ and Java interfaces for your vehicle software to implement the platform-specific behavior for audio input, media streaming, calling through a connected phone, turn-by-turn navigation, controlling vehicle features such as heaters and lights, and more. You can use the included sample applications, one for C++ and one for Android, to learn about the Auto SDK interfaces and to test interactions before integration.

Table of Contents

Auto SDK Architecture

The following architecture diagram illustrates a common design used for integrating the Auto SDK into the vehicle software.

The following sections describe the relationships among components in the architecture.

Auto SDK Engine

The Engine is a system of components that provide the runtime implementation of the Auto SDK. The main program of your application or background service creates an instance of the Engine and configures the instance, registers platform interface handlers, and manages its lifecycle. When started by the main program, the Engine maintains a connection to Alexa, manages runtime execution states, and provides the underlying implementation of the functionality of the platform interfaces.

Platform Interfaces

Platform interfaces are abstract interfaces provided by the Auto SDK for you to implement the platform-specific functionality of the Auto SDK integration. “Platform-specific functionality” refers to components of the integration that interact with the hardware, operating system, underlying software frameworks, or external libraries. Each platform interface defines an API for the application to interact with the Engine for a particular component, such as audio input or location services. The Engine invokes a registered platform interface “handler” when it needs to query data or delegate handling, such as rendering visual elements or placing a phone call, to your custom implementation. The handler invokes the Engine to provide a callback to a request from the Engine or provide a proactive notification of a state change.

Handlers

Bridging the Engine and other processes running in the head unit, a handler implements the functionality required by the platform interface it extends. The implementation of a handler may include using an event bus, platform-specific inter-process communication (IPC) mechanisms, direct implementations with system libraries, or deep integrations with existing applications.

Auto SDK Modules and Extensions

The Auto SDK is organized into logically related groups of functionality called “modules,” which enable you to select only the features you want to include in your integration. Each module includes “Platform” and “Engine” libraries. The Platform library includes the platform interfaces and configuration options required for a feature, and the Engine library augments the base functionality of the Engine with the underlying implementation of the feature.

Note: The libraries of each module are written in C++, but building the Auto SDK for an Android target enables an Android version of the modules that provide Java wrappers on the C++ interfaces for easier use.

The following sections describe the modules included in the Auto SDK. Modules not downloadable with the Auto SDK from GitHub are available as extensions, which you can obtain with help from your Amazon Solutions Architect (SA) or Partner Manager.

Core Module

The Core module (for C++ or Android) provides the infrastructure for audio input and output, authorization, logging, location reporting, metrics, property management, network monitoring services, local storage, and vehicle information services. The infrastructure is necessary for any module that provides platform interfaces (for example, the Alexa module).

Alexa Module

The Alexa module (for C++ or Android) supports Alexa features such as speech input and output, authorization, volume control, media playback, equalizer control, template and state rendering, local media sources, alerts, notifications, and do not disturb.

Navigation Module

The Navigation module (for C++ or Android) provides support for Alexa to interface with the onboard navigation system.

Phone Call Controller Module

The Phone Call Controller module (for C++ or Android) provides support for Alexa to interface with the onboard telephony system.

Address Book Module

The Address Book module (for C++ or Android) augments the communications and navigation capabilities of Alexa with user data such as phone contacts and navigation favorites ("home", "work", etc.).

Code-Based Linking (CBL) Module

The CBL module (for C++ or Android) implements the CBL mechanism of acquiring Login with Amazon (LWA) access tokens. For information about the CBL mechanism, see the Code-Based Linking documentation.

Alexa Presentation Language (APL) Module

The APL module (for C++ or Android) enables devices to support a visual Alexa experience.

Note: The APL Render module is provided to enable APL rendering capabilities in an Android application.

Messaging Module

The Messaging module (for C++ or Android) provides support for Short Message Service (SMS) capabilities of Alexa such as sending and reading text messages.

Car Control Module

The Car Control module (for C++ or Android) enables your application to build a custom vehicle-control experience that allows the user to voice-control vehicle features using Alexa.

Connectivity Module

The Connectivity module (for C++ or Android) creates a lower data consumption mode for Alexa, allowing automakers to offer tiered functionality based on the status of their connectivity plans.

Text To Speech (TTS) Module

The TTS module (for C++ or Android) enables a platform implementation to request synthesis of Alexa speech on demand from a text or Speech Synthesis Markup Language (SSML) string.

Text To Speech (TTS) Provider Module

The TTS provider module (for C++ or Android) synthesizes Alexa speech on demand. This module requires Auto SDK to be built with the Local Voice Control extension.

AmazonLite Wake Word Extension

Wake Word enables hands-free, voice-initiated interactions with Alexa. The Wake Word extension enables AmazonLite Wake Word support in the Auto SDK.

Alexa Communications Extension

The Alexa Communications extension enables integration with Alexa-to-Alexa calling, Alexa-to-PSTN calling, and messaging capabilities.

Alexa Custom Assistant Extension

The Alexa Custom Assistant extension provides the functionality for toggling the settings of Alexa and the automaker's voice assistant, and notifies the IVI system at runtime about updates to the acting assistant for a specific interaction.

Bluetooth Extension

The Bluetooth extension allows the Auto SDK to connect to devices through the Bluetooth Classic or Bluetooth Low Energy (BLE) protocol. Using these protocols, the Auto SDK can offer Bluetooth-based features to users of Android or iOS smartphones.

Device Client Metrics (DCM) Extension

The Device Client Metrics (DCM) extension enables logging and uploading Auto SDK metrics to the Amazon cloud. Voice request metrics, for example, include start and end timestamps of user and Alexa speech and user perceived latency (UPL) between the request and Alexa’s response.

Geolocation Extension

The Geolocation extension adds geolocation consent support to the Auto SDK, enabling the user to grant consent to location sharing with Alexa from your application.

Local Voice Control (LVC) Extension

The LVC extension provides car control, communication, navigation, local search, and entertainment functionality, without an internet connection. It includes components that run an Alexa endpoint inside the vehicle's head unit.

Local Voice Control Module

The Local Voice Control module adds core functionality to Auto SDK to enable offline features. The module infrastructure bridges the Auto SDK Engine to the offline Alexa endpoint running in the head unit and is necessary for all other modules in the LVC extension.

Local Skill Service Module

The Local Skill Service module provides a multipurpose service to the Auto SDK Engine that enables components running alongside the offline Alexa endpoint to communicate with the Auto SDK Engine. The module infrastructure is necessary for other modules in the LVC extension.

Local Navigation Module

The Local Navigation module enables you to provide customers with offline Alexa local search and navigation to points of interest (i.e., categories, chains, and entities) and addresses.

Address Book Local Service Module

The Address Book Local Service module works with the Address Book module and the Local Skill Service module to augment the offline communications and navigation capabilities of Alexa with user data such as phone contacts and navigation favorites.

Car Control Local Service Module

The Car Control Local Service module works with the Car Control module and the Local Skill Service module to enable users to control vehicle features offline with Alexa.

Mobile Authorization Extension

The Mobile Authorization extension enables applications running on the vehicle's head unit to simplify the login experience. To log in to Alexa, the user uses the Alexa mobile app on a paired smartphone instead of opening a web browser and entering a code.

Voice Chrome for Android Extension

The Voice Chrome extension adds Voice Chrome support to the Auto SDK for Android x86 64-bit and Android ARM 32/64-bit platforms. Voice Chrome provides a consistent set of visual cues representing Alexa attention state across a range of Alexa-enabled devices. The Voice Chrome extension includes a prebuilt Android AAR library for easy integration with your applications, as well as a patch to the Android Sample App that adds the Voice Chrome functionality.

Alexa Auto Client Service (AACS)

AACS simplifies the process of integrating the Auto SDK in Android-based devices. After you install, configure, and initialize AACS, it communicates with the applications, providing an interface between the applications and various Alexa functions, such as navigation and car control. You can also include AACS as an Android archive (AAR) in the application if you don't want to run AACS as a separate app. For more information about AACS, see the AACS README.

AACS requires the Alexa Auto Service Bridge (AASB) extension, which provides a message-based interface to the Auto SDK Engine. For more information about AASB, see the AASB README.

Security Best Practices

All Alexa products are required to follow the Security Best Practices for Alexa. When building an Alexa experience using the Auto SDK, additionally adhere to the following security principles:

  • Protect configuration files for the Auto SDK Engine from tampering and inspection.
  • Protect configuration parameters, such as those found in Auto SDK Engine configuration files, from tampering and inspection, including but not limited to the following: SQLite database files, Unix Domain Sockets, wake word models, and metrics sink files.
  • Protect components used for the Local Voice Control (LVC) extension, including associated LVC language model packages (Linux) and APKs (Android), from tampering and inspection, including but not limited to the following: Unix Domain Sockets, model directories, skill and service executables, prompts and assets JSON files, and all files configuring these components.
  • Your C++ implementation of Auto SDK interfaces must not retain locks, crash, hang, or throw exceptions.
  • Use exploit mitigation flags and memory randomization techniques when you compile your source code to prevent vulnerabilities from exploiting buffer overflows and memory corruptions.

See Also

The following documents or websites provide more information about the Auto SDK.