deploy: 91ffac4

main/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a3bd4de88cb22018c82f93ee29afc19f
+config: 6c3404a1632b53ac75402c8516c80442
 tags: 645f666f9bcd5a90fca523b33c5a78b7

main/_downloads/85bb13b2419ba78816c5000dfc448f81/tutorial2_position_capture-1.py

@@ -0,0 +1,2 @@
+from common.python.timing_plot import make_timing_plot
+make_timing_plot('/home/runner/work/PandABlocks.github.io/PandABlocks.github.io/docs/tutorials/tutorial2.timing.ini', 'Trigger Only', 'Milliseconds')

main/_downloads/b897bee6d8808d281368e46b1c6a0236/tutorial2_position_capture-2.py

@@ -0,0 +1,2 @@
+from common.python.timing_plot import make_timing_plot
+make_timing_plot('/home/runner/work/PandABlocks.github.io/PandABlocks.github.io/docs/tutorials/tutorial2.timing.ini', 'Trigger Counter 5x faster', 'Milliseconds')

main/_sources/explanations.rst.txt

@@ -0,0 +1,10 @@
+Explanations
+=============
+
+Explanations of how and why the library works.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    explanations/*

main/_sources/explanations/decisions.rst.txt

@@ -0,0 +1,17 @@
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Architectural Decision Records
+==============================
+
+We record major architectural decisions in Architecture Decision Records (ADRs),
+as `described by Michael Nygard
+<http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions>`_.
+Below is the list of our current ADRs.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    decisions/*

main/_sources/explanations/decisions/0001-record-architecture-decisions.rst.txt

@@ -0,0 +1,26 @@
+1. Record architecture decisions
+================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We need to record the architectural decisions made on this project.
+
+Decision
+--------
+
+We will use Architecture Decision Records, as `described by Michael Nygard
+<http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions>`_.
+
+Consequences
+------------
+
+See Michael Nygard's article, linked above. To create new ADRs we will copy and
+paste from existing ones.

main/_sources/explanations/decisions/0002-switched-to-pip-skeleton.rst.txt

@@ -0,0 +1,35 @@
+2. Adopt python3-pip-skeleton for project structure
+===================================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We should use the following `pip-skeleton <https://github.com/DiamondLightSource/python3-pip-skeleton>`_.
+The skeleton will ensure consistency in developer
+environments and package management.
+
+Decision
+--------
+
+We have switched to using the skeleton.
+
+Consequences
+------------
+
+This module will use a fixed set of tools as developed in python3-pip-skeleton
+and can pull from this skeleton to update the packaging to the latest techniques.
+
+As such, the developer environment may have changed, the following could be
+different:
+
+- linting
+- formatting
+- pip venv setup
+- CI/CD

main/_sources/how-to/contribute.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../.github/CONTRIBUTING.rst

main/_sources/how-to/make-release.rst.txt

@@ -0,0 +1,16 @@
+Make a release
+==============
+
+To make a new release, please follow this checklist:
+
+- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/)
+- Go to the GitHub release_ page
+- Choose ``Draft New Release``
+- Click ``Choose Tag`` and supply the new tag you chose (click create new tag)
+- Click ``Generate release notes``, review and edit these notes
+- Choose a title and click ``Publish Release``
+
+Note that tagging and pushing to the main branch has the same effect except that
+you will not get the option to edit the release notes.
+
+.. _release: https://github.com/PandABlocks/PandABlocks.github.io/releases

main/_sources/how-to/remote.rst.txt

@@ -0,0 +1,100 @@
+.. _ssh_doc:
+
+Updating a PandA via SSH
+========================
+
+The Admin interface of the PandA can be used to update the firmware as detailed
+in the quickstart_doc_, but sometimes it is necessary to update a number of
+PandAs at once. The SSH interface can be used to do this.
+
+To gain access over SSH, either add an ``authorized_keys`` file to the SD card,
+or load it from USB via the Admin interface.
+
+It is then possible to log in remotely and perform operations on the PandA.
+
+.. warning::
+
+    PandA only has a single user; root, and remote access is done as this user.
+    Root has privileges to break the system, so be careful when running the
+    commands below.
+
+First update rootfs and then, after a reboot, update to the latest available zpkg 
+packages (while making sure to match the major versions of everything).
+
+.. _quickstart_doc: https://pandablocks.github.io/PandABlocks-rootfs/master/quickstart.html
+
+Updating the rootfs
+-------------------
+
+Download a new ``boot-x.x.zip`` file from GitHub_ and unzip it somewhere. You
+can then::
+
+    $ md5sum boot/imagefile.cpio.gz
+    $ scp boot/* root@my_panda_ip:/boot
+    $ ssh root@my_panda_ip
+    # sync
+    # md5sum /boot/imagefile.cpio.gz
+
+
+If the two md5 sums match it has copied correctly. Within /boot you should find::
+    - boot.scr
+    - uImage
+    - boot.bin
+    - devicetree.dtb
+    - uinitramfs
+
+.. note::
+    For PandA v3.0 and beyond boot.bin and devicetree.dtb now come from the PandABlocks-FPGA build
+    but are combined in the ``boot-x.x.zip`` on the rootfs release page.
+
+You can power cycle the box and it will install the new rootfs.
+
+
+Updating zpkg packages
+----------------------
+
+A PandA firmware installation consists of 4 Zpkgs:
+    - panda-fpga\@*.zpg
+    - panda-server\@*.zpg
+    - panda-webcontrol\@*.zpg
+    - panda-slowfpga\@*.zpg (PandA 3.0 onwards)
+
+Download new zpkg files from GitHub_, then::
+
+    $ scp *.zpg root@my_panda_ip:/tmp
+    $ ssh root@my_panda_ip
+    # zpkg install /tmp/*.zpg
+
+This will install the new versions of the appropriate packages, and restart the services
+on the box to use them. From the PandA 3.0 release and beyond, a new zpkg file will be 
+needed: panda-slowfpga\@*.zpg.
+
+.. note::
+
+    Release 1.0 of the rootfs contained a bug which means that if 1.0 or later
+    versions of the FPGA zpkg were installed, then any subsequent installations
+    of the FPGA zpkg with **ANY** version of the rootfs would fail with 
+    message::
+
+        File lib/python2.7/site-packages/malcolm/modules/web/www/fpga_docs already exists
+
+    Once you have seen this error, run::
+
+        rm /opt/lib/python2.7/site-packages/malcolm/modules/web/www/fpga_docs
+
+    and then retry the ``zpkg`` command and it should succeed. Release 1.1 of
+    the rootfs fixes this, but you will still have to follow the steps above to
+    correct the error.
+
+.. _GitHub: https://github.com/PandABlocks/PandABlocks.github.io/releases
+
+Update 24V eeprom
+-----------------
+
+PandA 3.0 requires an update to the EEPROM of 24Vio FMC cards to do this:
+
+
+    - Find the right ipmi_definition file according the the product and revision (the one for FMC24V is under its module folder)
+    - Copy it to panda
+    - Run /opt/bin/write_eeprom <path-to-ipmi-definition>
+    - After writing, the script will read the EEPROM to confirm the content matches

main/_sources/how-to/run-container.rst.txt

@@ -0,0 +1,43 @@
+Run in a container
+==================
+
+A PandA Development container is available from on `Github Container reistry <https://ghcr.io/pandablocks/pandablocks-dev-container>`_.
+
+
+
+Starting the container
+----------------------
+
+To pull the container from github container registry ::
+
+    $ docker pull ghcr.io/pandablocks/pandablocks-dev-container:latest
+
+To get a released version, use a numbered release instead of ``latest``.
+
+Create three directories: 
+
+- ``REPO_DIR``, containing all the PandA repositories
+
+- ``VIVADO_DIR``, containing a Vivado installation
+
+- ``BUILD_DIR``, an empty directory
+
+The above directories will be mounted as volumes to the container as it is run with the following command:
+
+.. code-block:: bash
+
+    docker run --rm -it -v REPO_DIR:/repos:Z -v BUILD_DIR:/build:Z -v VIVADO_DIR:/scratch/Xilinx ghcr.io/pandablocks/pandablocks-dev-container /bin/bash
+
+The ``/repos``, ``/build``, and ``/scratch/Xilinx`` paths describe the container directories at which the mounts occur. 
+
+In each repo you will need to:
+
+.. code-block:: bash
+
+    cp CONFIG.example CONFIG
+
+.. note::
+
+    For the Vivado installation the container path will need to match your local system. 
+    i.e. if it is located in /FPGA/Xilinx you will use VIVADO_DIR:/FPGA/Xilinx 
+    and you will then need to edit CONFIG as appropriate.

main/_sources/how-to/update-tools.rst.txt

@@ -0,0 +1,16 @@
+Update the tools
+================
+
+This module is merged with the python3-pip-skeleton_. This is a generic
+Python project structure which provides a means to keep tools and
+techniques in sync between multiple Python projects. To update to the
+latest version of the skeleton, run::
+
+    $ git pull --rebase=false https://github.com/DiamondLightSource/python3-pip-skeleton
+
+Any merge conflicts will indicate an area where something has changed that
+conflicts with the setup of the current module. Check the `closed pull requests
+<https://github.com/DiamondLightSource/python3-pip-skeleton/pulls?q=is%3Apr+is%3Aclosed>`_
+of the skeleton module for more details.
+
+.. _python3-pip-skeleton: https://DiamondLightSource.github.io/python3-pip-skeleton

main/_sources/how.rst.txt

@@ -0,0 +1,10 @@
+How-to Guides
+==============
+
+Practical step-by-step guides for day-to-day dev tasks and experienced users.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    how-to/*

main/_sources/index.rst.txt

@@ -6,21 +6,55 @@
 How the documentation is structured
 -----------------------------------
 
-The documentation is split into 2 sections:
+The documentation is split into 4 sections:
 
 .. grid:: 2
+    :gutter: 4
 
-    .. grid-item-card:: :material-regular:`person;4em`
-        :link: user/index
-        :link-type: doc
+    .. grid-item-card:: :material-regular:`directions_walk;3em`
 
-        The User Guide contains documentation on how to install and use PandABlocks.github.io.
+        .. toctree::
+            :maxdepth: 2
+
+	    tutorial
 
-    .. grid-item-card:: :material-regular:`code;4em`
-        :link: developer/index
-        :link-type: doc
+        +++
 
-        The Developer Guide contains documentation on how to develop and contribute changes back to PandABlocks.github.io.
+        Tutorials for installation and typical usage. New users start here.
+
+    .. grid-item-card:: :material-regular:`task;3em`
+
+        .. toctree::
+            :maxdepth: 2
+
+            how
+
+        +++
+
+        Practical step-by-step guides for day-to-day dev tasks and experienced users.
+
+    .. grid-item-card:: :material-regular:`info;3em`
+
+        .. toctree::
+            :maxdepth: 2
+
+	    explanations
+
+        +++
+
+	Explanations of how and why the architecture is the way it is.
+
+    .. grid-item-card:: :material-regular:`menu_book;3em`
+
+        .. toctree::
+            :maxdepth: 2
+
+	    reference
+
+
+        +++
+
+        Technical reference material including APIs and release notes.
 
 The Existing Documentation for the PandABlocks projects can be found:
 
@@ -32,8 +66,3 @@ PandABlocks-webcontrol  https://PandABlocks.github.io/PandABlocks-webcontrol
 PandABlocks-client      https://PandABlocks.github.io/PandABlocks-client
 ======================= =====================================================
 
-.. toctree::
-    :hidden:
-
-    user/index
-    developer/index

main/_sources/reference.rst.txt

@@ -0,0 +1,10 @@
+References
+==============
+
+Practical step-by-step guides for day-to-day dev tasks and experienced users.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    reference/*

main/_sources/reference/genindex.rst.txt

@@ -0,0 +1,5 @@
+API Index
+=========
+
+..
+    https://stackoverflow.com/a/42310803