Skip to content

Windows Quick Start Guide with Script

leala-amzn edited this page Jun 12, 2019 · 12 revisions

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.

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

Get started

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

  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. Close MinGW64. Reopen MinGW64, and run this command to finish updating Pacman:

    pacman -Su
  4. Download the installation script and configuration file. Open the MinGW64 shell, and run this command to download the installation and configuration scripts:

    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

    Note: we recommend running these commands from your home directory (C:/msys64/home/<user_name>) or your desktop, however, you can run the script anywhere.

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 configuration

  1. Move the config.json file that you downloaded when you created your Security Profile to your home directory.

  2. Using the MinGW64 shell, run the setup.sh, using config.json and the device serial number (DSN) as arguments. You can either provide your own DSN, or use the system default (123456).

    For example:

    bash setup.sh config.json -s 998987
    

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

Finish authorization using Login with Amazon

  1. Start the sample app using the startsample.bat file that you downloaded earlier. Note: this script is a batch file, and not a bash script. You can run the script either from the Windows command line, or by using the Windows File Explorer to locate the file and then double-clicking it.

  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 will not need to go through the authorization process.

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.

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 by running: `startsample.bat``

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

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

You can’t perform that action at this time.