In this article we will explore how to get started with PYNQ on Alveo platforms and AWS F1 instances. We will use an AWS F1 instance for this writeup, but the same instructions will apply for any other Alveo-enabled system.
To simplify things and make the article as general as possible, we will assume the F1 instance is already up and running, and you are already connected through it via SSH. For more detailed instructions on how to setup an F1 instance, please read below the Appendix A section.
If you want to know more about the PYNQ Alveo Edition, refer to the More Info section.
Install Anaconda
The first step is to install Anaconda. For this, in your shell you will have to do:
wget https://repo.anaconda.com/archive/Anaconda3-2019.10-Linux-x86_64.sh
bash Anaconda3-2019.10-Linux-x86_64.sh
And then follow the installation wizard
You will have to
source anaconda3/bin/activate in case conda is not on your PATH, as shown above.
Install packages for PYNQ and Alveo examples
You are now ready to install pynq, and the examples package pynq-alveo-examples.
The commands to run are
pip install pynq
pip install pynq-alveo-examples
Get the examples
It is time to get the examples!
You can achieve that by typing in your shell session
pynq get-notebooks
The command will create a
pynq-notebooks folder where you will find all the available example notebooks.
Run the examples
Now move into the pynq-notebooks folder, and run Jupyter
cd pynq-notebooks
jupyter notebook
You can see that the Jupyter log will provide you with the token to use to connect to Jupyter from the browser. Copy it now as it will be needed later.
In case the the machine that mounts the FPGA board is remotely located, you will have to open a SSH tunnel to be able to connect to the Jupyter server from your local browser. This is for instance the case for AWS F1. You can achieve that using the dedicated option of the ssh command
ssh user@remote-machine -L 8888:localhost:8888
Don’t forget to change the ports from
8888 to the appropriate value in case needed.
Now open up a browser tab on your local machine, and go to localhost:8888. Paste the token you previously copied and you will finally have access to the Jupyter home. Once you have access, you can start from the welcome-to-pynq notebook and display the available devices in your system.
And to conclude, let us now run the notebook
1-vector-addition in the folder 1-introduction . This should be the first notebook to run as it will show you the basics to use your Alveo platform or the AWS F1 instance with PYNQ.
Feel free now to explore the remaining notebooks to learn more, and have fun with PYNQ - Alveo Edition!
More Info
Please refer to the official Alveo getting started guide for more info (and pre-requisites), and feel free to also look at the release announcement on discuss.pynq.io.
For more projects to try out, we recommend you take also a look at the PYNQ community page, under the PYNQ Alveo community projects and tutorials section.
Appendix A - Setup AWS F1 Instance
In case you have little experience with Amazon AWS, here is a few simple steps you can follow to get started.
First, launch the FPGA Developer AMI on a FPGA F1 instance. In case you don’t have access to F1 instances because you have a 0 quota, you will have to request access through the AWS support.
When you launch the instance, you will also be prompted to either use an existing authentication key, or create a new one. You will then need to use this key when connecting through SSH using the -i option
ssh -i key.pem user@aws-machine
You can get the instructions on how to connect directly within the AWS dashboard
Remember though that in the case of the FPGA Developer AMI, even though the user in the instructions is shown as root, you will have to change it to centos.
ssh -i key.pem centos@aws-instance
Finally, as soon as you connect to your F1 instance through SSH, you will have to clone the aws-fpga repository and source the vitis_runtime_setup.sh script to perform the required setup steps. If you don’t do this, you will not be able to program your F1 device.
git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR
cd $AWS_FPGA_REPO_DIR
source vitis_runtime_setup.sh
The very last step will be to install the packages lm_sensors lm_sensors-devel hddtemp through the centos package manager yum, or you will get a warning when using PYNQ.
Remember though that power monitoring functionalities will not work on AWS F1 instances. This step is just to get rid of this warning, and is therefore optional.
sudo yum install lm_sensors lm_sensors-devel hddtemp
Appendix B - XRT Setup Script
Don’t forget to source the Xilinx Run Time (XRT) setup script for every session before using pynq, or you will not be able to interact with your Alveo devices. On the AWS FPGA AMI, this is done automatically when you do the initial setup, as shown in the Appendix A section.
source /opt/xilinx/xrt/setup.sh
The path /opt/xilinx/xrt is the predefined install path for XRT and should not be changed. Therefore, the setup script will always be located there, except some rare cases for which you should contact your system administrator.