Picroft
Picroft is a ready-made way to run Mycroft on a Raspberry Pi 3, 3B+ or 4 and is provided as a disk image that you can burn to a Micro SD card.
Note as at 2022-11-11:
The official Picroft image is not currently being actively maintained as our teams attention is firmly on the Mark II at the moment. Picroft is intended as a DIY development platform and requires basic knowledge of Linux and the commandline.
If you need support with your Picroft please post in the Community Forums or Chat. Mycroft cannot provide technical support for Picroft and other DIY projects.
In order to set up Picroft, you will need to have a basic understanding of the Linux (Raspbian) command line, be comfortable connecting devices to WiFi networks, and have a little patience when setting up audio devices.
Model | Level of support |
Pi4 | Supported |
Pi3 B+ | Supported |
Pi3 B | Supported |
Pi 2 | Functions very slowly, limited wifi support |
Pi B | Not supported |
Pi A+ | Not supported |
Pi Zero, Zero W, Zero WH | Not supported |
As well as a Raspberry Pi, you will also need:
- Micro SD card, 8GB or larger highly recommended
- Power adapter with micro USB for your country. The Raspberry Pi Foundation has some excellent recommendations.
- An analog Speaker that can be plugged into the 3.5mm audio jack on the RPi or a USB Speaker (Bluetooth on Picroft is difficult to get working and is not recommended)
- USB Microphone
Installing Picroft may be easier if you also have:
- USB keyboard
- Monitor or TV connected via HDMI cable
- Ethernet cable (if not connecting via WiFi)
The following is a Community maintained list of hardware that has been used with Picroft. Whilst every effort is made to keep this list updated, upstream software changes may cause future problems with device compatibility. Mycroft can not guarantee that any specific hardware will work with Picroft.
If you are looking for a low-cost option to try out Picroft, we can recommend the PlayStation Eye (often called a PS3 Eye).
Brand | Model | Status | Type | Notes |
Adafruit | Working | Multi-mic hat | ||
AmazonBasics | LJ-USM-001 | Working | USB Conference Microphone | |
Andrea Electronics | C1-1028100-3 | Working | USB Dongle (Mic array & Speaker 3.5mm) | Superbeam Array Microphone Bundle SUMA ( 08a8:0016) |
Blue | Snowball iCE | Working | Microphone | |
Creative | VF0790 | Working | Mic and camera | |
Google | AIY v1 | Working | Mic and speaker | |
Jabra | Speak 410 | Mic and speaker | Premium microphone and speaker combination | |
Logitech | C270 | Working | Mic and camera | |
Logitech | C525 | Working | Mic and camera | |
Logitech | Webcam Pro 9000 | Working | Mic and camera | |
Logitech | Z50 | Working | Speaker | |
Matrix | Voice | Working | Mic array | |
PlayStation | Eye (PS3 Eye) | Working | Mic and camera | An excellent introductory model if you are just checking Picroft out. |
Seeed Studio | Mic Array 2.0 | Working | Mic array | Premium microphone array |
YOTTO | B08VD5JZJD | Working | Mic | 360° Omnidirectional Conference Mic |
Community members have reported some minor modifications that are required for this device to function.
In the file
/etc/pulse/default.pa, uncomment or add the following lines:load-module module-alsa-sink
load-module module-alsa-source device=hw:1,0
set-default-sink alsa_output.platform-soc_sound.stereo-fallback
set-default-source alsa_input.hw_1_0
Bluetooth audio devices are notoriously difficult and are not supported by default. At the time of writing, this thread on the Community Forums is a good starting point.
If you have had success using Bluetooth devices with Picroft please contribute your experience and help us update this documentation for a more positive wireless future.
Next, the disk image needs to be burnt to the Micro SD card.
If you prefer to use the Linux command line tool
dd to burn the disk image instead, follow these instructions:- 1.
- 2.Insert the Micro SD card you wish to burn the image to. It must have a storage capacity of 8GB or higher.
- 3.Identify the path where the MicroSD card is mounted by running the command
sudo fdisk -l. You will be able to tell the path based on the storage size of the device. - 4.Keep a note of this - it will be something like
/dev/sdb. If you are not 100% sure about which disk you are flashing, safely eject the disk and rerun the command to make sure it is no longer reported byfdisk. Performing the following operations will delete the entire contents of the disk. - 5.Unmount all partitions on that disk so that no other operation can write to the device while it is being imaged using the command
sudo umount /dev/sdb*. Make sure to substitute for the location of your device. - 6.Run the command
sudo dd if=path-to-your-image.img of=/dev/sdb bs=20M. Make sure to substitute the path to the.imgfile you downloaded, and the location of your device. - 7.This will take several minutes to run. The command prompt will return if successful, otherwise an error message will be displayed on your terminal.
There are two ways to see the output from a Picroft Device:
- 1.Plug Picroft into a HDMI monitor or television, and attach a USB keyboard. If you are planning to connect Picroft to a WiFi network, you will first need to connect to a HDMI monitor or television so that you can manually configure Picroft's WiFi settings.
- 2.
sshinto Picroft once Picroft is connected to a wired or wireless network
If you would like to see the output of Picroft on a monitor (rather than SSH'ing in to Picroft), you can plug a HDMI monitor in to the HDMI slot on the Raspberry Pi.
If you would like to connect a keyboard or mouse (rather than SSH'ing in to Picroft), connect them via the USB slots on the Raspberry Pi.
In our experience, we've found most monitors, keyboards and mice are plug-and-play - ie. you shouldn't have to install any additional drivers.
Once you've burned the disk image to the Micro SD card, insert the Micro SD card into the Micro SD card slot on the Raspberry Pi. Plug in your microphone, speakers, and if you're using a monitor and/or keyboard, plug these in too.
Next, plug in the power and connect the Micro USB cable to the RPi. This "power on" the device.
If you have a HDMI monitor connected, you should start to see some output on screen.
If you're going to
ssh into Picroft, do the following:SSH access to Picroft is enabled by default, so you don't have to enable SSH access.
- Ensure you know the IP address of your Picroft Device on your network. If your Picroft is already paired, then a handy way to do this is to install the IP Address Skill, and then Speak:
Hey Mycroft, what's your IP address?
"here are my available IP addresses: wlan IP address ... Those are all my available IP addresses"If not, you will need to know what IP address your Picroft has. You may need to log in to your router to find out the IP address of your Picroft.
- Open up your favorite terminal program, like PuTTy on Windows, or a new terminal on Linux
- The default password is
mycroft, so enter this when prompted. - If you have successfully logged in via SSH you will see a command prompt like the one below:
$ ssh [email protected] <-- in this case, the IP address was 192.168.0.13, your IP address may vary
[email protected]'s password:
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Wed Oct 18 13:02:44 2017
[email protected]_1:~ $
You are now connected to Picroft via SSH.
On first boot, you will see a screen which looks similar to the one below:
Picroft initial boot screen
Picroft will then ask you whether you would like to do the guided setup, or drop straight to a command line. If you are new to Picroft, we recommend that you complete the guided setup.
NOTE: Audio output and audio input is the single most problematic part of Picroft setup; we've tried to provide lots of guidance here to get you up and running, but you may need to experiment to find a solution for your chosen audio output and input devices.
The guided setup will then ask you to select your audio output device, as shown below:
Picroft select audio output
Enter the number
1, 2, 3 or 4 corresponding to:1) Speakers via 3.5mm output (aka 'audio jack' or 'headphone jack')
2) HDMI audio (e.g. a TV or monitor with built-in speakers)
3) USB audio (e.g. a USB soundcard or USB mic/speaker combo)
4) Google AIY Voice HAT and microphone board (Voice Kit v1)
Next, test and adjust the volume. You may need to reboot your Picroft in order for the audio output device to be correctly selected.
The final step of the guided setup is microphone configuration. You will be asked to select your audio input device, as shown below:
Picroft select audio input
Enter the number
1, 2, 3 or 4 corresponding to:1) PlayStation Eye (USB)
2) Blue Snoball ICE (USB)
3) Google AIY Voice HAT and microphone board (Voice Kit v1)
4) Matrix Voice HAT.
5) Other (unsupported -- good luck!)
The guided setup will then do a microphone test to ensure your chosen microphone is working OK.
Once the Picroft is connected to the internet, and you have run through the guided setup, Picroft will reboot. Picroft will boot into the
mycroft-cli-client screen, and a Registration Code will be spoken, and will also be shown on the mycroft-cli-client screen, as shown below:
Picroft pairing
Once paired, you can then use basic Skills to get started. For example, you can ask questions like 'Tell me about Abraham Lincoln' - shown below:
Picroft basic commands
Simply plug the ethernet cable into the RJ45 (ethernet) socket on the RPi. Picroft will then attempt to connect to the network, and request a DHCP address.
You will need to connect to your router, or use other networking diagnostics, to identify what IP address your Picroft has been allocated on the network.
By default, Picroft is not configured for WiFi. Picroft can connect to most 2.4GHz WiFi networks, but this has to be manually configured.
First, you need to be able to edit files on the filesystem of the Picroft. There are two ways to do this.
- 1.Plug the Picroft into a keyboard and HDMI monitor then type
Ctrl + Cto get to the command line or - 2.if you are already connected using a wired connection and you know the Picroft's IP address, SSH in to the Picroft device
Next, we edit the
wpa_supplicant.conf file. This file controls WiFi connections for the Raspberry Pi.- 1.Type
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf - 2.Using the down arrow key, navigate to the bottom of the file, and add credentials for your SSID. You may also need to add the relevant two-character country code.
country=US
network={
ssid="MyNetworkSSID"
psk="mypassword"
}
- 1.Type
Ctrl + Xto exit andYthenEnterto save your changes. - 2.Type
sudo reboot now
You will need to connect to your router, or use other networking diagnostics, to identify what IP address your Picroft has been allocated on the network.
Manually configuring WPA2 Enterprise WiFi with MSCHAPV2 authentication
If you are on an enterprise network, your network security might use WPA2 with MSCHAPV2 authentication. Configuring Picroft to use MSCHAPV2 is similar to the above, but requires some additional steps.
First, we need to generate a hash of your SSID's password.
echo -n your_password| iconv -t utf16le | openssl md4
This will use the NTLM hash which is a 16 bit MD4 hash. Make sure to copy this as we will need it for later steps.
Next, run the following commands:
cd /etc/wpa_supplicant
sudo nano wpa_supplicant.conf
Add the following to the bottom of the
wpa_supplicant.conf file, replacing ssid with your SSID name, identity with your username and password with the hash generated earlier. Type Ctrl + O to save, then Ctrl + x to exit.network={
ssid="ssid network name"
priority=1
proto=RSN
key_mgmt=WPA-EAP
pairwise=CCMP
auth_alg=OPEN
eap=PEAP
identity="user_name"
password=hash:hash_key_here
phase1="peaplabel=0"
phase2="auth=MSCHAPV2"
}
Next, reboot the Picroft using
sudo reboot now. If these steps have worked, you will be connected to your enterprise WiFi shortly after rebooting.You will need to connect to your router, or use other networking diagnostics, to identify what IP address your Picroft has been allocated on the network.
NOTE: Picroft cannot connect to WiFi networks that operate in the 5GHz band. You must select a WiFi network that operates in the 2.4GHz band.
NOTE: Picroft cannot connect to WiFi networks that operate on Channels 12 or 13 (2467MHz and 2472MHz frequencies). Please configure your SSID to use a different channel or frequency. These channels are often used in Germany and other European countries.
Congratulations! You now have a fully functional Picroft, and can start exploring all the options you now have. Consider using it as a stand-alone voice assistant, or connect it to a monitor and keyboard, and develop straight away. If you don't have a monitor and keyboard, SSH is enabled by default so you can remotely connect to it straight away.
Picroft uses a Raspbian Stretch Lite image under the hood - with Mycroft pre-installed - so everything you can do with Raspbian, you can do with Picroft. You can download other packages, get it running as a server - or more!
For more help or ideas, consider joining our Picroft channel on Mycroft Chat or reading through our Picroft topic on the Mycroft Forum.
There are several commands that are packaged into Picroft to help you with advanced functionality:
mycroft-cli-client: This command will start the Mycroft CLI client if you are on the Linux command linemycroft-help: This command brings up help informationmycroft-mic-test: This command re-runs the microphone test from the guided setupmycroft-pip: This command runspipwithin the Mycroft Pythonvirtual environment(venv). This is useful if you are installing dependencies for Skills.mycroft-say-to: This command sends a command to Picroft, just like you had 'spoken' a command. This is useful if your microphone is not working.mycroft-setup-wizard: This command re-runs the guided setupmycroft-skill-testrunner: This command runs thetestrunner- used to run unit tests for a Skill. This is useful if you are doing Skills development with Mycroftmycroft-speak: This command gets Mycroft to 'speak' using Text to Speech.mycroft-venv-deactivate: This command deactivates the Mycroft Pythonvirtual environmentand is useful if you want to install other software on the Picroft device.mycroft-wipe: This command wipes Picroft back to factory default status. This will unpair the device and remove any configuration changes you have made.
If you plan to do Skills development work, or other development work with Picroft, you'll find knowing these file locations useful.
- Skills - have a shortcut in
/home/pithat points to/opt/mycroft/skills mycroft-core- is located at/home/pi/mycroft-core- Logs - are located at
/var/log/mycroft/ mycroft.conf- is located at/home/mycroft/.mycroft/mycroft.conf- Identity file (do not share) - is located at
/home/mycroft/.mycroft/identity/identity2.json
To reimage a Picroft Device, download the latest disk image. Burn that to a MicroSD card using a tool like the Raspberry Pi Imager, and insert the burned MicroSD card into the Raspberry Pi, then connect the Raspberry Pi to power.
To keep
mycroft-core and the Skills on your Picroft updated, first ssh in to Picroft, then run the update.sh script:(.venv) [email protected]:~ $ bash update.sh
This script will update both
mycroft-core and the Skills on your Picroft device.The Picroft image building instructions can now be found on GitHub at; https://github.com/MycroftAI/enclosure-picroft/blob/stretch/image_recipe.md
One common question we get is - "Can I use the general purpose input output pins (GPIO) on the Raspberry Pi with Picroft?".
The answer is 'Yes' - but this requires some additional configuration.
You need to add the
pi user to the gpio group with the commandsudo usermod -g gpio piYou also need to install some additional packages:
sudo apt-get install python-rpi.gpio && sudo apt-get install python3-rpi.gpioThis example GPIO Skill provides some good examples of how to use GPIO input and output in your Mycroft Skill.
Last modified 2mo ago