Set up the AVS 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'll 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 - You download this version of the SDK later in the tutorial.

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

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 left 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 3rd party 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 do not have to go through the authorization process again. If you close the sample app, start it again by re-running the start sample script. startsample.bat

    Note

    if you exit out of sample app using 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 using tap-to-talk

This sample app does not 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 re-authorize your sample app. It also exits the application.
Quit q+Enter

Optional configurations

To run the sample app manually: Open the MinGW64 shell. 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:

Add <msys64_installed_path>/mingw64/bin into the path.

For this option, 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 the alexa_sdk/build folder.

Troubleshooting

See the Troubleshooting Guide.