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.
Before you get started, see the SDK overview page to establish a working knowledge of how the SDK works.
You complete the following activities in this tutorial:
- Register an AVS device with the Amazon developer portal.
- Install and configure AVS Device SDK dependencies on Android.
- Build the AVS sample app and run it on Android.
Prerequisites
You must meet the following prerequisites to complete this tutorial.
Required hardware
- Linux or macOS device – Your device must meet the following system requirements.
- Android hardware – You can use the following Android hardware to test and debug your build.
- Android Device – Your Android phone or tablet should have 500 MB minimum of available disk space.
- Android Things-supported Hardware – View the Android Things-supported hardware.
Required software
- Alexa Voice Service SDK 1.17 or higher – The instructions in this tutorial download the latest version of the SDK that's available.
- SDK dependencies – Install these Android dependencies on your device.
- Android software – You can use the following Android software to test and debug your build.
- Android Emulator – Your emulator should have 500 MB minimum of available disk space.
- Minimum dependencies – The Alexa app relies on external libraries to compile. For more details about the external libraries you must install, see AVS Device SDK Dependencies.
Step 1: Register your AVS device with Amazon
Before you install the AVS Device SDK, you must register an AVS product and create a security profile.
After registering your device, you download a config.json file. This file contains your client ID and client secret. The client ID and client secret authorize your device, so you can retrieve access tokens from AVS. Your config.json file facilitates the authorization calls between your device and AVS.
Save the config.json file somewhere accessible. You use it later in the tutorial to build the SDK.
Step 2: Set up your Android environment
Before you download and install the AVS Device SDK, you must set up the appropriate development environment for Android.
To Install Android Tools
- Install Android tools by either downloading Android Studio – which includes the tools by default – or by using the command line.
-
Set up the Android platform tools using the Android SDK manager. During this process, you must specify the CPU type and Android version number you are building with.
# 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"
-
Set your computers
PATH
environment variable to include Android tools. For example, if you've installed the Android tools in your home directory~/Android/sdk
, run the following command.export PATH=$PATH:~/Android/sdk/platform-tools:~/Android/sdk/tools:~/Android/sdk/tools/bin
-
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
Step 3: Download the configuration scripts
You use the Android Debug Bridge (ADB) to connect to your device and install the SDK.
To connect your device to the ADB
- Physically connect your Android device to your Mac or Linux machine with a USB cable.
- Enable USB debugging on your device.
-
Connect your device to ADB:
adb root adb connect <device_ip>
To download the AVS Device SDK
Open your terminal and run these three commands in a single block statement.
This downloads four AVS Device SDK configuration scripts. You can specify any directory you prefer to run the scripts and download these files to. These scripts are later used to download and authorize the AVS Device SDK and sample app.
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
Step 4: Modify the configuration settings
-
Navigate to the directory where you downloaded the configuration scripts in step 3.
-
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 versions: Android API level 23 to Android API level 29.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
,x86
,arm64
,x86_64
.DEVICE_INSTALL_PATH
The path on the device where the script should install the sample app and dependencies.
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
, andRelWithDebInfo
. -
Edit the
setup.sh
by replacinggit clone --single-branch $CLONE_URL avs-device-sdk
withgit clone -b v1.26.0 --single-branch $CLONE_URL avs-device-sdk
.Important: To use AVS Device SDK 1.26, you must replacegit clone --single-branch $CLONE_URL avs-device-sdk
withgit clone -b v1.26.0 --single-branch $CLONE_URL avs-device-sdk
in thesetup.sh
script before you perform the steps below. -
Run the
setup.sh
script usingconfig.json
,androidConfig.txt
, and the device serial number (DSN) as arguments.The DSN helps to identify your product or app instance. Use any unique alpha-numeric string up to 64 characters. If you don't supply a DSN, the default value
123456
is generated by the SDK.Example command
bash setup.sh config.json -a androidConfig.txt -s 998987
Step 5: Run and authorize the sample app
- Start the sample app by running the
startsample.bat
file. -
Wait for the sample app to display the following confirmation message.
################################## # NOT YET AUTHORIZED # ################################## ################################################################################################ # To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX} # ################################################################################################
- Use a browser to navigate to the URL specified in the message from the sample app.
- If requested, authenticate using your Amazon user credentials.
- Enter the code specified in the message from sample app.
- Select Allow.
-
Wait for the sample app to report that it's authorized and that Alexa is idle.
You are now ready to talk to Alexa. The next time you start the sample app, you don't have to go through the authorization process again. If you close the sample app, start it again by rerunning the
startsample.bat
file.########################### # Authorized! # ########################### ######################################## # Alexa is currently idle! # ########################################
Step 6: Use the sample app
Now that you have a working sample app, try an interaction with Alexa. For more details about how to interact with Alexa, see Use the sample app.
To relaunch the sample app, rerun the startsample.bat
file.
Troubleshooting
See the Troubleshooting Guide.
Last updated: Oct 25, 2022