Set up the AVS SDK on Raspberry Pi

The following guide provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device 1.17 SDK on a Raspberry Pi. 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 your Raspberry Pi with the Amazon developer portal.
  2. Install and configure AVS Device SDK dependencies on your Raspberry Pi.
  3. Build the sample app and run it on your Raspberry Pi.
Note

This tutorial builds the SDK from source. You can also build your prototype with a script for faster results.

Prerequisites

Required hardware

  • Raspberry Pi - Use a Raspberry Pi 3 or 4.
  • Micro SD card - Minimum 8 GB.
  • USB 2.0 microphone - Raspberry Pi does not have a built-in microphone. To interact with Alexa you must plug in an external microphone.
  • External speaker or headset - Your audio source needs to connect to the Pi with 3.5mm audio cable.
  • USB keyboard and mouse - Choose any compatible keyboard and mouse.
  • HDMI monitor - Choose any compatible monitor. Alternatively, you can remote SSH into your Pi.
  • Internet connection - Ethernet connection or a 2.4 GHZ Wi-Fi.

Required software

  • Raspbian Operating System - Use Raspbian Buster or Raspbian Strech to complete this tutorial.
  • 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 environment

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 /home/pi directory as your starting point. If you choose to use different folder names, update the %home% commands throughout the guide accordingly.

Open your terminal and run this command from your home directory.

cd /home/pi/
mkdir sdk-folder

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

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

To install dependencies

The first step is to run apt-get update. This ensures that your Pi has an updated list of packages.

cd /home/pi/
sudo apt-get update

To install the dependencies, run the following commands.

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 \
gstreamer1.0-plugins-good libasound2-dev doxygen

To record microphone data, install PortAudio with the following commands.

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

After the previous commands have finished, you must run the make command. This command automatically builds executable programs and libraries from source code.

make

Next, install commentjson with the following command.

pip install commentjson

Commentjson is a python package that provides the functionality to parse comments in AlexaClientSDKConfig.json. This file contains the SDK configuration settings for your device.

Download the AVS Device SDK and the Sensory wake word engine

Next, you download the AVS Device SDK from the SDK GitHub repository. You must also install the Sensory wake word engine if you want to wake the Pi up using the 'Alexa' wake word.

To download the SDK

  1. Clone the SDK into the sdk-source folder.
    cd /home/pi/sdk-folder/sdk-source
    git clone git://github.com/alexa/avs-device-sdk.git
    
  2. Clone the Sensory wake word engine into the third-party folder.
    cd /home/pi/sdk-folder/third-party
    git clone git://github.com/Sensory/alexa-rpi.git
    
  3. Run the licensing script to view the Sensory licensing agreement. You must accept this license agreement to use the Sensory wake word engine.
    cd /home/pi/sdk-folder/third-party/alexa-rpi/bin/
    ./license.sh
    

Build the SDK

Next you build the SDK. For the purpose of this tutorial, you are only compiling the sample app and not the entire SDK.

  1. Run cmake to generate the build dependencies for the sample app. This command enables the wake word engine and gstreamer. It also provides paths to the wake word engine and PortAudio. For a full list of available commands, see the cmake parameters page.
cd /home/pi/sdk-folder/sdk-build
cmake /home/pi/sdk-folder/sdk-source/avs-device-sdk \
-DSENSORY_KEY_WORD_DETECTOR=ON \
-DSENSORY_KEY_WORD_DETECTOR_LIB_PATH=/home/pi/sdk-folder/third-party/alexa-rpi/lib/libsnsr.a \
-DSENSORY_KEY_WORD_DETECTOR_INCLUDE_DIR=/home/pi/sdk-folder/third-party/alexa-rpi/include \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DPORTAUDIO=ON \
-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
  1. Build the SDK sample app by running the following command. If you want to build the rest of the SDK, including unit and integration tests, run make instead of make SampleApp
make SampleApp 

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. This file is called AlexaClientSDKConfig.json.

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.

This script is included with the SDK and is located in the Install folder located at /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

To set up AlexaClientSDKConfig.json using genConfig.sh

  1. Move the config.json you downloaded when you created your security profile into the Install folder of the SDK - /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.
  2. Run genConfig.sh, including the following parameters as arguments in the Install folder.

     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"
    

    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.

Set up the microphone

A fresh Raspbian OS image might require an update to the /.asoundrc file to make the microphone work.

To configure the microphone and speaker

  1. Create and open the ~/.asoundrc file by typing the following command in the terminal: sudo nano ~/.asoundrc.
  2. Add these lines to the file and save it (CTRL + O).
pcm.!default {
  type asym
   playback.pcm {
     type plug
     slave.pcm "hw:0,0"
   }
   capture.pcm {
     type plug
     slave.pcm "hw:1,0"
   }
}

To ensure the microphone is capturing audio data, run the following command.

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

This command might install some extra audio dependencies. After it finishes, you should see a message indicating that audio is recording. It's working if you see a running minute counter that is incrementing by the second. It looks similar to the following command.

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

To exit the sound test, type CTRL + C.

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. Go to your BUILD folder, set up an environment variable and 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 the following message.
    ##################################
    #       NOT YET AUTHORIZED       #
    ##################################
    ################################################################################################
    #       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
    ################################################################################################
    
  3. Use a browser to navigate to the URL specified in the message from the sample app.
  4. Authenticate using your Amazon user credentials, if required.
  5. Enter the code specified in the message from sample app.
  6. Select Allow.
  7. Wait for the sample app to report that it's authorized, and that Alexa is idle. It looks like the following message:
    ###########################
    #       Authorized!       #
    ###########################
    ########################################
    #       Alexa is currently idle!       #
    ########################################
    
  8. You are now ready to use the sample app. The next time you start the sample app, you do not have to authorization your device.

Notes:

  • If you exit out of sample app with the k command, the CBLAuthDelegate database clears and you must reauthorize your client.
  • If you want to move this authorization to another sample app installation, you must copy the deviceInfo object within AlexaClientSDKConfig.json to the new installation. You will also need to copy the file "/home/pi/sdk-folder/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. It includes the path to your configuration file and the Sensory wake word model.

cd /home/pi/sdk-folder/sdk-build
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json ../third-party/alexa-rpi/models

Configuration options

Enable debug logs

IMPORTANT: If you encounter any issues, use the debug flag to get more information. Accepted values include debug1 through debug9. For example:

./SampleApp /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json /home/pi/sdk-folder/third-party/alexa-rpi/models debug9

Enable Bluetooth

Building with Bluetooth is optional and supported on Linux and Raspberry Pi.

  • You must install all Bluetooth dependencies.
  • You can use either A2DP-SINK or AVRCP profiles.
  • You must disable any processes that obtain an incoming Bluetooth audio stream, such as BlueALSA or PulseAudio.

Disable BlueALSA

If you are using BlueALSA, you must disable Bluetooth by running this command:

ps aux | grep bluealsa
sudo kill <bluealsa pid>

Disable PulseAudio

If you are using PulseAudio, you must disable PulseAudio Bluetooth plugins. To do this:

  1. Navigate to /etc/pulse/default.pa (or equivalent file), and comment out the following 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
    
  2. Next, stop and restart PulseAudio with these commands (if auto-respawn is disabled):
     pulseaudio --kill
     pulseaudio --start
    

Troubleshooting

See the common issues page for information about fixing any errors.