Docs updates (#1491)

jogomojo · web-flow · commit 860462db637e · 2025-07-26T14:35:33.000+01:00
* more docs updates from feedback
diff --git a/docs/source/images/pynqremote_block_diagram.png b/docs/source/images/pynqremote_block_diagram.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -85,8 +85,8 @@ improve Adaptive Computing system design:
    pynq_libraries
    overlay_design_methodology
    pynq_sd_card
-   pynq_package
    pynq_remote
+   pynq_package
    faqs
    appendix
    changelog
diff --git a/docs/source/pynq_remote.rst b/docs/source/pynq_remote.rst
@@ -3,22 +3,30 @@
 PYNQ.remote 
 ===========
 
-.. note::
-      PYNQ.remote is currently in **beta**. Active development is ongoing, and some PYNQ features may have limited support. The API is subject to change in future releases. For more information on currently supported functionality and our development roadmap, see the :ref:`roadmap`.
-
 .. toctree::
    :maxdepth: 1
    :caption: Contents
 
    pynq_remote/quickstart
    pynq_remote/image_build
    pynq_remote/remote_device
-   pynq_remote/cppindex
+   pynq_remote/cpp_index
+   pynq_remote/status
    pynq_remote/env_variables
-   pynq_remote/roadmap
 
 PYNQ.remote is an extension to the PYNQ framework that enables remote control of AMD's FPGA-based devices. By moving the Python API to the host and communicating with the target device via gRPC, PYNQ.remote brings powerful new deployment, integration, and scalability features to PYNQ users, while preserving the familiar PYNQ user experience.
 
+**Introducing PYNQ.remote**
+
+PYNQ.remote provides two key benefits to PYNQ. First, by moving the Python API to the host machine we create opportunities to integrate PYNQ into host-based hardware and software workflows. This allows users to take full advantage of the Python ecosystem on the host, while still controlling AMD's adaptive SoC devices remotely. This is particularly useful for applications that require high-performance computing, such as AI inference, data processing, or real-time visualisations. This allows the host to handle complex computations, while the FPGA can focus on specialised tasks. 
+
+Second, by using a minimal Petalinux image the target device software requirements are reduced to a PYNQ meta-layer and a minimal root file system. Additionally, we have implemented a PYNQ C++ API called `PYNQ.cpp` that runs on the target device, which provides a low-level interface to the hardware. Together, this provides a greatly reduced image size (small enough to fit on a RAM disk) and allows deployment with a minimal software footprint. This is ideal for when resources are constrained, such as edge computing or IoT applications.
+
+The diagram below illustrates the key differences between Classic PYNQ and PYNQ.remote. 
+
+.. image:: ./images/pynqremote_block_diagram.png
+      :align: center
+
 **Key Features**
 
 * Offload the Python API to your host machine, reducing on-target resource requirements.
@@ -35,4 +43,7 @@ PYNQ.remote is an extension to the PYNQ framework that enables remote control of
 
 **Getting Started**
 
-To get started with PYNQ.remote, follow the quickstart guide in :ref:`quickstart`. This will walk you through setting up your environment, deploying the remote image, and running your first remote application.
+To get started with PYNQ.remote, follow the :ref:`quickstart` guide. This will walk you through setting up your environment, deploying the remote image, and running your first remote application.
+
+.. note::
+      PYNQ.remote is currently in **beta**. Active development is ongoing, and some PYNQ features may have limited support. The API is subject to change in future releases. For more information on currently supported functionality see :ref:`status`.
diff --git a/docs/source/pynq_remote/cpp_index.rst b/docs/source/pynq_remote/cpp_index.rst
@@ -0,0 +1,22 @@
+.. _cppindex:
+
+PYNQ.cpp
+=====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+   :titlesonly:
+   
+   pynq_cpp/cpp_usage
+   pynq_cpp/cpp_install
+   pynq_cpp/cpp_api
+
+**PYNQ.cpp** is a C++ hardware abstraction library that provides a C++ equivalent to PYNQ's Python API for AMD adaptive SoC platforms. 
+It delivers the same low-level interface capabilities as PYNQ for interacting with the FPGA fabric, memory management, and device operations.
+
+Like PYNQ's Python API, PYNQ.cpp is part of the PYNQ ecosystem and is specifically designed to work with PYNQ.remote, which allows remote access to PYNQ devices over a network.
+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.
diff --git a/docs/source/pynq_remote/cppindex.rst b/docs/source/pynq_remote/cppindex.rst
@@ -1,32 +0,0 @@
-.. _cppindex:
-
-PYNQ.cpp
-=====================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: PYNQ.cpp Contents
-   :titlesonly:
-   
-   pynq_cpp/cppapi
-   pynq_cpp/cppusage
-   pynq_cpp/cppinstall
-
-**PYNQ.cpp** is a C++ hardware abstraction library for AMD adaptive SoC platforms. 
-It provides a low-level interface to interact with the FPGA fabric, memory management, and device operations.
-It is part of the PYNQ ecosystem, specifically designed to work with PYNQ.remote, which allows remote access to PYNQ devices over a network.
-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.
-
-PYNQ.cpp is designed to be used in C++ applications running on AMD adaptive SoC platforms, providing a low-level interface to reprogram the FPGA fabric and manage memory.
-It is built on top of the Xilinx Runtime (XRT) library, which provides access to the FPGA Manager and other hardware resources.
-Because it exists as a standalone C++ library, it can be used independently of PYNQ.remote, allowing developers to create custom low-level applications that interact with PYNQ devices.
-
-Key Features
-------------
-
-* Load FPGA bitstreams via the FPGA Manager device driver.
-* Manage `xrt::bo` contiguous buffer objects with cacheable host-device memory mapping.
-* Perform memory-mapped I/O (MMIO) operations via `/dev/mem`
-* Directly synchronize and flush buffers to/from device memory
-* Filesystem operations for write/read access to bitstreams and device files.
diff --git a/docs/source/pynq_remote/env_variables.rst b/docs/source/pynq_remote/env_variables.rst
@@ -13,56 +13,41 @@ You can set environment variables in Python using the ``os`` module. This is use
 .. code-block:: python
 
     import os
-    os.environ['PYNQ_REMOTE_DEVICES'] - "192.168.2.99"
+    os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99"
 
 Setting an Environment Variable in Linux and macOS
 --------------------------------------------------
 
-In Linux and macOS shells, you can set environment variables using the `export` command. Make sure there are no spaces around the `-` sign.
+In Linux and macOS shells, you can set environment variables using the ``export`` command. Make sure there are no spaces around the ``=`` sign.
 
 .. code-block:: bash
 
-    export PYNQ_REMOTE_DEVICES-"192.168.2.99"
+    export PYNQ_REMOTE_DEVICES="192.168.2.99"
 
 The code above sets the environment variable for the current shell session. If you use a new terminal or restart your computer you will need to set it again. 
 
-This can be made easier in one of two ways. First, you can add the command to a shell file local to your working directory, such as `.env`. Each time you start a new terminal session, you can ``source`` this file to set the environment variable:
-
-.. code-block:: bash
-
-    source .env
-
-Alternatively, you can add the command to your shell's configuration file (e.g., `.bashrc`, `.bash_profile`, `.zshrc`), which will set the variable automatically each time you open a new terminal session:
-
-To check if the variable is set, you can use the `echo` command:
-
-.. code-block:: bash
-
-    echo $PYNQ_REMOTE_DEVICES
-
-
 Setting an Environment Variable in Windows
 ------------------------------------------
 
-In Windows, there are several ways to set environment variables, depending on which shell you are using. For Command Prompt (cmd.exe), you can use the `set` command:
+In Windows, there are several ways to set environment variables, depending on which shell you are using. For Command Prompt (`cmd.exe`), you can use the ``set`` command:
 
 .. code-block:: powershell
 
-    set PYNQ_REMOTE_DEVICES-192.168.2.99
+    set PYNQ_REMOTE_DEVICES=192.168.2.99
 
 For Powershell, you can use the ``$env:`` syntax:
 
 .. code-block:: powershell
 
-    $env:PYNQ_REMOTE_DEVICES-"192.168.2.99"
+    $env:PYNQ_REMOTE_DEVICES="192.168.2.99"
 
 Setting an Environment Variable in a Python Virtual Environment
 ---------------------------------------------------------------
 
-If you are using a Python virtual environment, you can set the environment variable in the `activate` script of your virtual environment. This way, the variable will be set automatically each time you activate the virtual environment.
+If you are using a Python virtual environment, you can set the environment variable in the ``activate`` script of your virtual environment. This way, the variable will be set automatically each time you activate the virtual environment.
 
-For example, if you are using a virtual environment named `venv`, you can add the code above in the following directories:
+For example, if you are using a virtual environment named ``venv``, you can add the code above in the following directories:
 
-* For Linux/macOS: Add the code above to the `venv/bin/activate` 
-* For Windows: If using Command Prompt, add the code to `venv/Scripts/activate.bat`
-* For Windows: If using PowerShell, add the following line to `venv/Scripts/Activate.ps1`
+* For Linux/macOS: Add the code above to the ``venv/bin/activate`` 
+* For Windows: If using Command Prompt, add the code to ``venv/Scripts/activate.bat``
+* For Windows: If using PowerShell, add the following line to ``venv/Scripts/Activate.ps1``
diff --git a/docs/source/pynq_remote/image_build.rst b/docs/source/pynq_remote/image_build.rst
@@ -10,9 +10,9 @@ Unlike Classic PYNQ, there are no pre-built PYNQ.remote SD card images available
 
 **Prerequisites:**
 
+- Host machine with Ubuntu 2022.4 OS installed
 - AMD Tools: `Vivado, Vitis, and Petalinux version 2024.1 <https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/2024-1.html>`_
 - `Docker installation <https://docs.docker.com/engine/install/>`_
-- Supported Linux distribution (see `UG973 <https://docs.amd.com/r/2024.1-English/ug973-vivado-release-notes-install-license/Supported-Operating-Systems>`_)
 
 **Using the Docker-base build flow:**
 
diff --git a/docs/source/pynq_remote/pynq_cpp/cpp_api.rst b/docs/source/pynq_remote/pynq_cpp/cpp_api.rst
diff --git a/docs/source/pynq_remote/pynq_cpp/cpp_install.rst b/docs/source/pynq_remote/pynq_cpp/cpp_install.rst
@@ -9,8 +9,8 @@ Requirements for building PYNQ.cpp
 
 Requirements for using PYNQ.cpp on SoC devices.
 -----------------------------------------------
-- Embedded Linux with FPGA Manager support (``/sys/class/fpga_manager/``)  
-- Root access on device (for device & filesystem operations)
+- Compatible Petalinux image with FPGA Manager support enabled.
+- Root access on device (for device & filesystem operations).
 - Embedded XRT 2.17 installed on the device.
 
 Build Instructions
diff --git a/docs/source/pynq_remote/pynq_cpp/cpp_usage.rst b/docs/source/pynq_remote/pynq_cpp/cpp_usage.rst
@@ -4,7 +4,7 @@ C++ API Usage Examples
 Load a Bitstream
 ----------------
 
-To write a bitstream file to the /lib/firmware directory, you can use the `Device` class to write the file directly.
+To write a bitstream file to the ``/lib/firmware directory``, you can use the `Device` class to write the file directly.
 
 .. code-block:: cpp
 
diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst
@@ -3,7 +3,7 @@
 Quick Start
 ===========
 
-This page shows the fastest way to get up and running with PYNQ.remote.
+This page how to get started with PYNQ.remote. We will use the ZCU104 and the `PYNQ-HelloWorld <https://github.com/Xilinx/PYNQ-HelloWorld>`_ overlay as an example, but the steps are similar for other supported AMD adaptive SoCs and overlays.
 
 Prerequisites
 -------------
@@ -12,59 +12,137 @@ Prerequisites
 * Python 3.10 or newer
 * Supported AMD adaptive SoCs with network access
 * Network connection between host and target
-* SD card
 
 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 either ``PYNQ_REMOTE`` or ``PYNQ_REMOTE_DEVICES`` environment variables set. See :doc:`env_variables` for more information on how to set environment variables.
+    For installation you need to have the ``PYNQ_REMOTE_DEVICES`` environment variables set. See :doc:`env_variables` for more information.
 
 Download PYNQ from GitHub and install the ``pynq`` package using pip. It is recommended to use a 
 `Python virtual environment <https://docs.python.org/3/library/venv.html>`_.
 
+To install the latest release version of PYNQ simply run:
+
+.. code-block:: bash
+
+   pip install pynq
+
+If you want to install the latest development version of PYNQ, you can clone the repository and install it from source:
+
 .. code-block:: bash
 
-   git clone https://github.com/Xilinx/PYNQ.git
-   cd PYNQ
-   pip install .
+   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 :doc:`image_build`.
-* Flash the image to your SD card.
+* Flash the image to your SD card (see :doc:`../appendix/sdcard` 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 <https://help.ubuntu.com/community/Minicom>`_ or `PuTTY <https://www.putty.org/>`_) 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.
 
-Step 3: Connect from Host and Run Your Code
--------------------------------------------
+First, install the required dependencies in your Python virtual environment:
 
-In your Python environment on the host, you can now use PYNQ.remote.
+.. code-block:: bash
+
+   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:**
+
+.. code-block:: bash
+
+   # 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:**
+
+.. code-block:: bash
 
-PYNQ.remote aims to provide an identical API to classic PYNQ. This means that you should be able to run your existing PYNQ code with minimal changes. However, not all PYNQ features are supported yet, and so some adjustments may be necessary.
+   BOARD=ZCU104 pip install --no-build-isolation pynq-helloworld
 
-In order for PYNQ to connect to the remote device, you need to specify the IP address of the target. The simplest way to do this is with the use of the ``PYNQ_REMOTE_DEVICES`` environment variable, which should be set as a string containing one or more IP addresses, separated by commas. For example:
+After installing the package, download the notebooks and overlay files:
 
 .. code-block:: bash
 
-   PYNQ_REMOTE_DEVICES="192.168.2.99, 10.42.0.99"
+   pynq get-notebooks pynq-helloworld -d ZCU104
 
-This can be set in your shell or in your Python script **before** importing the ``pynq`` package. For more information on how to set environment variables, refer to :ref:`env_variables`.
+The ``-d`` argument is required for PYNQ's get-notebooks function to know where to find the notebooks and overlay files.
 
-Once the environment variable is set, you can use the ``pynq`` package as usual. For example, to load an overlay and print the ``ip_dict``, you can do the following:
+After installation, the notebooks will be available in the current folder under ``pynq-notebooks/pynq-helloworld``. Start Jupyter Lab to access them:
+
+.. code-block:: bash
+
+   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:
+
+.. code-block:: python
+
+   # 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:
+
+.. code-block:: python
+
+   # 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:
 
 .. code-block:: python
 
-    import os 
-    os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99"
+   # Original cell:
+   run_kernel()
+   resized_image = Image.fromarray(out_buffer)
+
+Change it to:
+
+.. code-block:: python
 
-    from pynq import Overlay
-    ol = Overlay('my_overlay.xsa')
-    print(ol.ip_dict)
+   # Modified cell:
+   run_kernel()
+   resized_image = Image.fromarray(out_buffer[:])
 
-* Replace ``192.168.2.99`` with your target device’s IP address.
-* Replace ``my_overlay.xsa`` with your overlay
+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.
 
-That's it! You can now run your PYNQ code remotely, just like on a classic PYNQ board.
+Once these changes are made, you should be able to run through the entire notebook and resize images completely remotely using PYNQ.remote!
diff --git a/docs/source/pynq_remote/remote_device.rst b/docs/source/pynq_remote/remote_device.rst
@@ -9,7 +9,7 @@ This module includes classes for remote memory management (``RemoteBuffer``), me
 
 Remote devices can be configured through the ``PYNQ_REMOTE_DEVICES`` environment variable, which should contain a comma-separated list of IP addresses for target devices. Additionally, separate devices can be specified by directly passing the IP address to the ``RemoteDevice`` constructor.
 
-The ``RemoteDevice`` class is complimented by ``PYNQ.cpp`` which operates on the target device, providing a C++ implementation of the PYNQ API. For more details on the C++ implementation, see the :ref:`cppindex` module documentation.
+The ``RemoteDevice`` class is complemented by ``PYNQ.cpp`` which operates on the target device, providing a C++ implementation of the PYNQ API. For more details on the C++ implementation, see the :ref:`cppindex` module documentation.
 
 .. automodule:: pynq.pl_server.remote_device
     :members:
diff --git a/docs/source/pynq_remote/roadmap.rst b/docs/source/pynq_remote/roadmap.rst
diff --git a/docs/source/pynq_remote/status.rst b/docs/source/pynq_remote/status.rst
