Set Up the AVS Device SDK on macOS

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on macOS. This process includes installing, building, authorizing, and using the AVS Device SDK. When finished, you have a working sample app to test interactions with Alexa.

Before you get started, see the SDK overview page to establish a working knowledge of how the SDK works.

You complete the following activities in this tutorial:

1. Register an AVS device with the Amazon developer portal.
2. Install and configure AVS Device SDK dependencies on macOS.
3. Build the AVS sample app and run it on macOS.

• Prerequisites
  • Required hardware
  • Required software
• Step 1: Register your AVS device with Amazon
• Step 2: Set up your macOS environment
• Step 3: Download the SDK
• Step 4: Build the SDK sample app
• Step 5: Set up your configuration file
• Step 6: Run and authorize the sample app
• Step 7: Use the sample app
• Extra build options
  • Enable debug logs
• Troubleshooting

Prerequisites

You must meet the following prerequisites to complete this tutorial.

Required hardware

External speaker or headset – Your audio source.

Required software

• AVS Device SDK 1.17.0 or higher – The instructions in this tutorial download the latest version of the SDK that's available.
• Python – Minimum version 2.7.x.
• Homebrew – a software package management system that simplifies installation.
• XCode command line tools – an integrated development environment for macOS.
• Minimum dependencies – The Alexa app relies on external libraries to compile. For more details about the external libraries you must install, see AVS Device SDK Dependencies.

Step 1: Register your AVS device with Amazon

Before you install the AVS Device SDK, you must register an AVS product and create a security profile.

After registering your device, you download a config.json file. This file contains your client ID and client secret. The client ID and client secret authorize your device, so you can retrieve access tokens from AVS. Your config.json file facilitates the authorization calls between your device and AVS.

Step 2: Set up your macOS environment

Before you download and install the AVS Device SDK, you must set up the appropriate development environment for macOS.

To set up your development environment on macOS

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 my_project
   
    cd my_project
    mkdir build source third-party application-necessities
   
    cd application-necessities
    mkdir sound-files
   

2. Confirm that you have installed Python 2.7.x, Homebrew, and the Xcode command line tools.

    python -V
    brew --version
    xcode-select --version
   

3. Make sure that you have the latest version of Homebrew.

    brew update
   

4. Install curl.

   AVS requires this dependency to connect to HTTP.

     cd $HOME
     brew install curl
     export PATH="/usr/local/opt/curl/bin:$PATH"
     echo 'export PATH="/usr/local/opt/curl/bin:$PATH"' >> ~/.bash_profile
   

5. Install the SDK dependencies.

     cd $HOME
     brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav sqlite3 repo cmake clang-format doxygen wget git openssl@1.1
   

   Important: Make sure that all the dependencies installed without errors. If you receive errors, you might have to install each dependency independently with the brew install command.

6. Install and configure PortAudio.

   Audio input and output don't work without this dependency.

   cd $HOME/my_project/third-party
   wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz
   tar xf pa_stable_v190600_20161030.tgz
   
   # If you use MacOS Big Sur, install the following version instead
   # tar xf pa_stable_v190700_20210406.tgz
   
   cd portaudio
   ./configure --disable-mac-universal && make
   

7. Retrieve the correct PKG_CONFIG_PATH path and modification.

   brew info openssl@1.1
   

8. Update the libffi package configuration path to the path retrieved in the previous step.

    export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/path-to-openssl/lib/pkgconfig:$PKG_CONFIG_PATH"
    echo 'export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/path-to-openssl/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bash_profile
   

Step 3: Download the SDK

Clone the SDK into the $HOME/my_project/source folder.

  cd $HOME/my_project/source
  git clone --single-branch https://github.com/alexa/avs-device-sdk.git

Step 4: Build the SDK sample app

Next you build the SDK by using your terminal.

You use CMake parameters to customize what features you want to build in the sample app.

This example configures the following build options.

• Enables GStreamer.
• Enables PortAudio.
• Specifies the curl library location.
• Enables debug logging.

To build the sample app

