Set Up the AVS SDK on macOS

The following tutorial provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on a 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:

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

Note

This tutorial doesn't include instructions to enable wake word.

Prerequisites
Set up your macOS environment
Download the AVS Device SDK
Build the AVS Device SDK sample app
Set up your configuration file
- Set up the configuration file
Run and authorize the sample app
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

Alexa Voice Service SDK 1.17 or higher – The instructions in the tutorial download the latest version of the SDK download for you.
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.

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.

Important

Save the config.json file somewhere accessible. You use it later in the tutorial to build the SDK.

Set up your macOS environment

Before you download and install the AVS Device SDK, you must set up the appropriate development environment for macOS. The following instructions presume that you set your home directory to $HOME/. If you use different folder names, update the $HOME/ commands throughout the guide.

To set up your development environment on macOS

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

Confirm that you have installed the Python 2.7.x, Homebrew, and the Xcode command line tools.
```
 python -V
 brew --version
 xcode-select --version
```
Make sure that you have the latest version of Homebrew:
```
 brew update
```

Install curl-openssl.

AVS requires this dependency to connect to HTTP.

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

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
```
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.

Install and configure PortAudio.

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

  cd ../third-party
  wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz
  tar xf pa_stable_v190600_20161030.tgz
 
  cd portaudio
  ./configure --disable-mac-universal && make

Retrieve the correct PKG_CONFIG_PATH path and modification.
```
brew info openssl
```

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

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

Download the AVS Device SDK

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

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

Build the AVS Device 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. For example, to generate debug logs from the sample app build, include the -DCMAKE_BUILD_TYPE=DEBUG option.

This example configures the following build options.

Enables GStreamer
Enables PortAudio
Specifies the curl-openssl library location
Enables debug logging

To build the sample app

Generate the build dependencies for the sample app by using cmake.

 cd $HOME/my_project/build/

 cmake $HOME/my_project/source/avs-device-sdk \
 -DGSTREAMER_MEDIA_PLAYER=ON \
 -DCURL_LIBRARY=/usr/local/opt/curl-openssl/lib/libcurl.dylib \
 -DCURL_INCLUDE_DIR=/usr/local/opt/curl-openssl/include \
 -DPORTAUDIO=ON \
 -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

Build the sample app.
```
 make SampleApp
```
Note

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

Set up your configuration file

Before you run the sample app, you must set up an AlexaClientSDKConfig.json file for your device. This file contains your SDK settings and authorizes your device with Amazon.

Set up the 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 by using genConfig.sh

Move the config.json file you downloaded into the Install folder of the SDK - /my_project/source/avs-device-sdk/tools/Install.

Create a database directory.

 mkdir $HOME/my_project/build/Integration/database

Run genConfig.sh from the $HOME/my_project/source/avs-device-sdk/tools/Install directory. Include the following arguments.
- 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 does not, 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 application instance
- /my_project/build/Integration/database – Location of the dynamic database used by AlexaClientSDKConfig.json
- /my_project/source/avs-device-sdk – The root directory of the AVS SDK source code.
- /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="ubuntu"
```
Important

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

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

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

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}       #
################################################################################################

Open a browser, and then navigate to the URL specified in the message from the sample app.
Log in to your Amazon developer account.
Enter the code specified in the message from sample app.
Select Allow.
Wait for the sample to authorize.

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

You can now use the sample app to talk to Alexa

To relaunch the sample app, run the following command again. It includes the path to your configuration file.

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

Use the sample app

Now that you have a working sample app, try an interaction with Alexa.

Interact with Alexa by using wake word

Now that you have a working sample app, try an interaction with Alexa.

For example:

User: "Alexa, what is the current weather?"

Alexa: "Right now in Portland, it's 71 degrees with sun….

Interact with Alexa by using tap-to-talk

Ask Alexa something with tap-to-talk by pressing T+Enter.

For example:

User taps-to-talk: "Alexa, what is the current weather?"

Alexa: "Right now in Portland, it's 71 degrees with sun…."

Additional options

Interaction options

Action	Command
Tap-to-talk	t+Enter, followed by your query. You don't have to say "Alexa…".
Hold-to-talk	h+Enter, followed by your query. You don't have to say "Alexa…".
Simulate button release	h+Enter
Stop an interaction	s+Enter

Playback controls

Action	Command
Play	1
Pause	2
Next	3
Previous	4

Settings

Action	Command
View available settings	c+Enter
Adjust speaker settings	p+Enter
Report firmware version	f+Enter
Help screen	i+Enter
Reset device	k+Enter This command erases any data stored on the device and you have to reauthorize your sample app. It also exits the app.
Quit	q+Enter

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 /home/pi/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json /home/pi/sdk-folder/third-party/alexa-rpi/models debug9

Troubleshooting

For more information about fixing common issues, see Troubleshooting.

Set Up the AVS SDK on macOS

Prerequisites

Required hardware

Required software

Register your AVS device with Amazon

Set up your macOS environment

Download the AVS Device SDK

Build the AVS Device SDK sample app

Set up your configuration file

Set up the configuration file

Run and authorize the sample app

Use the sample app

Interact with Alexa by using wake word

Interact with Alexa by using tap-to-talk

Additional options

Extra build options

Enable debug logs

Troubleshooting

Alexa Skills Kit

Resources

Alexa Voice Service

AVS Resources

Connected Devices

Agreements

Blogs

Support