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.
cmake
build flag when you're using it together with the Alexa Smart Screen SDK.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
- Raspberry Pi OS – Use Debian Buster.
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
- Step 2: Set up your development environment
- Step 3: Download and build the AVS Device SDK
- Step 4: Generate a configuration file
- Step 5: Configure the microphone and speaker
- Step 6: Verify the AVS Device SDK build
- Step 7: Download and build the APL Core Library
- Step 8: Download and build the APL Client Library
- Step 9: Install Alexa Smart Screen SDK dependencies
- Step 10: Download the Alexa Smart Screen SDK
- Step 11: Build the Alexa Smart Screen SDK
- Step 12: Test the Alexa Smart Screen SDK sample app
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
-
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/"
-
Run the following command:
sudo apt-get update
-
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
-
Install the AVS Device SDK dependencies
-
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
-
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
-
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
-
After that command has completed, run
make
.cd $HOME/sdk_folder/third-party/portaudio make
-
Run the following command to install
commentjson
. You must havecommentjson
to parse comments inAlexaClientSDKConfig.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
-
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
-
Configure a
cmake
command for the AVS Device SDK and ignore any warnings about missingGTEST
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
-
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.Note: You might want to use a multi-threaded build, don't do this, because doing so can cause the Raspberry Pi to overheat or run out of memory.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
-
Locate the
config.json
file that you downloaded when you registered your AVS device on the developer portal. -
Copy the
config.json
file to yourInstall
folder.cp /config.json $HOME/sdk_folder/sdk-source/avs-device-sdk/tools/Install
-
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"
-
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" },
-
Create a backup copy of your
AlexaClientSDKConfig.json
file.Important: Make sure you have a backup copy because subsequent builds reset the contents of this 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
- If there's no
~/.asoundrc
file, create an empty one. -
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
-
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} # ################################################################################################
- Use a browser to navigate to the URL specified in the message from the sample app.
- If requested to do so, authenticate by using your Amazon user credentials.
- Enter the code specified in the message from the sample app.
-
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! # ########################################
-
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
-
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
-
To create and enter a
build
directory, configurecmake
, 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
-
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
-
Navigate to the APL Client Library directory, then create and enter the build directory.
cd ~/sdk_folder/apl-client-library mkdir build cd build
-
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 \ ..
-
Build the APL Client Library
make -j8
-
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
-
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
-
To install ASIO, run the following command.
cd $HOME/sdk_folder/third-party sudo apt-get -y install libasio-dev --no-install-recommends
-
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.
-
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
-
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
-
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
-
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
toDEBUG9
. -
The first time you run the sample app, follow the instruction shown in the console to authorize Alexa with your account.
-
On your Raspberry Pi, open a Chrome or Firefox browser window.
-
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.
-
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.
-
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.
-
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.
webvtt
GitHub repository.To add captions to your device
-
Download and install
webvtt
in a directory that's independent of the SDK directories, for example,$HOME/captions
. -
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 yourcmake
command.-DCAPTIONS=ON \ -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \ -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
-
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 yourcmake
command.-DCAPTIONS=ON \ -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \ -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
-
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.
Related topics
Last updated: Sep 28, 2022