macOS Quick Start Guide

This step-by-step guide will walk you through the process of installing, building, authorizing, and using the Alexa Voice Service (AVS) Device SDK for C++ on macOS. When finished, you'll have a sample app to test interactions with Alexa.

Important: This guide doesn't include instructions to enable wake word.

Prerequisites

Software

Python (minimum version 2.7.x)
Homebrew
XCode command line tools

Confirm that Python 2.7.x, Homebrew, and the Xcode command line tools are installed:

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

Get started

Make sure that you have the latest version of Homebrew:
```
brew update
```
Set up the SDK build environment.

Create a my_project folder, and these subfolders:
- build
- source
- third-party
- application-necessities > sound-files
Note: The following examples designate /Users/username as the SDK installation location; be sure to replace all instances of /Users/username in this guide with your explicit path.
```
cd /Users/username/
mkdir my_project

cd my_project
mkdir build source third-party application-necessities

cd application-necessities
mkdir sound-files
```

Install curl-openssl, which is required to connect to AVS via HTTP:

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

Install the SDK dependencies:
```
cd /Users/username/
brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav sqlite3 repo cmake clang-format doxygen wget git
```
Make sure that no errors occurred during the dependency installation; if any of the installations fail, run brew install individually.

Clone the SDK into the /Users/username/my_project/source folder:

cd /Users/username/my_project/source
git clone git://github.com/alexa/avs-device-sdk.git

Install and configure PortAudio (a required audio input/output library), and then make your build.

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

Set the libffi package configuration path:

export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/usr/local/Cellar/openssl/1.0.2r/lib/pkgconfig:$PKG_CONFIG_PATH"

Build the sample app

You can use CMake parameters to customize the sample app. For example, to get debug logs from the sample app, include the -DCMAKE_BUILD_TYPE=DEBUG option.

In this example, GStreamer and PortAudio are enabled, and we are creating a debug build.

cd /Users/username/my_project/build/

cmake /Users/username/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=/Users/username/my_project/third-party/portaudio/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=/Users/username/my_project/third-party/portaudio/include \
-DCMAKE_BUILD_TYPE=DEBUG

Now, you can build the sample app from your build folder by running this command:
```
 make SampleApp
```
Note: If you want to generate a full build, including unit and integration tests, run make instead of make SampleApp. You can use the arguments -j3 or j4 to run processes in parallel during make.

After you finish building the sample app, you'll need to authorize it, see the next step.

Authorization

Before you can use the Device SDK sample app, you'll need to authorize it with the Alexa cloud in order to leverage the full range of Alexa capabilities and features available to the sample app.

Prerequisites

You must register an AVS Product and Create a Security Profile, if you haven't already.

Note: The product must be enabled for code-based linking.

Set up the configuration file

You'll use the genConfig.sh script to modify the AlexaClientSDKConfig.json configuration file, which come with the SDK, to authorize the sample app with the Alexa cloud using Login with Amazon (LWA). The following dependencies are used during this process:

Dependencies

Name	Description	Location
AlexaClientSDKConfig.json	The configuration file that you'll use to authorize the sample app with the Alexa cloud.	Comes with the SDK: avs-device-sdk/Integration/AlexaClientSDKConfig.json
genConfig.sh	The configuration file generator.	Comes with the SDK: avs-device-sdk/tools/Install/genConfig.sh
config.json	Downloaded when you created a security profile during the product registration process.	Your download location.

First, move the config.json file into the avs-device-sdk/tools/Install/ directory:

mv /Users/username/Downloads/config.json /Users/username/my_project/source/avs-device-sdk/tools/Install/

Next, create a database directory; this is the dynamic database used by AlexaClientSDKConfig.json:
```
cd Users/username/my_project/build/Integration/ mkdir database
```
Now, run genConfig.sh from the Users/username/my_project/source/avs-device-sdk/tools/Install/ directory, with these arguments:

Arguments:
1. config.json - Downloaded when you created a security profile during the product registration process.
2. device_serial_number - the device serial number can be any unique alpha-numeric string (up to 64 characters). You should use the device serial number to identify your product or application instance. Many developers choose to use a product's SKU for this value.
3. db_path - The directory where the dynamic database used by AlexaClientSDKConfig.json is stored, such as: Users/username/my_project/build/Integration/database.
4. SDK source directory - Path to the avs-device-sdk source code, such as: Users/username/my_project/source/avs-device-sdk
5. AlexaClientSDKConfig.json location - Path to the AlexaClientSDKConfig.json file, such as: Users/username/my_project/build/Integration/AlexaClientSDKConfig.json.
For example:
```
cd Users/username/my_project/source/avs-device-sdk/tools/Install/

bash genConfig.sh config.json device_serial_number \
/Users/username/my_project/build/Integration/database \
/Users/username/my_project/source/avs-device-sdk \
/Users/username/my_project/build/Integration/AlexaClientSDKConfig.json
```
IMPORTANT: Create a backup of your AlexaClientSDKConfig.json file. Subsequent builds will reset the contents of this file.

2. Finish authorization using Login with Amazon

Navigate to your build folder, and initialize the SampleApp:

cd Users/username/my_project/build/
./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json

Wait for the sample app to display a message like this:

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

Use a browser to navigate to the URL specified in the message from the sample app.
If requested to do so, authenticate using your Amazon user credentials.
Enter the code specified in the message from sample app.
Select “Allow”.
Wait for the sample app to report that it is authorized, and that Alexa is idle. It will look something like this:

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

You are now ready to use the sample app! The next time you start the sample app, you won't need to go through the authorization process.

A couple more details:

If you exit out of sample app via the k command, the CBLAuthDelegate database will be cleared and you will need to reauthorize your client.
If you want to move this authorization to another sample app installation, you need to copy the deviceInfo object within AlexaClientSDKConfig.json to the new installation. You will also need to copy the file "Users/username/my_project/application-necessities/cblAuthDelegate.db" to the new installation, and update AlexaClientSDKConfig.json in the new installation so that the cblAuthDelegate's databaseFilePath property points to it.

Use the sample app

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

If you have quit the sample app, start it again:

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

Interact with Alexa using tap-to-talk

Press T+Enter, and ask Alexa something.

For example:

User taps-to-talk (T+Enter): "Alexa, what's the weather like?"

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 (no need to say "Alexa...").
Hold to talk	h+Enter, followed by your query (no need 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 will erase any data stored on the device, and you will have to re-register it. This will also exit the application.
Quit	q+Enter

Set up shortcuts

You can designate aliases to launch the sample app. To do this:

Open ~/.bash_profile. Add these aliases and save:
IMPORTANT: Make sure you update the paths to match your folder structure.

alias alexac="~/{my_project}/{build}/SampleApp/src/SampleApp {build}/Integration/AlexaClientSDKConfig.json"
alias alexacdebug="~/{my_project/build}/SampleApp/src/SampleApp ~/{my_project}/{build}/Integration/AlexaClientSDKConfig.json DEBUG9"

After you've added these aliases, make sure to activate your ~/.bash_profile:
```
source ~/.bash_profile
```
Now the sample app can be launched with this single command:
```
alexac  
```