Set Up the AVS Device SDK on Raspberry Pi from Source

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on a Raspberry Pi from source. This process includes installing, building, authorizing, and running the SDK. When finished, you have a working sample app to test interactions with Alexa. Note that these instructions don't build the SDK with a wake word. Instead, you activate Alexa using a tap-to-talk command.

Before you get started, see the SDK Overview to understand how the SDK works. This tutorial is applicable to both beginners and advanced users of the SDK. However, some basic knowledge of Linux is assumed.

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 on your Raspberry Pi.
  3. Build the AVS Device SDK sample app and run it on your Raspberry Pi.

Prerequisites

To complete this tutorial, meet the following prerequisites.

Required hardware

  • Raspberry Pi – Only use a Raspberry Pi 3 or 4.
  • Micro SD card – Any compatible Micro SD card. Minimum 8 GB.
  • External audio source – Any compatible speaker or headset. The Raspberry Pi features a 3.5-mm audio jack.
  • USB keyboard and mouse – Any compatible keyboard and mouse.
  • Raspberry Pi fan - Any compatible fan. Without a fan, the Raspberry Pi might overheat.
  • HDMI monitor – Any compatible HDMI monitor. Alternatively, you can remote SSH into your Raspberry Pi.
  • Internet connection – Ethernet connection or a 2.4 GHz Wi-Fi connection.

Required software

  • Raspbian Operating System – Only use Raspbian Buster.
  • 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 sample app relies on external libraries to compile. This tutorial includes instructions to download these dependencies for you. For more details about the external libraries you install, see AVS Device SDK Dependencies.

Step 1: Register your AVS device with Amazon

Before you can use the SDK, you must register an AVS device on the Amazon developer portal by following the instructions on 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 to retrieve access tokens from AVS. Your config.json file facilitates the authorization calls between AVS and your device.

Save your config.json file somewhere accessible. You need to use it later in this tutorial to build and authorize your instance of the SDK.

Step 2: Set up your Raspberry Pi environment

The following instructions use a home directory of /home/pi. If you use a different home directory, update the /home/pi commands accordingly.

To set up your Raspberry Pi environment

  1. Open your Raspberry Pi terminal and create your SDK folder structure.

     cd /home/pi/
 mkdir sdk-folder

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

  2. Update your Raspberry Pi package list.

     cd /home/pi/
 sudo apt-get update

  3. Install the core SDK dependencies.

    The AVS Device SDK uses external 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.
     sudo apt-get -y install \
 git gcc cmake build-essential libsqlite3-dev libcurl4-openssl-dev libfaad-dev \
 libssl-dev libsoup2.4-dev libgcrypt20-dev libgstreamer-plugins-bad1.0-dev \
 libnghttp2-dev nghttp2 gstreamer1.0-plugins-good libasound2-dev doxygen

  4. Install PortAudio and curl.

     cd /home/pi/sdk-folder/third-party
 wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz
 tar zxf pa_stable_v190600_20161030.tgz
 cd portaudio
 ./configure --without-jack
 make

 cd /home/pi/sdk-folder/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=/home/pi/sdk-folder/third-party/curl-7.67.0 --with-ssl
 make

Step 3: Download the AVS Device SDK

You download the SDK from the SDK GitHub repository.

To download the AVS Device SDK

Open your Raspberry Pi terminal and clone the SDK into the sdk-source folder.

cd /home/pi/sdk-folder/sdk-source
git clone -b v1.26.0 --single-branch https://github.com/alexa/avs-device-sdk.git

Step 4: Build the AVS Device SDK

You build the SDK with a cmake command. CMake is a build tool that manages app dependencies and creates native make files suitable for your SDK project.

To build the SDK

  1. Open your Raspberry Pi terminal and run the following CMake command.

    This builds the dependencies for your sample and enables Gstreamer, PortAudio, and curl.

     cd /home/pi/sdk-folder/sdk-build
 cmake /home/pi/sdk-folder/sdk-source/avs-device-sdk \
 -DGSTREAMER_MEDIA_PLAYER=ON \
 -DPORTAUDIO=ON \
 -DPKCS11=OFF \
 -DPORTAUDIO_LIB_PATH=/home/pi/sdk-folder/third-party/portaudio/lib/.libs/libportaudio.a \
 -DPORTAUDIO_INCLUDE_DIR=/home/pi/sdk-folder/third-party/portaudio/include \
 -DCURL_INCLUDE_DIR=/home/pi/sdk-folder/third-party/curl-7.67.0/include/curl \
 -DCURL_LIBRARY=/home/pi/sdk-folder/third-party/curl-7.67.0/lib/.libs/libcurl.so

  2. Build the SDK sample app.

     make SampleApp

Step 5: Set up your SDK configuration file

