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:
- Register an AVS device with the Amazon developer portal.
- Install and configure AVS Device SDK dependencies on your Raspberry Pi.
- 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
-
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
-
Update your Raspberry Pi package list.
cd /home/pi/ sudo apt-get update
-
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
-
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
-
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
-
Build the SDK sample app.
make SampleApp
Note: Themake SampleApp
command only builds the SDK sample app. To build the entire SDK, including unit and integration tests, runmake
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 /home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install.
To set up your SDK configuration file
- 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.
-
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
-
Open your AlexaClientSDKConfig.json file in your terminal text editor.
nano /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json
-
Add the following
gstreamerMediaPlayer
object to the top of your file, before thecblAuthDelegate
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
-
Open your
~/.asoundrc
file in your terminal text editor.nano ~/.asoundrc
-
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" } }
- Save the file by pressing CTRL + O.
-
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
-
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
-
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} # ################################################################################################
- Open a browser, and then navigate to the URL specified in the sample app message.
- Log-in to your Amazon developer account.
- In the text box, enter the four digit code specified
{XXXX}
in the sample app message. - Select Allow.
-
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
- Install all required Bluetooth dependencies.
-
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.
Last updated: Oct 13, 2022