1. Generate the build dependencies for the sample app by using the following CMake command.

    cd $HOME/my_project/build/
   
    cmake $HOME/my_project/source/avs-device-sdk \
    -DGSTREAMER_MEDIA_PLAYER=ON \
    -DCURL_LIBRARY=/usr/local/opt/curl/lib/libcurl.dylib \
    -DCURL_INCLUDE_DIR=/usr/local/opt/curl/include \
    -DPORTAUDIO=ON \
    -DPKCS11=OFF \
    -DPORTAUDIO_LIB_PATH=$HOME/my_project/third-party/portaudio/lib/.libs/libportaudio.a \
    -DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include \
    -DCMAKE_BUILD_TYPE=DEBUG
   

2. Build the sample app.

    make SampleApp
   

   Note: The make SampleApp command only builds the SDK sample app. To build the entire SDK – including unit and integration tests – run the make command instead.

Step 5: Set up your configuration file

You configure the AlexaClientSDKConfig.json file by running the genconfig.sh configuration script. This script uses data from your config.json file to populate your AlexaClientSDKConfig.json file.

To set up AlexaClientSDKConfig.json using the genConfig.sh script

1. Move the config.json file you downloaded into the Install folder located at /my_project/source/avs-device-sdk/tools/Install.

2. Create a database directory.

    mkdir $HOME/my_project/build/Integration/database
   

3. Run the genConfig.sh script. Include all the parameters shown in the following code example.
   

   Parameter descriptions:

   • config.json – Downloaded when you created a security profile during the product registration process. It should contain a value for both the clientId and the productId. If it doesn't, you might have to recreate a product and generate a new config.json file.
   • 12345 – The Device Serial Number (DSN). Use any unique alpha-numeric string up to 64 characters. The DSN helps to identify your product or app instance
   • $HOME/my_project/build/Integration/database – Location of the dynamic database used by the AlexaClientSDKConfig.json file.
   • $HOME/my_project/source/avs-device-sdk – The root directory of the SDK source code.
   • $HOME/my_project/build/Integration/AlexaClientSDKConfig.json – Path to the AlexaClientSDKConfig.json file.
   • -DSDK_CONFIG_MANUFACTURER_NAME – Manufacturer name. Choose any relevant value.
   • -DSDK_CONFIG_DEVICE_DESCRIPTION – Description. Choose any relevant value.

      cd $HOME/my_project/source/avs-device-sdk/tools/Install
   
      bash genConfig.sh config.json 12345 \
      $HOME/my_project/build/Integration/database \
      $HOME/my_project/source/avs-device-sdk \
      $HOME/my_project/build/Integration/AlexaClientSDKConfig.json \
      -DSDK_CONFIG_MANUFACTURER_NAME="my_project" \
      -DSDK_CONFIG_DEVICE_DESCRIPTION="macos"
   

   Important: Rerunning the genConfig.sh script overwrites any values set in the AlexaClientSDKConfig.json file. If necessary, back up AlexaClientSDKConfig.json.

Step 6: Run and authorize the sample app

When you run the sample app for the first time, you must authorize it with Amazon using a generated code specific to your device.

To run and authorize the sample app

1. Navigate to your build folder, set up an environment variable, and then start the sample app.

    cd $HOME/my_project/build/
    ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json
   

2. Wait for the sample app to display the following message.

   ##################################
   #       NOT YET AUTHORIZED       #
   ##################################
   ################################################################################################
   #       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
   ################################################################################################
   

3. Open a browser, and then navigate to the URL specified in the message from the sample app.
4. Log in to your Amazon developer account.
5. Enter the code specified in the message from sample app.
6. Select Allow.

7. Wait for the sample to authorize.

   You can now use the sample app to talk to Alexa.

    ###########################
    #       Authorized!       #
    ###########################
    ########################################
    #       Alexa is currently idle!       #
    ########################################
   

Step 7: Use the sample app

Now that you have a working sample app, try an interaction with Alexa. For more details about how to interact with Alexa, see Use the sample app.

To relaunch the sample app, run the following command.

cd $HOME/my_project/build
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

Extra build options

Use the following instructions to enable additional build options.

Enable debug logs

Use the debug flag to get more information about problems you might encounter. Accepted values include DEBUG1 through DEBUG9.

For example, the following command uses the DEBUG9 logging flag.

  ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

Troubleshooting

For more details about fixing common issues, see Troubleshooting.