Raspberry Pi Quick Start Guide with Script

Want to see the AVS Device SDK in action? This guide is designed to have a working sample running on a Raspberry Pi 3 running Raspbian Stretch with Desktop in less than an hour.

This guide uses a handful of scripts to download, build, and run the AVS Device SDK with wake word detection enabled. If you'd like to build from scratch, we also provide step-by-step instructions that will walk you through downloading dependencies, running the authorization service, and running the sample app in debug mode.

Prerequisites

Required Hardware

1. Raspberry Pi 3 (Recommended) or Pi 2 Model B (Supported) - Buy at Amazon - Pi 3 or Pi 2.
2. Micro-USB power cable for Raspberry Pi.
3. 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).
4. 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
5. External Speaker with 3.5mm audio cable - Buy on Amazon
6. A USB Keyboard & Mouse, and an external HDMI Monitor - we also recommend having a USB keyboard and mouse as well as an HDMI monitor handy if you're unable to remote(SSH) into your Pi.
7. Internet connection (Ethernet or WiFi)
8. (Optional) WiFi Wireless Adapter for Pi 2 (Buy on Amazon). Note: Pi 3 has built-in WiFi.
9. You can use any HDMI monitor and USB Keyboard/Mouse for these tutorials.

If your Raspberry Pi is not running Raspbian Stretch With Desktop use these instructions to upgrade. If you choose to build with Raspbian Jessie, you need to build certain dependencies from source (see commit a5646fc for instructions).

Get started

1. Copy and paste the following command into your terminal window and hit return to upgrade apt-get:

   sudo apt-get upgrade

2. Download the installation and configuration scripts. Copy and paste the following into your terminal and hit return:

   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

Build with Bluetooth (optional)

Building with Bluetooth is optional, and is currently limited to Linux and Raspberry Pi; A2DP-SINK and AVRCP profiles are supported. 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>

Authorization

Before you can use the Device SDK sample app, you'll need to authorize it with the Alexa cloud in order to leverage the full range of Alexa capabilities and features available to the sample app.

Prerequisites

You must register an AVS Product and Create a Security Profile, if you haven't already.

Note: The product must be enabled for code-based linking.

Download your credentials

Move the config.json file that you downloaded when you created your Security Profile to your home directory. Using the file manager, copy this file from the /downloads folder and place it in your home/pi folder.

Run the installation script

1. Run the setup.sh script that you downloaded earlier, using config.json and the device serial number (DSN) as arguments.

   For example:

   cd /home/pi/
   sudo bash setup.sh config.json -s 998987
   

Note: If you don't supply a DSN, then the default value 123456 will be generated by the SDK.

Select "AGREE" when it prompts you to accept the licensing terms from our third-party libraries. Unless, of course, you disagree!

This will kick off the installation process which could take over 20 minutes. Note that about 15 minutes into the install, it's going to pause and ask you to accept Sensory Wake Word's terms and conditions (you'll need to hit "return" and then type "yes" to accept).

Finish authorization using Login with Amazon

Your Raspberry Pi now has the AVS Device SDK installed and your credentials loaded, but your device still needs a refresh token to enable your client to maintain a connection to the Alexa Voice Service in the cloud. If you design an Alexa built-in product and ship a million of them to your customers, they can all use the same Client ID and ProductID - but each individual device will require a unique refresh token to authenticate with AVS through Login With Amazon (LWA).

1. Navigate to your home directory and initialize the sample app:

   cd /home/pi/
   sudo bash startsample.sh

2. 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}     #
   ############################################################################################

3. Use a browser to navigate to the URL specified in the message from the sample app.
4. Authenticate using your Amazon user credentials.
5. Enter the code specified in the message from sample app.
6. Select “Allow”.
7. Wait (it may take as long as 30 seconds) for CBLAuthDelegate to successfully get an access and refresh token from Login With Amazon (LWA). At this point the sample app will print a message like this:

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

8. 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.

Talk with Alexa

If the sample app isn't already running, you'll need to initialize the sample app:

```sh
cd /home/pi/
sudo bash startsample.sh
```

Now, to test your prototype, say "Alexa" into the microphone to trigger the Wake Word Engine; make sure that your headphones or speakers are plugged in.

When you say ""Alexa..."", you should see a bunch of messages scroll in your terminal window. One of those will show the status changing to Listening, indicating the wake word has been recognized. Then say "Tell me a joke." If Alexa responds with Thinking..., then Speaking, you have a working prototype… and probably, a very bad joke.

Run integration and unit tests

After you've built the AVS Device SDK, we recommend running integration and unit tests to make sure that the SDK is functioning as designed; to do this run:

sudo bash test.sh

Updating the SDK

To update the SDK, follow these instructions.