mx-bluesky 1.5.11__tar.gz → 1.5.14__tar.gz

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/.github/dependabot.yml

@@ -1,8 +1,3 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
 version: 2
 updates:
   - package-ecosystem: "github-actions"
@@ -26,3 +21,6 @@ updates:
           - "*"
     commit-message:
       prefix: "chore"
+    ignore:
+      - dependency-name: "pyright"
+        versions: [ ">=1.1.407" ]  # Until https://github.com/microsoft/pyright/issues/11060 is fixed

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/.github/workflows/_container.yml

@@ -28,6 +28,10 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      ################################
+      # Hyperion Container Image Build 
+      ################################
+
       - name: Build and export to Docker local cache
         uses: docker/build-push-action@v6
         env:
@@ -37,15 +41,6 @@ jobs:
           file: Dockerfile.hyperion
           load: true
 
-      - name: Build and export Dockerfile.blueapi to local cache
-        uses: docker/build-push-action@v6
-        env:
-          DOCKER_BUILD_RECORD_UPLOAD: false
-        with:
-          context: .
-          file: Dockerfile.blueapi
-          load: true
-
       - name: Create tags for publishing Hyperion image
         id: meta-hyperion
         uses: docker/metadata-action@v5
@@ -62,22 +57,6 @@ jobs:
             type=ref,event=tag
             type=raw,value=latest
 
-      - name: Create tags for publishing BlueAPI image
-        id: meta-blueapi
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            ghcr.io/${{ github.repository }}-blueapi
-          labels: |
-            org.opencontainers.image.title=mx-bluesky-blueapi
-            org.opencontainers.image.description=BlueAPI plans, stubs and utilities for MX beamlines
-          annotations: |
-            org.opencontainers.image.title=mx-bluesky-blueapi
-            org.opencontainers.image.description=BlueAPI plans, stubs and utilities for MX beamlines
-          tags: |
-            type=ref,event=tag
-            type=raw,value=latest
-
       - name: Push cached Hyperion image to container registry
         if: inputs.publish && github.ref_type == 'tag'
         uses: docker/build-push-action@v6
@@ -94,6 +73,45 @@ jobs:
           # Set the annotations to make the description appear in the GH repo page
           annotations: ${{ steps.meta-hyperion.outputs.annotations }}
 
+      - name: Check disk space before
+        run: df  -h && docker buildx du
+
+      - name: Prune local image cache before next build
+        run: docker buildx prune -f
+
+      - name: Check disk space after
+        run: df  -h && docker buildx du
+
+      ###############################
+      # BlueAPI Container Image Build
+      ###############################
+
+      - name: Build and export Dockerfile.blueapi to local cache
+        uses: docker/build-push-action@v6
+        env:
+          DOCKER_BUILD_RECORD_UPLOAD: false
+        with:
+          context: .
+          file: Dockerfile.blueapi
+          load: true
+
+
+      - name: Create tags for publishing BlueAPI image
+        id: meta-blueapi
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}-blueapi
+          labels: |
+            org.opencontainers.image.title=mx-bluesky-blueapi
+            org.opencontainers.image.description=BlueAPI plans, stubs and utilities for MX beamlines
+          annotations: |
+            org.opencontainers.image.title=mx-bluesky-blueapi
+            org.opencontainers.image.description=BlueAPI plans, stubs and utilities for MX beamlines
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest
+
       - name: Push cached BlueAPI image to container registry
         if: github.ref_type == 'tag'
         uses: docker/build-push-action@v6

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/.vscode/settings.json

