Set Up the AVS Device SDK on Generic Linux

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on Generic Linux. 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:

  1. Register an AVS device with the Amazon developer portal.
  2. Install and configure AVS Device SDK dependencies for Linux.
  3. Build the AVS sample app and run it on Linux.
Note

This tutorial requires you to build dependencies from source. It assumes that you're familiar with Linux.

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 you must have a microphone.
  • External speaker or headset – Your audio source.

Required software

  • Linux – Use the latest version available.
  • Alexa Voice Service SDK 1.17 or higher – The instructions in this tutorial download the latest version of the SDK that's available.

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.

Important

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

Set up your Linux environment

Before you download the AVS Device SDK, you must set up the appropriate development environment on Linux. 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 Linux

  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.

     cd $HOME
     mkdir my_project
    
     cd my_project
     mkdir build source third-party application-necessities
    
     cd application-necessities
     mkdir sound-files
    
  2. Update your Linux package list.

     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 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-dev \
     libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-good \
     libgstreamer-plugins-good1.0-dev libgstreamer-plugins-bad1.0-dev \
     gstreamer1.0-libav pulseaudio doxygen libsqlite3-dev repo libasound2-dev
    
    Important

    Make sure that all the dependencies installed without errors.

Download the AVS Device SDK

Clone the AVS Device SDK into your $HOME/my_project/source folder.

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

Build the AVS Device SDK sample app

Next you build the SDK by using the Linux 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

  1. Generate the build dependencies for the sample app by using cmake.
Note

To build the SDK with Alexa wake word, use the relevant Cmake parameter. This tutorial doesn't build with the wake word enabled.

AVS Device SDK 1.18 and higher
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.so \
-DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include \
-DCMAKE_BUILD_TYPE=DEBUG
AVS Device SDK 1.17 and lower
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
  1. Build the sample app.
make SampleApp -j2
Note

The make SampleApp command builds the SDK sample app. To build the entire SDK – including unit and integration tests – run the make command instead.

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.

Run the configuration script

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 populate your device authorizes with Amazon.

To set up AlexaClientSDKConfig.json by using genConfig.sh

  1. Move the config.json file you downloaded into the Install folder of the SDK - /my_project/source/avs-device-sdk/tools/Install.
  2. Create a database directory.

     mkdir $HOME/my_project/build/Integration/database
    
  3. 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"
    
    Important

    Rerunning genConfig.sh overwrites any values set in AlexaClientSDKConfig.json. If necessary, back up the file.

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 BUILD folder and start the sample app.

     cd $HOME/my_project/build
     ./SampleApp/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, and then navigate to the URL specified in the message from the sample app.
  4. Log 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.

  8. To relaunch 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 by using tap-to-talk

Ask Alexa something with tap-to-talk by pressing T+Enter.

For example:

User taps-to-talk: "Alexa, what is the current weather?"

Alexa: "In Portland, it's 71 degrees with sun."

Additional options

Interaction options

Action Command
Tap-to-talk t+Enter, followed by your query.

You don't have to say "Alexa…".
Hold-to-talk h+Enter, followed by your query.

You don't have 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 reauthorize your sample app. It also exits the app.
Quit q+Enter

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

  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. 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>
    

Troubleshooting

For more information about fixing common issues, see Troubleshooting.