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

The following quick start guide shows you how to set up the Alexa Voice Service (AVS) Device SDK on Ubuntu. This process includes installing, building, authorizing, and using the SDK. When finished, you have a working sample app to test interactions with Alexa.

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.

  • Microphone – If you build the SDK with a wake word, you must have a microphone.
  • External speaker or headset – Your audio source.
  • Ubuntu Desktop 20.04 – This version of Ubuntu is tested and verified to work with the SDK. You can also use console only versions like Ubuntu Server but might need to adjust the packages and follow the Troubleshooting guide to get audio playback to work properly.
  • AVS Device SDK 3.0 or higher – The instructions in this quick start guide download the latest version of the SDK that's available and are only applicable to that particular version.
  • 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 Ubuntu for smart screen devices

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

  1. Set up your Ubuntu 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. Start the IPC Server Sample App
  6. Connect a client application

Step 1: Set up your Ubuntu 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 development environment on Ubuntu

1. To create the necessary folders required to organize the files you extract from the SDK, open your Terminal, and then run the following commands.

Copied to clipboard.

cd $HOME
mkdir sdk-folder

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

2. Update your Ubuntu package list.

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 sox build-essential nghttp2 libsqlite3-dev curl libcurl4-openssl-dev libgtest-dev libssl-dev openssl \
libnghttp2-dev libasound2-dev doxygen pulseaudio portaudio19-dev libgstreamer1.0-0 libgstreamer-plugins-base1.0-dev \
gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
gstreamer1.0-libav gstreamer1.0-tools gstreamer1.0-alsa clang-format libgcrypt20-dev libarchive-dev 

b. Download and extract asio C++ library version 1.12.2.

Copied to clipboard.

cd $HOME/sdk-folder/third-party
wget https://sourceforge.net/projects/asio/files/asio/1.12.2%20%28Stable%29/asio-1.12.2.tar.gz/download -O asio-1.12.2.tar.gz
tar xvf asio-1.12.2.tar.gz
cd asio-1.12.2
./configure --without-boost && make && make install

c. 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: Set up 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.

You must build the APL Core Library before you can build APL Client Library. For details about the APL Core Library, see APL Core Library README.

To download and build the APL Core Library and APL Client Library

1. Build the APL Core Library.

Copied to clipboard.

cd $HOME/sdk-folder/src
git clone --single-branch --branch v2022.1.1 https://github.com/alexa/apl-core-library.git
cd apl-core-library
mkdir build
cd build
cmake .. -DCMAKE_POSITION_INDEPENDENT_CODE=ON
make install

2. Build the APL Client Library.

Copied to clipboard.

cd $HOME/sdk-folder/src
git clone --single-branch --branch v2022.1.1 https://github.com/alexa/apl-client-library.git

cd $HOME/sdk-folder/apl-client-build

cmake $HOME/sdk-folder/src/apl-client-library \
  -DCMAKE_INSTALL_PREFIX=$HOME/sdk-folder/apl-client-install \
  -DCMAKE_BUILD_TYPE=DEBUG \
  -DYOGA_INCLUDE_DIR=$HOME/sdk-folder/src/apl-core-library/build/yoga-prefix/src/yoga \
  -DYOGA_LIB_DIR=$HOME/sdk-folder/src/apl-core-library/build/lib \
  -DAPLCORE_INCLUDE_DIR=$HOME/sdk-folder/src/apl-core-library/aplcore/include \
  -DAPLCORE_BUILD=$HOME/sdk-folder/src/apl-core-library/build \
  -DAPLCORE_LIB_DIR=$HOME/sdk-folder/src/apl-core-library/build/aplcore \
  -DAPLCORE_BUILD_INCLUDE_DIR=$HOME/sdk-folder/src/apl-core-library/build/aplcore/include \
  -DAPLCORE_RAPIDJSON_INCLUDE_DIR=$HOME/sdk-folder/src/apl-core-library/build/rapidjson-prefix/src/rapidjson/include/ \
  -DAPL_CORE=ON  \
  -DBUILD_TESTING=OFF \
  -DSTANDALONE=ON

make -j2

make install

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 dependencies for your Sample App.

Copied to clipboard.

cd $HOME/sdk-folder/sdk-build
cmake $HOME/sdk-folder/src/avs-device-sdk \
  -DCURL_LIBRARY=$CURL_LIBRARY_PATH \
  -DCURL_INCLUDE_DIR=$CURL_INCLUDE_DIR \
  -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 -j2

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.

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 \
    -DCURL_LIBRARY=$CURL_LIBRARY_PATH \
    -DCURL_INCLUDE_DIR=$CURL_INCLUDE_DIR \
    -DRAPIDJSON_MEM_OPTIMIZATION=OFF \
    -DPKCS11=OFF \
    -DDISABLE_WEBSOCKET_SSL=ON \
    -DAPL_CLIENT_INSTALL_PATH=$HOME/sdk-folder/apl-client-install \
    -DCMAKE_CXX_FLAGS=-Wno-error=unused-variable

make -j2

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="ubuntu" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="ubuntu"

Step 5: 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 Sample App includes a default config used below, 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 6.

  #############################
  #       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 6: 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