Set Up the AVS Device SDK on Ubuntu
The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on Ubuntu. 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 for Ubuntu.
- Build the AVS sample app and run it on Ubuntu.
- Prerequisites
- Step 1: Register your AVS device with Amazon
- Step 2: Set up your Ubuntu environment
- Step 3: Download the AVS Device SDK
- Step 4: Build the AVS Device SDK sample app
- Step 5: Set up your configuration file
- Step 6: Run and authorize the sample app
- Step 7: Use the sample app
- Extra build options
- Troubleshooting
Prerequisites
You must meet the following prerequisites to complete this tutorial.
Required hardware
- Microphone – If you build the SDK with a wake word, you must have a microphone.
- External speaker or headset – Your audio source.
Required software
- Ubuntu 18.04 LTS – This version of Ubuntu is tested and verified to work with the SDK.
- AVS Device SDK – The instructions in this tutorial download the latest version of the SDK that's available and are only applicable to that particular version.
- 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 Ubuntu environment
Before you download the AVS Device SDK, you must set up the appropriate development environment on Ubuntu. The following instructions presume that the SDK installs to $HOME
. If you use a different path, update the $HOME
commands throughout the guide.
To set up your development environment on Ubuntu
-
To create the necessary folders required to organize the files you extract from the SDK, open your terminal, and then run the following commands.
cd $HOME mkdir my_project cd my_project mkdir build source third-party application-necessities cd application-necessities mkdir sound-files
-
Update your Ubuntu package list.
sudo apt-get update && sudo apt-get upgrade -y
-
Install the core SDK dependencies.
The AVS Device SDK requires libraries to handle the following functionality.
- Maintain an HTTP/2 connection with AVS.
- Play Alexa TTS and music.
- Record audio from the microphone.
- Store records in a database.
cd $HOME sudo apt-get install -y \ git gcc cmake openssl clang-format libgstreamer1.0-0 libgstreamer-plugins-base1.0-dev \ 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 libasound2-dev libcurl4-nss-dev
Important: Make sure that all the dependencies installed without errors. -
Install the OpenSSL and Nghttp2 dependencies.
You use the following commands to connect to AVS through HTTP.
sudo apt-get -y install build-essential nghttp2 libnghttp2-dev libssl-dev cd $HOME/my_project/third-party wget https://github.com/curl/curl/releases/download/curl-7_67_0/curl-7.67.0.tar.gz tar xzf curl-7.67.0.tar.gz cd curl-7.67.0 ./configure --with-nghttp2 --prefix=/usr/local --with-ssl make && sudo make install sudo ldconfig
-
Verify your curl installation 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
-
Install and configure PortAudio.
Audio input and output doesn't work without this dependency.
cd $HOME/my_project/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
Step 3: Download the AVS Device SDK
Clone the AVS Device SDK into your $HOME/my_project/source folder.
cd $HOME/my_project/source
git clone -b v1.26.0 --single-branch https://github.com/alexa/avs-device-sdk.git
Step 4: Build the AVS Device SDK sample app
Next you build the SDK by using the Ubuntu terminal.
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 configures the following build options.
- Enables GStreamer
- Enables PortAudio
- Specifies the
curl-openssl
library location - Enables debug logging
To build the sample app
-
Generate the build dependencies for the sample app by using
cmake
.AVS Device SDK 1.18.0 and higherNote: To build the SDK with Alexa wake word, use the relevant CMake parameters. This tutorial doesn't build with the wake word enabled.cd $HOME/my_project/build cmake $HOME/my_project/source/avs-device-sdk \ -DGSTREAMER_MEDIA_PLAYER=ON \ -DPORTAUDIO=ON \ -DPKCS11=OFF \ -DPORTAUDIO_LIB_PATH=$HOME/my_project/third-party/portaudio/lib/.libs/libportaudio.so \ -DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include \ -DCMAKE_BUILD_TYPE=DEBUG \ -DCURL_INCLUDE_DIR=$HOME/my_project/third-party/curl-7.67.0/include/curl \ -DCURL_LIBRARY=$HOME/my_project/third-party/curl-7.67.0/lib/.libs/libcurl.so
AVS Device SDK 1.17.0 and lowerNote: To build the SDK with Alexa wake word, use the relevant CMake parameters. This tutorial doesn't build with the wake word enabled.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=DEBUG
-
Build the sample app.
make SampleApp -j2
Note: Themake SampleApp
command builds the SDK sample app. To build the entire SDK – including unit and integration tests – run themake
command instead.
Step 5: Set up your configuration file
Before you run the sample app, you must set up an AlexaClientSDKConfig.json file for your device. This file contains your SDK settings and authorizes your device with Amazon.
You configure the AlexaClientSDKConfig.json file by running the genconfig.sh configuration script. This script uses data from your config.json file to populate your AlexaClientSDKConfig.json file.
To set up AlexaClientSDKConfig.json by using genConfig.sh
- Move the config.json file you downloaded into the Install folder of the SDK –
/my_project/source/avs-device-sdk/tools/Install
. -
Create a database directory.
mkdir $HOME/my_project/build/Integration/database
-
Run genConfig.sh from the $HOME/my_project/source/avs-device-sdk/tools/Install directory.
Include all the parameters shown in the following code example.
cd $HOME/my_project/source/avs-device-sdk/tools/Install sudo 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"
Important: Rerunning genConfig.sh overwrites any values set in AlexaClientSDKConfig.json. If necessary, back up the file.Note: If you get a python error after running the above command, it means you are missing python3 and you must install it.
Step 6: 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.
To run and authorize the sample app
-
Navigate to your BUILD folder and start the sample app.
cd $HOME/my_project/build ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json
-
Wait for the sample app to display the following message.
################################## # NOT YET AUTHORIZED # ################################## ################################################################################################ # To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX} # ################################################################################################
- Open a browser, and then navigate to the URL specified in the message from the sample app.
- Log in to your Amazon developer account.
- Enter the code specified in the message from sample app.
- Select Allow.
-
Wait for the sample to authorize.
########################### # Authorized! # ########################### ######################################## # Alexa is currently idle! # ########################################
You can now use the sample app to talk to Alexa.
Step 7: 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, run the following command.
cd $HOME/my_project/build
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9
Extra build options
Use the following instructions to enable additional build options.
Enable debug logs
Use the debug flag to get more information about problems you might encounter. Accepted values include DEBUG1
through DEBUG9
.
For example, the following command uses the DEBUG9
logging flag.
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9
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 functions 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 about running unit tests, see Unit and Integration Tests.
Build with Bluetooth
Bluetooth is optional. Supported Bluetooth profiles include: A2DP-SINK
, A2DP-SOURCE
, AVRCPTarget
, and AVRCPController
.
To enable Bluetooth
- Install all required Bluetooth dependencies.
- Install libpulse-dev
-
Install PulseAudio with the following command.
cd $HOME sudo apt-get install pulseaudio-module-bluetooth
-
Include the following CMake option in your build.
-DBLUETOOTH_BLUEZ_PULSEAUDIO_OVERRIDE_ENDPOINTS=ON -DBLUETOOTH_BLUEZ=ON
If you're using the
AVRCPTarget
profile, you must enable permissions for BlueZ to interact with"org.mpris.MediaPlayer2.Player"
.- Open /etc/dbus-1/system.d/bluetooth.conf.
- 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" "https://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>
Troubleshooting
For more details about fixing common issues, see Troubleshooting.
Last updated: Oct 13, 2022