Set up the AVS SDK on Raspberry Pi

The following tutorial 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 AVS Device SDK. When finished, you'll have a working sample app to test interactions with Alexa.

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

You must meet the following prerequisites to complete this tutorial.

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 must 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.
  • Alexa Voice Service SDK 1.17 - You download this version of the SDK later in the tutorial.

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 environment

Before you download and install the AVS Device SDK, you must set up the appropriate development environment on your Raspberry Pi. The following instructions presume that your home directory is /home/pi. If you use different folder names, update the /home/pi commands throughout the guide.

To set up your development environment on your Raspberry Pi

  1. Create the necessary folders required to organize the files you extract from the SDK. Open the Pi terminal and run the following commands.

     cd /home/pi/
     mkdir sdk-folder
    
     cd sdk-folder
     mkdir sdk-build sdk-source third-party sdk-install db 
    
    
  2. Update the package list on your Pi.

     cd /home/pi/
     sudo apt-get update
    
  3. Install the required dependencies on your Pi. 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.
     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
    
  4. Install PortAudio so your microphone captures data.

     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
    
  5. Run make. This command automatically builds executable programs and libraries from source code.

    make
    
  6. Install commentjson. This Python package provides functionality to parse comments in your AlexaClientSDKConfig.json file.

     pip install commentjson
    

Download the AVS Device SDK and the Sensory wake word engine

Next, download the AVS Device SDK from the SDK GitHub repository using the Pi terminal.

To download the AVS Device 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 and enable the "Alexa" wake word.

     cd /home/pi/sdk-folder/third-party/alexa-rpi/bin/
     ./license.sh
    

Build the SDK

Next you build the SDK using the Pi terminal.

To build the SDK

  1. Generate the build dependencies for the sample app using cmake. This command enables the wake word engine and Gstreamer. It also provides paths to the wake word engine and PortAudio.

     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
    
  2. Build the sample app.

     make SampleApp 
    
    Note

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

Set up your configuration file

Before you run the sample app, you must set up a SDK configuration file – AlexaClientSDKConfig.json. – for your device.

Run the configuration script

The AlexaClientSDKConfig.json file generates when you run the genconfig.sh configuration script. This script uses data from your config.json file to populate your AlexaClientSDKConfig.json file, so your device authorizes with Amazon. To find the script, navigate to the Install folder /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

To set up AlexaClientSDKConfig.json using genConfig.sh

  1. Move the config.json file you downloaded into the Install folder of the SDK - /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.
  2. Run genConfig.sh with the following parameters as arguments.

     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"
    
    Important

    Re-running genConfig.sh overwrites any values set in AlexaClientSDKConfig.json. If required, back up the file .

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.
     sudo nano ~/.asoundrc
    
  2. Add the following lines to the file. To save the file, press CTRL + O.

     pcm.!default {
       type asym
        playback.pcm {
          type plug
          slave.pcm "hw:0,0"
        }
        capture.pcm {
          type plug
          slave.pcm "hw:1,0"
        }
     }
    
  3. Update your audio dependencies and check if the microphone captures audio data.

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

    If your microphone records audio, you see the following output. To exit the sound test, press CTRL + C.

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

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, 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. Open a browser and 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. You can now use the sample app to talk to Alexa.

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

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

Use the sample app

Now that you have a working sample app, try an interaction with Alexa.

Interact with Alexa using wake word

Ask Alexa something by speaking the "Alexa" wake word.

For example:

User: "Alexa, what's the current weather?"

Alexa: "Right now in Portland, it's 71 degrees with sun..

Interact with Alexa using tap-to-talk

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

For example:

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

Alexa: "Right now 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 re-authorize your sample app. It also exits the app.
Quit q+Enter

Extra 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

Enable Bluetooth

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

To enable Bluetooth

  1. Install all required Bluetooth dependencies.
  2. Disable all processes that fetch incoming Bluetooth audio streams – such as BlueALSA or PulseAudio.

Disable BlueALSA with the following command.

  ps aux | grep bluealsa
  sudo kill <bluealsa pid>

Disable PulseAudio with the following steps

  1. Navigate to /etc/pulse/default.pa.
  2. 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
    
  3. Stop and restart PulseAudio with these commands.

     pulseaudio --kill
     pulseaudio --start
    

Troubleshooting

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