mx-bluesky 0.3.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

mx_bluesky/hyperion/external_interaction/callbacks/common/callback_util.py

@@ -0,0 +1,46 @@
+from collections.abc import Callable
+
+from bluesky.callbacks import CallbackBase
+
+from mx_bluesky.hyperion.external_interaction.callbacks.robot_load.ispyb_callback import (
+    RobotLoadISPyBCallback,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.rotation.ispyb_callback import (
+    RotationISPyBCallback,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.rotation.nexus_callback import (
+    RotationNexusFileCallback,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.xray_centre.ispyb_callback import (
+    GridscanISPyBCallback,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.xray_centre.nexus_callback import (
+    GridscanNexusFileCallback,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.zocalo_callback import (
+    ZocaloCallback,
+)
+
+CallbacksFactory = Callable[[], tuple[CallbackBase, ...]]
+
+
+def create_robot_load_and_centre_callbacks() -> (
+    tuple[GridscanNexusFileCallback, GridscanISPyBCallback, RobotLoadISPyBCallback]
+):
+    return (
+        GridscanNexusFileCallback(),
+        GridscanISPyBCallback(emit=ZocaloCallback()),
+        RobotLoadISPyBCallback(),
+    )
+
+
+def create_gridscan_callbacks() -> (
+    tuple[GridscanNexusFileCallback, GridscanISPyBCallback]
+):
+    return (GridscanNexusFileCallback(), GridscanISPyBCallback(emit=ZocaloCallback()))
+
+
+def create_rotation_callbacks() -> (
+    tuple[RotationNexusFileCallback, RotationISPyBCallback]
+):
+    return (RotationNexusFileCallback(), RotationISPyBCallback(emit=ZocaloCallback()))

mx_bluesky/hyperion/external_interaction/callbacks/common/ispyb_mapping.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import re
+
+from mx_bluesky.hyperion.external_interaction.ispyb.data_model import (
+    DataCollectionGroupInfo,
+    DataCollectionInfo,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.ispyb_store import (
+    EIGER_FILE_SUFFIX,
+    I03_EIGER_DETECTOR,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.ispyb_utils import (
+    VISIT_PATH_REGEX,
+    get_current_time_string,
+)
+from mx_bluesky.hyperion.parameters.components import DiffractionExperimentWithSample
+
+
+def populate_data_collection_group(params: DiffractionExperimentWithSample):
+    dcg_info = DataCollectionGroupInfo(
+        visit_string=params.visit,
+        experiment_type=params.ispyb_experiment_type.value,
+        sample_id=params.sample_id,
+    )
+    return dcg_info
+
+
+def populate_remaining_data_collection_info(
+    comment,
+    data_collection_group_id,
+    data_collection_info: DataCollectionInfo,
+    params: DiffractionExperimentWithSample,
+):
+    data_collection_info.visit_string = params.visit
+    data_collection_info.parent_id = data_collection_group_id
+    data_collection_info.sample_id = params.sample_id
+    data_collection_info.detector_id = I03_EIGER_DETECTOR
+    data_collection_info.comments = comment
+    data_collection_info.detector_distance = params.detector_params.detector_distance
+    data_collection_info.exp_time = params.detector_params.exposure_time
+    data_collection_info.imgdir = params.detector_params.directory
+    data_collection_info.imgprefix = params.detector_params.prefix
+    data_collection_info.imgsuffix = EIGER_FILE_SUFFIX
+    # Both overlap and n_passes included for backwards compatibility,
+    # planned to be removed later
+    data_collection_info.n_passes = 1
+    data_collection_info.overlap = 0
+    data_collection_info.start_image_number = 1
+    beam_position = params.detector_params.get_beam_position_mm(
+        params.detector_params.detector_distance
+    )
+    data_collection_info.xbeam = beam_position[0]
+    data_collection_info.ybeam = beam_position[1]
+    data_collection_info.start_time = get_current_time_string()
+    # temporary file template until nxs filewriting is integrated and we can use
+    # that file name
+    data_collection_info.file_template = f"{params.detector_params.prefix}_{data_collection_info.data_collection_number}_master.h5"
+    return data_collection_info
+
+
+def get_proposal_and_session_from_visit_string(visit_string: str) -> tuple[str, int]:
+    visit_parts = visit_string.split("-")
+    assert len(visit_parts) == 2, f"Unexpected visit string {visit_string}"
+    return visit_parts[0], int(visit_parts[1])
+
+
+def get_visit_string_from_path(path: str | None) -> str | None:
+    match = re.search(VISIT_PATH_REGEX, path) if path else None
+    return str(match.group(1)) if match else None

mx_bluesky/hyperion/external_interaction/callbacks/grid_detection_callback.py

@@ -0,0 +1,88 @@
+from typing import TypedDict
+
+import numpy as np
+from bluesky.callbacks import CallbackBase
+from dodal.devices.oav.oav_detector import OAVConfigParams
+from dodal.devices.oav.utils import calculate_x_y_z_of_pixel
+from event_model.documents import Event
+
+from mx_bluesky.hyperion.log import LOGGER
+
+
+class GridParamUpdate(TypedDict):
+    x_start_um: float
+    y_start_um: float
+    y2_start_um: float
+    z_start_um: float
+    z2_start_um: float
+    x_steps: int
+    y_steps: int
+    z_steps: int
+    x_step_size_um: float
+    y_step_size_um: float
+    z_step_size_um: float
+
+
+class GridDetectionCallback(CallbackBase):
+    def __init__(
+        self,
+        oav_params: OAVConfigParams,
+        *args,
+    ) -> None:
+        super().__init__(*args)
+        self.oav_params = oav_params
+        self.start_positions: list = []
+        self.box_numbers: list = []
+
+    def event(self, doc: Event):
+        data = doc.get("data")
+        top_left_x_px = data["oav_grid_snapshot_top_left_x"]
+        box_width_px = data["oav_grid_snapshot_box_width"]
+        x_of_centre_of_first_box_px = top_left_x_px + box_width_px / 2
+
+        top_left_y_px = data["oav_grid_snapshot_top_left_y"]
+        y_of_centre_of_first_box_px = top_left_y_px + box_width_px / 2
+
+        smargon_omega = data["smargon-omega"]
+        current_xyz = np.array(
+            [data["smargon-x"], data["smargon-y"], data["smargon-z"]]
+        )
+
+        centre_of_first_box = (
+            x_of_centre_of_first_box_px,
+            y_of_centre_of_first_box_px,
+        )
+
+        position_grid_start = calculate_x_y_z_of_pixel(
+            current_xyz, smargon_omega, centre_of_first_box, self.oav_params
+        )
+
+        LOGGER.info(f"Calculated start position {position_grid_start}")
+
+        self.start_positions.append(position_grid_start)
+        self.box_numbers.append(
+            (
+                data["oav_grid_snapshot_num_boxes_x"],
+                data["oav_grid_snapshot_num_boxes_y"],
+            )
+        )
+
+        self.x_step_size_mm = box_width_px * self.oav_params.micronsPerXPixel / 1000
+        self.y_step_size_mm = box_width_px * self.oav_params.micronsPerYPixel / 1000
+        self.z_step_size_mm = box_width_px * self.oav_params.micronsPerYPixel / 1000
+        return doc
+
+    def get_grid_parameters(self) -> GridParamUpdate:
+        return {
+            "x_start_um": self.start_positions[0][0],
+            "y_start_um": self.start_positions[0][1],
+            "y2_start_um": self.start_positions[0][1],
+            "z_start_um": self.start_positions[1][2],
+            "z2_start_um": self.start_positions[1][2],
+            "x_steps": self.box_numbers[0][0],
+            "y_steps": self.box_numbers[0][1],
+            "z_steps": self.box_numbers[1][1],
+            "x_step_size_um": self.x_step_size_mm,
+            "y_step_size_um": self.y_step_size_mm,
+            "z_step_size_um": self.z_step_size_mm,
+        }

mx_bluesky/hyperion/external_interaction/callbacks/ispyb_callback_base.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+from dodal.beamline_specific_utils.i03 import beam_size_from_aperture
+from dodal.devices.detector.det_resolution import resolution
+from dodal.devices.synchrotron import SynchrotronMode
+
+from mx_bluesky.hyperion.external_interaction.callbacks.plan_reactive_callback import (
+    PlanReactiveCallback,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.data_model import (
+    DataCollectionInfo,
+    DataCollectionPositionInfo,
+    ScanDataInfo,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.ispyb_store import (
+    IspybIds,
+    StoreInIspyb,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.ispyb_utils import get_ispyb_config
+from mx_bluesky.hyperion.log import ISPYB_LOGGER, set_dcgid_tag
+from mx_bluesky.hyperion.parameters.components import DiffractionExperimentWithSample
+from mx_bluesky.hyperion.parameters.constants import CONST
+from mx_bluesky.hyperion.utils.utils import convert_eV_to_angstrom
+
+from .logging_callback import format_doc_for_log
+
+D = TypeVar("D")
+if TYPE_CHECKING:
+    from event_model.documents import Event, EventDescriptor, RunStart, RunStop
+
+
+class BaseISPyBCallback(PlanReactiveCallback):
+    def __init__(
+        self,
+        *,
+        emit: Callable[..., Any] | None = None,
+    ) -> None:
+        """Subclasses should run super().__init__() with parameters, then set
+        self.ispyb to the type of ispyb relevant to the experiment and define the type
+        for self.ispyb_ids."""
+        ISPYB_LOGGER.debug("Initialising ISPyB callback")
+        super().__init__(log=ISPYB_LOGGER, emit=emit)
+        self._oav_snapshot_event_idx: int = 0
+        self.params: DiffractionExperimentWithSample | None = None
+        self.ispyb: StoreInIspyb
+        self.descriptors: dict[str, EventDescriptor] = {}
+        self.ispyb_config = get_ispyb_config()
+        if (
+            self.ispyb_config == CONST.SIM.ISPYB_CONFIG
+            or self.ispyb_config == CONST.SIM.DEV_ISPYB_DATABASE_CFG
+        ):
+            ISPYB_LOGGER.warning(
+                f"{self.__class__} using dev ISPyB config: {self.ispyb_config}. If you"
+                "want to use the real database, please set the ISPYB_CONFIG_PATH "
+                "environment variable."
+            )
+        self.uid_to_finalize_on: str | None = None
+        self.ispyb_ids: IspybIds = IspybIds()
+        self.log = ISPYB_LOGGER
+
+    def activity_gated_start(self, doc: RunStart):
+        self._oav_snapshot_event_idx = 0
+        return self._tag_doc(doc)
+
+    def activity_gated_descriptor(self, doc: EventDescriptor):
+        self.descriptors[doc["uid"]] = doc
+        return self._tag_doc(doc)
+
+    def activity_gated_event(self, doc: Event) -> Event:
+        """Subclasses should extend this to add a call to set_dcig_tag from
+        hyperion.log"""
+        ISPYB_LOGGER.debug("ISPyB handler received event document.")
+        assert self.ispyb is not None, "ISPyB deposition wasn't initialised!"
+        assert self.params is not None, "ISPyB handler didn't receive parameters!"
+
+        event_descriptor = self.descriptors.get(doc["descriptor"])
+        if event_descriptor is None:
+            ISPYB_LOGGER.warning(
+                f"Ispyb handler {self} received event doc {format_doc_for_log(doc)} and "
+                "has no corresponding descriptor record"
+            )
+            return doc
+        match event_descriptor.get("name"):
+            case CONST.DESCRIPTORS.HARDWARE_READ_PRE:
+                scan_data_infos = self._handle_ispyb_hardware_read(doc)
+            case CONST.DESCRIPTORS.HARDWARE_READ_DURING:
+                scan_data_infos = self._handle_ispyb_transmission_flux_read(doc)
+            case _:
+                return self._tag_doc(doc)
+        self.ispyb_ids = self.ispyb.update_deposition(self.ispyb_ids, scan_data_infos)
+        ISPYB_LOGGER.info(f"Received ISPYB IDs: {self.ispyb_ids}")
+        return self._tag_doc(doc)
+
+    def _handle_ispyb_hardware_read(self, doc) -> Sequence[ScanDataInfo]:
+        assert self.params, "Event handled before activity_gated_start received params"
+        ISPYB_LOGGER.info("ISPyB handler received event from read hardware")
+        assert isinstance(
+            synchrotron_mode := doc["data"]["synchrotron-synchrotron_mode"],
+            SynchrotronMode,
+        )
+
+        hwscan_data_collection_info = DataCollectionInfo(
+            undulator_gap1=doc["data"]["undulator-current_gap"],
+            synchrotron_mode=synchrotron_mode.value,
+            slitgap_horizontal=doc["data"]["s4_slit_gaps_xgap"],
+            slitgap_vertical=doc["data"]["s4_slit_gaps_ygap"],
+        )
+        hwscan_position_info = DataCollectionPositionInfo(
+            pos_x=doc["data"]["smargon-x"],
+            pos_y=doc["data"]["smargon-y"],
+            pos_z=doc["data"]["smargon-z"],
+        )
+        scan_data_infos = self.populate_info_for_update(
+            hwscan_data_collection_info, hwscan_position_info, self.params
+        )
+        ISPYB_LOGGER.info("Updating ispyb data collection after hardware read.")
+        return scan_data_infos
+
+    def _handle_ispyb_transmission_flux_read(self, doc) -> Sequence[ScanDataInfo]:
+        assert self.params
+        aperture = doc["data"]["aperture_scatterguard-selected_aperture"]
+        aperture_radius = doc["data"]["aperture_scatterguard-radius"]
+        beamsize = beam_size_from_aperture(aperture_radius)
+        beamsize_x_mm = beamsize.x_um / 1000 if beamsize.x_um else None
+        beamsize_y_mm = beamsize.y_um / 1000 if beamsize.y_um else None
+        hwscan_data_collection_info = DataCollectionInfo(
+            beamsize_at_samplex=beamsize_x_mm,
+            beamsize_at_sampley=beamsize_y_mm,
+            focal_spot_size_at_samplex=beamsize_x_mm,
+            focal_spot_size_at_sampley=beamsize_y_mm,
+            flux=doc["data"]["flux_flux_reading"],
+        )
+        if transmission := doc["data"]["attenuator-actual_transmission"]:
+            # Ispyb wants the transmission in a percentage, we use fractions
+            hwscan_data_collection_info.transmission = transmission * 100
+        event_energy = doc["data"]["dcm-energy_in_kev"]
+        if event_energy:
+            energy_ev = event_energy * 1000
+            wavelength_angstroms = convert_eV_to_angstrom(energy_ev)
+            hwscan_data_collection_info.wavelength = wavelength_angstroms
+            hwscan_data_collection_info.resolution = resolution(
+                self.params.detector_params,
+                wavelength_angstroms,
+                self.params.detector_params.detector_distance,
+            )
+        scan_data_infos = self.populate_info_for_update(
+            hwscan_data_collection_info, None, self.params
+        )
+        ISPYB_LOGGER.info("Updating ispyb data collection after flux read.")
+        self.append_to_comment(f"Aperture: {aperture}. ")
+        return scan_data_infos
+
+    @abstractmethod
+    def populate_info_for_update(
+        self,
+        event_sourced_data_collection_info: DataCollectionInfo,
+        event_sourced_position_info: DataCollectionPositionInfo | None,
+        params: DiffractionExperimentWithSample,
+    ) -> Sequence[ScanDataInfo]:
+        pass
+
+    def activity_gated_stop(self, doc: RunStop) -> RunStop:
+        """Subclasses must check that they are recieving a stop document for the correct
+        uid to use this method!"""
+        assert (
+            self.ispyb is not None
+        ), "ISPyB handler received stop document, but deposition object doesn't exist!"
+        ISPYB_LOGGER.debug("ISPyB handler received stop document.")
+        exit_status = (
+            doc.get("exit_status") or "Exit status not available in stop document!"
+        )
+        reason = doc.get("reason") or ""
+        set_dcgid_tag(None)
+        try:
+            self.ispyb.end_deposition(self.ispyb_ids, exit_status, reason)
+        except Exception as e:
+            ISPYB_LOGGER.warning(
+                f"Failed to finalise ISPyB deposition on stop document: {format_doc_for_log(doc)} with exception: {e}"
+            )
+        return self._tag_doc(doc)
+
+    def _append_to_comment(self, id: int, comment: str) -> None:
+        assert self.ispyb is not None
+        try:
+            self.ispyb.append_to_comment(id, comment)
+        except TypeError:
+            ISPYB_LOGGER.warning(
+                "ISPyB deposition not initialised, can't update comment."
+            )
+
+    def append_to_comment(self, comment: str):
+        for id in self.ispyb_ids.data_collection_ids:
+            self._append_to_comment(id, comment)
+
+    def _tag_doc(self, doc: D) -> D:
+        assert isinstance(doc, dict)
+        if self.ispyb_ids:
+            doc["ispyb_dcids"] = self.ispyb_ids.data_collection_ids
+        return cast(D, doc)

mx_bluesky/hyperion/external_interaction/callbacks/log_uid_tag_callback.py

@@ -0,0 +1,20 @@
+from bluesky.callbacks import CallbackBase
+from event_model import RunStart, RunStop
+
+from mx_bluesky.hyperion.log import set_uid_tag
+
+
+class LogUidTaggingCallback(CallbackBase):
+    def __init__(self) -> None:
+        """Sets the logging filter to add the outermost run uid to graylog messages"""
+        self.run_uid = None
+
+    def start(self, doc: RunStart):
+        if self.run_uid is None:
+            self.run_uid = doc.get("uid")
+            set_uid_tag(self.run_uid)
+
+    def stop(self, doc: RunStop):
+        if doc.get("run_start") == self.run_uid:
+            self.run_uid = None
+            set_uid_tag(None)

mx_bluesky/hyperion/external_interaction/callbacks/logging_callback.py

@@ -0,0 +1,29 @@
+import json
+
+from bluesky.callbacks import CallbackBase
+
+from mx_bluesky.hyperion.log import LOGGER
+
+
+class _BestEffortEncoder(json.JSONEncoder):
+    def default(self, o):
+        return repr(o)
+
+
+def format_doc_for_log(doc):
+    return json.dumps(doc, indent=2, cls=_BestEffortEncoder)
+
+
+class VerbosePlanExecutionLoggingCallback(CallbackBase):
+    def start(self, doc):
+        LOGGER.info(f"START: {format_doc_for_log(doc)}")
+
+    def descriptor(self, doc):
+        LOGGER.info(f"DESCRIPTOR: {format_doc_for_log(doc)}")
+
+    def event(self, doc):
+        LOGGER.info(f"EVENT: {format_doc_for_log(doc)}")
+        return doc
+
+    def stop(self, doc):
+        LOGGER.info(f"STOP: {format_doc_for_log(doc)}")

mx_bluesky/hyperion/external_interaction/callbacks/plan_reactive_callback.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from logging import Logger
+from typing import TYPE_CHECKING, Any
+
+from bluesky.callbacks import CallbackBase
+
+if TYPE_CHECKING:
+    from event_model.documents import Event, EventDescriptor, RunStart, RunStop
+
+
+class PlanReactiveCallback(CallbackBase):
+    log: Logger  # type: ignore # this is initialised to None and not annotated in the superclass
+
+    def __init__(
+        self,
+        log: Logger,
+        *,
+        emit: Callable[..., Any] | None = None,
+    ) -> None:
+        """A callback base class which can be left permanently subscribed to a plan, and
+        will 'activate' and 'deactivate' at the start and end of a plan which provides
+        metadata to trigger this.
+        The run_decorator of the plan should include in its metadata dictionary the key
+        'activate callbacks', with a list of strings of the callback class(es) to
+        activate or deactivate. On a recieving a start doc which specifies this, this
+        class will be activated, and on recieving the stop document for the
+        corresponding uid it will deactivate. The ordinary 'start', 'descriptor',
+        'event' and 'stop' methods will be triggered as normal, and will in turn trigger
+        'activity_gated_' methods - to preserve this functionality, subclasses which
+        override 'start' etc. should include a call to super().start(...) etc.
+        The logic of how activation is triggered will change to a more readable, version
+        in the future (https://github.com/DiamondLightSource/hyperion/issues/964)."""
+
+        super().__init__(emit=emit)
+        self.emit_cb = emit  # to avoid GC; base class only holds a WeakRef
+        self.active = False
+        self.activity_uid = 0
+        self.log = log
+
+    def _run_activity_gated(self, name: str, func, doc, override=False):
+        # Runs `func` if self.active is True or overide is true. Override can be used
+        # to run the function even after setting self.active to False, i.e. in the last
+        # handler of a run.
+
+        running_gated_function = override or self.active
+        if not running_gated_function:
+            return doc
+        try:
+            return self.emit(name, func(doc))
+        except Exception as e:
+            self.log.exception(e)
+            raise
+
+    def start(self, doc: RunStart) -> RunStart | None:
+        callbacks_to_activate = doc.get("activate_callbacks")
+        if callbacks_to_activate and not self.active:
+            activate = type(self).__name__ in callbacks_to_activate
+            self.active = activate
+            self.log.info(
+                f"{'' if activate else 'not'} activating {type(self).__name__}"
+            )
+            self.activity_uid = doc.get("uid")
+        return self._run_activity_gated("start", self.activity_gated_start, doc)
+
+    def descriptor(self, doc: EventDescriptor) -> EventDescriptor | None:
+        return self._run_activity_gated(
+            "descriptor", self.activity_gated_descriptor, doc
+        )
+
+    def event(self, doc: Event) -> Event | None:  # type: ignore
+        return self._run_activity_gated("event", self.activity_gated_event, doc)
+
+    def stop(self, doc: RunStop) -> RunStop | None:
+        do_stop = self.active
+        if doc.get("run_start") == self.activity_uid:
+            self.active = False
+            self.activity_uid = 0
+        return (
+            self._run_activity_gated(
+                "stop", self.activity_gated_stop, doc, override=True
+            )
+            if do_stop
+            else doc
+        )
+
+    def activity_gated_start(self, doc: RunStart) -> RunStart | None:
+        return doc
+
+    def activity_gated_descriptor(self, doc: EventDescriptor) -> EventDescriptor | None:
+        return doc
+
+    def activity_gated_event(self, doc: Event) -> Event | None:
+        return doc
+
+    def activity_gated_stop(self, doc: RunStop) -> RunStop | None:
+        return doc
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} with id: {hex(id(self))} - active: {self.active}>"

mx_bluesky/hyperion/external_interaction/callbacks/robot_load/ispyb_callback.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from event_model.documents import EventDescriptor
+
+from mx_bluesky.hyperion.external_interaction.callbacks.common.ispyb_mapping import (
+    get_proposal_and_session_from_visit_string,
+    get_visit_string_from_path,
+)
+from mx_bluesky.hyperion.external_interaction.callbacks.plan_reactive_callback import (
+    PlanReactiveCallback,
+)
+from mx_bluesky.hyperion.external_interaction.ispyb.exp_eye_store import (
+    ExpeyeInteraction,
+    RobotActionID,
+)
+from mx_bluesky.hyperion.log import ISPYB_LOGGER
+from mx_bluesky.hyperion.parameters.constants import CONST
+
+if TYPE_CHECKING:
+    from event_model.documents import Event, EventDescriptor, RunStart, RunStop
+
+
+class RobotLoadISPyBCallback(PlanReactiveCallback):
+    def __init__(self) -> None:
+        ISPYB_LOGGER.debug("Initialising ISPyB Robot Load Callback")
+        super().__init__(log=ISPYB_LOGGER)
+        self.run_uid: str | None = None
+        self.descriptors: dict[str, EventDescriptor] = {}
+        self.action_id: RobotActionID | None = None
+        self.expeye = ExpeyeInteraction()
+
+    def activity_gated_start(self, doc: RunStart):
+        ISPYB_LOGGER.debug("ISPyB robot load callback received start document.")
+        if doc.get("subplan_name") == CONST.PLAN.ROBOT_LOAD:
+            ISPYB_LOGGER.debug(f"ISPyB robot load callback received: {doc}")
+            self.run_uid = doc.get("uid")
+            assert isinstance(metadata := doc.get("metadata"), dict)
+            assert isinstance(
+                visit := get_visit_string_from_path(metadata["visit_path"]), str
+            )
+            proposal, session = get_proposal_and_session_from_visit_string(visit)
+            self.action_id = self.expeye.start_load(
+                proposal,
+                session,
+                metadata["sample_id"],
+                metadata["sample_puck"],
+                metadata["sample_pin"],
+            )
+        return super().activity_gated_start(doc)
+
+    def activity_gated_descriptor(self, doc: EventDescriptor) -> EventDescriptor | None:
+        self.descriptors[doc["uid"]] = doc
+        return super().activity_gated_descriptor(doc)
+
+    def activity_gated_event(self, doc: Event) -> Event | None:
+        event_descriptor = self.descriptors.get(doc["descriptor"])
+        if (
+            event_descriptor
+            and event_descriptor.get("name") == CONST.DESCRIPTORS.ROBOT_LOAD
+        ):
+            assert (
+                self.action_id is not None
+            ), "ISPyB Robot load callback event called unexpectedly"
+            barcode = doc["data"]["robot-barcode"]
+            oav_snapshot = doc["data"]["oav_snapshot_last_saved_path"]
+            webcam_snapshot = doc["data"]["webcam-last_saved_path"]
+            # I03 uses webcam/oav snapshots in place of before/after snapshots
+            self.expeye.update_barcode_and_snapshots(
+                self.action_id, barcode, webcam_snapshot, oav_snapshot
+            )
+
+        return super().activity_gated_event(doc)
+
+    def activity_gated_stop(self, doc: RunStop) -> RunStop | None:
+        ISPYB_LOGGER.debug("ISPyB robot load callback received stop document.")
+        if doc.get("run_start") == self.run_uid:
+            assert (
+                self.action_id is not None
+            ), "ISPyB Robot load callback stop called unexpectedly"
+            exit_status = (
+                doc.get("exit_status") or "Exit status not available in stop document!"
+            )
+            reason = doc.get("reason") or "OK"
+            self.expeye.end_load(self.action_id, exit_status, reason)
+            self.action_id = None
+        return super().activity_gated_stop(doc)