Set Up the AVS Device SDK on Raspberry Pi with a Script

Important: Due to a recent GitHub protocol change, you must replace the git command git://github.com/alexa/avs-device-sdk.git with https://github.com/alexa/avs-device-sdk.git in the setup.sh script. The SDK team is working on an update of the setup.sh in the next SDK release. See troubleshooting for details.

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.

Note: This tutorial builds the SDK from a script. You can also build your prototype from source.

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

Important: The AVS Device SDK requires the use of Raspbian Buster. Support for Bullseye is coming soon.

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.

Important: Currently the setup.sh script requires a change to get the script working due to a Git protocol improvement requirement. If you don't edit the setup.sh, you will encounter a git clone error after running the setup.sh script. Make sure you edit the setup.sh script by following the steps described in troubleshooting before you perform the steps below.

To run the install script

Open a terminal and navigate to your home directory.
```
 cd /home/pi/
```
Run the setup.sh script using your config.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 a default value of 123456.

Note: If you get an error, make sure your config.json file is in the same folder as the setup.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.

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

When the SDK finishes compiling, you see the following success message [100%] Built Target SampleApp.

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.