top of page

Setting up AlexaPi via Alexa Voice Services (AVS)

This really is not that difficult, even if you are new to the Raspberry Pi. I originally followed the step-by-step instructions from However, I recently came across a headless boot version of Alexa Voice Services (AVS) on the Raspberry Pi written by Rene Kliment and decided to change over to a totally headless setup. You can find a link to the code repository and Rene's fantastic ReadMe file, installation instructions, and code repository here.

The objectives are as follows:

1. Setup the Raspberry Pi with PIXEL OS

2. Install the Alexa API on to the Raspberry Pi using AlexaPi code from Rene Kliment

3. Test configuration


Below are the supplies needed along with the links to the components I used.

- Raspberry Pi (I suggest the new Model 3 with built in wifi)

- Micro SD Card (at least 8GB)

- Raspberry Pi power supply

- Auxiliary cord

- Keyboard and mouse (for setup, if you only have a VGA/DVI input see this post!)

- Monitor/TV with HDMI in (for setup

Step 1: Hardware setup

Plug your power supply cord to your Raspberry Pi computer board. Make sure the micro SD card is inserted. Connect your auxiliary cord to both the Raspberry Pi and the speaker. Plug in the USB microphone to the Pi. Plug in the Keyboard/mouse as well as the Monitor/TV.

Step 2: Setup the Raspberry Pi with PIXEL OS

If you are very new to the Raspberry Pi, I recommend you check out the organization's website at where there are great introductions to the Pi and a helpful community.

For those Windows users who know their way around a Pi, use Win32 Disk Imager to image the PIXEL OS which you can download from Remember you need to unpack the .ZIP file and image the .IMG file, not the .ZIP. For more detailed instructions or instructions for other OS's, has a great tutorial.

Screenshot of Raspberry Pixel OS

Insert the newly imaged micro sd card, plug in the pi to power and the display, and voila! You should be up and running.

Just to verify you have the newest version of PIXEL, run the following commands in the terminal:

sudo apt-get update

sudo apt-get upgrade

That last line will take a while to execute and will require responses from the user. This would be a good time to enjoy a hot cup of cocoa. Once this has completed, reboot the pi and you should be ready for step two!

Step 3: Install the Alexa API on to the Raspberry Pi using AlexaPi

At this point I will direct you to Rene Kilment's excellent github page with very thorough installation instructions. I will walk you though the instructions for setting up the Amazon Developer account and device registration as I found it confusing the first time I did it.

I recommend doing the Amazon Developer Account step first, only because I had to wait a couple hours to receive acceptance into the developer program. If this happens to you, you can use this time to continue setup on the Raspberry Pi. You can register for the amazon developer's account for free by going to the Amazon Developer Service. Scroll down and you will see the "Register for a free Amazon developer account" link.

Screenshot of Alexa API homepage

The original instructions I used for setting up the Alexa API on the pi were written by Thorin Klosowski. His instructions for registering for the account and subsequently registering your device are thorough and easy to understand. I will state the steps briefly here, but I recommend navigating to Thorin's instructions at if you need more detail.

You need to register every device you want to use the Alexa API with on the developer site. There are a few points worth clarifying in the device registration. What follows is a crude set of directions.

1. "Alexa" Tab

2. Alexa Voice Service > "Get Started"

3. "Register a Product Type"

4. Device Type Info Tab

Device Type ID > Raspberry_Pi

Display Name > Raspberry_Pi

(Avoid using spaces, these names will also be capitalization-specific!)

5. "Next"

6. Security Profile

Dropdown menu > "Create a new profile"

Security Profile Name > Raspberry_Pi

Security Profile Description > Security profile for Raspberry_Pi Alexa API


Note the Client ID "amzn1.application-0a2-client..."

Note the Client Secret (string of letters and numbers)

Web Settings > Edit

Allowed Origins > "Add Another" > https://localhost:5050

"Add Another" > https://ALEXA.DEVICE.IP.ADDRESS:5050

Allowed Returns > "Add Another" > https://localhost:5050/authresponse

"Add Another" > https://ALEXA.DEVICE.IP.ADDRESS:5050/code

Here, replace ALEXA.DEVICE.IP.ADDRESS is to be replaced with the IP Address of your pi


7. Device Details - add image, category, description, timeline, and number of devices to commercialize (this number must be zero)


8. Amazon Music > No

9. "Submit"

Step 4: Alex Voice Services API Setup

Before Kliment's AlexaPi, the only way to use the Alexa API was confirming the device at each startup using the browser, meaning no headless start - you needed a monitor. Now with AlexaPi the Alexa API runs and authenticates automatically at each startup, meaning no monitor or keyboard needed!

Unfortunately, in order to utilize the Alexa API you must still originally confirm the device using a browser, this means that the desktop environment for the Pi, Pixel (or Raspbian which is older), must be installed. If you are worried about the security I would recommend using a personal wifi network and setup a VPN client. As for concerns about performance, the PIXEL interface loads much faster than the old Raspbian OS, and the Raspberry Pi Model 3 has 1GB of RAM, so the performance is pretty snappy.

Again, the instructions from Thorin have a greater level of detail, but the steps are briefly listed here with some important items to note.

Now your Raspberry Pi runs Alexa! after this the only things left to do are to test it out. You can do this using the USB microphone and USB powered speakers. Use the following terminal command to adjust the audio gains.


udo alsactl store

Thorin's instructions also go on to add AirPlay support which I have decided to forgo for the time being as I am unsure of how it will work with the Billy Bass, but feel free to add it, it won't hurt anything!

Step 5: Setting up Headless (Remote) Boot

In order to break free from the screen and input peripherals on the Raspberry Pi, and thus integrate it into the project in a practical way, we need to initiate a headless boot. A headless boot simply means without a monitor. Normally, this can be achieved by SSH, but because we need access to more than just the terminal, we are going to need to setup a VNC client.

I found a great tutorial that walks through how to use tightVNC at, written by Christian Cawley. Even the most introductory of Pi users should be able to follow along. I will post a brief description of his instructions for more advanced users, but I would recommend you check out his tutorial for more detail and explanation. To set up tightVNC on your Raspberry Pi, enter the following commands in the terminal:

# Installing tightVNC

sudo apt-get update

sudo apt-get install tightvncserver


vncserver :0 -geometry 1920x1080 -depth 24

sudo apt-get install xtightvncviewer

# Setting tightVNC to run at boot

sudo nano

Enter the following into the new script


vncserver :0 -geometry 1920x1080 -depth 24 -dpi 96

ctrl+X, Y, Enter

sudo chmod +x


sudo su

cd /etc/init.d/

sudo nano vncboot

Enter the following into the new script

#! /bin/sh

# /etc/init.d/vncboot


# Provides: vncboot

# Required-Start: $remote_fs $syslog

# Required-Stop: $remote_fs $syslog

# Default-Start: 2 3 4 5 # Default-Stop: 0 1 6

# Short-Description: Start VNC Server at boot time

# Description: Start VNC Server at boot time.



HOME=/home/pi export USER HOME

case "$1" in


echo "Starting VNC Server"

#Insert your favoured settings for a VNC session

su - pi -c "/usr/bin/vncserver :0 -geometry 1280x800 -depth 16 -pixelformat rgb565"



echo "Stopping VNC Server"

/usr/bin/vncserver -kill :0



echo "Usage: /etc/init.d/vncboot {start|stop}"

exit 1



exit 0

Ctrl+X, Y, Enter

chmod 755 vncboot

update-rc.d /etc/init.d/vncboot defaults

update-rc.d vncboot defaults

Now tightVNC should run at startup on your Raspberry Pi. The last step here is to install tightVNC on your computer. You can navigate to the right file for your OS here.

* Remember, the default username for your raspberry pi is "pi" and the default password is "raspberry"


There were a few issues I ran into during the setup and I will address them here.

SSL Certificate Error in Chromium During Authentication

This one is deceptively simple. I was using a small screen so this initially escaped me. Scroll down on the error page and you will see a hyperlink that says "Advanced", click it. Then you will see another hyperlink that says "proceed to localhost anyway", click that and you should be directed to the sign-in for the Amazon Developer Account.

Authentication Error after Developer Account Sign-in

This drove me crazy and is something that I didn't catch on Thorin's directions. If you get an error that says an authentication error has occurred, after you signed in to your developer account, it is likely because you entered either the DeviceID, ClientID, or ClientSecret incorrectly. In my case, I incorrectly used the Security Profile ID instead of the DeviceID. open up in the text editor and double check. If you do find an error you need to repeat the steps for installing Alexa.

Featured Posts
Recent Posts
Search By Tags
Follow Us
  • Facebook Basic Square
  • Twitter Basic Square
  • Google+ Basic Square
bottom of page