Quick Start: Set Up the IPC Server Sample App for Smart Screen Devices on Raspberry Pi


The following quick start guide shows you how to set up the Alexa Voice Service (AVS) Device SDK on a Raspberry Pi from source. This process includes installing, building, authorizing, and running the SDK. When finished, you have a working sample app to test interactions with Alexa. Note that these instructions don't build the SDK with a wake word. Instead, you activate Alexa using a tap-to-talk command.

Before you get started, see the SDK Overview to understand how the SDK works. This quick start guide is applicable to both beginners and advanced users of the SDK. However, you should have some basic knowledge of Linux.

Prerequisites

You must meet the following prerequisites before you begin this quick start guide.

  • Raspberry Pi – Raspberry Pi 3B or 4.
  • Raspbian Bullseye OS or newer– 32-bit version of Bullseye desktop. If you have a Raspberry Pi 4, you can also use the 64-bit version of Bullseye desktop.
  • Micro SD card – Minimum 8 GB.
  • Microphone – Usually a USB 2.0 microphone or headset work best.
  • Speaker – Any compatible speaker or headset (3.5mm audio jack, USB, or HDMI).
  • Keyboard and mouse – Any compatible USB keyboard and mouse.
  • Display – HDMI monitor or remote SSH.
  • Internet connection – Ethernet or Wi-Fi connection.
  • Raspberry Pi fan (recommended) – Any compatible fan. Without a fan, the Raspberry Pi might overheat during compilation.
  • AVS Device SDK 3.0 or higher – The instructions in this quick start guide download the latest version of the SDK that's available.
  • Python3 – Minimum version 3.0.x.
  • Minimum dependencies – The IPC Server Sample App relies on external libraries to compile. For more details about the external libraries you must install, see AVS Device SDK Dependencies and IPC Server Sample App Dependencies.
  • Registered product with AVS – You must register your product with Alexa Voice Service. After you have registered your product, save the config.json for “Other devices and platforms” because you need it to complete this quick start guide. This file contains the client ID for your Alexa Voice Service product and is used as part of the authorization between Alexa Voice Service and your device.

Steps to set up the AVS Device SDK on Raspberry Pi for smart screen devices

To set up the AVS Device SDK on Raspberry Pi, complete the following steps:

  1. Set up your Raspberry Pi environment
  2. Download and build the APL Client Library
  3. Download and build the AVS Device SDK and IPC Server App
  4. Set up the IPC Server Sample App
  5. Set up your microphone
  6. Start the IPC Server Sample App
  7. Connect a client application

Step 1: Set up your Raspberry Pi environment

The following instructions use your home directory represented by $HOME. If you want to store the SDK under a different path, update the commands accordingly.

To set up your Raspberry Pi environment

1. Open your Raspberry Pi Terminal and create your SDK folder structure.

Copied to clipboard.

cd $HOME
mkdir sdk-folder

cd sdk-folder
mkdir src sdk-build sdk-install db apl-build ipc-server-app-build third-party

2. Update your Raspberry Pi package list and make sure your packages are running the latest version.

Copied to clipboard.

sudo apt-get update && sudo apt-get upgrade

3. Install the core SDK dependencies. The AVS Device SDK uses external libraries to handle the following functionality:

  • Maintain an HTTP/2 connection with AVS.
  • Play Alexa text-to-speech (TTS) and music.
  • Record audio from the microphone.
  • Store records in a database.

a. Install the following core SDK dependencies.

Copied to clipboard.

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

b. Install asio.

Copied to clipboard.

cd $HOME/sdk-folder/third-party
sudo apt-get -y install libasio-dev --no-install-recommends

c. Install the commentjson Python package. You must have commentjson to parse comments in AlexaClientSDKConfig.json.

Copied to clipboard.

pip install commentjson

d. Download and extract websocketpp version 0.8.2.

Copied to clipboard.

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

For more details about the external libraries you need, see AVS Device SDK Dependencies.

4. Install Node.js 14 or higher from source.

Copied to clipboard.

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs

After you install npm, you can run the following both to install and upgrade Yarn:

Copied to clipboard.

sudo npm install --global yarn

5. Set environment variables for PortAudio and cURL.

Copied to clipboard.

PORTAUDIO_LIB_PATH=$(find -P /usr/lib -name libportaudio.so)
CURL_LIBRARY_PATH=$(find -P /usr/lib -name libcurl.so)
CURL_INCLUDE_DIR=$(find -P /usr/include -name curl)

In addition, you need to set the directory for C include files for PortAudio. Usually, these are located in the /usr/include path.

Copied to clipboard.

PORTAUDIO_INCLUDE_DIR=/usr/include

Step 2: Download and build the APL Client Library

The AVS SDK IPC Server Sample App implements the Alexa Presentation Language (APL) Client Library runtime for rendering APL.

For build prerequisites, see prerequisites.

To download and build the APL Client Library

1. Change directory into your APL build folder.

Copied to clipboard.

cd $HOME/sdk-folder/apl-build

2. Follow steps one through five in the Sandbox Installation Steps in the APL Client Library README. Make sure that you use the release tag v2023.1.0.

3. Perform the Export the client library step from the same APL Client Library README. For example, you can export your APL client library to $HOME/sdk-folder/apl-build/apl-exports. In step 3.3, you need this export path.

Step 3: Download and build the AVS Device SDK and IPC Server Sample Application

1. Locate the AVS Device SDK on GitHub, and then clone the SDK into the src folder by using the following commands.

Copied to clipboard.

cd $HOME/sdk-folder/src
git clone --single-branch --branch v3.0.0 https://github.com/alexa/avs-device-sdk.git

