RISC-V SoC Soft Core w/ MicroPython on MATRIX Voice FPGA

Required Hardware

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)

Create SoC SoftCore on MATRIX Voice FPGA

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.

cd litex-buildenv/
export CPU=vexriscv
export CPU_VARIANT=minimal 
export PLATFORM=matrix_voice
export FIRMWARE=micropython
export TARGET=base
export HDMI2USB_UDEV_IGNORE=somevalue

Download the environment dependencies.

./scripts/download-env.sh

Enter the build environment.

source ./scripts/enter-env.sh

3. Build Gateware & Firmware Files

Build the MicroPython environment, source the Xilinx ISE, and build the FPGA gateware.

./scripts/build-micropython.sh

The process above should result in 2 key files:

• FPGA gateware: build/matrix_voice_base_vexriscv.minimal/gateware/top.bit
• BIOS+micropython firmware: build/matrix_voice_base_vexriscv.minimal/software/micropython/firmware.bin

4. Set Up Raspberry Pi

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 /boot/config.txt.

dtoverlay=disable-bt

Reboot your device for device initialization to occur.

sudo reboot

SSH back into your Pi from PC.

Install git if you don't have it on your Pi already.

sudo apt install git

Clone repo for FLTERM.

git clone https://github.com/timvideos/flterm

5. Flash MATRIX Voice FPGA from Pi

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.

cd flterm
make
./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.

Test the vexriscv SoC soft core with the following simple code to turn an indicator LED on and off.

import litex
l = litex.LED(1)
l.on()
l.off()

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.