1. Setup Your Pi

Note: you can skip this step if your Pi is already up and running.

Let’s begin by setting up the Pi. The Raspberry Pi 3 board includes -

  • 4 USB ports
  • HDMI port for video output (you’ll be using this to connect to your HDMI monitor)
  • 3.5mm audio jack for sound output (you’ll be using to connect your earphones)
  • Micro SD card slot
  • Ethernet port

Assembling Your Pi

  1. Check that your micro SD card is inserted into the micro SD card slot on your Pi.
  2. Plug in the USB microphone and 3.5mm earbuds.
  3. Connect the keyboard and mouse to the USB ports.
  4. Connect your monitor using the HDMI port.
  5. Insert ethernet cable into the Pi. (not shown in this picture)


Booting Your Pi

  1. Plug in the power supply to the micro USB connector on the Pi. You should see a loading screen go through some startup steps before booting to desktop - if you run into any errors, request a new SD micro card to boot the OS from.
  2. Verify ethernet is working by clicking on the connectivity icon in the top right of the tool bar (next to the speaker icon). You should see an up/down arrow pair (not X’d out).
  3. Open a web browser by clicking on the globe icon in the top left toolbar.

Checkpoint 1

  1. Make sure you’re connected to the internet and are able to navigate to https://developer.amazon.com.

2. Get an Amazon Dev Account

Register for an Amazon Developer Account

Unless you already have one, go ahead and create a free developer account at developer.amazon.com. Click “sign in” at the upper right corner and create your account (or log in with your existing credentials). You can review the AVS Terms and Agreements here.

Note - you can open these links in a new tab - and if you lose track of the lab manual, it’s bookmarked in your chromium browser - just click on the “AVS workshop” tab!

Checkpoint 2

  1. Once logged in, navigate to https://developer.amazon.com/avs/home.html#/avs/home

3. Create a Device & Security Profile

Register your prototype and create a security profile

After you’ve created an Amazon developer account, you’ll need to create a product and security profile. This will enable your software client to connect to AVS.

Log in to developer.amazon.com. You should be in the Dashboard by default - click the ALEXA VOICE SERVICE button in the global navigation to start building products with Alexa built-in. If you don’t see this screen, try this link: https://developer.amazon.com/avs/home.html#/avs/homes


If this is your first time using AVS, you’ll see a welcome screen. Click the GET STARTED button, then click the CREATE PRODUCT button.

If you’re a returning developer that has already created products in your dashboard, click the blue CREATE PRODUCT button at the top right corner of the screen to start building a new device profile.

Fill in product information

  1. Product Name: Use AVS Tutorials Project.
  2. Product ID: Use PrototypePi. No spaces are allowed for the Product ID field.
  3. Select Device with Alexa built-in for Please Select Your Product Type. Select No for Will your device use a companion app?
  4. Choose Other for Product Category and write Prototype in the (please specify) and Brief product description field.
  5. Select Hands-free for How will users interact with your product?
  6. Skip the Upload an image step. This is not required for prototyping.
  7. Select No for Do you intend to distribute this product commercially?
  8. Select No for Will your device be used for Alexa for Business?
  9. Select No for Is this a children’s product or is it otherwise directed to children younger than 13 years old?
  10. Click NEXT to continue.

Set up your security profile


  2. Enter your own custom Security Profile Name and Security Profile Description for the following fields - or use the below example names:
    • Security Profile Name: AVS Tutorials Project
    • Security Profile Description: AVS Tutorials
    • Click NEXT.

    Security Profile ID will be generated for you.

  3. Select Other devices and platforms from the Web - Android/Kindle - iOS - Other devices and platforms options in the Platform Information section.


  • Write a name for your Client ID here - you can just use Prototype.
  • Click “Generate ID”. You should get a Client ID and an option to download it.
  • If you’re creating this product profile on your Raspberry Pi, click Download to get your credentials onto your AVS prototype. Save the config.json file to your /home/pi directory. When you click download, it’ll automatically put it in your /home/pi/downloads folder.
  • Check the box beside I agree to the AVS agreement and the AVS Program Requirements.
    • Click FINISH.

Congratulations! You now have access to the Alexa Voice Service APIs. Click OK on the prompt to continue. Your device should now be listed on your AVS dashboard.

