Set up the AVS SDK on Ubuntu Linux

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

Before you get started, watch Getting Started with the AVS Device SDK to establish a working knowledge of how the SDK works.

You complete the following activities in this tutorial:

  1. Register an Alexa Built-in product on the Amazon developer portal.
  2. Install and configure AVS Device SDK dependencies for Ubuntu.
  3. Build the SDK and run the AVS sample app.
Note

These instructions are verified for Ubuntu Linux 16.04 LTS. For all other distributions, review the dependencies and Cmake parameters for Generic Linux.

Prerequisites

Required hardware

  • Microphone - To interact with Alexa you must plug in an external microphone.
  • External speaker or headset - Your audio source.

Required software

  • Ubuntu Linux 16.04 LTS
  • Alexa Voice Service SDK 1.17 - You download this version of the SDK later in the tutorial.

Register your product with Amazon

Before you install the AVS Device SDK, you must Register an AVS Product and Create a Security Profile. After your device is registered, you download a config.json file that 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.

Important

Save the config.json file somewhere accessible. You use it later in the tutorial to build the SDK.

Set up your Ubuntu environment

The first step is to run apt-get update. This ensures that Ubuntu updates and installs the latest packages.

sudo apt-get update && sudo apt-get upgrade -y

To follow this tutorial, you must create a few folders to organize the files you extract from the SDK. This guide presumes that you are using the default $HOME directory as your starting point. If you choose to use a different $HOME directory or different folder names, update the commands throughout the guide accordingly.

Create a my_project folder, and these subfolders:

  • build
  • source
  • third-party
  • application-necessities > sound-files
cd $HOME
mkdir my_project

cd my_project
mkdir build source third-party application-necessities

cd application-necessities
mkdir sound-files

Install the core SDK dependencies:

cd $HOME
sudo apt-get install -y \
git gcc cmake openssl clang-format libgstreamer1.0-0 gstreamer1.0-plugins-base \
gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-doc gstreamer1.0-tools \
pulseaudio doxygen libsqlite3-dev repo libasound2-dev
Important

Make sure that all the dependencies installed and that no errors are thrown. If there are install errors, you might have to run brew install for each individual dependency.

Install the openssl and nghttp2 dependencies. You use these to connect to AVS using HTTP:

sudo apt-get -y install build-essential nghttp2 libnghttp2-dev libssl-dev
wget https://curl.haxx.se/download/curl-7.63.0.tar.gz
tar xzf curl-7.63.0.tar.gz
cd curl-7.63.0
./configure --with-nghttp2 --prefix=/usr/local --with-ssl
make && sudo make install
sudo ldconfig

Verify your curl installation:

Verify the dependencies installed with the following command.

curl -I https://nghttp2.org/

If the request succeeds, you get an output similar to the following text.

HTTP/2 200
date: Fri, 15 Dec 2017 18:13:26 GMT
content-type: text/html
last-modified: Sat, 25 Nov 2017 14:02:51 GMT
etag: "5a19780b-19e1"
accept-ranges: bytes
content-length: 6625
x-backend-header-rtt: 0.001021
strict-transport-security: max-age=31536000
server: nghttpx
via: 2 nghttpx
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff

Next, clone the SDK into the ~/my_project/source folder:

cd $HOME/my_project/source
git clone git://github.com/alexa/avs-device-sdk.git

Install and configure PortAudio. Audio input and output does not work without this dependency.

cd ../third-party
wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz
tar xf pa_stable_v190600_20161030.tgz

cd portaudio
./configure --without-jack && make

Build the SDK

You use CMake parameters to customize what features you want to build in the sample app. For example, to generate debug logs from the sample app build, include the -DCMAKE_BUILD_TYPE=DEBUG option.

This example does the following: Enables GStreamer and PortAudio, specifies the curl-openssl library location, and enables debug logging:

cd $HOME/my_project/build

cmake $HOME/my_project/source/avs-device-sdk \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$HOME/my_project/third-party/portaudio/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include
-DCMAKE_BUILD_TYPE=DEBUG9

Finish building the SDK from your build directory:

make SampleApp -j2
Note

To build the full SDK – including unit and integration tests – run make instead of make SampleApp. To speed up the build, you can use the arguments j2,-j3 or j4 to run processes in parallel.

Set up your configuration file

Before you can run the AVS Device SDK, you must set up a configuration file for your device that contains your SDK settings. The name of this file is AlexaClientSDKConfig.json.

Dependencies

