Set Up the AVS Device SDK on Raspberry Pi with a Script
The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on a Raspberry Pi with a script. This process includes installing, building, authorizing, and using the 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:
- Register an AVS device with the Amazon developer portal.
- Install and configure AVS Device SDK dependencies on your Raspberry Pi.
- Build the AVS sample app and run it on your Raspberry Pi.
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 a 3.5-mm audio cable.
- USB keyboard and mouse – Choose any compatible keyboard and mouse.
- Raspberry Pi fan - Choose any compatible fan. Without a fan, the Raspberry Pi might overheat.
- 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.
- The latest version of the AVS Device SDK – The instructions in this tutorial download the latest version of the SDK that's available.
- Minimum dependencies – The Alexa app relies on external libraries to compile. For more details about the external libraries you must install, see AVS Device SDK Dependencies. This tutorial downloads the required dependencies for you in the included script.
Step 1: 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 to retrieve access tokens from AVS. Your config.json
file facilitates the authorization calls between your device and AVS.
Save the config.json file somewhere accessible. You use it later in the tutorial to build the SDK.
Step 2: Download and install the SDK
Update your Raspberry Pi packages list
Verify that your Raspberry Pi OS uses the latest packages — otherwise, SDK might not run properly.
To update your Raspberry Pi packages list
-
Open a terminal and navigate to your home directory.
cd /home/pi/
-
Enter the following commands.
sudo apt-get upgrade
Download the SDK configuration scripts
You can now download the AVS Device SDK configuration scripts from the AVS Device SDK GitHub repository. These scripts download the latest version of the AVS Device SDK and install any required dependencies.
To download the SDK configuration scripts
-
Open a terminal and navigate to your home directory.
cd /home/pi/
-
Enter the following commands.
wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/setup.sh \ wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/genConfig.sh \ wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/pi.sh
Run the install script
The setup.sh
script builds the SDK and installs dependencies 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 persistent storage database.
To run the install script
-
Edit the
setup.sh
by replacinggit clone --single-branch $CLONE_URL avs-device-sdk
withgit clone -b v1.26.0 --single-branch $CLONE_URL avs-device-sdk
.Important: To use AVS Device SDK 1.26, you must replacegit clone --single-branch $CLONE_URL avs-device-sdk
withgit clone -b v1.26.0 --single-branch $CLONE_URL avs-device-sdk
in thesetup.sh
script before you perform the steps below. -
Open a terminal and navigate to your home directory.
cd /home/pi/
-
Run the
setup.sh
script using yourconfig.json
file and a device serial number (DSN) as arguments.sudo bash setup.sh config.json [-s 1234]
The Device Serial Number is unique to each instance of the SDK. In the following example, it's pre-populated with 1234. If you don't supply a DSN, the SDK generates of default value of 123456.
Note: If you get an error, make sure your config.json file is in the same folder as thesetup.sh
script. -
The AVS Device SDK Raspberry Pi Script - Terms and Agreements appear. If you agree with the terms type AGREE.
The installation starts and can take over 20 minutes.
-
At some point, the SDK installation pauses and asks you to accept the Sensory Wake Word Terms and Conditions.
When asked Do you accept this licence agreement?, type yes.
-
When the SDK finishes compiling, you see the following success message [100%] Built Target SampleApp.
Important: If your device freezes and the install process stops, your Raspberry Pi might be too hot to continue operating. In most cases, you can fix this issue by unplugging the Raspberry Pi power cord and waiting a few minutes until it cools down. After it's cooled off, boot the Raspberry Pi back up. When you get back to your desktop, re-run thesetup.sh
command to finish your install. To prevent this from happening you can buy any compatible fan. Other safe methods to cool the device might also work, such as pointing a room fan at it.Tip: If your device freezes and the install process stops, try troubleshooting suggestions.
Step 3: 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
-
Open a terminal and navigate to your home directory.
cd /home/pi/
-
Run the
startsample.sh
script.sudo bash startsample.sh
-
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} # ################################################################################################
- Open a browser, and then navigate to the URL specified in the message from the sample app.
- Log in to your Amazon developer account.
- Enter the code specified in the message from sample app.
- Select Allow.
-
Wait for the sample to authorize.
########################### # Authorized! # ########################### ######################################## # Alexa is currently idle! # ########################################
You can now use the sample app to talk to Alexa.
Step 4: Use the sample app
Now that you have a working sample app, try an interaction with Alexa. For more details about how to interact with Alexa, see Use the sample app.
Troubleshooting
For more details about fixing common issues when building with the Raspberry Pi, see Troubleshooting.
Last updated: Oct 25, 2022