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.

IMPORTANT: 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).

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.

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.

Required dependencies

Starting with v1.10.0 of the SDK, we require that:

• BlueAlsa is disabled.
• PulseAudio must be installed in order to handle audio routing. PulseAudio is not installed by default.

Register a product

Before we get started, you'll need to register a device and create a security profile at developer.amazon.com. Click here for step-by-step instructions.

If you already have a registered product that you can use for testing, feel free to skip ahead.

Setup

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

   sudo apt-get upgrade

2. Download the installation and configuration scripts. We recommend running these commands from the home directory (~/) or Desktop; however, you can run the script anywhere.

   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

3. Move the config.json file that you downloaded when you created your Security Profile to your home directory.

4. Run the setup script with config.json and the device serial number (DSN) as arguments. The DSN can be any unique alpha-numeric string (up to 64 characters), and is provided by you. 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

Authorize and run

When you run the sample app for the first time, you'll need to authorize your client for access to AVS.

1. Initialize the sample app:

   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.

Integration and unit tests

You can run integration and unit tests using this command:

sudo bash test.sh

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

1. 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:

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

2. Next, stop and restart PulseAudio with these commands (if auto-respawn is disabled):

   pulseaudio --kill
   pulseaudio --start