4. Input Your Credentials

Download your credentials

If you didn’t already save it to your Pi when creating your product profile, it’s time to get your config.json file onto your client device. Start by opening a browser and logging into your AVS dashboard. Click on your Product Name, it should be AVS Tutorials Project or whatever you named it when creating the product profile.

If you don’t see your dashboard, click on “My Alexa Consoles” in the upper right corner and select “Alexa Built-in Products”.

This will take you to a product menu - on the left side you should see Product Details. Select Security Profile below that and choose Other devices and platforms from the Web - Android/Kindle - iOS - Other devices and platforms menu.

When you click the Download button on your Security Profile in your web browser, you’ll see a config.json file appear in your home/pi/downloads folder. In the file manager, copy this file from the /downloads folder and place it in your home/pi folder as shown in the picture below.


Now that your Raspberry Pi has your own unique credentials loaded on it, it’s time to build your SDK.

5. Run the Install Script

Run the Install Script

You are now ready to run the install script. This will install all dependencies, including the Wake Word Engine (WWE) from Sensory. The WWE compares incoming audio to an onboard model of a wake word (“Alexa”) and will initiate the transmission of audio to the cloud when triggered. Note that this WWE is provided for prototyping purposes only and would need to be licensed for a commercial device. The AVS Device SDK is modular and flexible. When you’re ready to build your product, you can choose any WWE you prefer. Remember that for AVS products, the wake word must be Alexa so that your customers aren’t confused about how to interact with your device.

To run the install script, open a terminal by clicking on the console window in the Pi’s toolbar in the upper-left corner of the screen (or just use your existing terminal window). You should see a setup.sh script in your /home/pi/ directory. This pulls the credentials from your config.json file to run the install script. To launch the setup script, copy and paste the following command into your terminal window and hit return:

cd /home/pi/
sudo bash setup.sh config.json -m /home/pi/Smart-screen-sdk-test/


Type “AGREE” when it prompts you to accept the licensing terms from our third-party libraries. Unless, of course, you disagree!

This will kick off the installation process which could normally take over 20 minutes, but for reInvent we’ve precompiled the image to save you some time.

Once you’ve finished compiling, you should see a success screen. If your device freezes up - don’t worry, just restart by unplugging your Pi’s power cord. When you get back to your desktop, re-run the above setup.sh command to finish your install.

Now you just need to launch the sample app and get a refresh token from AVS so your device can authenticate with the cloud via Login With Amazon (LWA).

6. Authorize your Device

When you run the sample app for the first time, you’ll need to authorize your client for access to AVS.

Initialize the sample app by pasting or typing the following command into your terminal:

cd /home/pi/
sudo bash startsample.sh

Wait for the sample app to display a message like the one in the picture below (but, a different code of course) - If you don’t see this, but you see “waiting for authorization” messages going by, then scroll up! It’s easy to miss the authorization code since the terminal window fills up pretty fast. Note - you need to leave this process running while you authorize, don’t close the window or otherwise stop the startsample script.


  1. Use a browser to navigate to amazon.com/us/code
  2. Authenticate using your Amazon user credentials. If you aren’t able to log in - try deleting all cookies or open a new tab in “guest mode” browser, then go to amazon.com/us/code. You can also just go to the link from your phone, laptop, or any connected device, and it should work.
  3. Enter the code specified in the message from sample app.
  4. Select “Allow”.
  5. Wait (it may take as long as 30 seconds) for CBLAuthDelegate to successfully get an access and refresh token from Login With Amazon (LWA).
  6. At this point the sample app will print a message informing you that you are now authorized!

Your raspberry pi is 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.

Now, you’ll need to open a browser to add a visual interface to your prototype. Open a new chromium tab to the following URL: file:///home/pi/avs-device-sdk/GUI/js/dist/index.html?insecure=1

Note, this should autocomplete in your browser when you start typing - it’s also in the bookmarks as “Alexa Home Screen”.

Congrats on your progress so far! Now it’s time to talk with Alexa.

7. Talk to Alexa

Interact with Your Prototype

Say “Alexa” into the microphone on your Raspberry Pi to trigger the Wake Word Engine. Since you are using a single microphone in a noisy environment, you may want to speak closely into your microphone to ensure your voice is heard clearly. You should see a blue light on the bottom of your screen, indicating the wake word was recognized. Then say “tell me a joke.” If Alexa responds, congratulations! You have a working prototype.