Build the SDK by using the CMake Parameters command. CMake is a build tool that manages app dependencies and creates native make files suitable for your SDK project. This section shows how to pass CMake parameters to enable PortAudio and GStreamer.

2. The following CMake command builds the SDK dependencies for your Sample App.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-build
cmake $HOME/sdk-folder/src/avs-device-sdk \
  -DGSTREAMER_MEDIA_PLAYER=ON \
  -DPORTAUDIO=ON \
  -DPKCS11=OFF \
  -DPORTAUDIO_LIB_PATH=$PORTAUDIO_LIB_PATH \
  -DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO_INCLUDE_DIR \
  -DCMAKE_INSTALL_PREFIX=$HOME/sdk-folder/sdk-install \
  -DCMAKE_BUILD_TYPE=DEBUG \
  -DRAPIDJSON_MEM_OPTIMIZATION=OFF \
  -DINSTALL_COMMON_SAMPLE_LIBS=ON

make

make install

3. The following CMake command builds the dependencies for IPC Server Sample Application, including the APL Client Library built in Step 2: Download and build APL Client Library. In the following example command, the DAPL_CLIENT_INSTALL_PATH is set to $HOME/sdk-folder/apl-build/apl-exports from step 2.3.

Copied to clipboard.

cd $HOME/sdk-folder/ipc-server-app-build

cmake $HOME/sdk-folder/src/avs-device-sdk/SampleApplications/IPCServerSampleApplication/ \
    -DCMAKE_PREFIX_PATH=$HOME/sdk-folder/sdk-install \
    -DWEBSOCKETPP_INCLUDE_DIR=$HOME/sdk-folder/third-party/websocketpp-0.8.2 \
    -DCMAKE_BUILD_TYPE=DEBUG \
    -DGSTREAMER_MEDIA_PLAYER=ON \
    -DPORTAUDIO=ON \
    -DPORTAUDIO_LIB_PATH=$PORTAUDIO_LIB_PATH \
    -DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO_INCLUDE_DIR \
    -DRAPIDJSON_MEM_OPTIMIZATION=OFF \
    -DPKCS11=OFF \
    -DDISABLE_WEBSOCKET_SSL=ON \
    -DAPL_CLIENT_INSTALL_PATH=$HOME/sdk-folder/apl-build/apl-exports \
    -DCMAKE_CXX_FLAGS=-Wno-error=unused-variable

make

Step 4: Set up your Alexa Client configuration file

Before you can run the sample app, you must set up a SDK configuration file named AlexaClientSDKConfig.json. This file contains your SDK settings to authorize your device with Amazon.

To set up this file, you run a configuration script named genconfig.sh. This script is located in your SDK download package at $HOME/sdk-folder/src/avs-device-sdk/tools/Install.

To set up your SDK configuration file

1. Place the config.json file you downloaded in the $HOME/sdk-folder/src/avs-device-sdk/tools/Install directory.

2. Run genConfig.sh script to generate your config. When you run the script, include all the parameters shown in the following code example.

Copied to clipboard.

cd $HOME/sdk-folder/src/avs-device-sdk/tools/Install

./genConfig.sh \
config.json \
12345 \
$HOME/sdk-folder/db \
$HOME/sdk-folder/src/avs-device-sdk \
$HOME/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json \
-DSDK_CONFIG_MANUFACTURER_NAME="raspberrypi" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="raspberrypi"

Step 5: Set up your microphone

Update your /.asoundrc file to include the following lines to get the microphone working.

Copied to clipboard.

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

Step 6: Start the IPC Server Sample App

In addition to the AlexaClientSDKConfig configured in Step 4, the IPC Server Sample App requires a separate config file for managing the websocket server implemented by the application, and other smart screen features. For more details, see AVS SDK IPC Server Sample App Config.

The app includes a default config file that you use in the following procedure, and several optional samples to demonstrate different device modalities.

To run the IPC Server Sample App

1. To start the IPC Server Sample App, open the Terminal, and then run the following command, providing paths to both configuration files.

Copied to clipboard.

$HOME/sdk-folder/ipc-server-app-build/src/IPCServerSampleApp \
-C $HOME/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json \
-C $HOME/sdk-folder/src/avs-device-sdk/SampleApplications/IPCServerSampleApplication/config/IPCServerSampleAppConfig.json \
-L INFO

2. Wait for the following console logs to appear, indicating that the build was successful, the app was able to start and it is now trying to connect to complete authorization. This authorization can be completed later, after you connect a client application in Step 7.

  #############################
  #       Connecting...       #
  #############################
  ...
  ##################################
  #       NOT YET AUTHORIZED       #
  ##################################


  ################################################################################################
  #       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: XXXXXX       #
  ################################################################################################

  #################################################
  #       Checking for authorization (1)...       #
  #################################################

3. If you receive any error messages, check Troubleshooting the Alexa Device SDK, which addresses several common sample app execution errors. Or, you can try running the app again, changing the verbosity level from INFO to DEBUG9.

The IPC Server Sample App is now connected to Alexa and is ready to locally broadcast and receive IPC Client Framework messages to a connected client.

Step 7: Connect a client application

Now that you’ve successfully built and started your IPC Server Sample App, you need a client that implements the IPC Client Framework to handle input to the server, complete visual rendering, and manage other interactions with Alexa.

For most smart screen device makers, Amazon recommends the Alexa Smart Screen Web Components framework and Sample Web Application for your client.

At this time, Amazon doesn't provide any alternative clients or visual rendering stacks.

To build the Sample Web App and connect the Sample Web App to the IPC Server Sample App

When you have built both applications, you can complete authorization, and then test common interactions.

To complete the authorization, and test common interactions


Was this page helpful?

Last updated: May 22, 2023