Set Up the AVS Device SDK on Windows 10

The following guide provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on Windows 10 64 bit. This includes installing, building, authorizing, and using the Alexa Voice Service (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 Alexa Built-in product with the Amazon developer portal.
  2. Install and configure AVS Device SDK dependencies on Windows.
  3. Build the SDK and run the AVS sample app.
Note

This guide doesn't include instructions to enable a wake word. Instead, you initialize Alexa with a keyboard command

Prerequisites

Required hardware

  • Microphone - To interact with Alexa you must plug in an external microphone.
  • External speaker or headset - Your audio source.

Required software

  • Windows 10 64 bit
  • Alexa Voice Service SDK 1.17 or higher - The instructions in this tutorial download the latest version of the SDK that's available.

Register your product with Amazon

Before you install the AVS Device SDK, you must Register an AVS Product and Create a Security Profile. After your device is registered, you download a config.json file that 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 Windows environment

You must set up MSYS2 (64-bit) and Pacman before the AVS Device SDK runs on Windows. MSYS2 is a software distribution and building platform for Windows.

This guide presumes that you use the MING64 home directory as your starting point – C:/msys64/home/<user_name>. If you choose to use different folder names, update the home commands throughout the guide accordingly.

  1. Download and run the MSYS2 (64-bit) installer. This installs three different shells: MSYS2, MinGW32, and MinGW64. After the installation finishes, open the MinGW64 shell. You should be in the home directory.

  2. Update the Pacman package list included with MSYS2. .

     pacman -Syu
    
  3. Finish updating Pacman. Close and reopen MinGW64, and run this command.

     pacman -Su
    

Download the configuration scripts

Open the MinGW64 shell and run these three commands in a single block statement. This downloads three AVS Device SDK configuration scripts into your MinGW64 home directory. These scripts are later used to download and authorize the AVS Device SDK and sample app.

 wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/setup.sh \
 wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/genConfig.sh \
 wget https://raw.githubusercontent.com/alexa/avs-device-sdk/master/tools/Install/mingw.sh

Optional: Enable Webvtt Captions

To enable captions in your build

  1. Clone the Alexa WebVTT project from the following Alexa webvtt GitHub repository. Save the files somewhere convienent, such as in a directory inside your SDK project.
  2. Follow the Windows 10 instructions on GitHub to generate a .dll file for the WebVTT library.
  3. Open the AVS SDK setup.sh script file in a text editor.
  4. Find the CMake command under the BUILDING SDK section and add the following flags.

     -DCAPTIONS=ON
     -DLIBWEBVTT_INCLUDE_DIR=<path to your WebVTT include dir>
     -DLIBWEBVTT_LIB_PATH=<path to the WebVTT .dll that you generated by following the instructions on the WebVTT github page>
    

    Make sure you update the path parameters to point to the same locations that you downloaded the WebVTT files to in step 1 and 2 of these instructions. For example, /home/alexa/webvtt/build/src/webvtt/libwebvtt.dll and /home/alexa/webvtt/include/.

Download the SDK and dependencies

  1. Move your config.json file to your MinGW64 home directory (C:/msys64/home/<user_name>).
  2. Open the MinGW64 shell and run setup.sh using your config.json file and a device serial number (DSN) as arguments. If these fields are blank, the SDK generates a default value of 123456.

     bash setup.sh config.json -s 998987
    
  3. The AVS Device SDK terms and Terms and Agreements are shown. This downloads the SDK, sample app and any required dependencies. It might take a few minutes to finish downloading all the assets.

Authorize the sample app

  1. Start the sample app by running startsample.bat. This script is a batch file, not a bash script. You run it from the Windows command line or by double-clicking it in Windows Explorer.

  2. Wait for the sample app to display a confirmation message.
    ##################################
    #       NOT YET AUTHORIZED       #
    ##################################
    ################################################################################################
    #       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
    ################################################################################################
    
  3. Use a browser to navigate to the URL specified in the message from the sample app.
  4. If requested to do so, authenticate using your Amazon user credentials.
  5. Enter the code specified in the message from sample app.
  6. Select Allow.
  7. Wait for the sample app to report that it's authorized, and that Alexa is idle.
    ###########################
    #       Authorized!       #
    ###########################
    ########################################
    #       Alexa is currently idle!       #
    ########################################
    
  8. You are now ready to talk to Alexa. The next time you start the sample app, you don't have to go through the authorization process again. If you close the sample app, start it again by rerunning the start sample script. startsample.bat

    Note

    if you exit out of sample app with the k command, the database clears and you have to reauthorize your client. The k command resets your device.

Use the sample app

Now that the sample app is running, you can talk to Alexa.

Interact with Alexa by using tap-to-talk

This sample app doesn't use a wake word. Instead, press T+Enter to talk to Alexa. This command simulates a Tap-to-Talk interaction, where the tap is equivalent to saying the Alexa wake word. To interact with the sample app, you might have to connect a microphone to your computer. A standard pair of earbuds with a microphone attached should work.

For example:

You (T+Enter): "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 command erases any data stored on the device and you have to reauthorize your sample app. It also exits the app.
Quit q+Enter

Optional configurations

To run the sample app manually

Open the MinGW64 shell and run the following commands:

cd <msys64_installed_path>/alexa_sdk/build/bin
./SampleApp.exe ../Integration/AlexaClientSDKConfig.json DEBUG9

To run the sample app using the Windows command line

  1. Add <msys64_installed_path>/mingw64/bin to your Windows path.
  2. Use mingw32-make.exe instead of make.

To build the SDK after making custom changes

Open the MinGW64 shell, and run make inside of the alexa_sdk/build folder.

Troubleshooting

See the Troubleshooting Guide.