Raspberry Pi Quick Start Guide

This guide provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on a Raspberry Pi 3 running Raspbian Stretch with Desktop. When finished, you'll have a working sample app to test interactions with Alexa.

Before you get started, we recommand watching Getting Started with the AVS Device SDK to establish a working knowledge of how the SDK works.

To finish this tutorial, here is what you'll do.

Register your device with Amazon.
Install and configure dependencies for the AVS Device SDK on your Raspberry Pi.
Build the SDK and run the sample app on your Raspberry Pi.

Prerequisites

Required Hardware

Raspberry Pi 3 (Recommended) or Pi 2 Model B (Supported) - Buy at Amazon - Pi 3 or Pi 2.
Micro-USB power cable for Raspberry Pi.
Micro SD Card (Minimum 8 GB) - You need an operating system to get started. NOOBS (New Out of the Box Software) is an easy-to-use operating system install manager for Raspberry Pi. The simplest way to get NOOBS is to buy an SD card with NOOBS pre-installed - Raspberry Pi 8GB Preloaded (NOOBS) Micro SD Card. Alternatively, you can download and install it on your SD card (follow instructions here).
USB 2.0 Mini Microphone - Raspberry Pi does not have a built-in microphone; to interact with Alexa you'll need an external one to plug in - Buy on Amazon
External Speaker with 3.5mm audio cable - Buy on Amazon 6.USB Keyboard & Mouse
HDMI Monitor - Alternativly, you can remote(SSH) into your Pi.
Internet connection - Ethernet or 2.4 GHZ WiFi
(Optional) WiFi Wireless Adapter for Pi 2 (Buy on Amazon). Note: Pi 3 has built-in WiFi.

Required Software

Raspbian Stretch With Desktop - You need to run Raspbian Strech to successfully complete this tutorial.
Raspbian Jessie - If you choose to build with Rasbian Jessie you need to build certain dependencies from source (see commit a5646fc for instructions).

Register your product with Amazon

Before you can run the AVS Device SDK and sample app, you need to Register an AVS Product and Create a Security Profile. Upon completion, you’ll download a config.json file that contains your client ID and client secret. These are used to retrieve access and refresh tokens to authorize your interactions with Alexa. Save the config.json file somewhere easily accessible, as you will need it in the steps below.

You can skip this step if you have a registered product you'd like to test with.

Set up your environment

Let's create a few folders to organize our files. This guide presumes that everything is built in /home/pi, which we will presume is your home directory. If you choose to use different folder names, please update the commands throughout this guide accordingly.

Open terminal and run this command from your home directory (~/):

cd /home/pi/
mkdir sdk-folder

cd sdk-folder
mkdir sdk-build sdk-source third-party application-necessities

cd application-necessities
mkdir sound-files

Install dependencies

The AVS Device SDK requires libraries to:

Maintain an HTTP/2 connection with AVS
Play Alexa TTS and music
Record audio from the microphone
Store records in a database (persistent storage)

The first step is to update apt-get. This ensures that you have access to required dependencies.

sudo apt-get update

Then run:

sudo apt-get -y install \
git gcc cmake build-essential libsqlite3-dev libcurl4-openssl-dev libfaad-dev \
libsoup2.4-dev libgcrypt20-dev libgstreamer-plugins-bad1.0-dev \
gstreamer1.0-plugins-good libasound2-dev doxygen

PortAudio is required to record microphone data. Run this command to install and configure PortAudio:

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

Once that command has finished, run make.

make

commentjson is required to parse comments in AlexaClientSDKConfig.json. Run this command to install commentjson:

pip install commentjson

Clone the AVS Device SDK and the Sensory wake word engine

Let's clone the SDK into the sdk-source folder:

cd /home/pi/sdk-folder/sdk-source
git clone git://github.com/alexa/avs-device-sdk.git

Next, let's clone the sensory wake word engine into our third-party directory:

cd /home/pi/sdk-folder/third-party
git clone git://github.com/Sensory/alexa-rpi.git

Now let's run the licensing script and accept the licensing agreement. This is required to use Sensory's wake word engine:

cd /home/pi/sdk-folder/third-party/alexa-rpi/bin/
./license.sh

Build the SDK

Run cmake to generate the build dependencies. This command declares that the wake word engine and gstreamer are enabled, and 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

NOTE: This is sample CMake command configured for the sample app. There are other CMake options available for use outside of this project, here's the full list of Build Options.

Here's the fun part, let's build! For this project we're only building the sample app. Run this command:

make SampleApp -j2

NOTE: The j2 flag allows you to run 2 proccesses in parallel, which should speed up the build. Try the -j3 or -j4 option if you're feeling bold, but you run the risk of overheating the Pi (maybe even melting it).

If you want to build the rest of the SDK, including unit and integration tests, run make instead of make SampleApp.

Set up your configuration file

`genConfig.sh`

genConfig.sh is a configuration file generator script that is included with v1.10.0 or greater of the SDK, located in the tools/Install folder (/home/pi/sdk-folder/sdk-source/avs-device-sdk/tools/Install). It uses data from config.json and the arguments below, to populate AlexaClientSDKConfig.json in order to authorize with LWA.

Follow these steps to setup AlexaClientSDKConfig.json using genConfig.sh:

Move the config.json you downloaded when you created your security profile into the tools/Install folder of the SDK.

mv ~/{{download location}}/config.json
{{path to source folder}}/avs-device-sdk/tools/Install

config.json should be populated with the clientID and productID values generate in the Security Profile process.

