Skip to content

Commit

Permalink
Version 3.0.0 Alexa Auto SDK
Browse files Browse the repository at this point in the history 
The Alexa Auto SDK is for automotive OEMs to integrate Alexa directly into vehicles.

**v3.0.0**

* v3.0.0 released on 2020-10-09

**Enhancements**

* Added Alexa Auto Client Service (AACS), which enables OEMs of Android-based devices to simplify the process of integrating the Auto SDK. For more information about AACS, see the AACS.

* Added support for removing local media sources at runtime, such as a USB drive or a Bluetooth device. Previously, if a user removed a USB drive and then requested to play music from the USB drive, the Auto SDK would attempt to play and not return an appropriate error message. This feature is enabled with an existing field in the `LocalMediaSource` platform interface state. For information about the platform interface state, see the `alexa` module.

**Resolved Issues**

* On QNX, when a portion of music on Spotify is skipped, either by the user saying, "Skip forward," or by the user skipping to a different song, the volume is no longer reset to the default level.
* A user barging in when music is playing no longer hears an Alexa response to the barge-in request. Previously, this issue happened if the System Audio extension was used.

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

* Car Control
    * For car control, there is a limit of two Device Serial Numbers (DSN) per account or Customer ID (CID). Limit the number of devices for testing with a single account accordingly. If you use the Android sample app, be sure to configure a specific DSN.
    * It can take up to 20 seconds from the time of user login to the time Alexa is available to accept utterances. The cloud uses this time to ingest the car control endpoint configurations sent by Auto SDK after login.
    * 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.
    * Car control utterances that are variations of supported utterances but do not follow the supported utterance patterns return errors. Examples include “please turn on the light in the car” instead of the supported “turn on the light“, and ”put on the defroster“ or “defrost the windshield” instead of the supported ”turn on the defroster”.
    * The air conditioner endpoint supports only Power Controller and Mode Controller capabilities, not Range Controller for numeric settings.

* Communications
    * A user request to send an SMS to an Alexa contact results in an Alexa-to-Alexa message instead. However ‘send message’ instead ‘send SMS’ to a contact works.
    * When using LVC in online mode, users can redial a call when the phone connection state is OFF.
    * 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.

* 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.
    * If you log out and log in, the client-side Do Not Disturb (DND) state may not be synchronized with the Alexa cloud.

* 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)`

     * In the commonutils library, the JSON parser (`RenderPlayerInfo.kt`) for the `renderPlayerInfo` message of `templateRuntime` can only parse the `payload` field of the AASB `RenderPlayerInfo` message payload. The `payload` field of `RenderPlayerInfo` is the inner payload of the nested payload structure. When using `TemplateRuntime.parseRenderInfo(String json)`, provide it with the embedded JSON as a string of the string value whose key is `payload` in the `RenderPlayerInfo` message’s payload instead of the overall AASB payload.

**Additional Changes**
Starting with Auto SDK v3.0, we no longer support the Automotive Grade Linux (AGL) Alexa Voice agent in the Auto SDK. If you intend to use the AGL Alexa Voice Agent, continue using Auto SDK v2.3.0, which is the last version that provides AGL support.

[Read the SDK Docs](https://alexa.github.io/alexa-auto-sdk/)
  • Loading branch information
@MuniSakkuru
MuniSakkuru authored and Muni Sakkuru committed Oct 9, 2020
1 parent d46f22b commit 241f245
Show file tree
Hide file tree
Showing 1,528 changed files with 281,002 additions and 46,538 deletions.
65 changes: 63 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,66 @@
# Change Log
___
## v3.0.0 released on 2020-10-09

### Enhancements
* Added Alexa Auto Client Service (AACS), which enables OEMs of Android-based devices to simplify the process of integrating the Auto SDK. For more information about AACS, see the AACS [README](./platforms/android/alexa-auto-client-service/README.md).

* Added support for removing local media sources at runtime, such as a USB drive or a Bluetooth device. Previously, if a user removed a USB drive and then requested to play music from the USB drive, the Auto SDK would attempt to play and not return an appropriate error message. This feature is enabled with an existing field in the `LocalMediaSource` platform interface state. For information about the platform interface state, see the `alexa` module [README](./modules/alexa/README.md).

### Resolved Issues
* On QNX, when a portion of music on Spotify is skipped, either by the user saying, "Skip forward," or by the user skipping to a different song, the volume is no longer reset to the default level.
* A user barging in when music is playing no longer hears an Alexa response to the barge-in request. Previously, this issue happened if the System Audio extension was used.

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

* Car Control
* For car control, there is a limit of two Device Serial Numbers (DSN) per account or Customer ID (CID). Limit the number of devices for testing with a single account accordingly. If you use the Android sample app, be sure to configure a specific DSN.
* It can take up to 20 seconds from the time of user login to the time Alexa is available to accept utterances. The cloud uses this time to ingest the car control endpoint configurations sent by Auto SDK after login.
* 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.
* Car control utterances that are variations of supported utterances but do not follow the supported utterance patterns return errors. Examples include “please turn on the light in the car” instead of the supported “turn on the light“, and ”put on the defroster“ or “defrost the windshield” instead of the supported ”turn on the defroster”.
* The air conditioner endpoint supports only Power Controller and Mode Controller capabilities, not Range Controller for numeric settings.

* Communications
* A user request to send an SMS to an Alexa contact results in an Alexa-to-Alexa message instead. However ‘send message’ instead ‘send SMS’ to a contact works.
* When using LVC in online mode, users can redial a call when the phone connection state is OFF.
* 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.

* 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.
* If you log out and log in, the client-side Do Not Disturb (DND) state may not be synchronized with the Alexa cloud.

* 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)`

