How to Build PYNQ v2.5 for Ultra96

In this post we’re going to build an SD image for PYNQ release v2.5 (tool version 2019.1) for the Ultra96 board. The starting point will be the virtual machine that we setup in an earlier post How to Install PetaLinux 2019.1. In that post we installed Vivado & SDK 2019.1 and PetaLinux 2019.1 on the VM, and we’ll need all three of them to build the PYNQ SD image. I highly recommend that you follow that post and recreate exact same VM to avoid any issues going through this post.

Step 1: Setup passwordless sudo privilege for your username

Passwordless sudo privilege allows you to use the sudo command without having to enter a password each time. The PYNQ SD build process can take several hours and there are multiple sudo calls made throughout the process, so you’re better off to set this up before launching the build. Follow these steps from a terminal on your VM:

1. Edit the sudoers file with nano: sudo nano /etc/sudoers
2. Add this new line to the bottom of the file: jeff ALL=(ALL) NOPASSWD: ALL (replace jeff with your user name).
3. Press Ctrl-O to save the changes, then Ctrl-X to exit nano.

Step 2: Clone and setup the Ultra96 PYNQ repository

1. We’ll keep everything in our home directory and contained within a subdirectory called ~/pynq. Create this directory and clone the Ultra96 PYNQ Git repository into it with these commands:

mkdir ~/pynq
cd ~/pynq
git clone https://github.com/Avnet/Ultra96-PYNQ.git
cd Ultra96-PYNQ
git checkout -b image_v2.5 origin/image_v2.5

2. The Ultra96 PYNQ repo contains the files required for both the v1 and v2, however when building PYNQ, it has to be setup to target only one of the two versions. To setup the repo to target the v2, run the following commands. If you want to target the v1 instead, just replace v2 with v1 in each line.

cd ~/pynq/Ultra96-PYNQ/Ultra96
ln -s specs/Ultra96_v2.spec Ultra96.spec
cp -f sensors96b/sensors96b.bit.v2 sensors96b/sensors96b.bit
cp -f sensors96b/sensors96b.tcl.v2 sensors96b/sensors96b.tcl
cp -f sensors96b/sensors96b.hwh.v2 sensors96b/sensors96b.hwh

Step 3: Clone the PYNQ repository and setup the build environment

1. Clone the PYNQ repository into the ~/pynq directory:

cd ~/pynq
git clone https://github.com/Xilinx/PYNQ.git
cd PYNQ
git checkout origin/image_v2.5.4

2. The PYNQ repository contains a script that installs all of the PYNQ dependencies. Run the script with these commands:

cd sdbuild
./scripts/setup_host.sh

3. Reboot the VM.
4. Source the setting scripts for Vivado and PetaLinux 2019.1. Note that the location of the settings files will depend on where you installed Vivado and PetaLinux, so you may need to change the paths before running the commands below:

source ~/Xilinx/Vivado/2019.1/settings64.sh
source ~/Xilinx/SDK/2019.1/settings64.sh
source ~/petalinux/2019.1/settings.sh

5. Turn PetaLinux WebTalk OFF:

petalinux-util --webtalk off

6. When the script completes successfully, run the following command to make sure that all of the dependencies are installed. If it outputs a list of packages and NO error messages, then it’s a success.

make checkenv

Step 4: Build the PYNQ image for Ultra96

You should expect the build process to last for several hours. One reason why it takes so long is that by default it will build PYNQ for three extra boards: PYNQ-Z1, PYNQ-Z2 and ZCU104. We need to build for PYNQ-Z2 as mentioned in this forum post, but we can remove the other two boards from the repository to save on build time:

1. Use git rm to remove the PYNQ-Z1 and ZCU104 board files, and then locally commit the changes. Note that we need to locally commit the changes, because the build process uses the most recent git commit and ignores any uncommited changes to the repository.

cd ~/pynq/PYNQ/boards
git config --global user.email "[email protected]"
git rm -r Pynq-Z1
git rm -r ZCU104
git commit -m "removed board files for pynq-z1 and zcu104"

2. Run make to launch the build. The build script expects you to pass a variable called BOARDDIR whose value is the path to the board files for which you want to build PYNQ. In our case, this path must be set to the location of our Ultra96 PYNQ repository: ~/pynq/Ultra96-PYNQ. Run the following commands to launch the build:

make clean
make BOARDDIR=~/pynq/Ultra96-PYNQ

Step 5: Write PYNQ image to SD card

If the build completes successfully, you will find an SD card image here: ~/pynq/PYNQ/sdbuild/output/Ultra96-2.5.img

1. Insert a blank SD card into a USB card reader that your VM can access
2. Find the SD card’s device name by running the dmesg command in the terminal. The SD card should be found at the end of the log, and it’s device name should be something like /dev/sdX where X is a letter such as a,b,c,d, etc. In the following commands, I will assume that the SD card is /dev/sdX, but you will need to replace the X with the right letter for your SD card.
3. Use the following command to write the PYNQ image to the SD card:

sudo dd if=~/pynq/PYNQ/sdbuild/output/Ultra96-2.5.img of=/dev/sdX status=progress bs=4M

Time to boot PYNQ!

Now all that is left to do is to plug the SD card into the Ultra96 and power it up. We’ll go through how to use PYNQ for Ultra96 in a future post, but for now you can read about it in the documentation.