Prerequisites

The prerequisites for this project are:

  • An SD card

  • A microphone

  • Optionally, a speaker

  • On your computer, Node (version 7.5.0 or later) and NPM

  • If on Windows, you will need to install Git

For hardware recommendations, we suggest you consider the Snips Maker Kit. Alternatively, you can check out see our Raspberry Pi Hardware Recommendations page:

This guides uses the Sam command-line interface to easily set up your Raspberry Pi. If you don't want to use Sam and want to set up your device manually, check out the Manual Installation Guide.

Step 1: Burn Raspbian to the SD card

Raspbian is the Linux distribution of choice running on the Raspberry Pi. In this guide, we will be using the Lite version, but the Desktop version (which comes with a graphical environment) can be used as well. To download and burn Raspbian to the SD card, follow the instructions on the Raspberry Pi website.

For this tutorial, we will assume the Raspbian Stretch version to be from April 2018 or later.

Step 2: Connect the device to your network

Follow the steps below:

Step 1
Step 2
Step 3
Step 4

If your device is connected via an Ethernet cable, you can skip this step.

Insert the SD card in your computer and create a file named wpa_supplicant.conf at the root of the boot volume of the SD card. Paste the following snippet:

country=<COUNTRY_CODE>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="Your Wi-Fi network name"
psk="Your Wi-Fi network password"
}

Make sure to update the country, ssid and psk keys.

Enable SSH access by adding an empty file ssh, again placed at the root of the boot volume on your SD card.

Insert the SD card into the Raspberry Pi. It will boot in roughly 20 seconds. You should now have SSH access to your Raspberry Pi. By default, its hostname will be raspberrypi.local.

On your computer, open a terminal window and type the following:

ssh pi@raspberrypi.local

The default password is raspberry. You should be greeted with a welcome message and an active prompt on the Raspberry Pi.

If you run into issues, check out the Raspberry Pi Network Configuration Guide.

Optionally, you may change the hostname of your Raspberry Pi to something more descriptive (instead of raspberrypi, it could be raspi-kitchen), and to avoid conflicts if you have other devices on your network with the same hostname. To do so, run the following command from your SSH session:

sudo raspi-config

Select 2 Network Options > N1 Hostname, enter a new hostname, save and reboot:

sudo reboot

This will also close your SSH session. Wait approximately 20 seconds for the device to reboot, then reconnect via SSH, but this time, using the new hostname (here, raspi-kitchen):

ssh pi@raspi-kitchen.local

For the remainder of this guide, all commands are run from your computer, not on the Raspberry Pi.

Step 3: Install the Snips Platform

If you haven't already, install the Sam Command Line Interface on your computer. Open a terminal window, and enter:

sudo npm install -g snips-sam

Find your Raspberry Pi on the network by running:

sam devices

This will scan the network for Raspberry Pi devices, and yours should appear:

Scanning Raspberry Pi devices on the network...
Found 1 device:
- raspberrypi (192.168.9.2)

Next, establish a connection to the device. You will be prompted for the device username and password (default is pi and raspberry, respectively):

sam connect raspberrypi

We are now ready to install the Snips platform on the Raspberry Pi. Enter the command:

sam init

This will take a few minutes, after which the device will reboot. Run the sam status command to check the status of your device. It should show that the platform has been installed:

sam status
Connected to device raspberrypi.local
OS version ................... Raspbian GNU/Linux 9 (stretch)
Installed assistant .......... Not installed
Status ....................... Installed, not running
Service status:
snips-analytics .............. 0.55.2 (not running)
snips-asr .................... 0.55.2 (not running)
snips-audio-server ........... 0.55.2 (running)
snips-dialogue ............... 0.55.2 (not running)
snips-hotword ................ 0.55.2 (not running)
snips-nlu .................... 0.55.2 (not running)
snips-skill-server ........... 0.55.2 (not running)
snips-tts .................... 0.55.2 (running)

Many of the services are not yet running. That is because no assistant has been installed, and because the microphone has not been set up. We will do this now.

Step 4: Configure the hardware

Sam provides some commands to easily set up and configure hardware components. In this section, we will set up a speaker and a microphone. Depending on your set up, some custom configuration needs to be done. If you need advice on the hardware to use, check out Hardware Recommendations.

Test the speaker (if you have one)

To check the the speaker is working, run

sam test speaker

If everything works fine, you should hear on your speaker a voice saying a few words.

Configure the microphone

You can check that your microphone is working:

sam test microphone

Assuming you have a speaker, if you can clearly hear what you just said, you can move on without further microphone configuration. If you can't hear yourself, start the interactive microphone setup guide:

sam setup audio

Once you are satisfied that your hardware setup is working, you are ready to move on to the next step, where you will deploy your first assistant.

Step 5: Import the assistant model from the Console

If you haven't done so already, head over to console.snips.ai and create your assistant. If this is the first time you are creating an assistant, make sure to follow the Quick Start Console guide:

Once you have created your assistant, log in to the console from the terminal window by running:

sam login

You will be asked to enter your Snips Console credentials.

Next, install the assistant:

sam install assistant

If you have created several assistants in the Console, you will be asked to choose which one to install from a list.

Step 6: Testing voice queries

Before adding actual handler code, let us first check that the assistant understands your voice commands. Enter the following:

sam watch

This will display all logs from the Snips platform running on your Raspberry Pi. For instance, a message is displayed when the wake word is detected, or when an intent is detected. Try out your assistant, starting with the wake word, followed by a query. For instance:

