mx-bluesky 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

mx_bluesky/beamlines/i24/serial/run_serial.py

@@ -1,9 +1,17 @@
-import logging
+import argparse
 import subprocess
 from os import environ
 from pathlib import Path
 
-logger = logging.getLogger("I24ssx.run")
+from mx_bluesky.beamlines.i24.serial.log import SSX_LOGGER
+from mx_bluesky.beamlines.i24.serial.parameters import SSXType
+
+
+def _parse_input(expt: SSXType):
+    parser = argparse.ArgumentParser(description=f"Run a {expt} collection.")
+    parser.add_argument("-t", "--test", action="store_true", help="Run in test mode.")
+    args = parser.parse_args()
+    return args
 
 
 def get_location(default: str = "dev") -> str:
@@ -19,18 +27,26 @@ def _get_file_path() -> Path:
 
 
 def run_extruder():
+    args = _parse_input(SSXType.EXTRUDER)
     loc = get_location()
-    logger.debug(f"Running on {loc}.")
+    SSX_LOGGER.info(f"Running on {loc}.")
     edm_path = get_edm_path()
     filepath = _get_file_path()
-    logger.debug(f"Running {filepath}/run_extruder.sh")
-    subprocess.run(["sh", filepath / "run_extruder.sh", edm_path.as_posix()])
+    test_mode = "--test" if args.test else ""
+    SSX_LOGGER.debug(f"Running {filepath}/run_extruder.sh")
+    subprocess.run(
+        ["bash", filepath / "run_extruder.sh", edm_path.as_posix(), test_mode]
+    )
 
 
 def run_fixed_target():
+    args = _parse_input(SSXType.FIXED)
     loc = get_location()
-    logger.info(f"Running on {loc}.")
+    SSX_LOGGER.info(f"Running on {loc}.")
     edm_path = get_edm_path()
     filepath = _get_file_path()
-    logger.debug(f"Running {filepath}/run_fixed_target.sh")
-    subprocess.run(["sh", filepath / "run_fixed_target.sh", edm_path.as_posix()])
+    test_mode = "--test" if args.test else ""
+    SSX_LOGGER.debug(f"Running {filepath}/run_fixed_target.sh")
+    subprocess.run(
+        ["bash", filepath / "run_fixed_target.sh", edm_path.as_posix(), test_mode]
+    )

mx_bluesky/beamlines/i24/serial/setup_beamline/ca.py

@@ -22,8 +22,6 @@ def caget(pv):
             a = Popen(["caget", pv], stdout=PIPE, stderr=PIPE)
             a_stdout, a_stderr = a.communicate()
             val = a_stdout.split()[1].decode("ascii")
-            # val = evaluate(val)
-            # val = val.decode('ascii')
         except Exception:
             print("Exception in ca_py3.py caget, maybe this PV doesnt exist:", pv)
             pass

mx_bluesky/beamlines/i24/serial/setup_beamline/setup_beamline.py