Before you can run the sample app, you must set up a SDK configuration file named AlexaClientSDKConfig.json. This file contains your SDK settings to authorize your device with Amazon.

To set up this file, you run a configuration script named genconfig.sh. This script is located in your SDK download package at /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

To set up your SDK configuration file

  1. Move the config.json file you downloaded into the Install folder of the SDK, located at /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

  2. Run the genConfig.sh script from the root of the Install folder.

    When you run the script, include all the parameters shown in the code example below.

     cd /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install

 bash genConfig.sh config.json 12345 \
 /home/pi/sdk-folder/db \
 /home/pi/sdk-folder/sdk-source/avs-device-sdk \
 /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json \
 -DSDK_CONFIG_MANUFACTURER_NAME="raspberrypi" \
 -DSDK_CONFIG_DEVICE_DESCRIPTION="raspberrypi"

Enable audio playback

To enable audio playback with the SDK, add a gstreamerMediaPlayer object to your AlexaClientSDKConfig.json file.

To enable audio playback

  1. Open your AlexaClientSDKConfig.json file in your terminal text editor.

     nano /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json

  2. Add the following gstreamerMediaPlayer object to the top of your file, before the cblAuthDelegate object.

    For example:

     {
     "gstreamerMediaPlayer":{
         "audioSink":"alsasink"
     },
     "cblAuthDelegate":{
         // Path to CBLAuthDelegate's database file. e.g. /home/ubuntu/Build/cblAuthDelegate.db
         // Note: The directory specified must be valid.
         // The database file (cblAuthDelegate.db) will be created by SampleApp, do not create it yourself.
         // The database file should only be used for CBLAuthDelegate (don't use it for other components of SDK)

       ...

Step 6: Set up your microphone

If you're using a fresh install of the Raspbian OS, you might need to update your /.asoundrc file to make the microphone work.

To set up your microphone

  1. Open your ~/.asoundrc file in your terminal text editor.

     nano ~/.asoundrc

  2. Copy and paste the following lines into the file.

     pcm.!default {
   type asym
    playback.pcm {
      type plug
      slave.pcm "hw:0,0"
    }
    capture.pcm {
      type plug
      slave.pcm "hw:1,0"
    }
 }
  3. Save the file by pressing CTRL + O.

  4. Update the audio dependencies on your device and run a sound test.

     sudo apt-get install sox -y && rec test.wav

    If your microphone records audio, you see the following output in your terminal.

     In: 0.00% 00:00:01 [00:00:00:00] out:0.00M [     |     ] clip:0

    To exit the sound test, press CTRL + C.

Step 7: Run and authorize the sample app

When you run the sample app for the first time, you must authorize it with Amazon by using a generated code specific to your device.

To run and authorize the sample app

  1. Navigate to your sdk-build folder, set up an environment variable, and then start the sample app.

     cd /home/pi/sdk-folder/sdk-build
 PA_ALSA_PLUGHW=1 ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

  2. Wait for the sample app to display a similar output.

     ##################################
 #       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 sample app message.
  4. Log-in to your Amazon developer account.
  5. In the text box, enter the four digit code specified {XXXX} in the sample app message.
  6. Select Allow.

  7. Wait for your sample app to authorize with Amazon.

     ###########################
 #       Authorized!       #
 ###########################
 ########################################
 #       Alexa is currently idle!       #
 ########################################

    You can now use the sample app to talk to Alexa.

Step 8: Use the sample app

Now that you have a working sample app, try a tap-to-talk interaction with Alexa. For more details about how to interact with Alexa, see Use the Sample App.

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 /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json /home/pi/sdk-folder/third-party/alexa-rpi/models DEBUG9

Build with Bluetooth

Building with Bluetooth is optional. Supported Bluetooth profiles include: A2DP-SINK or AVRCP.

To build with Bluetooth

  1. Install all required Bluetooth dependencies.

  2. Disable all processes that fetch incoming Bluetooth audio streams, such as BlueALSA or PulseAudio.

    a. Disable BlueALSA with the following command.

       ps aux | grep bluealsa
   sudo kill <bluealsa pid>

    b. Disable PulseAudio by opening the following file /etc/pulse/default.pa and comment out these lines:

       ### Automatically load driver modules for Bluetooth hardware
   #.ifexists module-bluetooth-policy.so
   #load-module module-bluetooth-policy
   #.endif

   #.ifexists module-bluetooth-discover.so
   #load-module module-bluetooth-discover
   #.endif

    Then, stop and restart PulseAudio.

       pulseaudio --kill
   pulseaudio --start

Troubleshooting

For more details about fixing common issues when building the SDK, see Troubleshooting.

Was this page helpful?

Last updated: Oct 13, 2022