* In the commonutils library, the JSON parser (`RenderPlayerInfo.kt`) for the `renderPlayerInfo` message of `templateRuntime` can only parse the `payload` field of the AASB `RenderPlayerInfo` message payload. The `payload` field of `RenderPlayerInfo` is the inner payload of the nested payload structure. When using `TemplateRuntime.parseRenderInfo(String json)`, provide it with the embedded JSON as a string of the string value whose key is `payload` in the `RenderPlayerInfo` message’s payload instead of the overall AASB payload.

### Additional Changes
Starting with Auto SDK v3.0, we no longer support the Automotive Grade Linux (AGL) Alexa Voice agent in the Auto SDK. If you intend to use the AGL Alexa Voice Agent, continue using Auto SDK v2.3.0, which is the last version that provides AGL support.

## v2.3.0 released on 2020-07-31

### Enhancements
Expand Down Expand Up @@ -101,7 +162,7 @@ ___
* Fixed an External Media Player (EMP) Engine implementation that caused an unexpected sequence of Local Media Source playControl() method invocations such as play, then pause, followed by play again in quick succession.
* Fixed an issue where the Engine might hang during shutdown if it was shut down while TTS was being played or read.
* Fixed an issue where Auto SDK initialization failed at startup when applications using the optional LVC extension didn't register a NetworkInfoProvider platform interface.
* Fixed an issue where building the Auto SDK with senstive logging enabled was not working as expected.
* Fixed an issue where building the Auto SDK with sensitive logging enabled was not working as expected.
* Added alerts error enums (`DELETED` and `SCHEDULED_FOR_LATER`) to the [`Alerts.h`](./modules/alexa/platform/include/AACE/Alexa/Alerts.h) and [`Alerts.java`](./platforms/android/modules/alexa/src/main/java/com/amazon/aace/alexa/Alerts.java) files.
* With the exception of road regulation and maneuver events, the Alexa cloud no longer returns an `INVALID_REQUEST_EXCEPTION` or `INTERNAL_SERVICE_EXCEPTION` in response to navigation events sent by the Auto SDK.
* Alexa now prompts or notifies the clients and rejects the ping packet when the user deregisters from the companion app.
Expand All @@ -110,7 +171,7 @@ ___
* General
* If the local timezone of your device differs from the timezone that was configured through the Alexa companion app, the user may experience unexpected behavior. For example, if your device shows 12pm PST, but the device on the Alexa companion app is configured with an EST timezone, then asking "Alexa set an alarm for 1pm today," will return, "Sorry I can't set alarms in the past". Auto SDK v2.2.0 adds support for setting the timezone of the vehicle, which allows your device to synchronize with the timezone set in the Alexa companion app; however, the Auto SDK currently does not receive a `SetTimeZone` directive when the timezone is changed from the companion app.
* Navigation
* The Alexa cloud currently returns an `INTERNAL_SERVICE_EXCEPTION` in response to any navigation road regulation or manuever event sent by the Auto SDK (triggered by an utterance such as "which lane should I take", for example). You may see a harmless error/exception in the logs.
* The Alexa cloud currently returns an `INTERNAL_SERVICE_EXCEPTION` in response to any navigation road regulation or maneuver event sent by the Auto SDK (triggered by an utterance such as "which lane should I take", for example). You may see a harmless error/exception in the logs.
* Car Control
* Certain car control utterances return errors. Problematic utterances include natural versions of certain test utterances (for example, “turn on the light“ instead of “please turn on the light in the car”); utterances that include the words “lights” or “my”; and utterances to control the defroster or defogger that use “put on” or “set on” rather than “turn on” or “switch on”.
* Setting the air conditioner using range controller control capabilities (for example “set the air conditioner to 65” or “set the air conditioner to low”) is not currently supported.
Expand Down
1 change: 0 additions & 1 deletion CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ else()
add_subdirectory(modules/apl)
add_subdirectory(modules/car-control)
add_subdirectory(modules/cbl)
add_subdirectory(modules/contact-uploader)
add_subdirectory(modules/core)
add_subdirectory(modules/messaging)
add_subdirectory(modules/navigation)
Expand Down
50 changes: 50 additions & 0 deletions GETSTARTED.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Getting Started with the Alexa Auto SDK
This document assumes that you have read the [README](./README.md) to understand the basic Auto SDK concepts. Complete the steps in this document to get started with the Auto SDK and to follow security best practices.