If you cannot hear Alexa’s response, ensure your speaker/earbuds are turned on and plugged in to your Raspberry Pi’s 3.5mm audio jack. Check that your audio output on your Pi is set to Analog by right-clicking on the speaker icon in the top right corner of the screen.

Try the following interactions, and note how the screen allows for Alexa to provide information-rich interactions -

  • Say “Alexa”, then ask “What’s the weather in Las Vegas?” Note how instead of just hearing today’s weather over the speaker, you also get a 5 day forecast visually as a bonus!

  • Say “Alexa”, then say “Play Katy Perry on TuneIn.” You get album art and transport controls (try clicking “next”!)

  • Say “Alexa”, then say “Add Milk, Eggs, Bread and Orange Juice to my shopping list.” You get a visual confirmation of how your list is shaping up, and if you fill up your list you can browse by using the scroll wheel (or if you had a touchscreen, a swipe)

  • Say “Alexa”, then say “Who is Angela Merkel?” Wikipedia provides a nice picture for your screen and some extra stats. A picture is worth a thousand words!

Try a Multi-Turn interaction

  • Say “Alexa”, then ask “Set an alarm for 12:30”. You should receive a response asking you to clarify AM or PM. Respond to the question with “Afternoon”. If you have DEBUG9 active, scroll up until you see Listening… - right above that you’ll see that the state of the Audio Input Processor (AIP) has changed from IDLE to EXPECTING_SPEECH and then RECOGNIZING - without you speaking the wake word! Typically, the AIP is triggered by the Wake Word Engine running on the client - but in this case, it’s been activated via a Directive delivered down to your client from the cloud.


Multi-turn interactions can feel like a more natural method of communication, since you can continue to speak with Alexa as part of a continuing conversation without starting every phrase with “Alexa”.

Other interactions to Try

  • Say “Alexa, Wikipedia” - you’ll have the option of looking up any subject without having to speak the wake word before the subject.
  • Say “Alexa, let’s chat” to initiate a conversation with a chat bot!
  • Say “Alexa, play Yes Sire” to play a medieval-themed game using your voice.

8. Customize your Renderer

Depending on the size of your screen or how your device is used, you might want to make changes in your screen’s display behavior. Navigate to the following folder in your File Manager: /home/pi/avs-device-sdk/GUI/js/src/components

Right click on the file apmlRenderer.tsx and open it with a text editor.


Scroll down to where you see Theme:ColorScheme.LIGHT and change it to Theme:ColorScheme.DARK - then save and close.

If you aren’t able to save, it may be an ownership issue, you can type the following into the terminal to fix it:

sudo chown -R pi:pi /home/pi

You will need to rebuild the GUI/js

cd /home/pi/avs-device-sdk/GUI/js/src/
npm run-script build

Now, refresh your browser and ask for the weather again! It should look different - better for low-light environments.

You can also try modifying the shape or screen size and see how the Smart Screen SDK makes it easy to optimize for your unique product capabilities.

9. Change your Home Screen

Modify your home screen

When you ship your screen-based product with Alexa built-in, you’ll probably want your own home screen to display when the device isn’t in use. For example, if you were building Alexa into your smart thermostat, you could display a control screen that showed your own data when the customer wasn’t asking Alexa a question. The Alexa for Smart Screen and TV SDK makes it easy to customize your device behavior.

In your File Manager, navigate to /home/pi/avs-device-sdk/GUI/js/src/lib/data Right click on the Home.json file and select open with Text Editor to modify the file as shown in the below picture.


Here, you can input any URL to replace your home screen with. Make your own, or try the following as an example:


Save and close the file. If you aren’t able to save, it may be an ownership issue, you can type the following into the terminal to fix it:

sudo chown -R pi:pi /home/pi

You will need to rebuild the GUI/js

cd /home/pi/avs-device-sdk/GUI/js/src/
npm run-script build

When you’re ready, you don’t need to re-compile the SDK or restart the sample app, just refresh your browser in Chromium after the build. You should see your own custom home screen image when you aren’t interacting with Alexa!

Feel free to poke around in the Home.json file and see what other changes you can make to improve the customer experience on your device.