@@ -26,8 +26,12 @@
     "python.analysis.typeCheckingMode": "basic",
     "cSpell.words": [
         "aperturescatterguard",
+        "beamline",
+        "beamlines",
+        "beamsize",
         "beamstop",
         "blueapi",
+        "caget",
         "cryostream",
         "deadtime",
         "dodal",
@@ -40,19 +44,16 @@
         "mrad",
         "murko",
         "ophyd",
+        "pmac",
         "readback",
         "scanspec",
         "scatterguard",
         "smargon",
+        "thawer",
         "topup",
         "Transfocator",
         "undulator",
         "xbpm",
-        "xspress",
-        "pmac",
-        "beamlines",
-        "caget",
-        "thawer",
-        "beamline",
+        "xspress"
     ],
 }

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/Dockerfile.blueapi

@@ -1,15 +1,17 @@
 # Before changing this BlueAPI version number, you should check that 
 # the BlueAPI pin in pyproject.toml is compatible, else the version will
 # be overridden
-FROM ghcr.io/diamondlightsource/blueapi:1.0.0-rc.2
+FROM ghcr.io/diamondlightsource/blueapi:1.11.0
 
 ARG DEBIAN_FRONTEND=noninteractive
 
-RUN apt update -y && apt upgrade -y
-# Needed for python cv2 dependency
-RUN apt install -y libgl1 libglib2.0-0
+# Need:
+# libgl, libglib2.0 for python cv2 dependency 
+RUN apt update -y && \
+    apt upgrade -y && \
+    apt install -y libgl1 libglib2.0-0
 
-RUN /venv/bin/pip install mx-bluesky
+RUN /venv/bin/pip install --no-cache-dir --no-compile mx-bluesky
 
 # Needed so that Blueapi's setup-scratch stage has permission to modify dependencies installed 
 # in the above pip installation

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/Dockerfile.hyperion

@@ -2,11 +2,13 @@ FROM python:3.11 AS build
 
 ARG DEBIAN_FRONTEND=noninteractive
 
-RUN apt update -y && apt upgrade -y
-# Needed for python cv2 dependency
-RUN apt install -y libgl1 libglib2.0-0
+# Need:
+# libgl, libglib2.0 for python cv2 dependency
+RUN apt update -y && \
+    apt upgrade -y && \
+    apt install -y libgl1 libglib2.0-0
 
-RUN pip install setuptools_scm
+RUN pip install --no-cache-dir --no-compile setuptools_scm
 
 # Copy the pyproject.toml and install dependencies for better caching when developing
 # & rerunning deployment scripts

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mx-bluesky
-Version: 1.5.11
+Version: 1.5.14
 Summary: Bluesky tools for MX Beamlines at DLS
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -218,11 +218,10 @@ Requires-Dist: annotated_types
 Requires-Dist: caproto
 Requires-Dist: fastapi[all]
 Requires-Dist: flask-restful
-Requires-Dist: ispyb
 Requires-Dist: jupyterlab
 Requires-Dist: matplotlib
 Requires-Dist: nexgen>=0.11.0
-Requires-Dist: numpy==2.2.6
+Requires-Dist: numpy>=2.3.5
 Requires-Dist: opencv-python
 Requires-Dist: opentelemetry-distro
 Requires-Dist: opentelemetry-exporter-otlp
@@ -238,17 +237,18 @@ Requires-Dist: deepdiff
 Requires-Dist: matplotlib
 Requires-Dist: cachetools
 Requires-Dist: daq-config-server>=v1.0.0-rc.2
-Requires-Dist: blueapi>=1.6.3
+Requires-Dist: blueapi>=1.8.0
 Requires-Dist: ophyd>=1.10.5
-Requires-Dist: ophyd-async>=0.13.5
+Requires-Dist: ophyd-async>=0.14.0
 Requires-Dist: bluesky>=1.14.6
-Requires-Dist: dls-dodal==1.65.0
+Requires-Dist: dls-dodal==1.67.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: diff-cover; extra == "dev"
 Requires-Dist: GitPython; extra == "dev"
 Requires-Dist: import-linter; extra == "dev"
+Requires-Dist: ispyb; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: myst-parser; extra == "dev"
@@ -262,6 +262,7 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-random-order; extra == "dev"
 Requires-Dist: pytest-timeout; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: sphinx-autobuild; extra == "dev"
 Requires-Dist: sphinx-copybutton; extra == "dev"

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/conftest.py

