Windows - rreimi/alexa-avs-sample-app GitHub Wiki

On this page

  1. Prerequisites
  2. Get the required files
  3. Initial Setup
  4. Generate Self-signed Certificates
  5. Authentication Method
  6. Run the Sample App
  7. Talk to Alexa
  8. Log Out Instructions

Overview

The following instructions will walk you through the workshop to build your own alexa in your PC.

1 - Prerequisites

a. Register for an Amazon developer account

Unless you already have one, go ahead and create a free developer account at developer.amazon.com. You should review the AVS Terms and Agreements here.

b. Create a device and security profile

Follow the steps here to register your product and create a security profile.

Make note of the following parameters. You'll need these in a minute or two.

  • ProductID (also known as Device Type ID),
  • ClientID, and
  • ClientSecret

2 - Get the required files

You will find an AlexaAVS folder in your Documents folder, this folder contains old the files and tools you need to run this workshop.

3 - Initial setup

  1. Get familiar with the folders and files inside AlexaAVS, you should find:
  • alexa-avs-sample-app-master this folder which contains the project files, all the changes that we are making through the workshop will happen inside this folder.
  • jdk-8u102-x64, this contains the Java Virtual Machine, a set of tools to compile and build programs written in Java.
  • vlc-2.2.6 this folder contains a media player that will help us with the audio.
  • node-v8.6.0-win-x64 this contains a set of tools to run javascript code.
  • OpenSSL-Win64 this contains tools that will help us with security things.
  • apache-maven-3.5.0 which contains tools to assemble programs made in Java.
  • Sublime Text Build 3143 x64 which contains a cool text editor in case you don't have one.
  1. Do a quick test to check the tools

Let's see if the tools we need are working properly:

Open a command prompt (Press [Windows Key + R] and then type cmd and then press [Enter]), we are going to type commands to check if the tools are working properly, every time you type a command you should press [Enter] key to run it and see the results.

  • Checking Java

Type: java -version, then press [Enter]
You should see java version "1.8.0_144" in the first line.

  • Checking Maven

Type: mvn -version, then press [Enter]
You should see at the beginning: Apache Maven 3.5.0....

  • Checking Node.js

Type: node --version, then press [Enter]
You should see v8.6.0

  • Checking OpenSSL

Type: openssl version, then press [Enter]
You should see OpenSSL 1.1.0f 25 May 2017

If everything is working let's move to the next step. If something's not right please ask the teachers :)

4 - Generating Self Signed Certificates

Now this is the part when we start building our Alexa, first we need to generate certificates, we need certificates to let Amazon Alexa services know who we are.

  1. The first file we need to edit is ssl.cnf, which contains the information OpenSSL needs to generate the certificates. To do so, do the following:

Open Sublime Text using the icon in your desktop. Then click File, Open File..., Go to: Documents > AlexaAVS > alexa-avs-sample-app-master > samples > javaclient > ssl.cnf

  1. Go to line 15, and replace the word YOUR_COUNTRY_NAME by US. Then Save the file clicking File > Save, You can close Sublime Text after that.

  2. Open a command prompt. (press Windows + R key then type cmd, then press [Enter])

  3. We need to run the script generate.bat in the command prompt window, the script is located in the directory AlexaAVS > alexa-avs-sample-app-master > samples > javaclient so we need to go there first:

let's go to that place using the command:

type: cd %userprofile%\Documents\AlexaAVS\alexa-avs-sample-app-master\samples\javaclient [then press Enter]

Now we should be in that place, let's run the script:

type generate.bat then press [Enter]

This will start asking you for productID, type: alexa_workshop, then press [Enter]
Then it will ask you for serial number, type: 123456, then press [Enter]
THen it will ask you for a password, just press [Enter] to skip this step.

  1. We need to tell Node where our certificates are, we can do that by editing the following configuration file:

Open Sublime Text again, then click File, then Open File..., then go to Documents > AlexaAVS > alexa-avs-sample-app-master > samples > companionService, select config.js then click Open.

  • In line 17 we need to set the value of clientId, replace YOUR_CLIENT_ID_HERE with the cliendId value you see in the developer website.
  • In line 18 we need to set the value of clientSecret, replace YOUR_CLIENT_SECRET_HERE with the clientSecret value you see in the developer website.
  • In line 23 we need to set the value of sslKey, replace YOUR_SSL_KEY_HERE for ..\\..\\samples\\javaclient\\certs\\server\\node.key
  • In line 24, we need to set the value of sslCert, replace YOUR_SSL_CERT_HERE for ..\\..\\samples\\javaclient\\certs\\server\\node.crt
  • In line 25, we need to set the value of sslCaCert, replace YOUR_SSL_CA_CERT_HERE for ..\\..\\samples\\javaclient\\certs\\ca\\ca.crt
  • In line 27 replace YOUR_PRODUCT_ID_HERE for alexa_workshop and replace YOUR_SERIAL_NUMBER_HERE for 123456

