Before you get started, let's review what you'll need.
- Raspberry Pi 3 (Recommended), Pi 3 Model B+ (Supported), or Pi 4.
- MATRIX Voice ESP32 version - Buy the MATRIX Voice.
- Micro-USB/USB-C power adapter for Raspberry Pi
- Micro-SD Card (Minimum 8 GB)
- A PersonalComputer to SSH into your Raspberry Pi
- Internet connection (Ethernet or WiFi)
FuPy is a framework that uses LiteX & Migen+MiSoC to build firmware for SoC softcores in FPGAs, as well as build the BIOS+MicroPython firmware for the softcore, all in Python. It also includes FLTERM for loading the firmware onto the FPGA.
We will be using FuPy to load a
vexriscv softcore on the MATRIX Voice's Spartan-6 FPGA.
The environment we're setting up in this guide will end with our PC serving as the development environment for the gateware (FPGA binary) and firmware. The binaries will then be sent to the Raspberry Pi which will upload them to the MATRIX Voice FPGA for deployment.
This guide sets up a base SoC accessible through a MicroPython REPL. All of the MATRIX Voice functions such as LEDs, GPIOs, and mics have not yet been ported to be controllable through the SoC. Those features will be covered in future guides.1. Set Up Xilinx ISE on Your PC
First, follow this guide to install the Xilinx ISE on your PC to compile Spartan-6 FPGA gateware.2. Clone Repo & Set up Build Environment
The following steps are for the terminal on your personal computer.
Clone the repo.
git clone https://github.com/matrix-io/litex-buildenv
Enter the repo and export all relevant environmental variables.
Download the environment dependencies.
Enter the build environment.
3. Build Gateware & Firmware Files
Build the MicroPython environment, source the Xilinx ISE, and build the FPGA gateware.
The process above should result in 2 key files:
- FPGA gateware:
- BIOS+micropython firmware:
Attach the MATRIX Voice to your Raspberry Pi and install the initialization packages.
Add the MATRIX repository 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 your repository and packages.
sudo apt update
sudo apt upgrade
Install MATRIX init package.
sudo apt install matrixio-creator-init
Update boot overlay by adding the following to the end of
Reboot your device for device initialization to occur.
SSH back into your Pi from PC.
git if you don't have it on your Pi already.
sudo apt install git
Clone repo for FLTERM.
5. Flash MATRIX Voice FPGA from Pi
git clone https://github.com/timvideos/flterm
Copy over the LiteX firmware files from your PC to your Pi by entering the following commands in your PC's terminal. Be sure to change
YOUR_PI_IP to your Pi's IP address.
scp ./build/matrix_voice_base_vexriscv.minimal/software/micropython/firmware.bin pi@YOUR_PI_IP:/tmp
scp ./build/matrix_voice_base_vexriscv.minimal/gateware/top.bit pi@YOUR_PI_IP:/tmp
Make and run FLTERM to flash the BIOS & MicroPython firmware once the FPGA gateware is flashed in the next step. Keep this process running.
./flterm --port=/dev/ttyAMA0 --speed=230400 --kernel=/tmp/firmware.bin
In another terminal session in the Pi, use
xc3sprog to flash the FPGA gateware to the MATRIX Voice.
sudo xc3sprog -c matrix_voice /tmp/top.bit
If the above does not work, try the following instead.
sudo xc3sprog -c sysfsgpio_voice /tmp/top.bit
The result should look like the following.
vexriscv SoC soft core with the following simple code to turn an indicator LED on and off.
l = litex.LED(1)
The above process has been tested with the lm32 MCU as well. You can see the list of supported MCUs here.
For more information on the FuPy project, check out the description and links here.