Raspberry Pi Quick Start Guide

Complete the following step-by-step instructions to set up the Alexa Smart Screen SDK on a Raspberry Pi running Raspbian with Desktop. The instructions guide you through obtaining the SDK, installing and building the SDK, and running the included sample app.

Hardware and software requirements

Raspberry Pi

  • CPU
    • Quad Core
    • 1.2 GHz
    • ARMv8 recommended (ARMv7 minimum)
  • GPU
    • OpenGL ES 2.0
    • 1080p30 H.264/MPEG-4 AVC high-profile decoder (only necessary if you want the device to display video)
  • Flash storage
    • 100 MB available for Alexa
  • RAM
    • 1 GB, 300 MB available for Alexa (100 MB when you can reuse a running browser)

Operating system

Browser

A browser built on the Webkit/Chromium-based web engine that supports the following features:

Additional required hardware

  • Micro-USB power cable for Raspberry Pi
  • Micro SD card (Minimum 16 GB, recommended 32 GB)
  • USB 2.0 mini microphone - Raspberry Pi doesn't have a built-in microphone; to interact with Alexa you need an external one to plug in.
  • Earbuds or external speaker with 3.5-mm audio cable
  • USB keyboard & pointer (such as a mouse)
  • HDMI monitor
  • Internet connection - Ethernet or 2.4 GHZ Wi-Fi

Procedure overview

The following task list outlines the procedure that you must follow to obtain, install, and build the Alexa Voice Service (AVS) Device SDK and the Alexa Smart Screen SDK to get the Smart Screen SDK sample app up and running on your computer.

Step 1: Register an AVS device on the developer portal and create a security profile

Before you can set up your development environment on your Raspberry Pi, you must Register your prototype and create a security profile. Upon completion, download the config.json file that contains your client ID and client secret. You need your client ID and client secret to retrieve access and refresh tokens to authorize your interactions with Alexa. Save the config.json file somewhere easily accessible. You will need this file in the following steps.

Step 2: Set up your development environment

Before you can download and install the AVS Device SDK and the Alexa Smart Screen SDK, you must set up your development environment on your Raspberry Pi.

To set up your development environment on your Raspberry Pi

  1. Open a command prompt, and enter the following command to make sure you have at least Buster.
     more /etc/os-release
    

    For example, for Buster, you should see the following output.

       PRETTY_NAME="Raspbian GNU/Linux 10 (buster)"
       NAME="Raspbian GNU/Linux"
       VERSION_ID="10"
       VERSION="10 (buster)"
       VERSION_CODENAME=buster
       ID=raspbian
       ID_LIKE=debian
       HOME_URL="http://www.raspbian.org/"
       SUPPORT_URL="http://www.raspbian.org/RaspbianForums"
       BUG_REPORT_URL="http://www.raspbian.org/RaspbianBugs"
    
  2. Run the following command:
     sudo apt-get update
    
  3. To create a directory structure for the SDKs and dependencies, enter the following commands.
     cd /home/pi
     mkdir sdk_folder
     cd sdk_folder
     mkdir sdk-build sdk-source third-party sdk-install db
    
  4. You must install some dependencies. The AVS Device SDK requires libraries to do the following tasks:
    • Maintain an HTTP/2 connection with AVS
    • Play Alexa TTS and music
    • Record audio from the microphone
    • Store records in a database

    a. First, run the following commands.

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

    b. Second, run the following commands to install and configure PortAudio. You must have PortAudio to record microphone data.

       cd $HOME/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
    

    c. After that command has completed, run make.

       cd $HOME/sdk_folder/third-party/portaudio
       make
    

    d. Run the following command to install commentjson. You must have commentjson to parse comments in AlexaClientSDKConfig.json.

       pip install commentjson
    

Step 3: Download the AVS Device SDK, APL Core Library and Alexa Smart Screen SDK

Now you're ready to download and build the AVS Device SDK.

To download and build the AVS Device SDK

  1. To clone version 1.20.0 of the AVS Device SDK into the sdk-source folder, run the following commands:
     cd $HOME/sdk_folder/sdk-source
        
     git clone --single-branch --branch v1.20.0 git://github.com/alexa/avs-device-sdk.git
    
  2. Configure a cmake command for the AVS Device SDK and ignore any warnings about missing GTEST libraries.
     cd $HOME/sdk_folder/sdk-build
        
     cmake $HOME/sdk_folder/sdk-source/avs-device-sdk \
     -DGSTREAMER_MEDIA_PLAYER=ON \
     -DPORTAUDIO=ON \
     -DPORTAUDIO_LIB_PATH=$HOME/sdk_folder/third-party/portaudio/lib/.libs/libportaudio.a \
     -DPORTAUDIO_INCLUDE_DIR=$HOME/sdk_folder/third-party/portaudio/include \
     -DCMAKE_BUILD_TYPE=DEBUG \
     -DCMAKE_INSTALL_PREFIX=$HOME/sdk_folder/sdk-install \
     -DRAPIDJSON_MEM_OPTIMIZATION=OFF
    
  3. To build the AVS Device SDK, run the command make install. This installation will take around two hours. Ignore any warnings about things that will change in future GCC versions.
     make install
    

Step 4: Generate a configuration file

Before you can test the AVS Device SDK, you must generate a configuration file for your device.

To generate a configuration file

  1. Locate the config.json file that you downloaded when you registered your AVS device on the developer portal.

  2. Copy the config.json file to your Install folder.
     cp /config.json $HOME/sdk_folder/sdk-source/avs-device-sdk/tools/Install
    
  3. To generate the configuration file, run the following command. The default device serial number is 123456. Be sure to use a unique value for each of the devices you're testing. Also, make sure to change the "manufacturer name" and "device description" values to the actual manufacturer name and device description.
     cd $HOME/sdk_folder/sdk-source/avs-device-sdk/tools/Install 
     bash genConfig.sh config.json \
     your-device-serial-number \
     $HOME/sdk_folder/db \
     $HOME/sdk_folder/sdk-source/avs-device-sdk \
     $HOME/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json \
     -DSDK_CONFIG_MANUFACTURER_NAME="manufacturer name" \
     -DSDK_CONFIG_DEVICE_DESCRIPTION="device description"
    
  4. Open the configuration file ($HOME/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json) in a text editor, and then add the following inside the first set of curly braces.
     "gstreamerMediaPlayer":{
      "audioSink":"alsasink"
     },
    
  5. Create a backup copy of your AlexaClientSDKConfig.json file.

Step 5: Configure the microphone and speaker

A fresh Raspbian image requires updates to the ~/.asoundrc file before you can test the microphone.

To configure the microphone and speaker

  1. If there's no ~/.asoundrc file, create an empty one.

  2. Open ~/.asoundrc in a text editor, replace the contents with the following lines, and save the file.

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

Step 6: Verify the AVS Device SDK build

Before you install the APL Core Library and the Alexa Smart Screen SDK, you must verify the AVS SDK build.

To verify the AVS Device SDK build

  1. To confirm that you have installed and configured the AVS Device SDK, run the AVS Device SDK sample app and try a few test Alexa commands.
     cd $HOME/sdk_folder/sdk-build
     PA_ALSA_PLUGHW=1 ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9
    

    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}       #
        ################################################################################################
    
  2. Use a browser to navigate to the URL specified in the message from the sample app.

  3. If requested to do so, authenticate by using your Amazon user credentials.

  4. Enter the code specified in the message from the sample app.

  5. Choose "Allow."

    Wait for the sample app to report that it's authorized, and that Alexa is idle. The report will look something like this:

        ###########################
        #       Authorized!       #
        ###########################
        ########################################
        #       Alexa is currently idle!       #
        ########################################
    
  6. You can now test out the AVS Device SDK sample app.

    a. To ask Alexa a question, press t + Enter. You don't need to include "Alexa" at the start of your question. For example, try, "What time is it?" or "How is the weather?"

    b. To quit and exit the app, press q + Enter.

Step 7: Download and build the APL Core Library

The Alexa Smart Screen SDK has two components: the APL Core Library and the SDK itself. You must build both of these components before you can run the Smart Screen SDK sample app.

To learn more about the APL Core Library, see APL Core Library README.

To download and build the APL Core Library

  1. To download version 1.3.3 of the APL Core Library, run the following commands.
     cd $HOME/sdk_folder
     git clone --single-branch --branch v1.3.3 git://github.com/alexa/apl-core-library.git
    
  2. To create and enter a build directory, configure cmake, and build the APL Core Library, run the following commands.
     cd $HOME/sdk_folder/apl-core-library
     mkdir build
     cd build
     cmake ..
     make
    

Step 8: Install Alexa Smart Screen SDK dependencies

The Alexa Smart Screen SDK depends on WebSocket++, ASIO, Node.js, npm, and the dependencies of those libraries. The Alexa Smart Screen SDK client libraries have been tested with the following versions of these dependencies.

Dependency Minimum version
WebSocket++ -0.8.1
asio 1:1.10.6-3
Node.js 12

To install Alexa Smart Screen SDK dependencies

  1. To install WebSocket++, run the following command.
     cd $HOME/sdk_folder/third-party
     wget https://github.com/zaphoyd/websocketpp/archive/0.8.1.tar.gz -O websocketpp-0.8.1.tar.gz
     tar -xvzf websocketpp-0.8.1.tar.gz
    
  2. To install ASIO, run the following command.
     cd $HOME/sdk_folder/third-party
     sudo apt-get -y install libasio-dev --no-install-recommends    
    
  3. To install Node.js and npm, run the following command.
     cd $HOME/sdk_folder/third-party
     curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
     sudo apt-get install -y nodejs
    

Step 9: Download and build the Alexa Smart Screen SDK

Now you're ready to download and build the Alexa Smart Screen SDK on your Raspberry Pi.

To download and build the Alexa Smart Screen SDK

  1. To download the Alexa Smart Screen SDK, run the following command.
     cd $HOME/sdk_folder
        
     git clone git://github.com/alexa/alexa-smart-screen-sdk.git
    
  2. To create a build folder for the Alexa Smart Screen SDK, run the following command.
     cd $HOME/sdk_folder
     mkdir ss-build
     cd ss-build
    
  3. To configure cmake, run the following command.
     cmake -DCMAKE_PREFIX_PATH=$HOME/sdk_folder/sdk-install \
     -DWEBSOCKETPP_INCLUDE_DIR=$HOME/sdk_folder/third-party/websocketpp-0.8.1 \
     -DDISABLE_WEBSOCKET_SSL=ON \
     -DGSTREAMER_MEDIA_PLAYER=ON \
     -DCMAKE_BUILD_TYPE=DEBUG \
     -DPORTAUDIO=ON -DPORTAUDIO_LIB_PATH=$HOME/sdk_folder/third-party/portaudio/lib/.libs/libportaudio.a \
     -DPORTAUDIO_INCLUDE_DIR=$HOME/sdk_folder/third-party/portaudio/include/ \
     -DAPL_CORE=ON \
     -DAPLCORE_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/aplcore/include \
     -DAPLCORE_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/aplcore \
     -DYOGA_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/yoga-prefix/src/yoga \
     -DYOGA_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/lib \
      ../alexa-smart-screen-sdk
    
  4. To build the Alexa Smart Screen SDK, run the following command.
     make
    

Step 10: Test the Alexa Smart Screen SDK sample app

Now that you've installed the Alexa Smart Screen SDK, you can test it by running the sample app.

To test the Alexa Smart Screen SDK sample app

  1. To run the sample app, run the following command.
     cd $HOME/sdk_folder/ss-build
     PA_ALSA_PLUGHW=1 ./modules/Alexa/SampleApp/src/SampleApp -C \
     $HOME/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json -C \
     $HOME/sdk_folder/alexa-smart-screen-sdk/modules/GUI/config/SmartScreenSDKConfig.json -L INFO
    

    If you receive any error messages at this step, check Troubleshooting Alexa Smart Screen SDK, which addresses several common sample app execution errors. You can also try running the sample again, changing the verbosity level from INFO to DEBUG9.

  2. The first time you run the sample app, follow the instruction shown in the console to authorize Alexa with your account.

  3. On your Raspberry Pi, open a Chrome or Firefox browser window.

  4. In the browser, navigate to the following file.
     file://$HOME/sdk_folder/ss-build/modules/GUI/index.html
    

    Your web browser displays the Alexa Smart Screen splash screen.

    AlexaSplashScreen
  5. Press and hold the A key on your keyboard to interact with Alexa. For example, with your mic and speakers enabled, press and hold the A key and ask, "What time is it?" (You do not need to preface your question with "Alexa.")

    Alexa responds with the current time.

  6. To try a question with a visual component, press and hold the A key and ask, "How is the weather?"

    Alexa recites and displays the current forecast.

    WeatherForecast
  7. Try to open an interactive skill, and interact with the skill not only verbally, but through your web browser. For example, press and hold the A key and ask, "Open Kayak."

    Alexa opens the Kayak skill in your web browser.

  8. To browse flights on Kayak, click or say "Search Flights"

  9. Try some of these other questions to explore various Alexa skills. If you try more than one skill utterance, be sure to exit each one by saying, "Stop," "Cancel," or "Quit" before trying the next one.
  • "Who is Jeff Bezos?"
  • "Tell me a joke."
  • "What does a corgi look like?"
  • "Play Jeopardy."
  • "Open Food Network."

Optional features

Now that you've installed the Alexa Smart Screen SDK and tested it by running the sample app, you can add optional features, such as captions, to your device.

Add captions

The following procedure shows how to add captions to your device.

To add captions to your device

  1. Download and install webvtt in a directory that's independent of the SDK directories, for example, $HOME/captions.

  2. Build the AVS Device SDK as you did in substeps 2 and 3 of Step 3: Download the AVS Device SDK, APL Core Library and Alexa Smart Screen SDK, only this time include webvtt by adding the following flags when you configure your cmake command.
     -DCAPTIONS=ON \
     -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \
     -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
    
  3. Build the Alexa Smart Screen SDK as you did in substeps 3 and 4 of Step 9: Download and build the Alexa Smart Screen SDK, only this time include webvtt by adding the following flags when you configure your cmake command.
       -DCAPTIONS=ON \
       -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \
       -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
    
  4. Run the Alexa Smart Screen SDK sample app as you did in Step 10: Test the Alexa Smart Screen SDK sample app. Captions are not enabled by default. After opening the sample app in the browser, press the C key on your keyboard to toggle captions on. The caption setting persists across restarts.

Modify the Smart Screen SDK configuration file for your device

For information about how to use the configuration file to define your device's visual capabilities, functionality, and supported server communication, see the Smart Screen SDK Config Specification.