A PYNQ-Z2 Guide for Absolute Dummies — Part I: Getting Started with PYNQ
In this blog, we will see how to bring up your board from scratch without going to any other website.
I am one of those people who love to read “How to do” Articles with a lot of self-explanatory images. So, for example, If I am looking for something or stuck on something, I sometimes love to read articles that describe all the steps with images instead of spending countless minutes watching videos. I am not saying that videos are useless. But sometimes, I am not in the mood to watch long videos. This article is written in a way that if you just keep scrolling, the images will guide you on everything.
If you have already brought up your board and want to write some Verilog code to toggle LEDs on the board, read the second part of the blog “Let’s Burn some Verilog code”.
Recently, I purchased PYNQ-Z2 to explore its features. It took me some time to figure out things. I am a person who dives deep into the concepts for every step I take. This article will, first of all, get you started with the board without looking for other sources, and second, it will explain every step and its purpose. And in the end, we will explore how to program different LEDs and switches on the board.
I have worked on FPGAs in different parts of my career. I have worked on boards from Xilinx, Altera, and Lattice Semiconductor. I always wanted to buy the ZYNQ series board and work on them. In 2018, I came across a client that wanted to do some Computer vision in real-time. I came across different ZYNQ boards that grabbed my attention. People are running Jupiter notebooks and doing all sorts of image and video processing with a reasonable frame rate.
You could install any python library like OpenCV, Matplotlib, pandas, NumPy, etc, and do all kinds of computational tasks. If you have come across Single board computers like Raspberry Pi etc you must be thinking that why even buy an FPGA kit to do all kinds of things that you can do with Single board processors for under $15? I bought the PYNQ-Z2 for a price of $140 without shipping cost. So why even bother to buy FPGA for running python-based applications?
There might be other questions in your mind. For example, what is the learning curve on PYNQ-Z2, How to get more information or study about it in-depth, How can you leverage the actual power of the FPGA, etc? These are all the questions in my mind when I started to use this board. In this article, I will explain to you all the things along with visuals so that you feel comfortable and confident to work on the board. If you have no idea about this board, you are in the right place.
Note: If for some reason you have or plan to buy PYNQ-Z1, Don’t Worry! You can also follow along with the tutorial. Most of the features are the same. The major difference is the Expansion header and the audio system. So, You just need to use the right board configurations and the whole tutorial will work for you as well.
Here is a detailed photo in which you can see all the interfaces.
Step 0: Getting Started with PYNQ — Things you MUST have!
Make sure you have the following things with you.
- PYNQ-Z2: Of course, the most important thing. Again don’t worry if you have purchased PYNQ-Z1. You can read my blog to understand more about PYNQ-Z1 vs PYNQ-Z2.
2. Micro-SD Card: The minimum you need is an 8GB Micro-SD card. I would recommend you get a 32GB Class10 Micro-SD Card. They have better reading and writing speeds.
3. Ethernet Cable: Yes You need an Ethernet cable. You will be using this to connect the board to your laptop or your router if you want internet capability. You will be connecting to the board from your PC/Laptop with Ethernet even if you don’t have internet.
4. Micro-USB Cable: This will be used to power up the FPGA. You can power up the FPGA board using your laptop with this cable. If for some case you need high power, then you can use an adapter (7–15V) that can provide sufficient current for your requirements.
Warning: Never connect both the adapter and the MicroUSB to power up the device. And make sure you configure the Source Selection jumper properly. If you are using the USB then you should configure the jumper at the blue position shown below.
5. External Micro-SD Card Reader: You will need to flash an OS image onto the Micro-SD Card. Either you should have a built-in, or you need to get an external Card Reader.
6. TPLink TL-WA850RE WiFi Range Extender (Optional): The only reason you can use it as a WiFi to Ethernet Converter. If you want to download packages from the internet on your PYNQ Development board, you need to have a connection with the internet. If you have a router nearby you can connect your kit and the router directly by the Ethernet cable. If you don’t need the internet, then you can directly connect your FPGA with your laptop Ethernet. Of course, it requires some additional IP configurations.
This device acts as a range extender and provides an Ethernet port for internet connectivity. I simply connected it to a power socket near my laptop and connected my PYNQ Board with it using Ethernet. And that’s an expensive way of connecting your FPGA with the internet.
Not so pro Tip: There are some blogs over the internet about how to share your WiFi over Ethernet which is by going to Network and Sharing Center → Clicking on the WiFi Network → In the Wi-Fi Status Screen Click Properties. Click the “Sharing” tab and check both boxes. I was not able to connect my FPGA to the internet this way. :(
Also, there is a software called “Connectify”. It can do so. Have a look at (https://support.connectify.me/article/83-ethernet-to-ethernet). You can try it if you want.
Step 1: Preparing the MicroSD Card:
If you have ever used FPGA in your life, you might have created a new project in your favorite IDE, wrote some Verilog/VHDL code, Defined Some inputs and outputs, Synthesized the hardware, and programmed it into your FPGA and Wallah. It didn’t work (Until you haven’t made a single mistake). But this time, the first step is to prepare your MicroSD Card.
Well, You must be thinking why are we even preparing some MicroSD Card? Here is a diagram that will be revealing the secret.
Both PYNQ-Z1 and PYNQ-Z2 are based on ZYNQ-7020 SoC that includes ARM Cortex-A9 Processors. This part of the FPGA is called the Processing System (PS). The second part is called Programmable Logic (PL) part that behaves exactly as all other FPGAs. This portion is basically the hardware part you can design using an IDE called VIVADO. Both PS and PL can talk with each other using AXI Interconnect Interface. So the whole idea is that you leverage the power of Linux on the ARM Processors while accelerates algorithms on the PL. Essentially, preparing an SD card means that you will install an OS on the SD card using some image file and boot the ARM processors from the SD Card. Let us prepare the SD card and get started.
- Download the Image file (PYNQ-Z2 latest PYNQ image) from http://www.pynq.io/board.html. Once you download the file, Please unzip the file.
2. The next step is to burn the image into the SD Card. I had Rufus Installed on my system. I tried that and failed. It should have worked but then I moved on to Win32 Disk Imager. So please download WIN32 Disk Imager if you don’t want to waste your time. (https://win32diskimager.download/).
3. You need a MicroSD Card Reader on your laptop to flash the image. Most Laptops come with the SD-Card slot. You can simply use a MicroSD Adapter. Otherwise, you need to buy an external card reader. Whatever is the case, insert your MicroSD card into your laptop or external card reader.
4. Run “Win32 Disk Imager”. Make the drive letters under the Device correspond to your MicroSD device. Press the button with folder icon on it and select the extracted “.img” file. Press the Write button. It should take a couple of minutes.
At this point, you have flashed the OS in your MicroSD Card.
Step 2: Board Setup
Now, this is where the fun begins. However, you should remember that you are a complete beginner and you need to know how to set up your board.
- You need to tell your board that “Hey, I have installed the MicroSD card and you should boot the ARM Processors from there”. There are two other options (QSPI and JTAG). Let’s ignore them for the while and make sure the jumper is placed in the blue position that corresponds to SD.
- You need to specify the power source. If you are using MicroUSB, then you should place the jumper at the position shown in blue.
- You might have forgotten your MicroSD card in your laptop or card reader. Take out the Adapter and then take out the MicroSD card. Flip your board and insert the card in the provided slot. There is only one way your MicroSD can go into the slot. You feel a slight click if inserted properly. Don’t push very hard.
- Connect one end of the MicroUSB cable to your laptop and the other end to the MicroUSB slot on the kit.
- If you have Internet: If you have a router nearby, then make a direct connection of your development kit Ethernet with the Ethernet port on the router. If you can share your Laptop WiFi with its Ethernet, then instead of the router you need to connect it with the Ethernet of your laptop. The option is if you have to use the WiFi to Ethernet connector. This will configure the IP address on the FPGA automatically using DHCP Server. What if you don’t have Internet: If for any reason, you don’t have internet connectivity then you will need to connect your FPGA with the Ethernet port of your PC/Laptop and configure the IP address of your PC/Laptop. You need to configure your IP address as 192.168.2.1 and subnet mask as 255.255.255.0. Leave other fields as blank. This is called assigning static IP Address. The Development board has a default static IP address as 192.168.2.99. For other operating systems, please refer to this page: (https://pynq.readthedocs.io/en/v2.5/appendix.html#assign-your-computer-a-static-ip)
- Slide the power switch to the on position. The RED LED should immediately turn on. If it doesn’t make sure the power cable is working and the Power Source Jumper is at the correct position. After a while, the DONE LED should be turned on followed by flashing of 2 Blue LEDs and 4 Green User LEDs. The blue LEDs will flash for a while then will switch off while the green LEDs will remain powered. This indicates that the board is ready to be used.
Here is a pictorial demonstration of the bootup process of the PYNQ-Z2 board.
Troubleshooting Tip: Make sure your power cable is not faulty. Mine was faulty and it took me some time to figure out why the DONE Led is NOT turning ON even though the Power LED was on. I changed my MicroSD card, I re-flashed the image multiple times with different software. Turn out the culprit was microUSB Cable.
Step 3: If your Ethernet is connected to your Router
Note: Please skip this step if you have no internet connectivity where you place your FPGA.
For some people, it can become a tricky step. When you connect any device to your router using Ethernet, the router assigns an IP address to that device via DHCP Server. To talk with the FPGA, you need to find the IP address of the FPGA. To find the IP address of all the devices connected to your network, there is a software called “Angry IP Scanner”. You can get it from (https://angryip.org/download). I use the Executable for 32-Bit Java as there is no need to install the software.
Once the download is complete, run the software. You will see a similar screen.
It usually automatically detects your network configuration and configures the IP ranges. You just have to press the START button. It will take a few second and scan your entire network for devices. This is the results on my screen. The IP address on your system would be different.
If you are unsure about your network configuration, it is easy to do so. In Windows Open Command Prompt, press the WIN + R and type cmd. Hit Enter. Type “ipconfig” without quotes. You will see a similar screen.
Now you need to find the configuration for your WiFi Adapter. The IPv4 Address starts with 192.168.10 and the subnet Mask is 255.255.255.0. To search the whole network, you must provide starting address in “Angry Scanner” as 192.168.10.0 to 192.168.10.255.
Step 4: Talking to your PYNQ Board: (Password for Jupiter Notebook is “xilinx”)
If you followed Step 3 and were able to find the IP address of your board which in my case is 192.168.10.13, then all you have to do is open your favorite browser and type the following in your address bar and hit enter.
Note: If you have no internet connectivity, make sure you have followed Step 2 and configured the Static IP Address of your Ethernet. In this case, you need to type 192.168.2.99 in your address bar and you should see the same screen.
If all goes well, you will see the following screen.
The password was easy to crack i.e “xilinx”. Type the password in the textbox and press Login. You should be seeing the following screen.
A note on Jupiter-Notebook:
I think at this point I should tell you about Jupiter-Notebook. Now as I told you earlier that we are basically installing an operating system (Linux) that can leverage the power of ARM Processors. Jupyter-Notebook is a server that runs in Linux. By using a PC/Laptop you can connect to the device using the Jupiter-Notebook Server. You can now write code directly on your PC/Laptop Browser screen. However, it will be executed inside the FPGA Arm Cortex Processors. So basically you are able to run commands on the processors remotely. I think that is all that you should know.
Step 5: Creating your first notebook:
Lets create our first Notebook file. We will first create a new folder by pressing New → Folder.
A folder called “Untitled Folder” will appear. Click the empty checkbox and select it and press Rename. You can call this folder whatever you want. We will call it “Examples”. After Renaming, Click on “Examples”.
Now we will create a new Python file and run some commands on it. Again press New → Python. Rename the Notebook by clicking the “Untitled” label and call it “BlinkyWorld”.
Step 6: Learn Python:
Well. This guide will not be teaching your python language. I will be however explaining to you what each line is doing in terms of the board. However, If you feel uncomfortable after looking at the python syntax, please watch some tutorials.
Step 7: Blinking your first LED:
One cool feature Jupiter-Notebook provides you is to insert or delete cells. You can write a part of the code and just execute that code. Press the Insert button on the menu and choose Insert Cell Above or Below depending upon your need. You can execute the code on each cell by pressing Shift + Enter.
Try adding four cells. Write the code as shown in the figure and press Shift + Enter which should yield 20 after cell 4.
Here are some useful things you can also do. If you execute a forever loop, you can use the Kernel → Interrupt to stop the execution of the code.
Let us do some real stuff now. i.e Blinking LEDs which is the Hello World sort of application for languages. The idea is to use the SW1 and SW0 to control all four green LEDs. If SW1 is pushed up, LED3 and LED2 turn ON and off otherwise. Similarly, the other two LEDs will behave exactly the same but will be controlled by SW0.
Disclaimer: The code we will be writing will consider you a newbie in python and hence we will write code that is easy to understand without using and complex statements. However, you should be familiar with the basics of python.
Clear all the code and write the code as follows:
The first part of the code is to import some libraries.
Code:
from time import sleep
from pynq.overlays.base import BaseOverlay
base = BaseOverlay("base.bit")Explanation: We first import the sleep command which is used to generate a delay if you want to experiment. You the sleep(timeinseconds) command for experimentation. We then import the BaseOverlay which is used to use some underlying hardware. I don’t want to confuse you here by talking about Overlays for now but if you remember about Programming Logic or PL, Overlay files are generated by VIVADO in the form of “.bit”. These are essentially hardware libraries that will leverage the power of FPGA. The hardware defines all the connection, inputs and the outputs. So by importing these bit files, you can share data to those inputs using APIs that we will explore next.
Code:
led0 = base.leds[0] #Corresponds to LED LD0
led1 = base.leds[1] #Corresponds to LED LD1
led2 = base.leds[2] #Corresponds to LED LD2
led3 = base.leds[3] #Corresponds to LED LD3Explanation: Now we need a reference to the LEDs somehow. These reference are provided by the bit file. We can get excess to the four leds using base.leds[LEDNo] and then we store them in a variable. Essentially, you are just getting a reference to the INPUTS.
Code:
sw0 = base.switches[0] #Corresponds to SW0
sw1 = base.switches[1] #Corresponds to SW1Explanation: Similarly we can get reference to the switches by using base.switches[SWITCHNo].
Code:
while(True): # All the code below while(True) runs forever
if (sw0.read() == True): # Reads SW0 and check if it toggled
led0.on() # IF SW0 is ON --> Turn on LED0
led1.on() # IF SW0 is ON --> Turn on LED1
else:
led0.off() # ELSE Turn off LED0
led1.off() # ELSE Turn off LED1
if (sw1.read() == True): # Reads SW1 and check if it toggled
led2.on() # IF SW1 is ON --> Turn on LED2
led3.on() # IF SW1 is ON --> Turn on LED3
else:
led2.off() # ELSE Turn off LED2
led3.off() # ELSE Turn off LED3Explanation: If you have no experience in python, then this can be a bit troublesome. But let me try to explain what we are doing. Also, please in mind that indentation is necessary. Blocks are identified using indentation. There are no brackets in Python that can define the block. Indentation is used for this purpose. We want our program to run forever polling the switches and make decisions. The indentation is defined below.
while(True):
Belongs to while loop
Belongs to while loop
Doesn't belong to while loopWe can use on() or off() function to power on or power off the led. Since we have a reference to all four LEDs i.e led0, led1, led2, led3 we can power these LEDs by using
led0.on() # Turns on LED0.You can also refer to LEDs without storing them in the variable. But its generally better to use variables. Here is how you can directly access LED0:
base.led[0].on()Reading Switches is extremely easy. You need to call read() function. They either return TRUE or FALSE depending upon the state of the variable. So if the SW0 reads TRUE, we turn on LED0 and LED1. If SW0 reads FALSE, we turn them off.
if (sw0.read() == True): # Reads SW0 and check if it toggled
led0.on() # IF SW0 is ON --> Turn on LED0
led1.on() # IF SW0 is ON --> Turn on LED1
else:
led0.off() # ELSE Turn off LED0
led1.off() # ELSE Turn off LED1Same goes for SW1.
while(True): # All the code below while(True) runs forever
if (sw0.read() == True): # Reads SW0 and check if it toggled
led0.on() # IF SW0 is ON --> Turn on LED0
led1.on() # IF SW0 is ON --> Turn on LED1
else:
led0.off() # ELSE Turn off LED0
led1.off() # ELSE Turn off LED1
if (sw1.read() == True): # Reads SW1 and check if it toggled
led2.on() # IF SW1 is ON --> Turn on LED2
led3.on() # IF SW1 is ON --> Turn on LED3
else:
led2.off() # ELSE Turn off LED2
led3.off() # ELSE Turn off LED3Now Run all the statements from top to button by either keep pressing SHIFT + ENTER or by going to Cell → Run All.
You should now be able to change the state of LEDs using Switches.
BONUS: Using Timer and Toggle Function
Toggling the LEDs is extremely easy. Just like on() and off() function, we have toggle() function. toggle() will check the state of the LED, if it is turned ON, toggle() will turn it off and vice versa.
Here is the code. I would want you to experiment with it yourself. Make sure you import the libraries and assign the LEDs first.
CHALLENGE FOR YOU:
Do you know there are two RGB LEDs on the board as well? Try to access them. I will give you a hint that you can use to solve the challenge. Type and execute the following command:
help(base)This will give you a hint of all the peripherals configured by the overlay you are using. Check if you find the “rgbleds” and manage to interface them. But this is your challenge. I am not going to share the code how to do that. Explore some new stuff along the journey while you complete this challenge.
ACHIEVEMENT UNLOCKED:
I made a post on LinkedIn when I bought this kit. Xilinx shared my post and It was a delightful surprise for me. So it deserves to be here.
Comparison between PYNQ-Z1 vs PYNQ-Z2
I have written a detailed article on the differences between both boards. In a nutshell, having PYNQ-Z1 board should not affect you as they have the same SOC. However, the board files are different. Thus you need to ensure that you are using the correct board files.
Enjoy Reading this article? Continue to Part II.
In the next part of the blog, we will learn to write how to use Verilog to toggle buttons and switches present on the board. You will learn about what exactly is Hardware Synthesis and further learn how to toggle LEDs via push buttons on the PYNQ board directly with Xilinx Vivado using Verilog.
