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
   Note: This quick start guide doesn't include instructions to enable wake word.
4. 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.
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.

2. Update your Ubuntu package list.

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.

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

c. Download and extract websocketpp version 0.8.2.

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

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

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

5. Set environment variables for PortAudio and cURL.

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

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.

For build prerequisites, see prerequisites.

To download and build the APL Client Library

1. Change directory into your APL build folder.

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.

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.

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.

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.

Parameter descriptions  

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.

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: May 22, 2023