Quick Start: Set Up the AVS Device SDK on Ubuntu for Voice-Only Devices

The following quick start guide 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. This quick start guide is applicable to both beginners and advanced users of the SDK. However, you should have some basic knowledge of Linux.

Prerequisites

You must meet the following prerequisites before you begin this quick start guide.

  • Microphone – If you build the SDK with a wake word, you must have a microphone.
  • External speaker or headset – Your audio source.
  • Ubuntu Desktop 20.04 – This version of Ubuntu is tested and verified to work with the SDK. You can also use console only versions like Ubuntu Server but might need to adjust the packages and follow the troubleshooting guide to get audio playback to work properly.
  • AVS Device SDK 3.0 and above – This quick start guide instructs you to download the latest version of the SDK.
  • 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.
  • Registered product with AVS – You must register your product with Alexa Voice Service. After you have registered your product, save the config.json for “Other devices and platforms” because you need it to complete this quick start guide. This file contains the client ID for your Alexa Voice Service product and is used as part of the authorization between Alexa Voice Service and your device.

Steps to set up the AVS Device SDK on Ubuntu for voice-only devices

To set up the AVS Device SDK on Ubuntu, complete the following steps:

  1. Set up your Ubuntu environment
  2. Download the AVS Device SDK
  3. Find paths to dependencies
  4. Build the SDK Sample App
  5. Set up your configuration file
  6. Run and authorize the Sample App
  7. Use the Sample App

Step 1: Set up your Ubuntu environment

The following instructions use your home directory represented by $HOME. If you want to store the SDK under a different path, update the commands accordingly.

To set up your development environment on Ubuntu

1. To create the necessary folders required to organize the files you extract from the SDK, open your Terminal, and then run the following commands.

Copied to clipboard.

cd $HOME
mkdir sdk-folder

cd sdk-folder
mkdir sdk-build sdk-source sdk-install db

2. Update your Ubuntu package list.

Copied to clipboard.

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

3. 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 text-to-speech (TTS) and music.
  • Record audio from the microphone.
  • Store records in a database.

Copied to clipboard.

cd $HOME
sudo apt-get install -y \
git gcc cmake sox build-essential nghttp2 libsqlite3-dev libcurl4-openssl-dev libgtest-dev libssl-dev openssl \
libnghttp2-dev libasound2-dev doxygen pulseaudio portaudio19-dev 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-tools clang-format libgcrypt20-dev libarchive-dev

Step 2: Download the AVS Device SDK

The AVS Device SDK is available on GitHub. Clone the SDK into the sdk-source folder by using the following commands.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-source
git clone --single-branch https://github.com/alexa/avs-device-sdk.git

Step 3: Find paths to dependencies

PortAudio is located in different paths in the /usr/lib/ folder depending on whether the chipset used by your system. The following command should help you find the path to the PortAudio library on your device.

find -P /usr/lib -name libportaudio.so

The commands below sets the PORTAUDIO_LIB_PATH environment variable for use in step 4.1.

Copied to clipboard.

PORTAUDIO_LIB_PATH=$(find -P /usr/lib -name libportaudio.so)

Step 4: Build the AVS Device SDK Sample App

Use the cmake command to build the SDK. CMake is a build tool that manages app dependencies and creates native make files suitable for your SDK project. This section shows how to pass CMake parameters to enable PortAudio and GStreamer.

1. The following CMake command builds the dependencies for your sample and enables GStreamer and PortAudio.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-build
cmake $HOME/sdk-folder/sdk-source/avs-device-sdk \
    -DGSTREAMER_MEDIA_PLAYER=ON \
    -DPORTAUDIO=ON \
    -DPKCS11=OFF \
    -DPORTAUDIO_LIB_PATH=$PORTAUDIO_LIB_PATH \
    -DPORTAUDIO_INCLUDE_DIR=/usr/include \
    -DCMAKE_BUILD_TYPE=DEBUG

2. Build the SDK Sample App.

Copied to clipboard.

make SampleApp
Notes

The command make SampleApp uses a single thread for compilation. You can speed up compilation with more threads by adding the -j2, -j4, or -j8 make flag, depending on your processor.

The make SampleApp command only builds the SDK Sample App. To build the entire SDK— including unit tests— run the make 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 your SDK configuration file

1. Place the config.json file you downloaded in the $HOME/sdk-folder/sdk-source/avs-device-sdk/tools/Install directory.

2. Run genConfig.sh script to generate your config. When you run the script, include all the parameters shown in the code example below.

Copied to clipboard.

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

bash genConfig.sh \
config.json \
12345 \
$HOME/sdk-folder/db \
$HOME/sdk-folder/sdk-source/avs-device-sdk \
$HOME/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json \
-DSDK_CONFIG_MANUFACTURER_NAME="Ubuntu" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="Ubuntu"

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

1. Navigate to your sdk-build folder and start the Sample App.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-build/
./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json 

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

3. Open a browser. If you're in the US, navigate to the US-specific URL to authorize the Sample App. If you're outside of the US, use the URL as shown in your step 6.2.

4. Sign in to your Amazon developer account.

5. Enter the code specified in the message from Sample App.

6. Select Allow.

7. 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 Console Sample App.

To relaunch the Sample App

  • Run the following command.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-build
./SampleApplications/ConsoleSampleApplication/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.

  ./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

Run unit tests

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

Use the following command to run unit tests.

make all test

For more details about running unit tests, see Unit Tests.

Build with Bluetooth

Bluetooth is optional. Supported Bluetooth profiles include: A2DP-SINK, A2DP-SOURCE, AVRCPTarget, and AVRCPController.

To enable Bluetooth

  1. Install all required Bluetooth dependencies.
  2. Install libpulse-dev.
  3. Install PulseAudio with the following command.

    cd $HOME
    sudo apt-get install pulseaudio-module-bluetooth
    
  4. 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".

    1. Open /etc/dbus-1/system.d/bluetooth.conf.
    2. The following example shows how to add <allow send_interface="org.mpris.MediaPlayer2.Player"/> to your root policy.
      <!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 details about fixing common issues, see Troubleshooting the AVS Device SDK Common Issues.