Skip to content

macOS Quick Start Guide

michrose edited this page Jul 23, 2019 · 57 revisions

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

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

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

Get started

  1. Make sure that you have the latest version of Homebrew:

    brew update
  2. 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
  3. 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
  4. 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.

  5. 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
  6. 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
  7. Obtain the correct PKG_CONFIG_PATH path and modification:

    brew info openssl
    
  8. Update the libffi package configuration path to the path that you just obtained:

    export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/_path-to-openssl_/lib/pkgconfig:$PKG_CONFIG_PATH
    

Build the sample app

  1. 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
  2. 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, both which come with the SDK, to authorize the sample app with the Alexa cloud using Login with Amazon (LWA). These 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 that is used to modify AlexaClientSDKConfig.json, using a few arguments. 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.
  1. 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/
  2. Next, create a database directory; this is the dynamic database used by AlexaClientSDKConfig.json:

    cd Users/username/my_project/build/Integration/ mkdir database
  3. 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

  1. Navigate to your build folder, and initialize the SampleApp:

    cd Users/username/my_project/build/
    ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json
  2. 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}       #
################################################################################################
  1. Use a browser to navigate to the URL specified in the message from the sample app.
  2. If requested to do so, authenticate using your Amazon user credentials.
  3. Enter the code specified in the message from sample app.
  4. Select “Allow”.
  5. 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!       #
########################################
  1. 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:

  1. Open ~/.bash_profile. Add these aliases and save:
    IMPORTANT: Make sure you update the paths to match your folder structure.
    alias alexac="/Users/username/my_project/build/SampleApp/src/SampleApp build/Integration/AlexaClientSDKConfig.json"
    alias alexacdebug="/Users/username/my_project/build/SampleApp/src/SampleApp /Users/username/my_project/build/Integration/AlexaClientSDKConfig.json DEBUG9"
  2. After you've added these aliases, make sure to activate your ~/.bash_profile:
    source ~/.bash_profile
  3. Now the sample app can be launched with this single command:
    alexac  

Common issues

See the Troubleshooting Guide.

Additional resources

You can’t perform that action at this time.