Hey Snips, what is the weather in New Delhi

If everything is working, you should see the matching output displayed in the terminal window. You may close the logs by entering Control + C.

Step 7: Adding action code

In order for the Raspberry Pi to actually do something, such as telling you the weather forecast, we will have to write some handler code. This is code which is executed when a certain event happens on the Snips platform, such as when an intent has been detected.

In this article, we show how to create actions manually. However, this can also be done directly in the Console, with no further setup required. Check out the Console Actions guide for how to do this.

Create a folder on your computer on which you want to store your handler code. From the terminal window, change to that directory, and enter:

npm init

This will create a file named package.json which contains your project's description, dependencies and more. Next, add the mqtt package dependency:

npm install mqtt --save

Now, create a file called index.js, and paste the following code, replacing the hostname variable with the hostname of your Raspberry Pi (if it differs from the default raspberrypi):

var mqtt = require('mqtt');
var hostname = "mqtt://raspberrypi.local";
var client = mqtt.connect(hostname);
client.on('connect', function () {
console.log("[Snips Log] Connected to MQTT broker " + hostname);
client.subscribe('hermes/#');
});
client.on('message', function (topic, message) {
if (topic === "hermes/asr/startListening") {
onListeningStateChanged(true);
} else if (topic === "hermes/asr/stopListening") {
onListeningStateChanged(false);
} else if (topic.match(/hermes\/hotword\/.+\/detected/g) !== null) {
onHotwordDetected()
} else if (topic.match(/hermes\/intent\/.+/g) !== null) {
onIntentDetected(JSON.parse(message));
}
});
function onIntentDetected(intent) {
console.log("[Snips Log] Intent detected: " + JSON.stringify(intent));
}
function onHotwordDetected() {
console.log("[Snips Log] Hotword detected");
}
function onListeningStateChanged(listening) {
console.log("[Snips Log] " + (listening ? "Start" : "Stop") + " listening");
}

Run this code using Node:

node index.js

You should see a message of a successful connection to the Snips MQTT broker. As before, perform a voice interaction with your Raspberry Pi:

Hey Snips, what is the weather in New Delhi

You should see the logs updating:

[Snips Log] Connected to MQTT broker mqtt://raspberrypi.local
[Snips Log] Hotword detected
[Snips Log] Start listening
[Snips Log] Stop listening
[Snips Log] Intent detected: {"sessionId":"c84b5aa5-3f14-4218-975e-8872b9217933",
"customData":null,"siteId": "default",
"input":"what is the weather going to be tomorrow in new delhi",
"intent":{"intentName":"searchWeatherForecast","probability":0.73845243},
"slots":[{"rawValue":"new delhi","value":{"kind":"Custom","value":"New Delhi"},"range":{"start":44,"end":53},"entity":"locality","slotName":"forecast_locality"}]}

The ball is in your camp! You can now fill in the functions with code to perform actual actions, such as controlling a getting real weather forecasts or controlling Philips Hue lamp:

For a full documentation on the messages emitted from the Snips Platform, read the Hermes Reference.

Step 7: Deploying the action code to the Raspberry Pi

Once you are satisfied with your action code, you can optionally deploy it to your device, for instance to have it run continuously.

First, copy the project to the Raspberry Pi using scp (replacing the raspberrypi hostname if needed):

scp -rp . pi@raspberrypi.local:/home/pi/HelloSnips

Now, log in to your Raspberry Pi using SSH, as in Step 2:

ssh pi@raspberrypi.local

In order to run the JavaScript code, you might need to manually reinstall Node, depending on your Raspbian version. This is done as follows:

(pi) sudo apt-get remove node nodejs nodejs-legacy nodered
(pi) curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
(pi) sudo apt-get install -y nodejs
(pi) sudo npm install npm@latest -g

We use the (pi) prefix to indicate that we are in an active SSH connection to the Raspberry Pi shell. When omitted, it is assumed that we are in a terminal window on your local machine.

You may now start the app from the Raspberry Pi, by changing to the HelloSnips directory and running Node again:

(pi) cd HelloSnips
(pi) node index.js

You should see the same output as in Step 6!

Step 8: Running the action code automatically on boot

The Snips Platform is configured to start automatically when the Raspberry Pi restarts. If you also want the action code to be executed when the device is restarted, you will have to create a systemd task that tells the system to run the above JavaScript code automatically.

On your computer, create a file named HelloSnips.service, and paste the following:

[Unit]
Description=Concierge
[Service]
Type=simple
User=%i
ExecStartPre=/bin/sleep 2
ExecStart=/usr/bin/node /home/pi/HelloSnips/index.js
[Install]
WantedBy=multi-user.target

Copy it to the home folder on your Raspberry Pi using scp:

scp HelloSnips.service pi@raspberrypi.local:/home/pi

Now, log in again to your Raspberry Pi using SSH, as in Step 2:

ssh pi@raspberrypi.local

Move the file to /etc/systemd/system and give it appropriate permissions:

(pi) sudo mv HelloSnips.service /etc/systemd/system
(pi) sudo chmod a+rx /etc/systemd/system/HelloSnips.service

Finally, reload the configuration and enable the HelloSnips service:

(pi) sudo systemctl --system daemon-reload
(pi) sudo systemctl enable HelloSnips

You should now be able to reboot your Raspberry Pi, and HelloSnips will automatically be launched. You can check the logs on the Pi using journalctl:

(pi) sudo journalctl -u HelloSnips.service

Next steps

Make sure to check the following articles to get you up and running on more advanced features and configurations: