mx-bluesky 1.4.7__tar.gz → 1.4.9__tar.gz

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/.github/workflows/_test.yml

@@ -51,7 +51,9 @@ jobs:
           pip-install: ".[dev]"
 
       - name: Run tests
-        run: tox -e tests -- -m "not dlstbx"
+        # Longer timeout for CI due to likelihood of cold caches,
+        # cloud infra hw contention etc.
+        run: tox -e tests -- -m "not dlstbx" --timeout=2
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/.gitignore

@@ -11,7 +11,7 @@ __pycache__/
 env/
 # Output
 *.png
-!docs/*.png
+!docs/**/*.png
 !tests/test_data/**/*.png
 
 # Distribution / packaging

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mx-bluesky
-Version: 1.4.7
+Version: 1.4.9
 Summary: Bluesky tools for MX Beamlines at DLS
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -220,7 +220,7 @@ Requires-Dist: flask-restful
 Requires-Dist: ispyb
 Requires-Dist: jupyterlab
 Requires-Dist: matplotlib
-Requires-Dist: nexgen
+Requires-Dist: nexgen>=0.11.0
 Requires-Dist: numpy
 Requires-Dist: opencv-python
 Requires-Dist: opentelemetry-distro
@@ -235,11 +235,11 @@ Requires-Dist: scipy
 Requires-Dist: semver
 Requires-Dist: matplotlib
 Requires-Dist: blueapi>=0.5.0
-Requires-Dist: daq-config-server>=0.1.1
-Requires-Dist: ophyd==1.9.0
-Requires-Dist: ophyd-async>=0.9.0a2
+Requires-Dist: daq-config-server==0.1.1
+Requires-Dist: ophyd>=1.10.5
+Requires-Dist: ophyd-async>=0.10.0a2
 Requires-Dist: bluesky>=1.13.1
-Requires-Dist: dls-dodal==1.44.0
+Requires-Dist: dls-dodal==1.48.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -257,6 +257,7 @@ Requires-Dist: pyright; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
 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: ruff; extra == "dev"
 Requires-Dist: sphinx-autobuild; extra == "dev"

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/conftest.py

@@ -1,21 +1,11 @@
 from collections.abc import Iterator
-from os import environ, getenv
+from os import environ
 from unittest.mock import patch
 
 import pytest
 
 environ["HYPERION_TEST_MODE"] = "true"
 