When you finish, Click on menu File > Save, to save your changes.

  1. No we need to tell our Alexa app where the certificates are. To do it, using your editor click File, then Open File.., then go to Documents > AlexaAVS > alexa-avs-sample-app-master > samples > javaclient, select config.json then click Open.
  • In line 15, set companionService.sslClientKeyStore by replacing YOUR_SSL_CLIENT_KEY_STORE for certs\\client\\client.pkcs12
  • In line 17, set companionService.sslCaCert by replacing YOUR_SSL_CA_CERT for certs\\ca\\ca.crt

When you finish, Click on menu File > Save, to save your changes.

5 - Authentication Method

The following instructions will walk you through building and running the Node.js server for authentication. This will allow us to request permission to Amazon to access Alexa Voice services using our account.

To run the server, follow these instructions:

  1. Open a command prompt. (Windows + R key, then type cmd, then press [Enter])

  2. Change directories to the companionService folder by typing:
    cd %userprofile%\Documents\AlexaAVS\alexa-avs-sample-app-master\samples\companionService
    [then press Enter]

  3. To install dependencies (software that we need), type: npm install. This process might take some minutes.

  4. When the previous command finishes type the following: npm start and press [Enter]

You should see something like server Listening on port 3000

The server is running. You are now ready to run the sample app and talk to Alexa :)

6 - Run the sample app

Now that you've set up your Node server which will help with the authentication, you're ready to run the sample app.

  1. Open a command prompt (Windows + R key, then type cmd, then press [Enter])
  2. Go to the the samples/javaclient directory by typing:
    cd %userprofile%\Documents\AlexaAVS\alexa-avs-sample-app-master\samples\javaclient
  3. Run mvn validate command to ensure the project is correct and that all necessary information is available.
  4. Run mvn install command to download dependencies and build the sample app.
  5. Run mvn exec:exec command to run the sample app.

Follow these instructions:

  • A window should pop up with a message that says something similar to Please register your device by visiting the following website on any system and following the instructions: https://localhost:3000/provision/d340f629bd685deeff28a917. Don't press OK until you've obtained your tokens.
  • Copy the URL from the popup window and paste it into a web browser. In this example, the URL to copy and paste is https://localhost:3000/provision/d340f629bd685deeff28a917. Note that, due to the use of a self-signed certificate, you will see a warning about an insecure website. This is expected. It is safe to ignore the warnings during testing.
  • You will be taken to a Login with Amazon web page.
  • Enter your Amazon credentials.
  • You will be redirected to a URL beginning with https://localhost:3000/authresponse followed by a query string. The body of the web page will say device tokens ready.
  • Return to the Java application and press OK. The sample app is now ready to accept requests.

You're now ready to talk to Alexa. Go to "Step 7 - Talk to Alexa".

7 - Talk to Alexa

  1. Click once on the Start Listening button, after releasing the click, wait for the audio cue before you begin to speak. It may take a second or two for the connection to be made before you hear the audio cue.
  2. Once you hear the audio cue, say What's the weather in Seattle? and wait. Alexa will send a StopCapture directive to the client when your intent is recognized. Then you will hear Alexa's response, which should be the current weather report for Seattle.
  3. Click the Start Listening button and wait for the audio cue. Once you hear the cue, say "Set a timer for 5 seconds" and wait. You should receive a response from Alexa, which should be "5 seconds starting now." When 5 seconds have elapsed, the timer will go off. To stop the timer, press the play/pause button directly below Start Listening.
  4. The previous, play/pause, and next buttons demonstrate music button events. Music button events allow you to initiate changes in the playback stream without having to speak to Alexa. For example, you can press the play/pause button to pause and restart a track of music. To demonstrate the play/pause button, you can speak the following command: Play DC101 on iHeartRadio, then press the play/pause button. The music will pause in response to the button press. Press the play/pause button again to restart the music.

8 - How to Log Out of the Sample App

See Sample App Log Out Instructions.