Name Description Location
AlexaClientSDKConfig.json The configuration file that you'll use to authorize the sample app with AVS. Comes with the SDK.
avs-device-sdk/Integration
/AlexaClientSDKConfig.json
genConfig.sh The configuration file generator. Comes with the SDK
avs-device-sdk/tools/Install/genConfig.sh
config.json Downloaded when you created a security profile during the product registration process. Your download location.

Run the configuration script

Your AlexaClientSDKConfig.json file is set up when you run the genconfig.sh configuration script. GenConfig.sh uses data from your config.json file to populate your AlexaClientSDKConfig.json file so you can authorize your device with Amazon.

First, move the config.json file into the /my_project/source/avs-device-sdk/tools/Install directory:

mv $HOME/Downloads/config.json $HOME/my_project/source/avs-device-sdk/tools/Install

Next, create a database directory. This is the dynamic database used by AlexaClientSDKConfig.json:

mkdir $HOME/my_project/build/Integration/database

Now, run genConfig.sh from the $HOME/my_project/source/avs-device-sdk/tools/Install directory. Include the following arguments:

cd $HOME/my_project/source/avs-device-sdk/tools/Install

bash genConfig.sh config.json 12345 \
$HOME/my_project/build/Integration/database \
$HOME/my_project/source/avs-device-sdk \
$HOME/my_project/build/Integration/AlexaClientSDKConfig.json \
-DSDK_CONFIG_MANUFACTURER_NAME="my_project" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="ubuntu"

For more details about running this command, see the following parameters descriptions.

Important

Re-running genConfig.sh overwrites any values set in AlexaClientSDKConfig.json. Back up the file if required.

Run and authorize the sample app

When you run the sample app for the first time, you must authorize it with Amazon using a generated code specific to your device. This code generates when you run a script on the files listed in the following table.

Navigate to your build folder, and initialize the sample app:

cd $HOME/my_project/build
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json

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}       #
################################################################################################
  1. Use a browser to navigate to the URL specified in the message from the sample app.
  2. If requested to do so, authenticate using your Amazon user credentials.
  3. Enter the code specified in the message from sample app.
  4. Select Allow.
  5. Wait for the sample app to report that it's authorized, and that Alexa is idle.
    ###########################
    #       Authorized!       #
    ###########################
    ########################################
    #       Alexa is currently idle!       #
    ########################################
    
  6. You are now ready to use the sample app! The next time you start the sample app, you don't have to go through the authorization process.

Notes:

  • If you exit out of sample app with the k command, the database clears and you have to reauthorize your client.
  • If you want to move this authorization to another sample app installation, you have to copy the deviceInfo object within AlexaClientSDKConfig.json to the new installation. You have to copy the file "$HOME/my_project/application-necessities/cblAuthDelegate.db" to the new installation, and update AlexaClientSDKConfig.json in the new installation so that the cblAuthDelegate's databaseFilePath property points to it.

To re-launch the sample app, run the following command again. It includes the path to your configuration file

cd $HOME/my_project/build
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

Use the sample app

Now that you have a working sample app, try an interaction with Alexa.

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 command erases any data stored on the device and you have to re-authorize your sample app. It also exits the application
Quit q+Enter

Configuration options

Enable Bluetooth

Building with Bluetooth is optional and supported on Linux and Raspberry Pi. You can use either A2DP-SINK, A2DP-SOURCE, AVRCPTarget, or AVRCPController profiles.

To build with Bluetooth

  1. Install all core Bluetooth dependencies.
  2. InstallPulseAudio Bluetooth modules
     cd $HOME
     sudo apt-get install pulseaudio-module-bluetooth
    
  3. Include the following CMake option in your build: BLUETOOTH_BLUEZ_PULSEAUDIO_OVERRIDE_ENDPOINTS
  4. Install the AVRCPTarget profile (if applicable)

If you are using the AVRCPTarget profile, you must enable permissions for BlueZ to interact with "org.mpris.MediaPlayer2.Player". To enable permissions,

  1. Open /etc/dbus-1/system.d/bluetooth.conf.
  2. Add <allow send_interface="org.mpris.MediaPlayer2.Player"/> to your root policy.

For example:

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>

<!-- ../system.conf have denied everything, so we just punch some holes -->

<policy user="root">
...
<allow send_interface="org.mpris.MediaPlayer2.Player"/>
</policy>

...

</busconfig>

Run integration and unit tests

After you've built the AVS Device SDK, you should run integration and unit tests to make sure that the SDK is functioning as designed.

Use the following command to run integration tests:

make all integration

Use the following command to run unit tests:

make all test

For more details, see Unit and Integration Tests.

Troubleshooting

See the Troubleshooting Guide.