<!-- omit in toc -->
## Table of Contents
- [Before You Start](#before-you-start)
- [Getting Started](#getting-started)
- [Downloading Optional Extensions](#downloading-optional-extensions)

## Before You Start
Complete the following steps before you get started with the Auto SDK:

1. Register for an [Amazon Developer Account](https://developer.amazon.com/home.html) and [create an Alexa device and security profile](./NEED_HELP.md#registering-a-product-and-creating-a-security-profile) to use the Auto SDK.
2. Make sure that you meet the requirements for building the Auto SDK and understand the dependencies, as described in the SDK builder [README](./builder/README.md).

## Getting Started
Follow these steps to get started with the Auto SDK:

1. Clone the `alexa-auto-sdk` repository into your project.
2. If you want to use the optional Auto SDK modules, download the modules from the locations listed in [Downloading Optional Extensions](#downloading-optional-extensions).

3. Build the Auto SDK as described in the builder [README](./builder/README.md).
>**Note:** If your target platform is Android and you want to implement any optional modules (such as wake word support and Alexa Communications), you must use the Android Archive (AAR) files generated by the Auto SDK Builder. Do not use the prebuilt platform .AARs and sample-core AAR available in JCenter; they are for the default Auto SDK modules only.
4. Install the built package on your device as described in the builder [README](./builder/README.md).

5. Create and configure an instance of the Engine. For details, see the [C++](./modules/core/README.md#creating-the-engine) or [Android](./platforms/android/modules/core/README.md#creating-the-engine) Core module documentation.

6. Extend the Auto SDK interfaces by creating a custom handler for each interface that you want to implement and registering the handler with the Engine.

7. Start the Engine using the `start()` command.

8. Use the Sample App ([C++](./samples/cpp/README.md) or [Android](./samples/android/README.md)) to see how the Auto SDK works and to test end-to-end functionality.

## Downloading Optional Extensions

**NOTE**: The version of the optional extension archive must match the version of the Auto SDK that you are using. For example, if you are using Auto SDK 3.0 and want to install the Local Voice Control extension, you must download version 3.0 of the Local Voice Control extension archive.

Click the link in the following list to go to the directory where the extension archive is located:

* [AmazonLite Wake Word extension](https://developer.amazon.com/alexa/console/avs/preview/resources/details/Auto%20SDK%20Amazonlite%20Extension)

* [Alexa Communications extension](https://developer.amazon.com/alexa/console/avs/preview/resources/details/Auto%20SDK%20Alexa%20Comms%20Extension)

* [Local Voice Control extension](https://developer.amazon.com/alexa/console/avs/preview/resources/details/Auto%20SDK%20Local%20Voice%20Control%20Extension)

* [Device Client Metrics (DCM) extension](https://developer.amazon.com/alexa/console/avs/preview/resources/details/Auto%20SDK%20Metric%20Upload%20Service%20Extension)

* [Voice Chrome for Android extension](https://developer.amazon.com/alexa/console/avs/preview/resources/details/Auto%20SDK%20Voice%20Chrome%20Extension)

Loading

0 comments on commit 241f245

Please sign in to comment.