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

The following quick start guide shows you how to set up the AVS Device SDK Inter-Process Communication (IPC) Server Sample Application for smart screen devices on macOS. The instructions guide you through obtaining the SDK, installing, and building the SDK, and running the included IPC Server Sample App.

Before you get started, see the Get Started with Alexa Voice Service Device SDK 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 the Mac Terminal.

Prerequisites

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

  • Mac running OS X 12.4+– 12.4 and 12.5 are tested to work with the SDK but other versions of Mac OS X might work.
  • AVS Device SDK 3.0 or higher– The instructions in this quick start guide download the latest version of the SDK.
  • Python3– Minimum version 3.0.x.
  • Homebrew– A software package management system that simplifies installation.
  • XCode command line tools– An integrated development environment for macOS.
  • 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 macOS for smart screen devices

To set up the IPC Server Sample App for smart screen devices on macOS, complete the following steps:

  1. Set up your macOS 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 macOS 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 macOS

1. Open a Terminal window, and then create your SDK folder structure.

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 Homebrew package list.

Copied to clipboard.

brew update && brew 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.

cd $HOME
brew install curl gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav clang-format doxygen googletest openssl@1.1 portaudio node@16 sqlite3 git cmake

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

4. Set the PKG_CONFIG_PATH and environment variables.

Copied to clipboard.

echo 'export PATH="$(brew --prefix)/opt/openssl@1.1/bin:$(brew --prefix)/opt/libffi/lib/pkgconfig:$PATH"' >> $HOME/.zshrc
export PKG_CONFIG_PATH="$(brew --prefix)/opt/openssl@1.1/lib/pkgconfig:$(brew --prefix)/opt/libffi/lib/pkgconfig:$PKG_CONFIG_PATH"
echo 'export PATH="$(brew --prefix)/opt/curl/bin:$PATH"' >> $HOME/.zshrc
export PKG_CONFIG_PATH="$(brew --prefix)/opt/curl/lib/pkgconfig:$PKG_CONFIG_PATH"

5. Set environment variables for PortAudio and cURL.

Copied to clipboard.

export CURL_LIBRARY_PATH=$(brew --prefix)/opt/curl/lib/libcurl.dylib
export CURL_INCLUDE_DIR=$(brew --prefix)/opt/curl/include
export PORTAUDIO_LIB_PATH=$(brew --prefix)/opt/portaudio/lib/libportaudio.dylib
export PORTAUDIO_INCLUDE_DIR=$(brew --prefix)/opt/portaudio/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.

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
source apl-dev-env.sh
apl-build-core

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. Use the following CMake command to build the SDK library 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. Use the following CMake command to build the dependencies for IPC Server Sample App, 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

make -j2

Step 4: Set up your Alexa client configuration file

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

To set up this file, run a configuration script named genconfig.sh. This script is 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. To generate your config file, run the genConfig.sh script. When you run the script, include all the parameters 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="mac" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="mac"

Step 5: Start the IPC Server Sample App

In addition to the AlexaClientSDKConfig file 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.

GST_PLUGIN_PATH=$(brew --prefix)/lib/gstreamer-1.0/ $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