Quick Start: Set Up the AVS Device SDK on Raspberry Pi for Voice-Only Devices

The following quick start guide 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 quick start guide is applicable to both beginners and advanced users of the SDK. However, you should have some basic knowledge of Linux.

Prerequisites

You must meet the following prerequisites before you begin this quick start guide.

  • Raspberry Pi – Raspberry Pi 3B or 4.
  • Raspbian Bullseye OS or newer– 32-bit version of Bullseye desktop. If you have a Raspberry Pi 4, you can also use the 64-bit version of Bullseye desktop.
  • Micro SD card – Minimum 8 GB.
  • Microphone – Usually a USB 2.0 microphone or headset work best.
  • Speaker – Any compatible speaker or headset (3.5mm audio jack, USB, or HDMI).
  • Keyboard and mouse – Any compatible USB keyboard and mouse.
  • Display – HDMI monitor or remote SSH.
  • Internet connection – Ethernet or Wi-Fi connection.
  • Raspberry Pi fan (recommended) – Any compatible fan. Without a fan, the Raspberry Pi might overheat during compilation.
  • AVS Device SDK 3.0 and above – This quick start guide instructs you to download the latest version of the SDK.
  • Registered product with AVS – You must register your product with Alexa Voice Service. After you have registered your product, save the config.json for “Other devices and platforms” because you need it to complete this quick start guide. This file contains the client ID for your Alexa Voice Service product and is used as part of the authorization between Alexa Voice Service and your device.

Steps to set up the AVS Device SDK on Raspberry Pi for voice-only devices

To set up the AVS Device SDK on Raspberry Pi, complete the following steps:

  1. Set up your Raspberry Pi environment
  2. Download the AVS Device SDK
  3. Find paths to dependencies
  4. Build the SDK Sample App
  5. Set up your configuration file
  6. Set up your microphone
  7. Run and authorize the Sample App
  8. Use the Sample App

Step 1: Set up your Raspberry Pi environment

The following instructions use your home directory represented by the tilde (~). If you want to store the SDK under a different path, update the commands accordingly.

To set up your Raspberry Pi environment

  1. Open your Raspberry Pi Terminal, and then create your SDK folder structure.

     cd ~
     mkdir sdk-folder
    
     cd sdk-folder
     mkdir sdk-build sdk-source sdk-install db
    
  2. Update your Raspberry Pi package list and make sure your packages are running the latest version.

     sudo apt-get update && sudo apt-get upgrade
    
  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 text-to-speech (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 \
     libgtest-dev libssl-dev libsoup2.4-dev libgcrypt20-dev libgstreamer-plugins-bad1.0-dev \
     libnghttp2-dev nghttp2 gstreamer1.0-plugins-good libasound2-dev doxygen portaudio19-dev
    

    For more details about the external libraries you need, see AVS Device SDK Dependencies.

Step 2: Download the AVS Device SDK

The AVS Device SDK is available on GitHub. Clone the SDK into the sdk-source folder using the following commands.

cd ~/sdk-folder/sdk-source
git clone --single-branch https://github.com/alexa/avs-device-sdk.git

Step 3: Find paths to dependencies

PortAudio is located in different paths in the /usr/lib/ folder depending on whether the chipset used by your system. The following command should help you find the path to the PortAudio library on your device.

find -P /usr/lib -name libportaudio.so

For Raspberry Pi, likely your path is one of the following.

For 32-bit Raspbian

PORTAUDIO_LIB_PATH=/usr/lib/arm-linux-gnueabihf/libportaudio.so

For 64-bit Raspbian

PORTAUDIO_LIB_PATH=/usr/lib/aarch64-linux-gnu/libportaudio.so

Step 4: Build the AVS Device SDK

Use the cmake command to build the SDK. CMake is a build tool that manages app dependencies and creates native make files suitable for your SDK project. This section shows how to pass CMake parameters to enable PortAudio and GStreamer.

  1. The following CMake command builds the dependencies for your sample and enables GStreamer and PortAudio.

     cd ~/sdk-folder/sdk-build
     cmake ~/sdk-folder/sdk-source/avs-device-sdk \
     -DGSTREAMER_MEDIA_PLAYER=ON \
     -DPORTAUDIO=ON \
     -DPKCS11=OFF \
     -DPORTAUDIO_LIB_PATH=$PORTAUDIO_LIB_PATH \
     -DPORTAUDIO_INCLUDE_DIR=/usr/include \
     -DCMAKE_BUILD_TYPE=DEBUG
    
  2. Build the SDK Sample App.

     make SampleApp
    
    Notes

    The command make SampleApp uses a single thread for compilation. You can speed up compilation with more threads by adding the -j2, -j4, or -j8 make flag, depending on your processor.

    The make SampleApp command only builds the SDK Sample App. To build the entire SDK— including unit tests— run the make command instead.

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 ~/sdk-folder/sdk-source/avs-device-sdk/tools/Install.

To set up your SDK configuration file

  1. Place the config.json file you downloaded in the ~/sdk-folder/sdk-source/avs-device-sdk/tools/Install directory.
  2. Run genConfig.sh script to generate your config. When you run the script, include all the parameters shown in the following code example.

cd ~/sdk-folder/sdk-source/avs-device-sdk/tools/Install

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

Step 6: Set up your microphone

Update your ~/.asoundrc file to include the following lines to get the microphone work.

```
pcm.!default {
  type asym
   playback.pcm {
     type plug
     slave.pcm "hw:0,0"
   }
   capture.pcm {
     type plug
     slave.pcm "hw:1,0"
   }
}
```

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. Start the Sample App.

     export PA_ALSA_PLUGHW=1 
     cd ~/sdk-folder/sdk-build/
     ./SampleApplications/ConsoleSampleApplication/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. Sign 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 Console 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.

export PA_ALSA_PLUGHW=1 
cd ~/sdk-folder/sdk-build/
./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json 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 details about fixing common issues, see Troubleshooting the AVS Device SDK Common Issues.