In this article, I’m going to walk you through installing the Amazon Voice Service (Alexa) on your Raspberry Pi. Installing AVS on a Raspberry Pi will help you understand how Amazon’s intelligent voice assistant works, and how you can deploy it on pretty much any device.
When Amazon launched its flagship product the Amazon Echo in 2015, it was nothing more than a voice-controlled speaker. But in barely two years, the intelligent voice assistant had already conquered the consumer electronics market, and was found in 5 million homes.
Alexa’s dominance was evident by 2017, when concept designs from consumer brands like Ford, Whirlpool and LG had a built-in Alexa integration. Fast forward to 2021, when estimates show that one in four households have a smart speaker, with Amazon’s echo dot being the most popular device.
While the widespread popularity of the device can largely be attributed to its intuitive voice processing capabilities, the fact that Amazon opened up its platform to collaborators for developing voice apps accelerated the early adoption.
Let’s look at how you can install the Amazon Voice Service (Alexa) on your Raspberry Pi, which should teach you how Amazon’s intelligent voice assistant works in the background. Then, you should feel confident using it with any device imaginable.
Once you have a grip on the boilerplate code, you’ll also be able to use Alexa’s search capabilities to prototype a smart home device, develop an advanced skill set on the AVS platform, or create an interactive, voice-controlled electronic project.
However, since it’s a DIY setup, you won’t be able to build something that looks as cool as the Amazon Echo. For instance, see the image above showing what the homebrew version of my Amazon Echo looks like.
That being said, the above DIY setup is a fully functional Amazon Echo device that can respond to your voice commands and take contextual actions. For instance, you’ll be able to use your Raspberry Pi to check weather, stream your favorite music, or control connected devices in your home, like LIFX, Philips Hue or the Nest thermostat.
Here’s what you’ll need for the project:
Raspberry Pi 3 (If you’re using Raspberry Pi Model A or Zero, you’ll need an Ethernet cable or USB Wi-Fi adapter to connect to the Internet.)
Micro SD card with Raspbian installed
3.5 mm line-in speaker
PlayStation Eye Camera (Alternatively, you can even use an USB microphone.)
Micro USB cable (for powering Pi)
Keyboard, mouse and display (or you can even use VNC to connect to your Raspberry Pi from your Mac, Linux or Windows machine)
Power bank (optional)
I’ve used the PlayStation eye camera, as it provides better audio reception than most USB microphones under $10. But, in case you have a good quality USB microphone, you can use that, too.
Step 1: Setup your Raspberry Pi
Before we move ahead with the installation, it’s important to get your Raspberry Pi up and running. Here’s a checklist of the initial setup process:
Connect peripherals: While I’m using a Bluetooth mouse and keyboard, you can also use USB peripherals for your convenience. Also, hook up your Pi with a HDMI display, so that you’re able to see the output.
Set up a VNC server (optional): In case you don’t have any peripherals or display device, you can even connect to your Raspberry Pi using VNC, so that you can access your Pi from any Linux, Mac or Windows machine. Here’s an easy guide on how to setup VNC on your Raspberry Pi.
Audio check: Connect the microphone and external speaker to your Raspberry Pi. Enable the speaker output by right-clicking on the speaker menu on the taskbar, and selecting “Analog”. You can configure the Pi to recognize the USB microphone as default by running the following command on the terminal:
Once you open up the editor window, navigate to the line that reads:
Change it to:
Press Ctrl + X to exit the editor and save the configurations.
Step 2: Configure your Amazon Developer Account
Once you have setup your Raspberry Pi, the next step is to configure your Amazon Developer Account, so that you can link your Raspberry Pi with Alexa Voice Service (AVS).
The developer account is a prerequisite for the setup, since Amazon provides Alexa “as a service”. All the complex tasks associated with voice processing, like, context binding, semantic analysis or deep learning happen on Amazon’s cloud servers, while the client (in our case Raspberry Pi) just needs to invoke the voice service (AVS) by passing along the input.
However, in order to communicate with AVS, we would need to get the authentication tokens, so that Amazon’s servers can recognize our client and send responses. Here’s how to setup the security profile and get the authentication tokens:
1) First, you’ll need to register for a free Amazon Developer account. Once you’re registered, you should be able to login and see a dashboard that looks something like this:
2) Once you’re on the dashboard, click on Alexa in the navigation menu. It’ll give you two choices– Alexa Skills Set or Alexa Voice Service. Select “Alexa Voice Service”.
3) Next, the screen will ask you to register your product with Alexa Voice Service. Click on “Register a Product Type” button. You’ll be prompted whether you wish to register a device or an application. Select “Device”.
4) Once you’re through that, you’ll be navigated to “Create a New Device Type” screen, where you’ll be asked to enter a Type ID and Name. Here, you are free to enter any name or value that you wish. Just for convenience, we choose to name our device “Raspberry Pi” and set the ID as “RPi”.
5) Next, you’ll be asked to create a security profile. In the dropdown box, select “Create a new profile”. The name of the security profile and description would be auto-populated. Click “Next”.
6) In the next screen, you’ll be able to see the authentication credentials for accessing AVS. Make a note of your Client ID and Client Secret key, as you’ll need them later.
7) After noting down the credentials, click on the “Web Settings” tab. Once you’re there, click on the “Edit” button on the top-right corner. It should allow you to modify the “Allowed Origins” and “Allowed Return URLs” for the security profile.
Click on “Add Another” to enable editing for Allowed Origins, and enter the following URL:
Similarly, set the Allowed Return URL to:
When you’re done, save the settings, and click on “Next”.
8) After you have configured your security profile, you’ll be asked to enter the device details. It really doesn’t matter what you enter here, so you can choose an image of your choice, pick any random category, write a relevant description and set an arbitrary timeline for the device.
Make sure you enter a small number (like “10”) for the commercialization question, and select “No” when asked if the device is a children’s product. Once you’re done, click “Next”. In the final step you’ll be asked whether you wish to add Amazon Music to your device, select “No”, as we don’t require the integration for now.
Step 3: Install Alexa Voice Service on Your Raspberry Pi
Now that you have successfully configured your Amazon Developer account, the next step is to install the setup files on your Raspberry Pi, and invoke the client service. Here’s how you can install Alexa Voice Service on your Raspberry Pi:
1) Open the terminal on your Raspberry Pi and enter the following command:
The above command will fetch all the code files required for the installation from Amazon’s Github repository and download it to your Pi.
2) Once the download finishes, enter the following command.
It will open up a text editor, which should look something like this:
You’ll need to enter your authentication credentials (Client ID and Client Secret that you noted in the first step) in the bash script. You’ll need to set the “Device Type ID” (the ID that you gave to your device in the first step) as the ProductID
NOTE: Product ID is NOT the Security Profile ID.
You can use the arrow keys or mouse to alter the bash script and once you’re done, press Ctrl + X to save the script and exit the window.
3) Once you’re on the terminal screen again, type in the following command to initiate the automated installation of Alexa on your Raspberry Pi:
When you type in the command, it will open up a prompt window, where you’ll be asked multiple questions. Just type “Y” for each question to breeze through the setup. Once you have answered all the questions, the installation process should begin. It will take at least 30-45 minutes for the setup to complete (depending on your Internet connection speed), so it’s best to grab a coffee and let Pi do the work.
4) When the installation completes, you should ideally see a screen that looks something like this:
If you see that the setup has finished building and that there are no visible error traces, you have successfully installed the client on your Raspberry Pi.
But, wait, we’re not finished. We managed to install the client, but we also need to invoke the companion service, run the client and then trigger the wake agent. So, let’s move forward to the next step.
Step 4: Run Alexa Companion Service on terminal
Before invoking our AVS client, we need to run the Alexa Companion service. You can think of ACS as the interface (or gateway!) between your client and server. While you can always have multiple clients running on your Raspberry Pi, you can only have a single companion service running on your device.
The Alexa Companion Service listens to communication requests from multiple clients, manages the authentication and pushes the response to AVS servers.
You can start the companion service by entering the following command:
After you run the above command, you should see a screen that’s similar to this:
If it reads “Listening on port 3000”, you have successfully invoked the Alexa Companion Service. Now, minimize the window but don’t close it, and open a new terminal.
NOTE: Do NOT close the window, as we’ll need to run the companion service in the background for communication with AVS servers
Step 5: Invoke AVS client and authenticate the service
In order to invoke an AVS client, open a new terminal and enter the following command:
Once you run the command, in a few seconds, you will get a popup that asks you to authenticate the device. Copy the URL (just in case) and click “OK”. If you don’t see a window opening up automatically after a few seconds, open the link in your browser.
NOTE: Once you have clicked on “OK” the first time, open the link and authenticate the device. Don’t click “OK” on the second dialog box, until you have logged into your Amazon Developer account.
You can authenticate the device by entering your Amazon Developer account credentials and once you’re signed in, it would ask for permissions. Click “Allow”. If you have entered the correct credentials (Product ID, Client ID and Client Secret), you would get a message that reads “device tokens ready”.
If you get the above message, congratulations! Your client now has the authentication tokens required to communicate with AVS.
Go ahead and click “Ok” on the AVS client dialog box. All the buttons, including Listen, Play and Stop will now be enabled. You can click on “Listen” and say something, like, “Alexa, how are you?”. You should get a response from Alexa. Wow, too cool!
But that isn’t exactly how it’s supposed to work.
Ideally, you should be able to call “Alexa” and just say anything that you want. If you have to click a button every time you wish to tell her something, that’s a deal-breaker, right?
Well, yes, but in order to enable passive listening, we’ll need to trigger the wake word agent. The agent will run in the background and passively listen to our wake word (“Alexa”). When it detects the wake word, it tells our AVS client to start listening.
Now there are two wake word agents available for Alexa– Sensory and KITT.AI. Both of these services are available for prototyping purposes, with the limitation that Sensory expires after 120 days. For my setup, I choose to use Sensory, just because it worked better, but you’re free to pick either wake word agent.
Step 6: Initiate the wake word agent
In order to trigger the wake word agent for your Raspberry Pi-Amazon Echo device, run the following command on a new terminal:
NOTE: Don’t close the terminal window in which the AVS client is running since the wake word agent will connect to your AVS client.
Once you run the above command, your wake word agent will be up and running in a few seconds. If you read a message that reads “Connected to AVS client”, you have successfully binded your wake agent to the AVS client.
That’s it. Your Raspberry Pi is now listening to you. Go ahead and say “Alexa”. You should hear a small “beep” as an acknowledgement, which means it’s now listening to you. You can start out by asking her any question, like, “How’s the weather?” or “How far is Los Angeles from Phoenix?”
While we managed to create a fully functional Echo that can interact with users in real-time, our DIY setup is still missing one important functionality — AirPlay. For instance, Amazon Echo can be paired up with your smartphone or computer to act as a Bluetooth speaker.
Now, although the AirPlay functionality does not come built-in with the AVS setup, you can install it by downloading a few external files. Here’s how you can add that last missing piece:
1) Open the Terminal window and run the following command:
It’ll install all the software you need for running AirPlay on your Raspberry Pi.
2) After the installation completes, run the following command:
3) When the above download finishes, type in:
4) Build the files in the directory by executing the command:
5) Once the build completes, install and test the service by running the following commands one by one (press Enter after each line):
sudo ./Build test
sudo ./Build install
6) When you’re done, install the DIY Airport software by typing:
7) Switch the directory by typing in cd shairport and run the make command.
8) Finally, run the AirPlay service by entering the following command:
Once the service is up and running, go ahead and pair up your smartphone with your DIY Amazon Echo device.
Writing a bash script to trigger Alexa automatically
I know it’s been quite a long tutorial, and it won’t make any sense to run all these commands every time you reboot your Raspberry Pi. That’s the reason I created a bash script that can run all the commands for you.
Here’s the script:
lxterminal -e bash -c 'cd /home/pi/alexa-avs-sample-app/samples/companionService && npm start ; exec bash' &
lxterminal -e bash -c 'cd /home/pi/alexa-avs-sample-app/samples/javaclient && mvn exec:exec ; exec bash' &
lxterminal -e bash -c 'cd /home/pi/alexa-avs-sample-app/samples/wakeWordAgent/src && ./wakeWordAgent -e sensory' &
lxterminal -e bash -c 'cd /home/pi/shairport && make && ./shairport.pl -a AlexaPi' &
You can save the above script as autorunPi.sh, so that next time you wish to trigger Alexa, you don’t have to run tens of commands. You can run Alexa by just running the command ./autorunPi in your terminal window.
Taking it forward
While the above setup works can be used a replacement to Amazon Echo, there’s still a lot more to explore. For instance, you can configure the Pi to run the script automatically every time Pi boots up. While you can easily do that using cronjob, the tricky part is to automate the authentication workflow, as the AVS client is always required to be authenticated through your Amazon Developer Account in order to get the authentication tokens.
The easiest workaround for circumventing the authentication workflow is to use PhantomJS to automate the process. Alternatively, it’s also possible to authorize Echo from a companion app (iOS/Android), and Amazon has a detailed technical tutorial on how to set that up.
Did it work out for you? I’d love to know how was your experience installing Amazon Echo on your Raspberry Pi. As always if you have questions just post them in the comments section below and I will answer them as soon as possible.
Other content you may like:
- How to Connect an ESP32 WiFi Microcontroller to a Raspberry Pi Using IoT MQTT
- How to Add Voice Recognition to Your New Hardware Device
- Home Automation with an Arduino: A Basic Tutorial
- How to Update Embedded Firmware Over-The-Air (OTA)
- Teardown of an Amazon Echo Dot