Quick Start

This page how to get started with PYNQ.remote. We will use the ZCU104 and the PYNQ-HelloWorld overlay as an example, but the steps are similar for other supported AMD adaptive SoCs and overlays.

Prerequisites

  • Host machine running Linux, Windows, or macOS

  • Python 3.10 or newer

  • Supported AMD adaptive SoCs with network access

  • Network connection between host and target

Step 1: Install PYNQ.remote on the Host

Note

PYNQ.remote relies on environment variables for installation and target device identification. For installation you need to have the PYNQ_REMOTE_DEVICES environment variables set. See Setting Environment Variables for more information.

Download PYNQ from GitHub and install the pynq package using pip. It is recommended to use a Python virtual environment.

To install the latest release version of PYNQ simply run:

pip install pynq

If you want to install the latest development version of PYNQ, you can clone the repository and install it from source:

pip install git+https://github.com/Xilinx/PYNQ.git

Step 2: Prepare and Boot the Target Device

  • Create a PYNQ.remote image using the instructions in Remote Image Build Guide.

  • Flash the image to your SD card (see Writing an SD Card Image for instructions on how to flash the image).

  • Insert the SD card and power on the device (make sure it is connected to your network).

  • Wait for the device to boot up. You can check the device’s IP address using a serial console (e.g. minicom or PuTTY) or by checking your router’s DHCP client list.

Note

Your board must be connected to the same network as your host machine. If you are using a direct connection, you may need to set a static IP address on both the host and the target device.

Step 3: Install and Run PYNQ-HelloWorld

In this step, we’ll install the PYNQ-HelloWorld overlay and run it remotely using PYNQ.remote.

First, install the required dependencies in your Python virtual environment:

pip install jupyterlab matplotlib pillow wheel

Next, install the PYNQ-HelloWorld overlay. You need to set the BOARD environment variable before installation so that PYNQ-Utils knows which board you are targeting:

Windows:

# PowerShell:
$env:BOARD="ZCU104"; pip install --no-build-isolation pynq-helloworld

# Command Prompt:
set BOARD=ZCU104 && pip install --no-build-isolation pynq-helloworld

Linux/macOS:

BOARD=ZCU104 pip install --no-build-isolation pynq-helloworld

After installing the package, download the notebooks and overlay files:

pynq get-notebooks pynq-helloworld -d ZCU104

The -d argument is required for PYNQ’s get-notebooks function to know where to find the notebooks and overlay files.

After installation, the notebooks will be available in the current folder under pynq-notebooks/pynq-helloworld. Start Jupyter Lab to access them:

jupyter lab

# On some shells it may be necessary to use:
python -m jupyterlab

Modifying the Notebook for PYNQ.remote

When you open the resizer_pl.ipynb notebook, you need to make two changes to make it compatible with PYNQ.remote:

1. Add the environment variable setting

Find the cell with the imports and modify it to include the PYNQ_REMOTE_DEVICES environment variable:

# Original cell:
from PIL import Image
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline
from pynq import allocate, Overlay

Change it to:

# Modified cell:
from PIL import Image
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline
import os
os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99"  # Replace with your board's IP
from pynq import allocate, Overlay

2. Fix the image display for RemoteBuffer

Find the cell that creates the PIL Image from the output buffer and modify it to work with PYNQ.remote’s RemoteBuffer:

# Original cell:
run_kernel()
resized_image = Image.fromarray(out_buffer)

Change it to:

# Modified cell:
run_kernel()
resized_image = Image.fromarray(out_buffer[:])

The [:] slice is necessary because PYNQ.remote’s RemoteBuffer works slightly differently than PYNQ’s PynqBuffer, and PIL won’t be able to read the data correctly otherwise.

Once these changes are made, you should be able to run through the entire notebook and resize images completely remotely using PYNQ.remote!