Merge pull request #381 from tomhepz/patch-1

Add note on PYNQ compat

Author: meeg

README.md

@@ -16,17 +16,20 @@ It consists of:
 * The `qick` Python package, which includes the interface to the firmware and an API for writing QICK programs
 * [Jupyter notebooks](qick_demos) demonstrating usage
 
-See our [Read the Docs site](https://qick-docs.readthedocs.io/) for:
+See our [Read the Docs site](https://docs.qick.dev/) for:
 * Documentation of the firmware and software
-* A quick-start guide for setting up your board and running the example Jupyter notebooks
-* Ways to communicate with QICK developers and the community
+* A [quick-start guide](https://docs.qick.dev/latest/quick_start.html) for setting up your board and running the example Jupyter notebooks
+* [Ways to communicate](https://docs.qick.dev/latest/contact.html) with QICK developers and the community
 * Extensions to QICK for added functionailty
 
 ## Updates
 
 The QICK firmware and software is still very much a work in progress.
 We strive to be consistent with the APIs but cannot guarantee backwards compatibility.
 
+> [!NOTE]
+> QICK does not yet support PYNQ v3.1. The QICK quick-start guide (linked above) lists the currently recommended PYNQ OS images for your SD card.
+
 Frequent updates to the QICK firmware and software are made as pull requests.
 Each pull request will be documented with a description of the notable changes, including any changes that will require you to change your code.
 We hope that this will help you decide whether or not to update your local code to the latest version.

qick_demos/000_Install_qick_package.ipynb

@@ -21,7 +21,7 @@
     "## pynq library\n",
     "Let's check that the Xilinx pynq library is installed: you should see (among things) a version number, which should match the version of the PYNQ Linux image you installed.\n",
     "\n",
-    "The QICK software supports pynq versions 2.6.0 and above."
+    "The QICK software supports pynq versions 2.6 through 3.0 (including 3.0.1). Version 3.1 is not supported at this time."
    ]
   },
   {
@@ -165,7 +165,11 @@
    "source": [
     "### Installing using pip (recommended option)\n",
     "\n",
-    "You could run these `pip3` commands from the shell over SSH - they need to be run as root (using `sudo`), and on pynq 2.7 you must additionally enable the pynq `venv`. Running the commands inside a notebook, as we do here, conveniently ensures that the commands run in (and install to) the same environment that the notebook runs in."
+    "You could run these `pip3` commands from the shell over SSH - they need to be run as root (using `sudo`), and on pynq 2.7 you must additionally enable the pynq `venv`. Running the commands inside a notebook, as we do here, conveniently ensures that the commands run in (and install to) the same environment that the notebook runs in.\n",
+    "\n",
+    "The options `--no-index --no-build-isolation` are important for two reasons:\n",
+    "1. they allow pip to run even if the board doesn't have Internet access\n",
+    "2. they prevent pip from attempting to install the `pynq` library, which may happen if you've somehow broken your board's Python environment or your `pynq` version is unsupported; pip can't actually install `pynq` correctly so this is unhelpful"
    ]
   },
   {
@@ -205,19 +209,15 @@
     "# It is recommended if you expect to update the git repo, or you want to test changes to the QICK library, \n",
     "# and don't want to reinstall the library every time.\n",
     "\n",
-    "!pip3 install -e ../\n",
-    "\n",
-    "# If your board doesn't have Internet access, you may need to add some extra options:\n",
-    "\n",
-    "# !pip3 install --no-index --no-build-isolation -e ../\n",
+    "!pip3 install --no-index --no-build-isolation -e ../\n",
     "\n",
     "# Use the line below instead for a normal pip install, which copies the library files to a central location.\n",
     "# In contrast to an editable install, you will need to re-install whenever you modify or update the qick library;\n",
     "# a normal install is somewhat slower for the initial install and infinitely slower for updates.\n",
     "# This is only recommended if for some reason you want to delete the git repo after installing,\n",
     "# or the git repo is on a temporarily available filesystem (e.g. flash drive).\n",
     "\n",
-    "# !pip3 install ../\n"
+    "# !pip3 install --no-index --no-build-isolation ../"
    ]
   },
   {

qick_lib/qick/VERSION

@@ -1 +1 @@
-0.2.380
+0.2.381

qick_lib/qick/__init__.py

@@ -37,6 +37,18 @@ def bitfile_path():
     src = os.path.join(os.path.dirname(qick.__file__), filename)
     return src
 
+# Check for supported PYNQ versions that are compatible with QICK library
+# only do the check if running on a Zynq
+if platform.machine() in ['aarch64', 'armv7l']:
+    import pkg_resources
+
+    pynq_version = pkg_resources.get_distribution("pynq").version
+    if pkg_resources.parse_version(pynq_version) >= pkg_resources.parse_version("3.1"):
+        raise RuntimeError(
+            f"Unsupported PYNQ version {pynq_version}. "
+            "QICK library requires PYNQ < 3.1."
+        )
+
 # tie in to rpyc, if using
 try:
     from rpyc.utils.classic import obtain

setup.py

@@ -157,7 +157,7 @@ def get_version(rel_path):
     # We may therefore lose compatibility with the QICK library on a PC running NumPy 2.0.
     install_requires=[
         "numpy",
-        "pynq>=2.6;platform_machine=='aarch64' or platform_machine=='armv7l'",
+        "pynq>=2.6,<3.1; platform_machine=='aarch64' or platform_machine=='armv7l'",
         "tqdm", # Optional
     ],