MATRIX Devices Running Mycroft.AI

Required Hardware

Before getting started, let's review what you'll need.

• Raspberry Pi 3 (Recommended) or Pi 3 Model B+ (Supported).
• MATRIX Voice or MATRIXCreator - Raspberry Pi does not have a built-in microphone, the MATRIX Voice&MATRIXCreator each have an 8 mic array - Buy MATRIX Voice or Buy MATRIX Creator.
• Micro-USB power adapter for Raspberry Pi.
• Micro-SD Card (Minimum 8 GB) - Steps on how to install the Picroft OS provided below.
• External Speaker
• Micro-USB Cable
• A PersonalComputer to SSH into your Raspberry Pi.
• Internet connection (Ethernet or WiFi)

Let's Get Started

Below are all the steps to setup and install Mycroft, the open source voice assistant, with your MATRIX device. Each Assistant you make will need to be tied to a Mycroft account.

You can sign up for an account here.

1. Setting up Picroft OS with Your Raspberry Pi

• Download the Picroft Stretch image from https://mycroft.ai/to/picroft-unstable.
• Burn the image to your micro-SD card. We Recommend Using Etcher.io for this.

2. Enable SSH on Your Raspberry Pi

Insert your micro-SD card into your personal computer. Once inserted, a drive named boot will appear. The example below is from Windows 10 but you will see the same drive appear in the Finder on Mac.

You'll then need to create 1 file inside the boot drive.

• wpa_supplicant.conf: The WiFi credentials to connect to.

The wpa_supplicant.conf file needs the following:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={    
  ssid="INSERT_YOUR_WIFI_NAME_BETWEEN_THE_QUOTES"
  psk="INSERT_YOUR_WIFI_PASSWORD_BETWEEN_THE_QUOTES"    
}

Make sure your Raspberry Pi is on the same WiFi as your personal computer!

Starting Your Raspberry Pi

With your Raspberry Pi's Micro-SD Card configured, follow the steps bellow to SSH Into your Pi.

• Attach your MATRIX device to your Raspberry Pi
• Insert the microSD card
• Attach a speaker via audio jack, HDMI or USB
• Power your Raspberry Pi

SSH Into Your Raspberry Pi

Open an SSH enabled terminal application on your personal computer

• Windows 10: PowerShell
• macOS/Linux: Terminal
• Windows 7 & 8:Download Putty

You can then insert the following command to SSH into your Pi.

ssh pi@picroft.local

If the command above doesn't work, you can enter the IP Address of your Pi instead. Below is an example.

ssh pi@192.168.1.80

You will then be prompted for a password (default password is mycroft).

3. Configuring Mycroft on the Raspberry Pi

• Follow the Mycroft guided setup on the Pi's terminal.
• Choose “Other” under microphone options.
• When prompted, choose to setup the microphone later.
• Continue to follow the guided setup by selecting your desired options.
• At the end of the setup, you will arrive at the Mycroft command line as shown below, use Ctrl+C to quit out of the Mycroft CLI client. This will bring you to your Raspberry Pi's command line.

4. Installing MATRIX Kernel Modules from Package

In your Raspberry Pi's terminal,

Add repo and key

curl https://apt.matrix.one/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.matrix.one/raspbian $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/matrixlabs.list

Update and install packages

sudo apt-get update
sudo apt-get upgrade

Reboot in case of Kernel Updates

sudo reboot

SSH back into your Raspberry Pi and Ctrl+C to leave the Mycroft CLI client.

Install MATRIX Packages

sudo apt install matrixio-kernel-modules

Install pulseaudio

sudo apt-get install pulseaudio

One more reboot

sudo reboot

SSH back into your Raspberry Pi and Ctrl+C to leave the Mycroft CLI client again.

5. Setting Up Your MATRIX Device's Microphones with Mycroft

• Make sure that the MATRIX device's microphone is recognized by typing the following command in the terminal.

pactl list sources short

The result should look something like this.

Make sure one of the sources points to an alsa input with the matrixio-codec as shown in source 2 above and take note of the source number.

• To make sure that the standard microphone is the MATRIX device, input the commands below to kill pulseaudio, set it as default (with the correct source), and restart pulseaudio.

pulseaudio -k
pactl set-default-source 2
pulseaudio --start

• Check the output volume.

amixer

Take note of the Front Left and Front Right Playback %.

If they are low, then set the volume higher using the following command.

amixer set Master 99%

The result of amixer should now be this.

• If after a reboot the volume goes back down, then follow the steps below to keep the audio at your desired volume.

Type the following command in your Pi's terminal.

sudo nano audio_setup.sh

Add the following line to the end of the file, then exit and save (Ctrl+X, then Y).

amixer set Master 99%

• Test your MATRIX device's microphone using the following command in your Pi's terminal.

mycroft-mic-test

6. Registering Your Device with Mycroft

• Mycroft will periodically speak a 6-character code out loud to you once it is connected to the internet. That is your device registration code.
• Note down the registration code Mycroft speaks.
• Go to https://home.mycroft.ai/ and click on your account name in the top right corner.
• Select "Devices" from the drop-down menu. This will take you to the Registered Devices page.
• Then click on the "Add Device" button.
• Provide the 6-character code, add a device name, and description.
• Click on "OK, LET'S PAIR".
• Momentarily, your Mycroft assistant will alert you that it is ready and give you some sample commands to ask.

7. (Optional) Set Your Device Location

If you want to change the location of your device, in your Mycroft dashboard,

• Navigate back to the Registered Devices page as mentioned above.
• Click on your device.
• Fill in the Location field with the appropriate location.

You're all set, enjoy talking to Mycroft!