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 Debian Buster. 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

The Alexa Smart Screen SDK reference implementation relies on the browser to play APL media. It therefore requires a browser built on the WebKit/Chromium-based web engine that supports the following features:

  • ECMAScript 2015, ECMAScript 6 (ES6)
  • Must be capable of playing MP3 MPEG-2 Audio Layer III at a bit rate of 48 KBPS
  • Must be capable of playing video MPEG-4 AVC
  • HTTP/2 (RFC 7540)
  • HTML5 WebKit/Chromium-based web engine

Additional required software

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 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="Debian GNU/Linux 10 (buster)"
    NAME="Debian GNU/Linux"
    VERSION_ID="10"
    VERSION="10 (buster)"
    VERSION_CODENAME=buster
    ID=debian
    HOME_URL="http://www.debian.org/"
    SUPPORT_URL="http://www.debian.org/support"
    BUG_REPORT_URL="http://bugs.debian.org/"
    
  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. Install the AVS Device SDK dependencies

    1. First, run the following commands.

      sudo apt-get -y install \
      git gcc cmake build-essential libsqlite3-dev nghttp2 libnghttp2-dev libfaad-dev \
      libssl-dev libsoup2.4-dev libgcrypt20-dev libgstreamer-plugins-bad1.0-dev \  gstreamer1.0-plugins-good libasound2-dev doxygen
      
    2. Run the following commands to install cURL:

      cd $HOME/sdk_folder/third-party
      wget https://curl.haxx.se/download/curl-7.67.0.tar.gz
      tar xzf curl-7.67.0.tar.gz
      
      cd curl-7.67.0
      ./configure --with-nghttp2 --prefix=/usr/local --with-ssl
      
      make && sudo make install
      sudo ldconfig
      
    3. 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
      
    4. After that command has completed, run make.

      cd $HOME/sdk_folder/third-party/portaudio
      make
      
    5. Run the following command to install commentjson. You must have commentjson to parse comments in AlexaClientSDKConfig.json.

      pip install commentjson
      

Step 3: Download and build the AVS Device 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.26.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.26.0 https://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 \
    -DPKCS11=OFF
    
  3. To build the AVS Device SDK, run the command make install. This installation takes 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 Raspberry Pi OS 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 Device 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 looks 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 Client Library and the SDK itself. The APL Client Library relies on the APL Core Library.

You must build the APL Core Library before you can build APL Client Library.

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.8.1 of the APL Core Library, run the following commands.

    cd $HOME/sdk_folder
    git clone --single-branch --branch v1.8.1 https://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: Download and build the APL Client Library

Before you can build the SDK and run the Smart Screen SDK sample app, you must download and build the APL Client Library.

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

To download the APL Client Library

  1. To download version 1.8.3 of the APL Client Library, run the following commands.

    cd ~/sdk_folder
    git clone --single-branch --branch v1.8.3 https://github.com/alexa/apl-client-library.git
    
  2. Navigate to the APL Client Library directory, then create and enter the build directory.

    cd ~/sdk_folder/apl-client-library
    mkdir build
    cd build
    
  3. Configure a cmake command for the APL Client Library.

    cmake -DAPLCORE_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/aplcore/include \
    -DYOGA_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/yoga-prefix/src/yoga \
    -DAPLCORE_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/aplcore \
    -DAPLCORE_BUILD_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/aplcore/include \
    -DYOGA_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/lib \
    -DAPL_CORE=ON  \
    -DAPLCORE_RAPIDJSON_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/rapidjson-prefix/src/rapidjson/include/ \
    -DCMAKE_BUILD_TYPE=DEBUG \
    -DAPLCORE_BUILD=$HOME/sdk_folder/apl-core-library/build \
    -DBUILD_TESTING=OFF \
    -DSTANDALONE=ON \
    -DCMAKE_INSTALL_PREFIX=$HOME/sdk_folder/apl-client-library/preinstall \
    ..
    
  4. Build the APL Client Library

    make -j8
    
  5. Install the APL Client Library

    make install
    

Step 9: 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.2
ASIO 1:1.10.6-3
Node.js 14.17.4

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.2.tar.gz -O websocketpp-0.8.2.tar.gz
    tar -xvzf websocketpp-0.8.2.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_14.x | sudo -E bash -
    sudo apt-get install -y nodejs
    

Step 10: Download the Alexa Smart Screen SDK

Before you can build the SDK and run the Smart Screen SDK sample app, you must download the Alexa Smart Screen SDK.

To download and build the Alexa Smart Screen SDK

To download the Alexa Smart Screen SDK, run the following command.

cd $HOME/sdk_folder

git clone https://github.com/alexa/alexa-smart-screen-sdk.git

Step 11: Build the Alexa Smart Screen SDK

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

  1. 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
    
  2. 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.2 \
    -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_CLIENT_INSTALL_PATH=$HOME/sdk_folder/apl-client-library/preinstall \
    -DAPL_CLIENT_JS_PATH=$HOME/sdk_folder/apl-client-library/apl-client-js \
    -DPKCS11=OFF \
    ../alexa-smart-screen-sdk
    
  3. To build the Alexa Smart Screen SDK, run the following command.

    make
    

Step 12: 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 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 and build the AVS Device 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 2 and 3 of Step 11: 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 12: Test the Alexa Smart Screen SDK sample app. Captions aren't 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.


Was this page helpful?

Last updated: Sep 28, 2022