Windows Quick Start Guide with Script

This guide provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on 64-bit Windows. When finished, you'll have a working sample app to test interactions with Alexa.

To finish this tutorial, here is what you'll need to do.

1. Register your device with Amazon.
2. Set up your Windows environment.
3. Build the SDK and run the sample app.

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

Get Started

Register your product with Amazon

Before you can run the AVS Device SDK and sample app, you need to Register an AVS Product and Create a Security Profile. Upon completion, you’ll download a config.json file that contains your client ID and client secret. These are used to retrieve access and refresh tokens to authorize your interactions with Alexa. Save the config.json file somewhere easily accessible, as you will need it in the steps below.

You can skip this step if you have a registered product you'd like to test with.

Set up your Windows environment

You must set up MSYS2 (64-bit) and Pacman before the AVS Device SDK runs on Windows.

1. Download and run the MSYS2 (64-bit) installer. MSYS2 is a software distribution and building platform for Windows. This installs three different shells: MSYS2, MinGW32, and MinGW64. You need to use the MinGW64 shell in the steps below.

2. Update Pacman, the package management system included with MSYS2. The latest version of Pacman is required to build the SDK. Open the MinGW64 shell, and run this command.

   pacman -Syu

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

   pacman -Su

Set up the SDK

Download the SDK configuration scripts

Open the MinGW64 shell and run these 3 commands in a single block statement. This downloads three AVS Device SDK configuration scripts into your MinGW64 home directory (C:/msys64/home/<user_name>). 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

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.

   bash setup.sh config.json -s 998987
   

   Note: If you don't supply a DSN, then the default value 123456 is generated by the SDK.

3. The AVS Device SDK terms and Terms and Agreements are shown. Enter AGREE. This downloads the SDK, sample app (startsample.bat) and any required 3rd party dependencies. It may take a few minutes to finish downloading all the assets.

Authorize the sample app

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

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

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 is authorized, and that Alexa is idle. It will look something like this:

###########################
#       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 need to go through the authorization process again. If you close the sample app you can start it again by re-running: startsample.bat

Note: 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. 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 simulates a tap-to-talk interaction, where the tap is equivalent to saying the Alexa wake word.

For example:

You (T+Enter): "What's the weather like?"

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

Note: To interact with the sample app, you might need to connect a microphone to your computer. A standard pair of earbuds with a microphone attached will work.

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

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.

Common Issues

See the Troubleshooting Guide.

Additional Resources

• Cmake parameters
• Unit and Integration Tests
• Updating the SDK