-print("Adjusting S03 EPICS environment ...")
-s03_epics_server_port = getenv("S03_EPICS_CA_SERVER_PORT")
-s03_epics_repeater_port = getenv("S03_EPICS_CA_REPEATER_PORT")
-if s03_epics_server_port:
-    environ["EPICS_CA_SERVER_PORT"] = s03_epics_server_port
-    print(f"[EPICS_CA_SERVER_PORT] = {s03_epics_server_port}")
-if s03_epics_repeater_port:
-    environ["EPICS_CA_REPEATER_PORT"] = s03_epics_repeater_port
-    print(f"[EPICS_CA_REPEATER_PORT] = {s03_epics_repeater_port}")
-
 
 def pytest_addoption(parser):
     parser.addoption(

mx_bluesky-1.4.9/docs/developer/code-map/grid_detect_xrc.rst

@@ -0,0 +1,60 @@
+Grid Detect Then Xray Centre
+============================
+
+The aim of this page is to provide a general overview of the Hyperion ``grid_detect_then_xray_centre_plan``.
+
+Most of the code for the ``grid_detect_then_xray_centre_plan`` plan is in ``mx-bluesky/hyperion``. Some code is located in ``mx-bluesky/common`` and `dodal <https://github.com/DiamondLightSource/dodal>`_, and plans are increasingly being generalised and moved into ``mx-bluesky/common`` where possible. Therefore, the structure of the codebase is subject to change and this document should be updated accordingly.
+
+There are then a number of plans that make up the ``grid_detect_then_xray_centre_plan`` plan. Some important ones:
+
+* :ref:`grid_detection_plan<grid-detect>` - Use the OAV to optically calculate a grid for a scan that would cover the whole sample.
+* :ref:`flyscan_xray_centre_plan<flyscan>` - Triggers a hardware-based grid scan and moves to the X-ray centre as returned from ``zocalo``.
+* :ref:`grid_detect_then_xray_centre_plan<grid-detect-xrc>` - This top-level plan performs an :ref:`OAV grid detection <grid-detect>` then a :ref:`flyscan x-ray centre <flyscan>`.
+
+The diagram below shows all the plans that make up the ``grid_detect_then_xray_centre_plan``. The colors indicate where these plans can be found.
+
+.. image:: grid_detect_then_xray_centre.drawio.png
+
+.. _grid-detect-xrc:
+
+Grid Detect Then Xray Centre Plan
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`This plan <https://github.com/DiamondLightSource/mx-bluesky/blob/main/src/mx_bluesky/hyperion/experiment_plans/grid_detect_then_xray_centre_plan.py>`__ does the following, in roughly this order:
+
+1. If called standalone, start preparing for data collection.
+2. Perform an :ref:`OAV grid detection <grid-detect>`.
+3. Convert the parameters calculated in step 2 into something we can send to the flyscan X-ray centre.
+4. Move the backlight out, set the aperture to small, and wait for the detector to finish moving.
+5. Perform a :ref:`flyscan X-ray centre <flyscan>`.
+6. Move the sample based on the results of step 5.
+
+.. _grid-detect:
+
+OAV Grid Detection
+~~~~~~~~~~~~~~~~~~
+
+`This plan <https://github.com/DiamondLightSource/mx-bluesky/blob/main/src/mx_bluesky/hyperion/experiment_plans/oav_grid_detection_plan.py>`__ does the following, in roughly this order:
+
+1. Move to omega 0.
+2. Calculate the 2D grid size using the edge arrays from the OAV.
+3. Trigger the OAV device to take snapshots, both with and without the grid.
+4. Read the snapshot paths (which will be gathered for ispyb in the background).
+5. Repeat steps 2–4 for omega 90.
+6. Return the grid positions.
+
+.. _flyscan:
+
+Flyscan Xray Centre No Move
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`This plan <https://github.com/DiamondLightSource/mx-bluesky/blob/main/src/mx_bluesky/hyperion/experiment_plans/flyscan_xray_centre_plan.py>`__ does the following, in roughly this order:
+
+1. Move to the desired transmission (and turn off xbpm feedback).
+2. Move to omega 0.
+3. Read hardware values for ispyb (a grid scan entry will be added in the background).
+4. Set up zebra and motion devices for a grid scan to be done in the motion controller.
+5. Wait for the Eiger to finish arming or arm the Eiger if it hasn't already been done.
+6. Run the motion control grid scan.
+7. Wait for the grid scan to end.
+8. Retrieve the X-ray centering results from ``Zocalo`` (which will be gathered in the background).

mx_bluesky-1.4.9/docs/developer/code-map/index.rst

@@ -0,0 +1,17 @@
+Code Map
+==================================
+
+Explanation of the structure of the codebase
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: :material-regular:`code;3em`
+
+        .. toctree::
+            :caption: Grid Detect Then Xray Centre
+            :maxdepth: 1
+
+            grid_detect_xrc
+
+        +++

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/general/tutorials/profile-tests.rst

@@ -27,7 +27,7 @@ e.g.
 
 .. code-block:: bash
 
-    pytest -m "not (s03 or dlstbx)" --durations=10
+    pytest -m "not dlstbx" --durations=10
 
 in order to find the top 10 slowest tests
 

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/hyperion/deploying-hyperion.rst

@@ -68,7 +68,17 @@ For further information, see https://github.com/containers/podman/issues/2542
 Deploying to kubernetes
 -----------------------
 
-Once the docker image is built, the image can be deployed to kubernetes using the ``deploy_hyperion_to_k8s.sh`` script
+Once the docker image is built, the image can be deployed to kubernetes using the ``deploy_mx_bluesky_app_to_k8s.sh``
+script.
+
+Secrets
+~~~~~~~
+
+The deployment requires the following secrets to be created with the corresponding zocalo rabbitmq credentials if they
+are not already present:
+
+* ``rmq-creds``
+* ``rmq-api-reader``
 
 Production deployment
 ~~~~~~~~~~~~~~~~~~~~~
@@ -77,12 +87,13 @@ Then create and deploy the helm release
 
 ::
 
-    ./utility_scripts/deploy/deploy_hyperion_to_k8s.sh --beamline=<beamline> --checkout-to-prod hyperion
+    ./utility_scripts/deploy/deploy_mx_bluesky_app_to_k8s.sh --appVersion=x.y.z --beamline=<beamline> --checkout-to-prod hyperion hyperion
 
 This will run the ``deploy_mx_bluesky.py`` script to deploy the latest hyperion to ``/dls_sw``.
 You will be prompted to log into the beamline cluster, then it will create a helm release "hyperion".
 The source folders will be mounted as bind mounts to allow the pod to pick up changes in production.
 For production these are expected to be in the normal place defined in ``values.yaml``.
+If the non-k8s deployment of hyperion has already been performed, then omit ``--checkout-to-prod``.
 
 Development deployment
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -93,7 +104,7 @@ above, you install a dev deployment to the cluster you are currently logged into
 
 ::
 
-    ./utility_scripts/deploy/deploy_hyperion_to_k8s.sh --dev --beamline=<beamline> --repository=<your image repo> hyperion-test
+    ./utility_scripts/deploy/deploy_mx_bluesky_app_to_k8s.sh --dev --beamline=<beamline> --repository=<your image repo> hyperion-test hyperion
 
 
 The dev deployment bind-mounts the current ``hyperion`` workspace and ``../dodal`` into the container so that you can

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/hyperion/index.rst

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

mx_bluesky-1.4.9/docs/developer/hyperion/reference/coordinate-systems.puml

@@ -0,0 +1,20 @@
+@startuml
+box "Request Coordinate Space"
+participant "GDA/Agamemnon"
+participant Hyperion
+end box
+
+boundary omega_flip
+
+box "Hardware Coordinate Space"
+participant "Ophyd Devices"
+participant "Nexus File"
+end box
+
+"GDA/Agamemnon" -> Hyperion: Hyperion Request\n(Request Coordinate Space)
+Hyperion -> "Ophyd Devices": Rotation Operations
+"Ophyd Devices" -> "Nexus File": PCAP Data 
+Hyperion -> "Nexus File": Write metadata\nRecord actual hardware coordinate system
+
+
+@enduml

mx_bluesky-1.4.9/docs/developer/hyperion/reference/coordinate-systems.rst

@@ -0,0 +1,76 @@
+Hyperion Coordinate Systems
+===========================
+
+Rotation Coordinate Systems
+---------------------------
+
+Within hyperion coordinates are expressed both in requests to Hyperion, in commands issued to hardware, and in the 
+output files sent to downstream analysis.
+
+.. uml:: coordinate-systems.puml
+
+Within requests to Hyperion, the requested rotations are defined with respect to a fixed coordinate system, that is 
+defined to be the same for all installations and the intention is that this should be the same as that defined by the
+nexus file format when all axes are in their positive orientations. Thus the same request made across different 
+deployments of Hyperion should result in the same physical motion regardless of the coordinate space conventions of 
+the underlying hardware.
+
+In the ``RotationScan`` parameter class ``scan_width_deg`` is defined to always be positive and the direction is 
+defined by ``rotation_direction`` which can be ``POSITIVE`` or ``NEGATIVE``
+
+The coordinate systems of the underlying hardware may differ from the request. At Diamond traditionally the omega 
+axis is implemented to be in the opposite direction, therefore the commands sent to the hardware are transformed and 
+the ``omega_flip`` feature flag controls this behaviour, which by default is set to ``True`` as this is 
+generally expected to be required for the beamlines here.
+
+In the Nexus output file, there is provision for describing the choice of axis orientations in the nexus file, and 
+the ``omega_flip`` parameter affects the omega axis description in ``/entry/sample/transformations/omega``. 
+This is especially important as if PCAP position capture is enabled then referenced data files will contain positions
+with respect to this axis.
+ 
+
+Gridscan Coordinate System
+--------------------------
+
+The diagram below shows how the coordinate system used in the 3D gridscan relates to the beam and sample loop. The blue arrows indicate the direction of the beam. The red grids represent the grids used during the scan.
+
+.. image:: ../../../images/176701633-b93bba62-b2e7-4740-a863-c6b388beb14f.png
+
+Motors Coordinate System
+------------------------
+
+.. include:: <isogrk1.txt>
+
+The diagram below shows the x,y,z directions of the smargon motor coordinate system. The smargon y, z axes change with the :math:`\omega`. x,y,z are measured in millimetres.
+
+
+* The pin runs from -ve x to +ve x
+* y is +ve towards the ceiling when :math:`\omega = 0`.
+* z is +ve towards the detector/away from the oav and parallel to the beam when :math:`\omega = 0`.
+* The x and y coordinates of the image are also shown, the image feed has x from left to right, y from top to bottom, with the pin to the right of the image.
+* |ohgr| rotates from the y axis at :math:`\omega = 0` (the floor to ceiling).
+
+:math:`\omega = 0`
+
+
+.. image:: ../../../images/motor-coords-omega-0.svg
+
+
+:math:`\omega = \alpha`
+
+.. image:: ../../../images/motor-coords-omega-alpha.svg
+
+
+OAV Image Coordinate System
+---------------------------
+
+In the OAV image the below coordinate system is used (with units in pixels). 
+
+.. image:: ../../../images/207297611-f67dfc25-a3a5-4ade-a1e7-28b54a136fa6.png
+
+Conversion Between OAV Image and Smargon
+----------------------------------------
+
+At :math:`\omega = 0`, :math:`x` and :math:`y` in the camera are antiparallel to :math:`x` and :math:`y` in the smargon. :math:`y` in the camera are is parallel to :math:`z` of the smargon at :math:`x` = :math:`\frac{\pi}{2}`. Then to convert from the camera to smargon coordinate systems we map
+
+:math:`x_\text{smargon} = -x, \quad y_\text{smargon} = -y\cos(\omega),\quad z_\text{smargon} = y sin(\omega).`

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/hyperion/reference/gridscan.puml

@@ -77,7 +77,7 @@ GridParamUpdate --> HyperionThreeDGridScan : combines with GridScanWithEdgeDetec
 
 class experiment_plans {
     grid_detect_then_xray_centre()
-    flyscan_xray_centre_no_move()
+    common_flyscan_xray_centre()
     create_parameters_for_flyscan_xray_centre(GridScanWithEdgeDetect, GridParamUpdate) -> HyperionThreeDGridScan
 }
 

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/hyperion/reference/readme.md

@@ -1,7 +1,5 @@
 # hyperion
 
-![Tests](https://github.com/DiamondLightSource/hyperion/actions/workflows/code.yml/badge.svg) [![codecov](https://codecov.io/gh/DiamondLightSource/hyperion/branch/main/graph/badge.svg?token=00Ww81MHe8)](https://codecov.io/gh/DiamondLightSource/hyperion)
-
 Repository for the Hyperion project to implement Unattended Data Collections on the Diamond MX beamlines using the [BlueSky](https://nsls-ii.github.io/bluesky/) / Ophyd framework from BNL.
 
 Currently the software is able to:
@@ -27,9 +25,17 @@ Note that because Hyperion makes heavy use of [Dodal](https://github.com/Diamond
 
 ## Starting the bluesky runner
 
-You can start the bluesky runner by running `run_hyperion.sh`. Note that this will fail on a developer machine unless you have a simulated beamline running, instead you should do `run_hyperion.sh --dev --skip-startup-connection`, which will give you a running instance (note that without hardware trying to run a plan on this will fail). The `--dev` flag ensures that logging will not be sent to the production Graylog.
+The bluesky runner is (re)started in production by GDA when it invokes `run_hyperion.sh`.
+
+
+This script will determine which beamline you are on based on the `BEAMLINE` environment variable. If on a 
+beamline Hyperion will run with `INFO` level logging, sending its logs to both production graylog and to the
+beamline/log/bluesky/hyperion.log on the shared file system.
 
-This script will determine whether you are on a beamline or a production machine based on the `BEAMLINE` environment variable. If on a beamline Hyperion will run with `INFO` level logging, sending its logs to both production graylog and to the beamline/log/bluesky/hyperion.log on the shared file system.
+If you wish to attempt to run from a developer machine, then (if you are able to connect all devices) 
+you may `run_hyperion.sh --dev --beamline=<beamline>`, which will give you a running instance albeit with
+read-only devices. The `--dev` flag ensures that logging will not be sent to the production Graylog/output folders
+and that hyperion will create mock devices.
 
 If in a dev environment Hyperion will log to a local graylog instance instead and into a file at `./tmp/dev/hyperion.log`. A local instance of graylog will need to be running for this to work correctly. To set this up and run up the containers on your local machine run the `setup_graylog.sh` script.
 
@@ -37,23 +43,9 @@ This uses the generic defaults for a local graylog instance. It can be accessed
 
 The hyperion python module can also be run directly without the startup script. It takes the same command line options, including:
 
-`INFO` level logging of the Bluesky event documents can be enabled with the flag
-
-```
-python -m hyperion --dev --verbose-event-logging
-```
-
-Lastly, you can choose to skip running the hardware connection scripts on startup with the flag
-
-```
-python -m hyperion --skip-startup-connection
-```
-
 ## Testing
 
-Unit tests can be run with `python -m pytest -m "not s03" --random-order`. To see log output from tests you can turn on logging with the `--logging` command line option and then use the `-s` command line option to print logs into the console. So to run the unit tests such that all logs are at printed to the terminal, you can use `python -m pytest -m "not s03" --random-order --logging -s`. Note that this will likely overrun your terminal buffer, so you can narrow the selection of tests with the `-k "<test name pattern>"` option.
-
-To be able to run the system tests, or a complete fake scan, we need the simulated S03 beamline. This can be found at: https://gitlab.diamond.ac.uk/controls/python3/s03_utils
+Unit tests can be run with `pytest --random-order`. To see log output from tests you can turn on logging with the `--logging` command line option and then use the `-s` command line option to print logs into the console. So to run the unit tests such that all logs are at printed to the terminal, you can use `python -m pytest --random-order --logging -s`. Note that this will likely overrun your terminal buffer, so you can narrow the selection of tests with the `-k "<test name pattern>"` option.
 
 To fake interaction and processing with Zocalo, you can run `fake_zocalo/dls_start_fake_zocalo.sh`, and make sure to run `module load dials/latest` before starting hyperion (in the same terminal).
 

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/index.rst

@@ -53,3 +53,15 @@ Documentation is split general and topic-specific sections. Each section is spli
         +++
 
         Documentation relating to integrating the murko image recognition system
+
+    .. grid-item-card:: :material-regular:`code;3em`
+
+        .. toctree::
+            :caption: Code Map
+            :maxdepth: 1
+
+            code-map/index
+
+        +++
+
+        Code map explaining the structure of the codebase

mx_bluesky-1.4.7/docs/developer/serial-crystallography-on-i24/how-to/stage-pmac-moves.rst → mx_bluesky-1.4.9/docs/developer/serial-crystallography-on-i24/how-to/pmac-docs.rst

@@ -1,3 +1,20 @@
+=================================
+PMAC-run operations on I24 serial
+=================================
+
+
+Several operations in a fixed target (FT) collection are run vie the PMAC, by sending a command to the ``PMAC_STRING`` PV.
+
+Among these:
+
+- Stage moves
+- Kickoff data collection
+- Laser control
+
+
+For reference, see also the PMAC device implementation in dodal: `PMAC docs <https://diamondlightsource.github.io/dodal/main/reference/generated/dodal.devices.i24.pmac.html>`_
+
+
 Stage motor moves using the PMAC device
 ---------------------------------------
 
@@ -18,6 +35,8 @@ to motors. The axes allocations defined for the chip stages set up are:
 
 When an X-axis move is executed, the #1 motor will make the move.
 
+It should be noted that the PMAC coordinate system used by I24 serial is number 2, which can be specified in a PMAC string by starting the command with ``&2``.
+
 When running chip collections, the stage motors are moved via the `PMAC
 device <https://github.com/DiamondLightSource/dodal/blob/main/src/dodal/devices/i24/pmac.py>`__
 in a couple of different ways.
@@ -28,19 +47,31 @@ in a couple of different ways.
    -  Using a JOG command ``J:{const}``, to jog the motor a specified
       distance from the current position. For example, this will move
       motor Y by 10 motor steps:
-      ``python      yield from bps.abs_set(pmac.pmac_string, "#2J:10")``
+
+      .. code:: python
+
+         yield from bps.abs_set(pmac.pmac_string, "#2J:10")
+
 
    -  The ``hmz`` strings are homing commands which will reset the
       encoders counts to 0 for the axis. All three motors are homed by
       sending the string: ``#1hmz#2hmz#3hmz``. In the plans this is done
       by triggering the home move:
-      ``python       yield from bps.trigger(pmac.home)``
+
+      .. code:: python
+
+         yield from bps.trigger(pmac.home)
+
 
    -  Another pmac_string that can start a move has the format
       ``!x..y..``. This is a command designed to blend any ongoing move
       into a new position. A common one through the serial collection
       code is ``!x0y0z0``, which will start a move to 0 for all motors.
-      ``python      yield from bps.trigger(pmac.to_xyz_zero)``
+
+      .. code:: python
+
+         yield from bps.trigger(pmac.to_xyz_zero)
+
 
 2. The stage motors can also be moved directly through the existing PVs
    ``ME14E-MO-CHIP-01:{X,Y,Z}``, for example:
@@ -49,6 +80,7 @@ in a couple of different ways.
 
       yield from bps.mv(pmac.x, 0, pmac.y, 1)
 
+
 Notes on the coordinate system for a fixed-target collection
 ============================================================
 
@@ -81,7 +113,7 @@ Theory for this computation
 
 The plan needs information stored in a few files:
 
-* The motor directions are stored in ``src/mx_bluesky/i24/serial/parameters/fixed_target/cs/motor_directions.txt.`` The motor number multiplied by the motor direction should give the positive chip direction. 
+* The motor directions are stored in ``src/mx_bluesky/i24/serial/parameters/fixed_target/cs/motor_direction.txt.`` The motor number multiplied by the motor direction should give the positive chip direction.
 * The scale values for x,y,z, the skew value and the sign of Sx, Sy, Sz are all stored in ``src/mx_bluesky/i24/serial/parameters/fixed_target/cs/cs_maker.json``
 * The fiducials 1 and 2 positions are written to file when selecting the fiducials (Setting fiducial 0 instead sends a homing command directly to the pmac_string PV)
 
@@ -106,3 +138,78 @@ the following pmac_strings:
    "#1->10000X+0Y+0Z"
    "#2->+0X-10000Y+0Z"
    "#3->0X+0Y-10000Z"
+
+
+
+
+Data collection via the PMAC
+----------------------------
+
+The data collection for a FT experiment is kicked off by sending a PMAC_STRING with the program number of the motion program the PMAC should run.
+
+Two P-variables - general purpose variables that can be used to store information on the PMAC - have been set aside to monitor the collection run:
+
+::
+
+   P2401 is the "scan_status" variable. It goes to 1 once the motion program starts and will go back to 0 at the very end of the collection
+   P2402 is the "counter" variable. It keeps count of how many images have been acquired so far in the collection.
+
+
+The program number is chosen depending on the input collection parameters:
+
+::
+
+   11 -> Custom, Mini and PSI type chip collections, as well as Oxford chips with mapping set to "None" (full chip collections)
+   12 -> Oxford Chips with Lite mapping (only some blocks collected)
+   13 -> In the past was used for "Full Mapping". **CURRENTLY DISABLED**
+   14 -> Any Pump Probe collection, with any chip type. **WARNING** Assumes Lite mapping for Oxford chips.
+
+To do this, the PMAC device in dodal implements a Flyable device (``ProgramRunner``) and a soft signal (``program_number``).
+The ``kickoff_and_complete_collection_plan`` first sets up the PMAC by setting the program_number signal and calculating the expected duration of the collection, and then triggers the collection by:
+
+.. code:: python
+
+   yield from bps.kickoff(pmac.run_program, wait=True)
+   yield from bps.complete(pmac.run_program, wait=True)
+
+
+The ``kickoff`` method works out the pmac_string to send from the program number in the following way:
+
+::
+
+   "&2b{prog_num}r" where
+      - &2 is the coordinate system in use
+      - b sets the motion program to run
+      - r runs it
+
+
+and then waits for the scan status P-variable to go to 1.
+The ``complete`` method instead monitors the scan status variable and waits for it to go back to 0.
+
+
+In the event of an aborted data collection, an additional Triggerable signal has been added to the PMAC device to be able to reset the PMAC.
+The abort plan for FT will call:
+
+.. code:: python
+
+   yield from bps.trigger(pmac.abort_program)
+
+
+which first sends a ``A`` command to the PMAC to tell it to abort the motion program being currently run and then resets the ``P2041`` variable to 0.
+There is no need to reset the ``P2402`` variable as it's automatically reset once the new motion program starts.
+
+
+
+Laser control
+-------------
+
+The ``laser_control`` plan switches a laser on and off by sending PMAC_STRINGS that set a pair of M-variables.
+M-variables point to a location in memory and are usually used for user access or I/O operations - in this case they have to do with position compare settings.
+
+The M-variables used here are M712/M711 for laser1 and M812/M811 for laser2.
+M711 and M811 are set to 1, while and the value set to M712/M812 indicates when the triggering happens, eg:
+
+::
+
+   M712 = 0 if triggering on the falling edge -> laser off
+   M712 = 1 if triggering on the rising edge -> laser on

{mx_bluesky-1.4.7 → mx_bluesky-1.4.9}/docs/developer/serial-crystallography-on-i24/index.rst

@@ -1,11 +1,11 @@
-I24 Serial Crystallography 
+I24 Serial Crystallography
 ==========================
 
 Documentation is split into four categories, and each is also accessible from links in the side-bar.
 
 .. grid:: 2
     :gutter: 2
-        
+
     .. grid-item-card:: :material-regular:`map;3em`
 
         .. toctree::
@@ -26,7 +26,7 @@ Documentation is split into four categories, and each is also accessible from li
 
             how-to/environment-setup
             how-to/run-a-collection
-            how-to/stage-pmac-moves
+            how-to/pmac-docs
 
         +++
 
@@ -62,4 +62,4 @@ Documentation is split into four categories, and each is also accessible from li
 
         +++
 
-        Tutorials for getting up and running as a developer.    
+        Tutorials for getting up and running as a developer.