Set up the AVS Device SDK on Android

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on Android. This process includes installing, building, authorizing, and using the SDK. When finished, you have a working sample app to test interactions with Alexa.

Prerequisites

You must meet these Prerequisites to use the SDK on Android.

Storage

You should install the Android sample app onto the internal storage of your Android device or emulator. Installing onto external storage might result in installation failures, depending on the storage format. For example, the sample app won't work on FAT32.

Supported platforms

You can use any of these Android platforms to test and debug your build:

Device Type Minimum Requirements
Android Emulator 500 MB minimum of available disk space.
Android Device, such as a phone 500 MB minimum of available disk space.
Android Things-supported Hardware See requirements here

Get started

To Install Android Tools

  1. Install Android tools by either downloading Android Studio (which includes the tools by default) or with the command line.
  2. After you've installed Android tools, you must install the Android platform tools using the Android SDK manager, which is part of the Android tools package. During this process, you must specify the CPU type and Android version number.

     # install cmake, ndk-bundle, and android abi sdkmanager "ndk-bundle"
     sdkmanager "cmake;3.6.4111459"
     sdkmanager "system-images;android-23;google_apis;armeabi-v7a"
     sdkmanager "platform-tools"
    
  1. After the tools install, set your PATH environment variable to include the Android tools. For example, if you've installed the Android tools on your home directory ~/Android/sdk, run this command:

     export PATH=$PATH:~/Android/sdk/platform-tools:~/Android/sdk/tools:~/Android/sdk/tools/bin
    
  1. After the tools install, install the following packages: autoconf, automake, libtool, pkg-config. To install these packages, run the following commands.

    MacOS

     brew install autoconf automake libtool pkg-config
    

    Linux

     sudo apt-get update
     sudo apt-get install autoconf automake libtool pkg-config
    
  1. Install the SDK on your device. Connect your target device to the Android Debug Bridge (ADB).For Android devices and Android Things-enabled hardware, you must enable USB debugging and connect your device to the ADB before you run the startsample.sh build script. The Android Emulator connects to ADB by default. No configuration is required.

To connect your device to the ADB

  1. Physically connect your device to your Mac or Linux machine with a USB cable.
  2. Enable USB debugging for your device.
  3. Connect your device to the ADB:

     adb root adb connect <device_ip>
    
  1. Download installation script and configuration file.

    You can specify any directory you prefer to run the scripts and download these files to. The following commands download all the necessary files:

     wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/androidConfig.txt
     wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/setup.sh
     wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/genConfig.sh
     wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/android.sh
    

Authorization

Before you can use the SDK sample app, you must authorize it with the AVS to leverage the full range of Alexa capabilities and features available to the sample app.

Prerequisites

You must register an AVS Product and Create a Security Profile, if you haven't already.

  1. Navigate to the directory where you downloaded the set up android.sh script.
  2. Update androidConfig.txt with the variables in the following table.

    Parameter Value
    PLATFORM Set the variable to "android".
    API_LEVEL The Android API level. See the Android build page to identify the target level. The API level depends on the device or emulator configuration.

    Supported version: API 23+ or greater is supported.
    TARGET_SYSTEM Choose this value according to the CPU architecture of your target device. For example, choose arm for the Raspberry Pi.

    Accepted values: arm and x86.
    DEVICE_INSTALL_PATH The path on the device where the script should install the sample app and dependencies.

    Note: Make sure this path exists on the device, and that you have write permissions.
    BUILD_TYPE The type of build used.

    Accepted values: debug, release, MinSizeRel, and RelWithDebInfo.
  3. Run android.sh, using config.json, androidConfix.txt, and the device serial number (DSN) as arguments. You can either provide your own DSN, or use the system default (123456). The DSN can be any unique alpha-numeric string (up to 64 characters). You should use this string to identify your product or app instance. Many developers choose to use a product's SKU for this value. If you don't supply a DSN, the default value 123456 are generated by the SDK.

Example

  bash setup.sh config.json -a androidConfig.txt -s 998987

Finish authorization using Login with Amazon

  1. Initialize the sample app using the startsample.sh script that you previously generated when you ran the setup.sh script. Type bash startsample.sh to run the sample app. This script is a batch file and not a bash script, you can run the script either from the command line, or by locating the file and then double-clicking it.

  2. Wait for the sample app to display a message like this:

     ##################################
     #       NOT YET AUTHORIZED       #
     ##################################
     ################################################################################################
     #       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
     ################################################################################################
    
  3. Use a browser to navigate to the URL specified in the message from the sample app.
  4. If requested to do so, authenticate using your Amazon user credentials.
  5. Enter the code specified in the message from sample app.
  6. Select “Allow”.
  7. Wait for the sample app to report that it's authorized, and that Alexa is idle. It looks something like this:

     ###########################
     #       Authorized!       #
     ###########################
     ########################################
     #       Alexa is currently idle!       #
     ########################################
    
  8. You are now ready to use the sample app. The next time you start the sample app, you don't have to reauthorize it.

Note: if you exit out of sample app with the k command, the CBLAuthDelegate database clears and you must reauthorize your client.

Use the sample app

Now that you have a working sample app, try an interaction with Alexa. If you have quit the sample app, start it again with: bash startsample.sh.

Interact with Alexa using tap-to-talk

Press T+Enter, and ask Alexa something.

For example:

User taps-to-talk (T+Enter): "Alexa, what's the weather like?"

Alexa: "Right now in Portland, it's 71 degrees with sun…"

Additional options

Interaction options

Action Command
Tap to talk t+Enter, followed by your query (no need to say "Alexa…").
Hold to talk h+Enter, followed by your query (no need to say "Alexa…").
Simulate button release h+Enter
Stop an interaction s+Enter

Playback controls

Action Command
Play 1
Pause 2
Next 3
Previous 4

Settings

Action Command
View available settings c+Enter
Adjust speaker settings p+Enter
Report firmware version f+Enter
Help screen i+Enter
Reset device k+Enter; this erases any data stored on the device, and you have to re-register it. This also exits the app.
Quit q+Enter

Troubleshooting

See the Troubleshooting Guide.