@@ -7,6 +7,9 @@ import pytest
 environ["HYPERION_TEST_MODE"] = "true"
 
 
+pytest_plugins = ["dodal.testing.fixtures.run_engine"]
+
+
 def pytest_addoption(parser):
     parser.addoption(
         "--logging",

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/docs/developer/general/explanations/callback_and_run_logic.rst

@@ -16,11 +16,9 @@ In general, the ordering flow of when callbacks are triggered is controlled by e
 Rotation Scans
 ---------------------
 
-There are currently two ways of doing rotation scans. A single scan creates one hdf file, one ispyb deposition and then triggers zocalo once. Multi rotation scans create one hdf file for all rotations but then N nexus files, N ispyb depositions and triggers zocalo N times.
+Rotation scans are generalised so that multiple scans can be done at once. The plan will create one hdf file for all rotations but then N nexus files, N ispyb depositions and triggers zocalo N times.
 
-Single scans will be removed in https://github.com/DiamondLightSource/mx-bluesky/issues/847
-
-For multi rotations this is does by starting 1+2*N different runs:
+It does this by starting 1+2*N different runs:
 
 1. ``CONST.PLAN.ROTATION_MULTI``: This is emitted once for the whole multiple rotation. It is used by the nexus callback to get the full number of images and meta_data_run_number so that it knows which hdf file to use. When this is finished zocalo end is triggered.
 2. ``CONST.PLAN.ROTATION_OUTER``: Emitted N times, inside a ``CONST.PLAN.ROTATION_MULTI`` run. This is used to create the initial ispyb deposition and create the nexus writer (but not actually write the file)

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/docs/developer/general/how-to/create-a-release.rst

@@ -3,14 +3,14 @@ Create a New Release
 ===========
 Pre-release
 ===========
-Make sure that dodal has an up-to-date release. If not, create one (see `dodal release instructions <https://diamondlightsource.github.io/dodal/main/developer/how-to/make-release.html>`_).
+Make sure that dodal has an up-to-date release. If not, create one (see `dodal release instructions <https://diamondlightsource.github.io/dodal/main/how-to/make-release.html>`_).
 
 =======
 Release
 =======
 
-1. Create a new branch from main named pre followed by the release version e.g. pre_v0.1.0. The release versions should look like ``v{major}.{minor}.{patch}``.
-2. On this branch pin the up-to-date version of dodal and the latest release of nexgen if necessary, then push to GitHub.
+1. Create a new branch from main named pre followed by the release version e.g. pre_0.1.0. The release versions should look like ``{major}.{minor}.{patch}``.
+2. On this branch pin the latest release of dodal, and nexgen if necessary, then push to GitHub. (e.g "dls-dodal == 1.63.0")
 3. Make sure the CI is passing for this new pre-release branch.
 4. Go `here <https://github.com/DiamondLightSource/mx-bluesky/releases/new>`_.
 5. Select Choose a new tag and type the version of the release, then select the branch created in step 1 as the target.
@@ -19,6 +19,7 @@ Release
 8. Publish the release
 
 NOTE FOR USING THE MX-BLUESKY-BLUEAPI IMAGE: If using this image with BlueAPI's helmchart for deployment, the version of dodal which is installed will be the version which is pinned in the BlueAPI, rather than what's in mx-bluesky's pyproject.toml. Before releasing, you should pin BlueAPI to a version which uses a dodal version which is compatible with itself AND mx-bluesky. The deployment will fail if BlueAPI has no version which works with the desired dodal version
+Follow `these instructions <setup-blueapi-for-mx.html>`_ on using the mx-bluesky-blueapi image.
 
 ------------------------
 Deciding release numbers

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/docs/developer/general/how-to/deploy-a-release.rst

@@ -1,9 +1,13 @@
 Deploy a New Release
 ====================
 
+.. warning::
+
+   This guide is for pre-containerised deployments. To see how deployments work using BlueAPI with kubernetes, please see `the updated guide <setup-blueapi-for-mx.html>`_.
+
 **Remember to discuss any new deployments with the appropriate beamline scientist.**
 
-The ``utility_scripts/deploy/deploy_mx_bluesky.py`` script will deploy the latest mx-bluesky version to a specified beamline. Deployments live in ``/dls_sw/ixx/software/bluesky/mx-bluesky_vX.X.X``. To do a new deployment you should run the deploy script from your mx-bluesky dev environment with e.g.
+The ``utility_scripts/deploy/deploy_mx_bluesky.py`` script will deploy the latest mx-bluesky version to a specified beamline. Deployments live in ``/dls_sw/ixx/software/bluesky/mx-bluesky_X.X.X``. To do a new deployment you should run the deploy script from your mx-bluesky dev environment with e.g.
 If you have just created a new release, you may need to run git fetch --tags to get the newest release.
 
 .. code:: console
@@ -31,28 +35,3 @@ The script has a few additional optional arguments, which can be viewed with:
 .. code:: console
 
     python ./deploy/deploy_mx_bluesky.py -h
-
-
-For building and deploying a Docker image please see :doc:`../../hyperion/deploying-hyperion`.
-
-
-.. note::
-
-    On i03 the installation will succeed with error messages due to RedHat7 versions of dependencies being unavailable.
-    This results in the installation being incomplete, thus requiring the following post-installation steps:
-
-    First, on a RedHat8 workstation, run
-
-    .. code:: console
-
-        . ./.venv/bin/activate
-        pip install confluent-kafka
-        pip install contourpy
-
-    Then, on the control machine, run
-
-    .. code:: console
-
-        . ./.venv/bin/activate
-        pip install -e .
-        pip install -e ../dodal

mx_bluesky-1.5.14/docs/developer/general/how-to/setup-blueapi-for-mx.md

@@ -0,0 +1,40 @@
+# Setting up BlueAPI for an MX beamline
+
+## Background
+
+The Athena DAQ platform is intended to run in microservices using kubernetes. A beamline ixx has a gitlab repository `ixx-services`, which contains that beamline's available services and their helm configurations, as well as `ixx-deployments` which says which available services should be deployed. Services managed in this way will be deployed into the `ixx-beamline` namespace. ArgoCD provides a useful dashboard for the deployed services and their kubernetes objects. See [here](https://dev-guide.diamond.ac.uk/athena/how-tos/migration/) for more information. This guide will explain how to setup BlueAPI using mx-bluesky within this framework.
+
+## Prerequisites
+
+1. The beamline has a kubernetes cluster with gitlab deployment and services repos. See [here](https://dev-guide.diamond.ac.uk/epics-containers/how-tos/intro/) for a guide on this. DAQ members should be codeowners of these repos.
+2. Confirm the beamline cluster has a Blueapi ingress and DNS entry for `ixx-blueapi.diamond.ac.uk` - create a scicomp ticket if it doesn't.
+
+## Guide to run BlueAPI with mx-bluesky through kubernetes
+
+The best way to add BlueAPI to the services and deployments repo with the correct configuration is to copy from an existing setup and change the relevant values. i04 will be used as an example for this guide - [see their blueapi configuration](https://gitlab.diamond.ac.uk/controls/containers/beamline/i04-services/-/tree/main/services/i04-blueapi?ref_type=heads). The `chart.yaml` tells us which helmcharts are being used. The BlueAPI helmchart gives us the bulk of the configuration. See [here](https://github.com/DiamondLightSource/blueapi/tree/main/helm/blueapi) for a table of its settings. In MX we use an additional `mx-bluesky-blueapi` helmchart - right now this is purely for configuring Zocalo, but anything else which is generic to MX should be added.
+
+`values.yaml` lets us configure the helmcharts that we had listed in dependencies. This file should look the same for each MX beamline, other than the actual beamline name. Unfortunately, there's no way to get a templated file here which automatically fills in the beamline name. Some notes:
+
+- The BlueAPI image should be set to `ghcr.io/diamondlightsource/mx-bluesky-blueapi` and you should specify a version tag. See all releases of this image [here](https://github.com/DiamondLightSource/mx-bluesky/pkgs/container/mx-bluesky-blueapi). This image will install any MX-specific dependencies on top of the BlueAPI image.
+- We are currently mounting `/dls/ixx` and `/dls_sw/ixx` to BlueAPI, but the long-term goal is to not mount the file system. Nexgen currently requires `/dls/ixx` to be mounted. Once Nexgen is migrated into a separate service, we can unmount `/dls/ixx` from Blueapi and mount it in Nexgen only. Unmounting `/dls_sw/ixx`requires us to be using the config server for all settings - this is currently being worked on.
+- Until the above is done, BlueAPI needs to run as the detector user so that it has permission to write files. Type `id ixxdetector` into a terminal to find the user id. This then needs to be added in the `runAsUser: [number]` part of the values.
+
+MX Bluesky plans require some secrets to be added to the beamline cluster. The configuration from the above requires these secrets, so will not work without this. At the time of writing this guide, there are 3 that we need: ispyb (expeye) credentials, rabbitMQ credentials for zocalo, and config for rabbitMQ api reader for zocalo. These should be added as sealed secrets and committed to the services repo. Here's how this works:
+
+1. Open a terminal and enter your beamline cluster with `module load k8s-ixx`
+2. Set the default namespace to ixx-beamline with `kubectl config set-context --current --namespace=ixx-beamline`
+3. Create a regular secret and save to a yaml file with `kubectl create secret generic [secret-name] --from-file=/path/to/sensitive/file --save-config --dry-run=client -o yaml > [secret-file-name.yaml]`
+4. Seal the secret with `kubeseal --controller-namespace kube-system --controller-name sealed-secrets-controller --format yaml < [secret-file-name.yaml] > [sealed-secret-file-name.yaml]`. This will encrypt your secret - the beamline cluster comes installed with the private key to decrypt information sealed with this command.
+5. Commit the sealed secret into `ixx-services/services/ixx-blueapi/templates`. Importantly, do not commit the unsealed secret!
+6. Once this is pushed to the main branch, you can check the k8s dashboard to see if the secret has successfully been added.
+
+<div style="border: 2px solid #f39c12; background-color: #fef2e4; padding: 10px; margin: 15px 0; border-radius: 5px;">
+  <strong>Warning:</strong> The mx-bluesky-blueapi image is responsible for your blueapi version and your python environment. It is independent from the mx-bluesky and dodal repos in the scratch folder. Currently, the versions of these repos must be manually managed. This will be addressed <a href="https://github.com/DiamondLightSource/blueapi/issues/933" target="_blank" style="color: #e67e22; text-decoration: underline;">here</a>. 
+</div>
+
+Paths to required credentials:
+
+- Zocalo api reader: `/dls_sw/apps/zocalo/secrets/rabbitmq-api-reader.yml`
+- Zocalo RMQ credentials: `/dls_sw/apps/zocalo/secrets/rabbitmq-credentials.yml`
+- ispyb (expeye) credentials: `/dls_sw/dasc/mariadb/credentials/ispyb-mx-bluesky-ixx.cfg`
+  See [here](https://gitlab.diamond.ac.uk/controls/containers/beamline/i24-services/-/tree/main/services/i24-blueapi/templates?ref_type=heads) For what the templates folder should look like once the above steps have been done.

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/docs/developer/general/index.rst

@@ -1,3 +1,5 @@
+:: _dev-guide:
+
 General MX-Bluesky Developer Guide
 ==================================
 
@@ -25,6 +27,7 @@ Documentation is split into four categories, and each is also accessible from li
             :maxdepth: 1
 
             how-to/get-started
+            how-to/setup-blueapi-for-mx
             how-to/contribute
             how-to/create-a-release
             how-to/deploy-a-release

{mx_bluesky-1.5.11 → mx_bluesky-1.5.14}/docs/developer/hyperion/index.rst

@@ -16,7 +16,6 @@ Documentation specific for the Hyperion module within MX-Bluesky
             reference/baton
             reference/param-hierarchy
             reference/coordinate-systems
-            deploying-hyperion
             system-tests
 
         +++

mx_bluesky-1.5.14/docs/user/hyperion/advanced/concurrent_operations.puml

@@ -0,0 +1,131 @@
+@startuml
+!pragma teoz true
+participant "BlueSky RunEngine" as RE
+box "Opyhd Async Devices"
+participant "Aperture\nScatterguard" as ap_sg
+participant "Smargon" as smargon
+participant "Robot" as robot
+participant "Backlight" as backlight
+participant "OAV" as oav
+participant "Panda" as panda
+participant "Zebra" as zebra
+participant "Zocalo\nResults" as zocalo
+participant "Eiger" as eiger
+end box
+box "Callbacks"
+participant "Robot Load\nISPyB" as RobotLoadISPyB
+participant "Gridscan\nISPyB" as GridscanISPyB
+participant "Grid\nDetection" as GridDetection
+participant "GridScan\nNexus" as GridScanNexus
+participant "Zocalo\nTrigger" as ZocaloCallback
+participant "XRC\nResults" as XRayCentreEventHandler
+participant "Snapshot\nBeam Centre\nAnnotation" as BeamDrawingCallback 
+end box
+
+RE -> RE:robot_load_then_xray_centre
+activate RE #ffeeee
+    opt pin not already loaded
+        RE -> RE: robot_load_and_change_energy_plan
+        activate RE  #ffdddd
+            RE -> RE: prepare_for_robot_load
+            activate RE  #ffcccc
+                RE -> ap_sg: Move Aperture Scatterguard out of beam
+                activate ap_sg
+                    RE -> smargon: Home smargon
+                    activate smargon
+                deactivate ap_sg
+            deactivate RE /' prepare_for_robot_load '/
+            RE -> RE: robot_load_and_snapshots
+            activate RE #ffcccc
+                activate RobotLoadISPyB
+                RE -> RobotLoadISPyB: send parameters to robot load callback
+                RE -> backlight: move backlight in
+                RE -> RE: do_robot_load
+                activate RE  #ffbbbb
+                    RE -> robot: trigger robot load
+                    activate robot
+                    RE -> RE: set_energy_plan
+                    note right of RE: (see below)
+                    deactivate robot
+                deactivate RE /' do_robot_load '/
+                RE -> smargon: Restore motor positions
+                deactivate smargon
+                RE -> oav: trigger snapshots
+                RE -> RobotLoadISPyB: read hardware
+                RE -> RobotLoadISPyB: record snapshots
+            deactivate RE /'robot_load_and_snapshots'/
+        return /'robot_load_and_change_energy_plan'/
+        deactivate RobotLoadISPyB
+    end /'pin not already loaded'/
+    alt pin is loaded
+        RE -> RE: set_energy_plan
+    end /'pin is loaded'/
+    RE -> RE++ : start_preparing_data_collection_then_do_plan
+        RE -> eiger ++ : arm the eiger
+        RE -> GridscanISPyB ++ : send parameters to grdscan callback
+            RE -> RE ++ #ffdddd : pin_centre_then_flyscan_plan
+                RE -> RE: setup_beamline_for_oav
+                RE -> RE: pin_tip_centre_plan
+                ...do pin tip centring...
+                RE -> RE ++ #ffcccc: detect_grid_and_do_gridscan
+                    RE -> RE: setup_beamline_for_oav
+                    RE -> ap_sg ++: prepare aperture scatterguard\nfor gridscan in background
+                    activate GridDetection
+                        RE -> RE ++ #ffbbbb: grid_detection_plan
+                            loop xy and xz grids
+                                RE -> smargon: rotate omega
+                                RE -> oav: trigger OAV snapshot
+                                RE -> GridscanISPyB: snapshot event with oav + smargon state
+                                & RE -> BeamDrawingCallback ++
+                                BeamDrawingCallback -> BeamDrawingCallback : save snapshot details\n\
+to generate rotation\n\
+snapshots later
+                            end
+                        deactivate RE /'grid_detection_plan'/
+                    deactivate GridDetection
+                    RE -> RE ++
+                    ...grid detection...
+                    return
+                    RE -> backlight: move backlight out 
+                    ap_sg -> RE --: aperture scatterguard completes
+                    RE -> RE ++ #ffaaaa : common_flycan_xray_centre
+                        RE -> eiger : setup detector parameters
+                        RE -> GridScanNexus++: send gridscan parameters
+                        RE -> panda : configure panda
+                        RE -> zebra : configure zebra for panda
+                        RE -> panda ++ : arm panda
+                        RE -> zocalo ++ : stage zocalo device
+                        RE -> RE ++ #ff9999 : run_gridscan 
+                            RE -> GridscanISPyB : read hardware before
+                            & RE -> GridScanNexus
+                            RE <-> eiger : stage eiger (ensures arming complete if not already)
+                            RE -> ZocaloCallback ++ : send params to Zocalo callback
+                            zocalo -> RE : zocalo stage completes
+                            RE -> ZocaloCallback : trigger zocalo with detector filename
+                            RE -> panda ++ : kickoff gridscan
+                            RE -> GridscanISPyB : read hardware during
+                            & RE -> GridScanNexus
+                            deactivate GridScanNexus
+                            ...perform gridscan...
+                            panda -> RE --
+                            eiger -> RE -- : unstage eiger
+                            RE -> ZocaloCallback : notify Zocalo of completion
+                            deactivate ZocaloCallback
+                        deactivate RE /' run_gridscan '/
+                        RE -> zocalo ++: fetch results from zocalo
+                        ...wait for Zocalo processing...
+                        zocalo -> RE -- : detected xtal centres
+                        RE -> XRayCentreEventHandler ++ : post detected centres to callback
+                        zocalo -> RE -- : unstage zocalo
+                        panda -> RE -- : unstage panda
+                        RE -> zebra : tidy zebra
+                    deactivate RE /'common_flyscan_xray_centre'/
+                deactivate RE /' detect_grid_and_do_gridscan'/
+            return /' pin_centre_then_flyscan_plan'/
+        deactivate GridscanISPyB
+    deactivate RE /' start_preparing_data_collection_then_do_plan '/
+deactivate RE /'robot_load_then_xray_centre'/
+note over XRayCentreEventHandler
+Results collected later by rotation
+end note
+@enduml

mx_bluesky-1.5.14/docs/user/hyperion/advanced/concurrent_operations_rotation.puml

@@ -0,0 +1,77 @@
+@startuml
+!pragma teoz true
+participant "BlueSky RunEngine" as RE
+box "Opyhd Async Devices"
+participant "Aperture\nScatterguard" as ap_sg
+participant "Smargon" as smargon
+participant "Robot" as robot
+participant "Backlight" as backlight
+participant "OAV" as oav
+participant "Zebra" as zebra
+participant "Eiger" as eiger
+participant "Synchrotron" as synchrotron
+end box
+box "Callbacks"
+participant "Rotation\nISPyB" as RotationISPyB
+participant "Rotation\nNexus" as RotationScanNexus
+participant "XRC\nResults" as XRayCentreEventHandler
+participant "Snapshot\nBeam Centre\nAnnotation" as BeamDrawingCallback
+end box
+
+activate XRayCentreEventHandler
+activate BeamDrawingCallback
+XRayCentreEventHandler -> RE : results from gridscan
+deactivate XRayCentreEventHandler
+
+RE -> eiger : configure eiger parameters
+
+RE -> RE ++ : start_preparing_data_collection_then_do_plan
+    RE -> eiger ++ : start arming the eiger
+    RE -> RotationScanNexus ++ : send rotation parameters
+    loop for each rotation
+        RE -> RotationISPyB ++: send rotation parameters (ROTATION_OUTER)
+        & RotationISPyB -> RotationScanNexus
+        RE -> smargon : move to xtal centre
+        RE -> RE : setup_beamline_for_oav
+        note right of RE : (if snapshots not derived from gridscan snapshots)
+        RE -> ap_sg ++ : prepare aperture
+        RE -> RE ++ #ffdddd : oav_snapshot_plan
+            loop for each snapshot
+                RE -> smargon : rotate
+                RE -> oav : configure + trigger snapshot (if taking real snapshots)
+                oav -> oav : save snapshots
+                RE -> RotationISPyB : generate snapshot event
+                & RE -> BeamDrawingCallback
+                BeamDrawingCallback -> BeamDrawingCallback : annotate snapshots
+            end
+            deactivate BeamDrawingCallback
+        deactivate RE /' oav_snapshot_plan '/
+        RE -> RE ++ #ffdddd : rotation_scan_plan
+            RE -> RotationISPyB ++ : send scan points (ROTATION_SCAN_MAIN)
+            RE -> zebra ++ : configure zebra for rotation
+            RE -> RE ++ #ffcccc : setup_sample_environment
+                RE -> backlight : move backlight out
+                ap_sg -> RE -- : select aperture completed
+            deactivate RE /' setup_sample_environment '/
+            RE -> smargon : set velocity
+            RE -> zebra : arm zebra PC
+            opt wait for topup
+                RE -> synchrotron ++ : check synchrotron status vs desired exposure
+                ...wait until topup is complete if necessary...
+                return 
+            end
+            RE -> smargon : trigger scan
+            RE -> RotationISPyB : read hardware during scan
+            & -> RotationScanNexus
+        deactivate RE /' rotation_scan_plan '/
+        RE -> RotationISPyB : record subplan exit status
+        deactivate RotationISPyB
+    end /' loop for each rotation '/
+    deactivate RotationISPyB
+    eiger -> RE -- : unstage eiger
+    RE -> zebra : tidy zebra
+    deactivate zebra
+    deactivate RotationScanNexus
+deactivate RE /' start_preparing_data_collection_then_do_plan '/
+
+@enduml

mx_bluesky-1.5.14/docs/user/hyperion/advanced/concurrent_operations_set_energy.puml

@@ -0,0 +1,38 @@
+@startuml
+!pragma teoz true
+participant "BlueSky RunEngine" as RE
+box "Opyhd Async Devices"
+participant "Undulator" as undulator
+participant "DCM" as dcm
+participant "Transmission\nand Feedback" as feedback
+participant "Mirrors" as mirrors
+participant "Mirror\nVoltages" as voltages
+end box
+
+group set_energy_plan
+    RE -> RE: set_energy_plan
+    activate RE
+    RE -> feedback: feedback off
+    activate feedback
+    RE -> undulator: set undulator gap for requested energy
+    activate undulator
+    RE -> dcm: Adjust DCM pitch and roll for energy
+    activate dcm
+    opt mirror stripe needs changing
+        RE -> mirrors: Adjust mirror stripe
+        activate mirrors
+        RE -> mirrors: Adjust yaw, lat
+        {start_voltages} RE -> voltages: Adjust mirror voltages
+        activate voltages
+        ...Wait for all voltages to settle...
+        {end_voltages} voltages -> RE
+        deactivate voltages
+        deactivate mirrors
+    end
+    undulator -> RE
+    deactivate undulator
+    deactivate dcm
+    deactivate feedback
+    deactivate RE /' set energy plan '/
+end
+@enduml