From 05b268460bf5c89b1c715bde01f7ba8d95ee26b6 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 00:23:41 +0100 Subject: [PATCH 01/14] beginning to port over rfsoc-remote tutorial to docs --- docs/source/pynq_remote/quickstart.rst | 34 +++++++++----------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst index 2f8688c55..ab73609cf 100644 --- a/docs/source/pynq_remote/quickstart.rst +++ b/docs/source/pynq_remote/quickstart.rst @@ -6,7 +6,8 @@ Quick Start This page shows how to get started with PYNQ.remote. We use the ZCU104 and the `PYNQ-HelloWorld `_ overlay as an example, but the steps are similar for other supported AMD adaptive SoCs and -overlays. +overlays. The steps are provided for Windows, Linux and maxOS operating systems. +Use the commands that match your machine to setup and use PYNQ.remote. Prerequisites ------------- @@ -16,40 +17,29 @@ Prerequisites * Supported AMD adaptive SoC with network access * Network connection between host and target -Step 1: Install PYNQ.remote on the Host ---------------------------------------- +Step 1: Install uv +------------------ -PYNQ.remote uses two environment variables at different stages. Set -``PYNQ_REMOTE=1`` when installing the ``pynq`` package on the host so that -remote client dependencies are installed and native board binaries are skipped. -Set ``PYNQ_REMOTE_DEVICES`` at runtime, before ``import pynq``, to identify the -target board. See :doc:`env_variables` for platform-specific ways to set -``PYNQ_REMOTE_DEVICES``. +When using PYNQ.remote, the ``uv`` tool is used to manage Python versions, +projects and packages from within an isolated environment. This avoids any +project specific dependencies clashing with your system. Dependencies from +you project are recorded in a ``pyproject.toml``. -It is recommended to use a -`Python virtual environment `_. +The ``uv`` tool can be installed using the following command: **Linux/macOS:** .. code-block:: bash - PYNQ_REMOTE=1 pip install pynq - -To install the development version from source: - -.. code-block:: bash - - git clone --recursive https://github.com/Xilinx/PYNQ.git - cd PYNQ - PYNQ_REMOTE=1 pip install . + curl -LsSf https://astral.sh/uv/install.sh | sh **Windows (PowerShell):** .. code-block:: powershell - $env:PYNQ_REMOTE="1"; pip install pynq + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -Step 2: Prepare and Boot the Target Device +Step 2: Creating a Project ------------------------------------------ * Create a PYNQ.remote image using the instructions in :doc:`image_build`. From df6118acd2785e50c58360c4cf587cd431efc629 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 11:36:18 +0100 Subject: [PATCH 02/14] EDF images not petalinux anymore --- docs/source/pynq_remote.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pynq_remote.rst b/docs/source/pynq_remote.rst index a991aec3b..20dc7c3ff 100644 --- a/docs/source/pynq_remote.rst +++ b/docs/source/pynq_remote.rst @@ -32,7 +32,7 @@ The diagram below illustrates the key differences between Classic PYNQ and PYNQ. * Offload the Python API to your host machine, reducing on-target resource requirements. * Target-side C++ implementation (`PYNQ.cpp`) for boosting on-device performance. -* Lightweight Petalinux images: shrink SD card images from ~7GB to around 200MB (small enough for a RAM disk). +* Lightweight EDF/Yocto images: shrink SD card images from ~7GB to around 200MB (small enough for a RAM disk). * PYNQ API compatibility: classic PYNQ code and Jupyter notebooks run remotely, with minimal or no changes. * Extend with custom remote APIs using Protobuf definitions. From fc70edbf5e4692a7379e237961be3144371d0750 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 11:43:01 +0100 Subject: [PATCH 03/14] support added for PDIs --- docs/source/pynq_remote/remote_device.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pynq_remote/remote_device.rst b/docs/source/pynq_remote/remote_device.rst index 906763ff0..6250a9477 100644 --- a/docs/source/pynq_remote/remote_device.rst +++ b/docs/source/pynq_remote/remote_device.rst @@ -5,7 +5,7 @@ The RemoteDevice Class The ``RemoteDevice`` class enables controlling PYNQ boards over network connections using gRPC. It provides a complete remote access solution including bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionalities through remote procedure calls. -This module includes classes for remote memory management (``RemoteBuffer``), memory-mapped I/O (``RemoteMMIO``), bitstream handling, and communication channel management. The implementation handles multiple bitstream formats (.bit, .bin, .xsa), metadata parsing, and caching while maintaining compatibility with the local PYNQ API. +This module includes classes for remote memory management (``RemoteBuffer``), memory-mapped I/O (``RemoteMMIO``), overlay handling, and communication channel management. The implementation handles multiple bitstream formats (.bit, .pdi, .bin, .xsa), metadata parsing, and caching while maintaining compatibility with the local PYNQ API. Remote devices can be configured through the ``PYNQ_REMOTE_DEVICES`` environment variable, which should contain a comma-separated list of IP addresses for target From 49a4bbd39db283c038502c9ca55652f7c5920236 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 11:57:46 +0100 Subject: [PATCH 04/14] updating RemoteDevice docstring to include PDI support --- pynq/pl_server/remote_device.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pynq/pl_server/remote_device.py b/pynq/pl_server/remote_device.py index 276bb1eee..f8171d15d 100644 --- a/pynq/pl_server/remote_device.py +++ b/pynq/pl_server/remote_device.py @@ -165,7 +165,7 @@ class RemoteDevice(Device): It provides bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionality through gRPC remote procedure calls. - The device supports multiple bitstream formats (.bit, .bin, .xsa) and + The device supports multiple bitstream formats (.bit, .pdi, .bin, .xsa) and handles metadata parsing, caching, and AXI port width configuration remotely. """ From e0cd3f8ee087e63d189ba4e92f4613e0a5eef465 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 13:02:02 +0100 Subject: [PATCH 05/14] updating pynq.remote installation steps --- docs/source/pynq_remote/quickstart.rst | 135 +++++++++++++++---------- 1 file changed, 82 insertions(+), 53 deletions(-) diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst index ab73609cf..5075b6b41 100644 --- a/docs/source/pynq_remote/quickstart.rst +++ b/docs/source/pynq_remote/quickstart.rst @@ -6,24 +6,23 @@ Quick Start This page shows how to get started with PYNQ.remote. We use the ZCU104 and the `PYNQ-HelloWorld `_ overlay as an example, but the steps are similar for other supported AMD adaptive SoCs and -overlays. The steps are provided for Windows, Linux and maxOS operating systems. -Use the commands that match your machine to setup and use PYNQ.remote. +overlays. The steps are provided for Windows, Linux, and macOS operating systems. +Use the commands that match your machine to set up and use PYNQ.remote. Prerequisites ------------- * Host machine running Linux, Windows, or macOS -* Python 3.10 or newer -* Supported AMD adaptive SoC with network access +* Supported AMD adaptive SoC running a PYNQ.remote image (see :doc:`image_build`) * Network connection between host and target Step 1: Install uv ------------------ -When using PYNQ.remote, the ``uv`` tool is used to manage Python versions, -projects and packages from within an isolated environment. This avoids any -project specific dependencies clashing with your system. Dependencies from -you project are recorded in a ``pyproject.toml``. +We use the ``uv`` tool to manage Python versions, projects, and packages in an +isolated environment. This stops project-specific dependencies from clashing +with your system. Dependencies for your project are recorded in a +``pyproject.toml`` file. The ``uv`` tool can be installed using the following command: @@ -39,86 +38,116 @@ The ``uv`` tool can be installed using the following command: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -Step 2: Creating a Project ------------------------------------------- -* Create a PYNQ.remote image using the instructions in :doc:`image_build`. -* Flash the image to your SD card (see :doc:`../appendix/sdcard`). -* Insert the SD card and power on the device. +Step 2: Create a Project +------------------------ -Remote images configure both a static address of ``192.168.2.99`` and DHCP. -If your host is on the ``192.168.2.0/24`` network, continue to Step 3 and use -that address in ``PYNQ_REMOTE_DEVICES``. +Running ``uv init --bare`` sets up a project containing a minimal +``pyproject.toml``. Additionally, passing ``--python "==3.11.*"`` specifies +that the project uses Python 3.11. Run the following command to create the +project: -If the board is on a different network, use the DHCP address from your router's -client list. See :doc:`troubleshooting` if you need to use a USB serial console. -The first time you connect over serial, log in as ``amd-edf`` and set a password -when prompted. +**Linux/macOS and Windows (PowerShell):** -Step 3: Install and Run PYNQ-HelloWorld ---------------------------------------- +.. code-block:: bash + + uv init remote-project --bare --python "==3.11.*" + cd remote-project -Install the required dependencies in your Python virtual environment: +Step 3: Install PYNQ and Dependencies +------------------------------------- + +Before you install any dependencies into the ``uv`` environment, PYNQ's +installer needs to be instructed to build in *remote mode*. To do this, set the +``PYNQ_REMOTE`` environment variable before installing PYNQ. + +**Linux/macOS:** .. code-block:: bash - pip install jupyterlab matplotlib pillow wheel + export PYNQ_REMOTE=1 + +**Windows (PowerShell):** + +.. code-block:: powershell + + $env:PYNQ_REMOTE = "1" -Install the PYNQ-HelloWorld overlay. Set the ``BOARD`` environment variable -before installation so that PYNQ-Utils knows which board you are targeting: +PYNQ can then be installed, **followed by** any other dependencies required +for your project. The first command below installs the most recent version of +PYNQ from GitHub. ``uv add`` installs packages into the project environment and +records each package in the ``pyproject.toml``. -**Windows:** +**Linux/macOS and Windows (PowerShell):** .. code-block:: bash - # PowerShell: - $env:BOARD="ZCU104"; pip install --no-build-isolation pynq-helloworld + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" + uv add "setuptools<78" "pycparser<3" "numpy<2" scipy ipywidgets plotly anywidget matplotlib pillow ipython jupyterlab voila + +Step 4: Install PYNQ-HelloWorld +------------------------------- - # Command Prompt: - set BOARD=ZCU104 && pip install --no-build-isolation pynq-helloworld +Before installing the PYNQ-HelloWorld overlay, set the ``BOARD`` environment +variable so that PYNQ-Utils knows which board you are targeting. **Linux/macOS:** .. code-block:: bash - BOARD=ZCU104 pip install --no-build-isolation pynq-helloworld + export BOARD=ZCU104 -Download the notebooks and overlay files: +**Windows (PowerShell):** + +.. code-block:: powershell + + $env:BOARD = "ZCU104" + +PYNQ-HelloWorld is then ready to be installed: + +**Linux/macOS and Windows (PowerShell):** .. code-block:: bash - pynq get-notebooks pynq-helloworld -d ZCU104 + uv pip install --no-build-isolation pynq-helloworld + uv run pynq get-notebooks pynq-helloworld -d ZCU104 -The ``-d`` argument tells ``pynq get-notebooks`` which board package to use. +Step 5: Running Jupyter Labs +---------------------------- -Start Jupyter Lab: +Before starting JupyterLab, store the IP address assigned to your board in an +environment variable called ``PYNQ_REMOTE_DEVICES``. Running ``uv run jupyter-lab`` +starts the Jupyter session allowing you to interact with the board using PYNQ.remote. + +**Linux/macOS:** .. code-block:: bash - jupyter lab + export PYNQ_REMOTE_DEVICES=192.168.2.99 + uv run jupyter-lab - # On some shells it may be necessary to use: - python -m jupyterlab +**Windows (PowerShell):** -Connecting to the Board -~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: powershell -Before importing ``pynq``, set ``PYNQ_REMOTE_DEVICES`` to the board address: + $env:PYNQ_REMOTE_DEVICES = "192.168.2.99" + uv run jupyter-lab -.. code-block:: python +Navigate to the ``pynq-notebooks/pynq-helloworld`` directory and explore the +``resizer_pl.ipynb`` notebook. - import os - os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # default static IP +Connecting through an IDE +~~~~~~~~~~~~~~~~~~~~~~~~~ - from pynq import allocate, Overlay +With PYNQ.remote, IDEs that support Python execution, such as VS Code and MATLAB, +can also be used to run PYNQ overlays. Before importing ``pynq``, set +``PYNQ_REMOTE_DEVICES`` to the board address: - overlay = Overlay("resizer.bit") +.. code-block:: python -Modifying the Notebook for PYNQ.remote -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + import os + os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # IP assigned to your board -When you open the ``resizer_pl.ipynb`` notebook, add the lines above to the -imports cell before ``from pynq import allocate, Overlay``. + from pynq import allocate, Overlay -Once this change is made, you should be able to run through the entire notebook -and resize images completely remotely using PYNQ.remote. + overlay = Overlay("resizer.bit") \ No newline at end of file From 4efaad34120e750501d4fa107ec9d354fb0505bd Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 13:32:09 +0100 Subject: [PATCH 06/14] updating quickstrat.rst --- docs/source/pynq_remote/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst index 5075b6b41..f486fcd32 100644 --- a/docs/source/pynq_remote/quickstart.rst +++ b/docs/source/pynq_remote/quickstart.rst @@ -13,7 +13,7 @@ Prerequisites ------------- * Host machine running Linux, Windows, or macOS -* Supported AMD adaptive SoC running a PYNQ.remote image (see :doc:`image_build`) +* Supported AMD adaptive SoC with network access * Network connection between host and target Step 1: Install uv @@ -76,7 +76,7 @@ installer needs to be instructed to build in *remote mode*. To do this, set the PYNQ can then be installed, **followed by** any other dependencies required for your project. The first command below installs the most recent version of PYNQ from GitHub. ``uv add`` installs packages into the project environment and -records each package in the ``pyproject.toml``. +records each them in the ``pyproject.toml``. **Linux/macOS and Windows (PowerShell):** From 2501e5d40aec93b260d377ddde74898b37a915ed Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 13:32:33 +0100 Subject: [PATCH 07/14] improving clarity of pynq remote image build steps --- docs/source/pynq_remote/image_build.rst | 33 +++++++++++++++++++------ 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/source/pynq_remote/image_build.rst b/docs/source/pynq_remote/image_build.rst index aa0f25c6a..d6b0b44c4 100644 --- a/docs/source/pynq_remote/image_build.rst +++ b/docs/source/pynq_remote/image_build.rst @@ -27,18 +27,37 @@ Using the Docker-based build flow .. code-block:: bash git clone --recursive https://github.com/Xilinx/PYNQ.git + cd PYNQ -#. Set up the build environment by following :ref:`pynq-sd-card`. This includes - setting ``XILINX_TOOLS`` and ``XILINXD_LICENSE_FILE`` before starting the - container. +#. Build the Docker image: -#. Build the remote image for your target board: + .. code-block:: bash + + cd sdbuild + docker build \ + --build-arg USERNAME=$(whoami) \ + --build-arg USER_UID=$(id -u) \ + --build-arg USER_GID=$(id -g) \ + -t pynqdock:latest . + cd .. + +#. Set the paths to the AMD tools and licence, then build the remote image for + your target board: .. code-block:: bash - # Inside the Docker container - cd PYNQ/sdbuild - make pynqremote BOARDS= + export XILINX_TOOLS=/tools/Xilinx/2025.2 + export XILINXD_LICENSE_FILE="$HOME/.Xilinx" + + docker run --init --rm \ + --network host \ + -e XILINX_TOOLS -e XILINXD_LICENSE_FILE \ + -v "$XILINX_TOOLS:$XILINX_TOOLS:ro" \ + -v "$XILINXD_LICENSE_FILE:$XILINXD_LICENSE_FILE" \ + -v "$PWD:/workspace" \ + --privileged \ + pynqdock:latest \ + bash -lc 'cd /workspace/sdbuild && make pynqremote BOARDS=' Replace ```` with your target board (``ZCU104`` or ``VCK190``). The remote image target does not require the prebuilt classic PYNQ root From 2a3894068fa41ed648d2af44a4db28eb669f9eaa Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 13:39:38 +0100 Subject: [PATCH 08/14] tidying up build commands --- docs/source/pynq_remote/image_build.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/source/pynq_remote/image_build.rst b/docs/source/pynq_remote/image_build.rst index d6b0b44c4..9bf69b2ba 100644 --- a/docs/source/pynq_remote/image_build.rst +++ b/docs/source/pynq_remote/image_build.rst @@ -27,18 +27,14 @@ Using the Docker-based build flow .. code-block:: bash git clone --recursive https://github.com/Xilinx/PYNQ.git - cd PYNQ #. Build the Docker image: .. code-block:: bash - cd sdbuild - docker build \ - --build-arg USERNAME=$(whoami) \ - --build-arg USER_UID=$(id -u) \ - --build-arg USER_GID=$(id -g) \ - -t pynqdock:latest . + cd PYNQ/sdbuild + docker build --build-arg USERNAME=$(whoami) --build-arg USER_UID=$(id -u) \ + --build-arg USER_GID=$(id -g) -t pynqdock:latest . cd .. #. Set the paths to the AMD tools and licence, then build the remote image for From 116bc5b4fbfa3f3b5c626cf536c192f9695a30cd Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 15:05:51 +0100 Subject: [PATCH 09/14] removing unused uncalled rst --- docs/source/pynq_remote/cppindex.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/source/pynq_remote/cppindex.rst diff --git a/docs/source/pynq_remote/cppindex.rst b/docs/source/pynq_remote/cppindex.rst deleted file mode 100644 index e69de29bb..000000000 From 459e8c3452e7ce4693591a24e17a9a309d12b051 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 15:08:05 +0100 Subject: [PATCH 10/14] being more specific about the console to use --- docs/source/pynq_remote/image_build.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/pynq_remote/image_build.rst b/docs/source/pynq_remote/image_build.rst index 9bf69b2ba..26548320c 100644 --- a/docs/source/pynq_remote/image_build.rst +++ b/docs/source/pynq_remote/image_build.rst @@ -66,8 +66,9 @@ Using the Docker-based build flow #. Flash the generated ``sdbuild/output/-4.0.0-remote.img`` image to an SD card and boot your device (see :doc:`../appendix/sdcard`). -#. After booting, the ``pynq-remote`` server starts automatically. Use - ``ip addr`` on the board to find its address, then follow :doc:`quickstart`. +#. After booting, the ``pynq-remote`` server starts automatically. Run + ``ip addr`` on the board through a serial console to find its address, + then follow :doc:`quickstart`. Image size ---------- From e3273e47947f123d5f9eba35365296f02e41c3ed Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 15:14:59 +0100 Subject: [PATCH 11/14] typo fix --- docs/source/pynq_remote/cpp_index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pynq_remote/cpp_index.rst b/docs/source/pynq_remote/cpp_index.rst index e3670e34f..70aecf913 100644 --- a/docs/source/pynq_remote/cpp_index.rst +++ b/docs/source/pynq_remote/cpp_index.rst @@ -19,4 +19,4 @@ Like PYNQ's Python API, PYNQ.cpp is part of the PYNQ ecosystem and is specifical PYNQ.remote uses gRPC to communicate with PYNQ devices, allowing remote management of FPGA resources and memory operations. PYNQ.remote images use a gRPC server to interact with PYNQ.cpp, which provides the necessary C++ backend functionality equivalent to what PYNQ's Python API offers. -Because it exists as a standalone C++ library, PYNQ can be used independently of PYNQ.remote. This allows developers to create custom low-level C++ applications that interact with AMD adaptive SoC platforms using familiar PYNQ concepts. \ No newline at end of file +Because it exists as a standalone C++ library, *PYNQ.cpp* can be used independently of PYNQ.remote. This allows developers to create custom low-level C++ applications that interact with AMD adaptive SoC platforms using familiar PYNQ concepts. \ No newline at end of file From 0d3d62c77f921c1553b43eb3b482e7ff4846b3a1 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 15:41:58 +0100 Subject: [PATCH 12/14] updating pynq.remote status page --- docs/source/pynq_remote/status.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/pynq_remote/status.rst b/docs/source/pynq_remote/status.rst index 3474f69d5..6f4aeb63a 100644 --- a/docs/source/pynq_remote/status.rst +++ b/docs/source/pynq_remote/status.rst @@ -10,8 +10,8 @@ This document outlines the current status of PYNQ.remote. * **Validated Platforms**: * `ZCU104 `_ * `VCK190 `_ - * `AUP-ZU3 `_ - * `RFSoC-PYNQ `_ + * `AUP-ZU3 `_ (coming soon!) + * Supported `RFSoC-PYNQ `_ platforms. * **Image build**: EDF/Yocto remote rootfs (see :doc:`image_build`) * **Supported Features**: * :doc:`../pynq_overlays/loading_an_overlay` @@ -20,6 +20,6 @@ This document outlines the current status of PYNQ.remote. * :doc:`../pynq_libraries/allocate` * :doc:`../pynq_libraries/psgpio` (``RemoteGPIO``) * RFSoC clock and data converter control (RFSoC remote images) - * Multi-board support * **Not yet supported**: * :doc:`../pynq_libraries/interrupt` + * Multi-board support \ No newline at end of file From 784af91e8a5c374d55fdc473e849182fa207e189 Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 16:39:09 +0100 Subject: [PATCH 13/14] fixing environment variables --- docs/source/pynq_remote/env_variables.rst | 63 +++++++++++++---------- docs/source/pynq_remote/quickstart.rst | 32 ++++-------- 2 files changed, 45 insertions(+), 50 deletions(-) diff --git a/docs/source/pynq_remote/env_variables.rst b/docs/source/pynq_remote/env_variables.rst index 9e6e36f67..40cbfeee2 100644 --- a/docs/source/pynq_remote/env_variables.rst +++ b/docs/source/pynq_remote/env_variables.rst @@ -6,7 +6,7 @@ Setting Environment Variables PYNQ.remote uses two environment variables on the host. ``PYNQ_REMOTE`` - Set to ``1`` when installing the ``pynq`` package with pip. This selects the + Set to ``1`` when installing the ``pynq`` package. This selects the remote client install path and skips native board binaries and overlays. ``PYNQ_REMOTE_DEVICES`` @@ -14,58 +14,67 @@ PYNQ.remote uses two environment variables on the host. comma-separated list of IP addresses. When multiple addresses are listed, each becomes a separate ``RemoteDevice`` instance. -Installing for PYNQ.remote --------------------------- +Installing PYNQ for PYNQ.remote +------------------------------- + +The commands below use the ``uv`` environment manager tool to install PYNQ, as described +in :ref:`quickstart`. However, ``pip install`` may also be used. **Linux/macOS:** .. code-block:: bash - - PYNQ_REMOTE=1 pip install pynq + + export PYNQ_REMOTE=1 + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" **Windows (PowerShell):** .. code-block:: powershell - $env:PYNQ_REMOTE="1"; pip install pynq - -Runtime device selection ------------------------- + $env:PYNQ_REMOTE = "1" + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" Setting ``PYNQ_REMOTE_DEVICES`` at runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------ + +Python Runtime Device Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can set environment variables in Python using the ``os`` module. This works across all operating systems and does not require shell configuration. Set the variable before importing ``pynq``. .. code-block:: python - + import os - os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" + os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # IP assigned to your board + + from pynq import Overlay + + ol = Overlay("my_design.xsa") -Linux and macOS shells +Shell Device Selection ~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: bash - - export PYNQ_REMOTE_DEVICES="192.168.2.99" +Alternatively, the environment may be configured in your shell. Variables apply +to the current shell session only. -The variable applies to the current shell session only. +**Linux/macOS:** -Windows -~~~~~~~ +.. code-block:: bash + + export PYNQ_REMOTE_DEVICES="192.168.2.99" -Command Prompt: - -.. code-block:: powershell +**Windows (Command Prompt):** +.. code-block:: bat + set PYNQ_REMOTE_DEVICES=192.168.2.99 -PowerShell: +**Windows (PowerShell):** .. code-block:: powershell - + $env:PYNQ_REMOTE_DEVICES="192.168.2.99" Python virtual environments @@ -74,6 +83,6 @@ Python virtual environments To set ``PYNQ_REMOTE_DEVICES`` automatically when a virtual environment is activated, add the appropriate line to the environment's activate script: -* Linux/macOS: ``venv/bin/activate`` -* Windows Command Prompt: ``venv/Scripts/activate.bat`` -* Windows PowerShell: ``venv/Scripts/Activate.ps1`` +* Linux/macOS: ``.venv/bin/activate`` +* Windows Command Prompt: ``.venv/Scripts/activate.bat`` +* Windows PowerShell: ``.venv/Scripts/Activate.ps1`` \ No newline at end of file diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst index f486fcd32..5f4115ea5 100644 --- a/docs/source/pynq_remote/quickstart.rst +++ b/docs/source/pynq_remote/quickstart.rst @@ -76,7 +76,7 @@ installer needs to be instructed to build in *remote mode*. To do this, set the PYNQ can then be installed, **followed by** any other dependencies required for your project. The first command below installs the most recent version of PYNQ from GitHub. ``uv add`` installs packages into the project environment and -records each them in the ``pyproject.toml``. +records each of them in the ``pyproject.toml``. **Linux/macOS and Windows (PowerShell):** @@ -112,12 +112,14 @@ PYNQ-HelloWorld is then ready to be installed: uv pip install --no-build-isolation pynq-helloworld uv run pynq get-notebooks pynq-helloworld -d ZCU104 -Step 5: Running Jupyter Labs ----------------------------- +Step 5: Running JupyterLab +-------------------------- -Before starting JupyterLab, store the IP address assigned to your board in an -environment variable called ``PYNQ_REMOTE_DEVICES``. Running ``uv run jupyter-lab`` -starts the Jupyter session allowing you to interact with the board using PYNQ.remote. +Before running any overlays, the IP address assigned to your board must be stored in an +environment variable called ``PYNQ_REMOTE_DEVICES``. This can be configured directly in a +Linux/macOS or PowerShell terminal, or in Python using the ``os`` module **before** +running ``import pynq``. Running ``uv run jupyter-lab`` starts the Jupyter session, allowing +you to interact with the board using PYNQ.remote. **Linux/macOS:** @@ -134,20 +136,4 @@ starts the Jupyter session allowing you to interact with the board using PYNQ.re uv run jupyter-lab Navigate to the ``pynq-notebooks/pynq-helloworld`` directory and explore the -``resizer_pl.ipynb`` notebook. - -Connecting through an IDE -~~~~~~~~~~~~~~~~~~~~~~~~~ - -With PYNQ.remote, IDEs that support Python execution, such as VS Code and MATLAB, -can also be used to run PYNQ overlays. Before importing ``pynq``, set -``PYNQ_REMOTE_DEVICES`` to the board address: - -.. code-block:: python - - import os - os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # IP assigned to your board - - from pynq import allocate, Overlay - - overlay = Overlay("resizer.bit") \ No newline at end of file +``resizer_pl.ipynb`` notebook. \ No newline at end of file From 9b65ece2e321d91959d928b8e12de9693078804a Mon Sep 17 00:00:00 2001 From: ryanprovan Date: Wed, 7 Oct 2026 17:26:53 +0100 Subject: [PATCH 14/14] adding new classes to pynq.cpp usgae docs --- docs/source/pynq_remote/pynq_cpp/cpp_api.rst | 30 ++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/source/pynq_remote/pynq_cpp/cpp_api.rst b/docs/source/pynq_remote/pynq_cpp/cpp_api.rst index ef64062ff..56232fddf 100644 --- a/docs/source/pynq_remote/pynq_cpp/cpp_api.rst +++ b/docs/source/pynq_remote/pynq_cpp/cpp_api.rst @@ -45,3 +45,33 @@ XrtBufferManager Class :undoc-members: :protected-members: :private-members: + +GPIO Class +---------- + +.. doxygenclass:: GPIO + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: + +XRFCLK Class (RFSoC only) +------------------------- + +.. doxygenclass:: XRFCLK + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: + +XrfdcRemote Class (RFSoC only) +------------------------------ + +.. doxygenclass:: XrfdcRemote + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: \ No newline at end of file