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:
- Set up your Ubuntu environment
- Download and build the APL Client Library
- Download and build the AVS Device SDK and IPC Server App
Note: This quick start guide doesn't include instructions to enable wake word.
- Set up the IPC Server Sample App
Note: Full use of the IPC Server Sample App requires a connected client application, for which Amazon recommends the Alexa Smart Screen Web Components framework and its Sample Web Application. For more details on using these applications to complete your Alexa smart screen integration, see Use the Smart Screen Sample Apps.
- Start the IPC Server Sample App
- 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.
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.
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.
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.
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.
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.
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:
sudo npm install --global yarn
5. Set environment variables for PortAudio
and cURL
.
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.
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.
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.
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
-j4
or -j8
in the command above.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.
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.
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
-j4
or -j8
in the command above.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.
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
-j4
or -j8
in the command above.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
.
AlexaClientSDKConfig.json
before you run genconfig.sh
. Running the genConfig.sh
script overwrites the values contained in your AlexaClientSDKConfig.json
file. 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.
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.
$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
- Complete the steps in the Alexa Smart Screen Web Components Quick Start Guide.
When you have built both applications, you can complete authorization, and then test common interactions.
To complete the authorization, and test common interactions
- Complete the steps in Use the Smart Screen Sample Applications.
Related topics
- Alexa Device SDK Overview
- Alexa Smart Screen Web Components
- Troubleshooting AVS Device SDK Common Issues
- Alexa Smart Screen Web Components Quick Start Guide
Last updated: Nov 29, 2022