@@ -42,7 +42,7 @@ def move_detector_stage_to_position_plan(
     logger.debug(
         f"Waiting for detector move. Detector distance: {detector_distance} mm."
     )
-    yield from bps.mv(detector_stage.z, detector_distance)
+    yield from bps.mv(detector_stage.z, detector_distance)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
 
 
 def modechange(action):

mx_bluesky/beamlines/i24/serial/setup_beamline/setup_detector.py

@@ -2,8 +2,6 @@
 Utilities for defining the detector in use, and moving the stage.
 """
 
-import logging
-import time
 from collections.abc import Generator
 from enum import IntEnum
 
@@ -13,7 +11,7 @@ from bluesky.utils import Msg
 from dodal.common import inject
 from dodal.devices.i24.i24_detector_motion import DetectorMotion
 
-from mx_bluesky.beamlines.i24.serial import log
+from mx_bluesky.beamlines.i24.serial.log import SSX_LOGGER
 from mx_bluesky.beamlines.i24.serial.parameters import SSXType
 from mx_bluesky.beamlines.i24.serial.setup_beamline import pv
 from mx_bluesky.beamlines.i24.serial.setup_beamline.ca import caget
@@ -23,8 +21,6 @@ from mx_bluesky.beamlines.i24.serial.setup_beamline.pv_abstract import (
     Pilatus,
 )
 
-logger = logging.getLogger("I24ssx.sup_det")
-
 EXPT_TYPE_DETECTOR_PVS = {
     SSXType.FIXED: pv.me14e_gp101,
     SSXType.EXTRUDER: pv.ioc12_gp15,
@@ -39,11 +35,6 @@ class DetRequest(IntEnum):
         return self.name
 
 
-def setup_logging():
-    logfile = time.strftime("SSXdetectorOps_%d%B%y.log").lower()
-    log.config(logfile)
-
-
 class UnknownDetectorType(Exception):
     pass
 
@@ -53,19 +44,19 @@ def get_detector_type(detector_stage: DetectorMotion) -> Generator[Msg, None, De
     # DetectorMotion should also be used for this.
     # This should be part of https://github.com/DiamondLightSource/mx_bluesky/issues/51
     if float(det_y) < Eiger.det_y_threshold:
-        logger.info("Eiger detector in use.")
+        SSX_LOGGER.info("Eiger detector in use.")
         return Eiger()
     elif float(det_y) > Pilatus.det_y_threshold:
-        logger.info("Pilatus detector in use.")
+        SSX_LOGGER.info("Pilatus detector in use.")
         return Pilatus()
     else:
-        logger.error("Detector not found.")
+        SSX_LOGGER.error("Detector not found.")
         raise UnknownDetectorType("Detector not found.")
 
 
 def _move_detector_stage(detector_stage: DetectorMotion, target: float) -> MsgGenerator:
-    logger.info(f"Moving detector stage to target position: {target}.")
-    yield from bps.mv(detector_stage.y, target)
+    SSX_LOGGER.info(f"Moving detector stage to target position: {target}.")
+    yield from bps.mv(detector_stage.y, target)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
 
 
 # Workaround in case the PV value has been set to the detector name
@@ -94,14 +85,13 @@ def _get_requested_detector(det_type_pv: str) -> str:
 def setup_detector_stage(
     expt_type: SSXType, detector_stage: DetectorMotion = inject("detector_motion")
 ) -> MsgGenerator:
-    setup_logging()
     # Grab the correct PV depending on experiment
     # Its value is set with MUX on edm screen
     det_type_pv = EXPT_TYPE_DETECTOR_PVS[expt_type]
     requested_detector = _get_requested_detector(det_type_pv)
-    logger.info(f"Requested detector: {requested_detector}.")
+    SSX_LOGGER.info(f"Requested detector: {requested_detector}.")
     det_y_target = (
         Eiger.det_y_target if requested_detector == "eiger" else Pilatus.det_y_target
     )
     yield from _move_detector_stage(detector_stage, det_y_target)
-    logger.info("Detector setup done.")
+    SSX_LOGGER.info("Detector setup done.")

mx_bluesky/beamlines/i24/serial/setup_beamline/setup_zebra_plans.py

@@ -70,12 +70,12 @@ def get_zebra_settings_for_extruder(
 
 
 def arm_zebra(zebra: Zebra):
-    yield from bps.abs_set(zebra.pc.arm, ArmDemand.ARM, wait=True)
+    yield from bps.abs_set(zebra.pc.arm, ArmDemand.ARM, wait=True)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
     logger.info("Zebra armed.")
 
 
 def disarm_zebra(zebra: Zebra):
-    yield from bps.abs_set(zebra.pc.arm, ArmDemand.DISARM, wait=True)
+    yield from bps.abs_set(zebra.pc.arm, ArmDemand.DISARM, wait=True)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
     logger.info("Zebra disarmed.")
 
 

mx_bluesky/common/device_setup_plans/read_hardware_for_setup.py

@@ -0,0 +1,14 @@
+import bluesky.plan_stubs as bps
+from dodal.devices.eiger import EigerDetector
+
+from mx_bluesky.common.parameters.constants import DocDescriptorNames
+
+
+def read_hardware_for_zocalo(detector: EigerDetector):
+    """ "
+    If the RunEngine is subscribed to the ZocaloCallback, this plan will also trigger zocalo.
+    A bluesky run must be open to use this plan
+    """
+    yield from bps.create(name=DocDescriptorNames.ZOCALO_HW_READ)
+    yield from bps.read(detector.odin.file_writer.id)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
+    yield from bps.save()

mx_bluesky/common/parameters/components.py

@@ -0,0 +1,221 @@
+import json
+from abc import abstractmethod
+from collections.abc import Sequence
+from enum import StrEnum
+from pathlib import Path
+from typing import SupportsInt
+
+from dodal.devices.aperturescatterguard import ApertureValue
+from dodal.devices.detector import (
+    DetectorParams,
+    TriggerMode,
+)
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic_extra_types.semantic_version import SemanticVersion
+from scanspec.core import AxesPoints
+from semver import Version
+
+from mx_bluesky.common.parameters.constants import TEST_MODE, DetectorParamConstants
+
+PARAMETER_VERSION = Version.parse("5.2.0")
+
+
+class RotationAxis(StrEnum):
+    OMEGA = "omega"
+    PHI = "phi"
+    CHI = "chi"
+    KAPPA = "kappa"
+
+
+class XyzAxis(StrEnum):
+    X = "sam_x"
+    Y = "sam_y"
+    Z = "sam_z"
+
+
+class IspybExperimentType(StrEnum):
+    # Enum values from ispyb column data type
+    SAD = "SAD"  # at or slightly above the peak
+    SAD_INVERSE_BEAM = "SAD - Inverse Beam"
+    OSC = "OSC"  # "native" (in the absence of a heavy atom)
+    COLLECT_MULTIWEDGE = (
+        "Collect - Multiwedge"  # "poorly determined" ~ EDNA complex strategy???
+    )
+    MAD = "MAD"
+    HELICAL = "Helical"
+    MULTI_POSITIONAL = "Multi-positional"
+    MESH = "Mesh"
+    BURN = "Burn"
+    MAD_INVERSE_BEAM = "MAD - Inverse Beam"
+    CHARACTERIZATION = "Characterization"
+    DEHYDRATION = "Dehydration"
+    TOMO = "tomo"
+    EXPERIMENT = "experiment"
+    EM = "EM"
+    PDF = "PDF"
+    PDF_BRAGG = "PDF+Bragg"
+    BRAGG = "Bragg"
+    SINGLE_PARTICLE = "single particle"
+    SERIAL_FIXED = "Serial Fixed"
+    SERIAL_JET = "Serial Jet"
+    STANDARD = "Standard"  # Routine structure determination experiment
+    TIME_RESOLVED = "Time Resolved"  # Investigate the change of a system over time
+    DLS_ANVIL_HP = "Diamond Anvil High Pressure"  # HP sample environment pressure cell
+    CUSTOM = "Custom"  # Special or non-standard data collection
+    XRF_MAP = "XRF map"
+    ENERGY_SCAN = "Energy scan"
+    XRF_SPECTRUM = "XRF spectrum"
+    XRF_MAP_XAS = "XRF map xas"
+    MESH_3D = "Mesh3D"
+    SCREENING = "Screening"
+    STILL = "Still"
+    SSX_CHIP = "SSX-Chip"
+    SSX_JET = "SSX-Jet"
+
+    # Aliases for historic hyperion experiment type mapping
+    ROTATION = "SAD"
+    GRIDSCAN_2D = "mesh"
+    GRIDSCAN_3D = "Mesh3D"
+
+
+class MxBlueskyParameters(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="allow",
+    )
+
+    def __hash__(self) -> int:
+        return self.model_dump_json().__hash__()
+
+    parameter_model_version: SemanticVersion
+
+    @field_validator("parameter_model_version")
+    @classmethod
+    def _validate_version(cls, version: Version):
+        assert (
+            version >= Version(major=PARAMETER_VERSION.major)
+        ), f"Parameter version too old! This version of hyperion uses {PARAMETER_VERSION}"
+        assert (
+            version <= Version(major=PARAMETER_VERSION.major + 1)
+        ), f"Parameter version too new! This version of hyperion uses {PARAMETER_VERSION}"
+        return version
+
+    @classmethod
+    def from_json(cls, input: str | None):
+        assert input is not None
+        return cls(**json.loads(input))
+
+
+class WithSnapshot(BaseModel):
+    snapshot_directory: Path
+    snapshot_omegas_deg: list[float] | None = None
+
+    @property
+    def take_snapshots(self) -> bool:
+        return bool(self.snapshot_omegas_deg)
+
+
+class WithOptionalEnergyChange(BaseModel):
+    demand_energy_ev: float | None = Field(default=None, gt=0)
+
+
+class WithVisit(BaseModel):
+    beamline: str = Field(default="BL03I", pattern=r"BL\d{2}[BIJS]")
+    visit: str = Field(min_length=1)
+    det_dist_to_beam_converter_path: str = Field(
+        default=DetectorParamConstants.BEAM_XY_LUT_PATH
+    )
+    insertion_prefix: str = "SR03S" if TEST_MODE else "SR03I"
+    detector_distance_mm: float | None = Field(default=None, gt=0)
+
+
+class DiffractionExperiment(
+    MxBlueskyParameters, WithSnapshot, WithOptionalEnergyChange, WithVisit
+):
+    """For all experiments which use beam"""
+
+    file_name: str
+    exposure_time_s: float = Field(gt=0)
+    comment: str = Field(default="")
+    trigger_mode: TriggerMode = Field(default=TriggerMode.FREE_RUN)
+    run_number: int | None = Field(default=None, ge=0)
+    selected_aperture: ApertureValue | None = Field(default=None)
+    transmission_frac: float = Field(default=0.1)
+    ispyb_experiment_type: IspybExperimentType
+    storage_directory: str
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_snapshot_directory(cls, values):
+        snapshot_dir = values.get(
+            "snapshot_directory", Path(values["storage_directory"], "snapshots")
+        )
+        values["snapshot_directory"] = (
+            snapshot_dir if isinstance(snapshot_dir, Path) else Path(snapshot_dir)
+        )
+        return values
+
+    @property
+    def num_images(self) -> int:
+        return 0
+
+    @property
+    @abstractmethod
+    def detector_params(self) -> DetectorParams: ...
+
+
+class WithScan(BaseModel):
+    """For experiments where the scan is known"""
+
+    @property
+    @abstractmethod
+    def scan_points(self) -> AxesPoints: ...
+
+    @property
+    @abstractmethod
+    def num_images(self) -> int: ...
+
+
+class SplitScan(BaseModel):
+    @property
+    @abstractmethod
+    def scan_indices(self) -> Sequence[SupportsInt]:
+        """Should return the first index of each scan (i.e. for each nexus file)"""
+        ...
+
+
+class WithSample(BaseModel):
+    sample_id: int
+    sample_puck: int | None = None
+    sample_pin: int | None = None
+
+
+class DiffractionExperimentWithSample(DiffractionExperiment, WithSample): ...
+
+
+class OptionalXyzStarts(BaseModel):
+    x_start_um: float | None = None
+    y_start_um: float | None = None
+    z_start_um: float | None = None
+
+
+class XyzStarts(BaseModel):
+    x_start_um: float
+    y_start_um: float
+    z_start_um: float
+
+    def _start_for_axis(self, axis: XyzAxis) -> float:
+        match axis:
+            case XyzAxis.X:
+                return self.x_start_um
+            case XyzAxis.Y:
+                return self.y_start_um
+            case XyzAxis.Z:
+                return self.z_start_um
+
+
+class OptionalGonioAngleStarts(BaseModel):
+    omega_start_deg: float | None = None
+    phi_start_deg: float | None = None
+    chi_start_deg: float | None = None
+    kappa_start_deg: float | None = None

mx_bluesky/common/parameters/constants.py

@@ -0,0 +1,133 @@
+from enum import Enum
+
+from dodal.devices.aperturescatterguard import ApertureValue
+from dodal.devices.zocalo.zocalo_constants import ZOCALO_ENV as ZOCALO_ENV_FROM_DODAL
+from dodal.utils import get_beamline_name
+from pydantic.dataclasses import dataclass
+
+BEAMLINE = get_beamline_name("test")
+TEST_MODE = BEAMLINE == "test"
+
+
+@dataclass(frozen=True)
+class DocDescriptorNames:
+    # Robot load event descriptor
+    ROBOT_LOAD = "robot_load"
+    # For callbacks to use
+    OAV_ROTATION_SNAPSHOT_TRIGGERED = "rotation_snapshot_triggered"
+    OAV_GRID_SNAPSHOT_TRIGGERED = "snapshot_to_ispyb"
+    HARDWARE_READ_PRE = "read_hardware_for_callbacks_pre_collection"
+    HARDWARE_READ_DURING = "read_hardware_for_callbacks_during_collection"
+    ZOCALO_HW_READ = "zocalo_read_hardware_plan"
+
+
+@dataclass(frozen=True)
+class OavConstants:
+    OAV_CONFIG_JSON = (
+        "tests/test_data/test_OAVCentring.json"
+        if TEST_MODE
+        else (
+            f"/dls_sw/{BEAMLINE}/software/daq_configuration/json/OAVCentring_hyperion.json"
+        )
+    )
+
+
+@dataclass(frozen=True)
+class PlanNameConstants:
+    # Robot load subplan
+    ROBOT_LOAD = "robot_load"
+    # Gridscan
+    GRID_DETECT_AND_DO_GRIDSCAN = "grid_detect_and_do_gridscan"
+    GRID_DETECT_INNER = "grid_detect"
+    GRIDSCAN_OUTER = "run_gridscan_move_and_tidy"
+    GRIDSCAN_AND_MOVE = "run_gridscan_and_move"
+    GRIDSCAN_MAIN = "run_gridscan"
+    DO_FGS = "do_fgs"
+    # Rotation scan
+    ROTATION_MULTI = "multi_rotation_wrapper"
+    ROTATION_OUTER = "rotation_scan_with_cleanup"
+    ROTATION_MAIN = "rotation_scan_main"
+
+
+@dataclass(frozen=True)
+class EnvironmentConstants:
+    ZOCALO_ENV = ZOCALO_ENV_FROM_DODAL
+
+
+@dataclass(frozen=True)
+class TriggerConstants:
+    ZOCALO = "trigger_zocalo_on"
+
+
+@dataclass(frozen=True)
+class HardwareConstants:
+    OAV_REFRESH_DELAY = 0.3
+    PANDA_FGS_RUN_UP_DEFAULT = 0.17
+    CRYOJET_MARGIN_MM = 0.2
+
+
+@dataclass(frozen=True)
+class GridscanParamConstants:
+    WIDTH_UM = 600.0
+    EXPOSURE_TIME_S = 0.004
+    USE_ROI = True
+    BOX_WIDTH_UM = 20.0
+    OMEGA_1 = 0.0
+    OMEGA_2 = 90.0
+    PANDA_RUN_UP_DISTANCE_MM = 0.2
+
+
+@dataclass(frozen=True)
+class RotationParamConstants:
+    DEFAULT_APERTURE_POSITION = ApertureValue.LARGE
+
+
+@dataclass(frozen=True)
+class DetectorParamConstants:
+    BEAM_XY_LUT_PATH = (
+        "tests/test_data/test_det_dist_converter.txt"
+        if TEST_MODE
+        else "/dls_sw/{BEAMLINE}/software/daq_configuration/lookup/DetDistToBeamXYConverter.txt"
+    )
+
+
+@dataclass(frozen=True)
+class ExperimentParamConstants:
+    DETECTOR = DetectorParamConstants()
+    GRIDSCAN = GridscanParamConstants()
+    ROTATION = RotationParamConstants()
+
+
+@dataclass(frozen=True)
+class PlanGroupCheckpointConstants:
+    # For places to synchronise / stop and wait in plans, use as bluesky group names
+    GRID_READY_FOR_DC = "grid_ready_for_data_collection"
+    ROTATION_READY_FOR_DC = "rotation_ready_for_data_collection"
+    MOVE_GONIO_TO_START = "move_gonio_to_start"
+    READY_FOR_OAV = "ready_for_oav"
+
+
+@dataclass(frozen=True)
+class SimConstants:
+    BEAMLINE = "BL03S"
+    INSERTION_PREFIX = "SR03S"
+    # this one is for unit tests
+    ISPYB_CONFIG = "tests/test_data/test_config.cfg"
+    # this one is for system tests
+    DEV_ISPYB_DATABASE_CFG = "/dls_sw/dasc/mariadb/credentials/ispyb-hyperion-dev.cfg"
+
+
+class Actions(Enum):
+    START = "start"
+    STOP = "stop"
+    SHUTDOWN = "shutdown"
+    STATUS = "status"
+
+
+class Status(Enum):
+    WARN = "Warn"
+    FAILED = "Failed"
+    SUCCESS = "Success"
+    BUSY = "Busy"
+    ABORTING = "Aborting"
+    IDLE = "Idle"

mx_bluesky/common/plans/__init__.py

@@ -0,0 +1 @@
+"""Common MX plans which includes open and close data collection runs. These be used in isolation or as part of a larger plan"""

mx_bluesky/common/plans/do_fgs.py

@@ -0,0 +1,121 @@
+from collections.abc import Callable
+from time import time
+
+import bluesky.plan_stubs as bps
+import bluesky.preprocessors as bpp
+from blueapi.core import MsgGenerator
+from dodal.devices.eiger import EigerDetector
+from dodal.devices.fast_grid_scan import FastGridScanCommon
+from dodal.devices.synchrotron import Synchrotron
+from dodal.devices.zocalo.zocalo_results import (
+    ZOCALO_STAGE_GROUP,
+)
+from dodal.log import LOGGER
+from dodal.plans.check_topup import check_topup_and_wait_if_necessary
+from scanspec.core import AxesPoints, Axis
+
+from mx_bluesky.common.device_setup_plans.read_hardware_for_setup import (
+    read_hardware_for_zocalo,
+)
+from mx_bluesky.common.parameters.constants import (
+    EnvironmentConstants,
+    PlanNameConstants,
+    TriggerConstants,
+)
+from mx_bluesky.common.utils.tracing import TRACER
+
+
+def _wait_for_zocalo_to_stage_then_do_fgs(
+    grid_scan_device: FastGridScanCommon,
+    detector: EigerDetector,
+    synchrotron: Synchrotron,
+    during_collection_plan: Callable[[], MsgGenerator] | None = None,
+):
+    expected_images = yield from bps.rd(grid_scan_device.expected_images)
+    exposure_sec_per_image = yield from bps.rd(detector.cam.acquire_time)  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
+    LOGGER.info("waiting for topup if necessary...")
+    yield from check_topup_and_wait_if_necessary(
+        synchrotron,
+        expected_images * exposure_sec_per_image,
+        30.0,
+    )
+
+    # Make sure ZocaloResults queue is clear and ready to accept our new data. Zocalo MUST
+    # have been staged using ZOCALO_STAGE_GROUP prior to this
+    LOGGER.info("Waiting for Zocalo device queue to have been cleared...")
+    yield from bps.wait(ZOCALO_STAGE_GROUP)
+
+    # Triggers Zocalo if RE is subscribed to ZocaloCallback
+    yield from read_hardware_for_zocalo(detector)
+    LOGGER.info("Wait for all moves with no assigned group")
+    yield from bps.wait()
+
+    LOGGER.info("kicking off FGS")
+    yield from bps.kickoff(grid_scan_device, wait=True)
+    gridscan_start_time = time()
+    if during_collection_plan:
+        yield from during_collection_plan()
+    LOGGER.info("completing FGS")
+    yield from bps.complete(grid_scan_device, wait=True)
+    # Remove this logging statement once metrics have been added
+    LOGGER.info(
+        f"Grid scan motion program took {round(time()-gridscan_start_time,2)} to complete"
+    )
+
+
+def kickoff_and_complete_gridscan(
+    gridscan: FastGridScanCommon,
+    detector: EigerDetector,  # Once Eiger inherits from StandardDetector, use that type instead
+    synchrotron: Synchrotron,
+    scan_points: list[AxesPoints[Axis]],
+    scan_start_indices: list[int],
+    plan_during_collection: Callable[[], MsgGenerator] | None = None,
+    zocalo_environment: str = EnvironmentConstants.ZOCALO_ENV,
+):
+    """Triggers a grid scan motion program and waits for completion, accounting for synchrotron topup.
+    If the RunEngine is subscribed to ZocaloCallback, this plan will also trigger Zocalo.
+
+    Can be used for multiple successive grid scans, see Hyperion's usage
+
+    Args:
+        gridscan (FastGridScanCommon):          Device which can trigger a fast grid scan and wait for completion
+        detector (EigerDetector)                Detector device
+        synchrotron (Synchrotron):              Synchrotron device
+        scan_points (list[AxesPoints[Axis]]):   Each element in the list contains all the grid points for that grid scan.
+                                                Two elements in this list indicates that two grid scans will be done, eg for Hyperion's 3D grid scans.
+        scan_start_indices (list[int]):         Contains the first index of each grid scan
+        plan_during_collection (Optional, MsgGenerator): Generic plan called in between kickoff and completion,
+                                                eg waiting on zocalo.
+        zocalo_environment (Optional, str)      Used for zocalo connection
+    """
+
+    assert len(scan_points) == len(
+        scan_start_indices
+    ), "scan_points and scan_start_indices must be lists of the same length!"
+
+    plan_name = PlanNameConstants.DO_FGS
+
+    @TRACER.start_as_current_span(plan_name)
+    @bpp.set_run_key_decorator(plan_name)
+    @bpp.run_decorator(
+        md={
+            "subplan_name": plan_name,
+            TriggerConstants.ZOCALO: plan_name,
+            "scan_points": scan_points,
+            "scan_start_indices": scan_start_indices,
+            "zocalo_environment": zocalo_environment,
+        }
+    )
+    @bpp.contingency_decorator(
+        except_plan=lambda e: (yield from bps.stop(detector)),  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
+        else_plan=lambda: (yield from bps.unstage(detector)),  # type: ignore # See: https://github.com/bluesky/bluesky/issues/1809
+    )
+    def _decorated_do_fgs():
+        yield from _wait_for_zocalo_to_stage_then_do_fgs(
+            gridscan,
+            detector,
+            synchrotron,
+            during_collection_plan=plan_during_collection,
+        )
+
+    yield from _decorated_do_fgs()