Set Up the AVS Device SDK on Raspberry Pi

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on a Raspberry Pi. This process includes installing, building, authorizing, and using the Alexa Voice Service (AVS) Device 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 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 doesn't have an onboard microphone. To interact with Alexa, you must plug in an external microphone.
  • External speaker or headset – Your audio source must connect to the Raspberry Pi with 3.5-mm 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 Raspberry Pi.
  • Internet connection – Ethernet connection or a 2.4 GHZ Wi-Fi.

Required software

  • Raspbian Operating System – Use Raspbian Buster or Raspbian Stretch
  • Alexa Voice Service SDK 1.17 – The instructions in the tutorial download the latest version of the SDK download for you.

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 Raspberry Pi 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 you set your home directory to /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. To create the necessary folders required to organize the files you extract from the SDK, open the Raspberry Pi terminal, and then 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 Raspberry Pi.

     cd /home/pi/
     sudo apt-get update
    
  3. Install the required dependencies on your Raspberry 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 that 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
    

Download the AVS Device SDK and the Sensory wake word engine

Next, download the AVS Device SDK from the SDK GitHub repository by using the Raspberry 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 --single-branch 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 by using the Raspberry Pi terminal.

To build the SDK

  1. Generate the build dependencies for the sample app by 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

    The make SampleApp command only builds the AVS 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. You find the script in the SDK download, located at /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

To set up AlexaClientSDKConfig.json by 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 from the $HOME/my_project/source/avs-device-sdk/tools/Install directory. Include the following 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"
    

Add an audioSink to AlexaClientSDKConfig.json

You must also modify the AlexaClientSDKConfig.json file and change the audiosink in the gstreamerMediaPlayer object.

  1. Open AlexaClientSDKConfig.json.

     nano /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json
    
  2. Add the following json object before "cblAuthDelegate":{.

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

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

Set up the microphone

A new 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.
     nano ~/.asoundrc
    
  2. Add the following lines to 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. To save the file, press CTRL + O.
  4. Update the devices audio dependencies, and then check if the microphone captures audio data.

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

    If the microphone successfully records audio, you see the following output.

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

  5. To exit the sound test, press CTRL + C.

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

    It includes the path to your configuration file and the Sensory wake word model.

     cd /home/pi/sdk-folder/sdk-build
     PA_ALSA_PLUGHW=1 ./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 by using wake word

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

For example:

User: "Alexa, what is the current weather?"

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

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

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

    a. Disable BlueALSA with the following command.

       ps aux | grep bluealsa
       sudo kill <bluealsa pid>
    

    b. Disable PulseAudio by navigating to /etc/pulse/default.pa.

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

    d. Stop and restart PulseAudio.

       pulseaudio --kill
       pulseaudio --start
    

Troubleshooting

For more information about fixing common issues, see Troubleshooting.