Example:

    {
     "deviceInfo": {
      "clientId": "amzn1.application-oa2-client.{{string}}",
      "productId": "Test_123"
     }
    }

Run genConfig.sh, including the following as arguments:
```
bash genConfig.sh config.json {device serial number} \
/{{path to database}} \
/{{path to source folder}}/avs-device-sdk \
{{path to source}}/Integration/AlexaClientSDKConfig.json
```
Example:
```
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-source/avs-device-sdk/Integration/AlexaClientSDKConfig.json
```
Parameters:
- config.json: Downloaded when you created your security profile. It should contain the following:
```
"clientId": "{OAuth client ID}"
"productId": "{product name for the device}"
```
- {{device serial number}}: You can provide your own device serial number (DSN), or use the system default (123456). The DSN can be any unique alpha-numeric string (up to 64 characters). You should use this string to identify your product or application instance. Many developers choose to use a product's SKU for this value. If you don't supply a DSN, then the default value 123456 will be generated by the SDK.
  
  For example:
```
sudo bash setup.sh config.json -s 998987
```
- {{path to database}}: Specifies where the databases will be located. Choose any folder you want.
- {{path to source folder}}: Specifies the root directory where the avs-device-sdk source code is located.
- {{path to source}}: Specifies where the source folder is, which contains the Integration/AlexaClientSDKConfig.json file.
Once AlexaClientSDKConfig.json generates, you must add a gstreamer object to it. Open AlexaClientSDKConfig.json and paste the gstreamer object at the top of the file.

   {

     "gstreamerMediaPlayer":{
       audioSink":"alsasink"
       },
     
     // the rest of the default AlexaClientSDKConfig.json configurations start here
    
     "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)
        "databaseFilePath":"${SDK_CBL_AUTH_DELEGATE_DATABASE_FILE_PATH}"
       },
    
    ...

    }

IMPORTANT: Create a backup of your AlexaClientSDKConfig.json file. Subsequent builds will reset the contents of this file.

Test the microphone

A fresh Raspbian Stretch image requires updates to /.asoundrc before we can test the microphone. With your favorite text editor, open ~/.asoundrc. For example:

Terminal editor: sudo nano ~/.asoundrc
GUI-based editor: gedit ~/.asoundrc

Then add these lines to the file and save:

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

To ensure the microphone is capturing audio data, run this command:

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

If everything works, you should see a message indicating that audio is recording. To exit, hit Control + C.

Run and authorize

Navigate to your BUILD folder, then:

Set up an environment variable and start the sample app:

cd /home/pi/sdk-folder/sdk-build
PA_ALSA_PLUGHW=1 ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json

Wait for the sample app to display a message like this:

##################################
#       NOT YET AUTHORIZED       #
##################################
################################################################################################
#       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
################################################################################################

Use a browser to navigate to the URL specified in the message from the sample app.
If requested to do so, authenticate using your Amazon user credentials.
Enter the code specified in the message from sample app.
Select “Allow”.
Wait for the sample app to report that it is authorized, and that Alexa is idle. It will look something like this:

###########################
#       Authorized!       #
###########################
########################################
#       Alexa is currently idle!       #
########################################

You are now ready to use the sample app. The next time you start the sample app, you will not need to go through the authorization process.

A couple more details:

If you exit out of sample app via the k command, the CBLAuthDelegate database will be cleared and you will need to reauthorize your client.
If you want to move this authorization to another sample app installation, you need to copy the deviceInfo object within AlexaClientSDKConfig.json to the new installation. You will also need to copy the file "/home/pi/sdk-folder/application-necessities/cblAuthDelegate.db" to the new installation, and update AlexaClientSDKConfig.json in the new installation so that the cblAuthDelegate's databaseFilePath property points to it.

Setup shortcuts

Run this command to launch the sample app. This includes the path to your configuration file and the Sensory wake word model:

cd /home/pi/sdk-folder/sdk-build/SampleApp/src
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json ../third-party/alexa-rpi/models

Enabling debug logs

IMPORTANT: If you encounter any issues, use the debug option for additional information. debug1 through debug9 are accepted values. For example:

./SampleApp /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json /home/pi/sdk-folder/third-party/alexa-rpi/models debug9

Bluetooth

Building with Bluetooth is optional, and is currently limited to Linux and Raspberry Pi. This release supports A2DP-SINK and AVRCP profiles. In order to use Bluetooth for these platforms, you must install all Bluetooth dependencies and disable any processes which obtain an incoming Bluetooth audio stream, such as:

BlueALSA

If you are using BlueALSA, you must disable Bluetooth by running this command:
```
ps aux | grep bluealsa
sudo kill <bluealsa pid>
```

PulseAudio

If you are using PulseAudio, you must disable PulseAudio Bluetooth plugins. To do this:

Navigate to /etc/pulse/default.pa (or equivalent file), and 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

Next, stop and restart PulseAudio with these commands (if auto-respawn is disabled):
```
pulseaudio --kill
pulseaudio --start
```

Additional Resources

Home

API Reference

API Reference

Quick-start Guides

Other Guides + Optimizations

Development Kits

AVS Development Kits

Resources

Issue Reporting Guide

Raspberry Pi Quick Start Guide

Prerequisites

Required Hardware

Required Software

Register your product with Amazon

Set up your environment

Install dependencies

Clone the AVS Device SDK and the Sensory wake word engine

Build the SDK

Set up your configuration file

genConfig.sh

Test the microphone

Run and authorize

Setup shortcuts

Enabling debug logs

Bluetooth

BlueALSA

PulseAudio

Additional Resources

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Home

Clone this wiki locally

`genConfig.sh`