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

mx_bluesky/hyperion/experiment_plans/rotation_scan_plan.py

@@ -0,0 +1,436 @@
+from __future__ import annotations
+
+import dataclasses
+
+import bluesky.plan_stubs as bps
+import bluesky.preprocessors as bpp
+from blueapi.core import BlueskyContext, MsgGenerator
+from dodal.devices.aperturescatterguard import ApertureScatterguard
+from dodal.devices.attenuator import Attenuator
+from dodal.devices.backlight import Backlight
+from dodal.devices.dcm import DCM
+from dodal.devices.detector.detector_motion import DetectorMotion
+from dodal.devices.eiger import EigerDetector
+from dodal.devices.flux import Flux
+from dodal.devices.oav.oav_detector import OAV
+from dodal.devices.oav.oav_parameters import OAVParameters
+from dodal.devices.robot import BartRobot
+from dodal.devices.s4_slit_gaps import S4SlitGaps
+from dodal.devices.smargon import Smargon
+from dodal.devices.synchrotron import Synchrotron
+from dodal.devices.undulator import Undulator
+from dodal.devices.xbpm_feedback import XBPMFeedback
+from dodal.devices.zebra import RotationDirection, Zebra
+from dodal.devices.zebra_controlled_shutter import ZebraShutter
+from dodal.plans.check_topup import check_topup_and_wait_if_necessary
+
+from mx_bluesky.hyperion.device_setup_plans.manipulate_sample import (
+    cleanup_sample_environment,
+    move_phi_chi_omega,
+    move_x_y_z,
+    setup_sample_environment,
+)
+from mx_bluesky.hyperion.device_setup_plans.read_hardware_for_setup import (
+    read_hardware_during_collection,
+    read_hardware_for_zocalo,
+    read_hardware_pre_collection,
+)
+from mx_bluesky.hyperion.device_setup_plans.setup_zebra import (
+    arm_zebra,
+    setup_zebra_for_rotation,
+    tidy_up_zebra_after_rotation_scan,
+)
+from mx_bluesky.hyperion.device_setup_plans.utils import (
+    start_preparing_data_collection_then_do_plan,
+)
+from mx_bluesky.hyperion.device_setup_plans.xbpm_feedback import (
+    transmission_and_xbpm_feedback_for_collection_decorator,
+)
+from mx_bluesky.hyperion.experiment_plans.oav_snapshot_plan import (
+    OavSnapshotComposite,
+    oav_snapshot_plan,
+    setup_beamline_for_OAV,
+)
+from mx_bluesky.hyperion.log import LOGGER
+from mx_bluesky.hyperion.parameters.constants import CONST
+from mx_bluesky.hyperion.parameters.rotation import (
+    MultiRotationScan,
+    RotationScan,
+)
+from mx_bluesky.hyperion.utils.context import device_composite_from_context
+
+
+@dataclasses.dataclass
+class RotationScanComposite(OavSnapshotComposite):
+    """All devices which are directly or indirectly required by this plan"""
+
+    aperture_scatterguard: ApertureScatterguard
+    attenuator: Attenuator
+    backlight: Backlight
+    dcm: DCM
+    detector_motion: DetectorMotion
+    eiger: EigerDetector
+    flux: Flux
+    robot: BartRobot
+    smargon: Smargon
+    undulator: Undulator
+    synchrotron: Synchrotron
+    s4_slit_gaps: S4SlitGaps
+    sample_shutter: ZebraShutter
+    zebra: Zebra
+    oav: OAV
+    xbpm_feedback: XBPMFeedback
+
+
+def create_devices(context: BlueskyContext) -> RotationScanComposite:
+    """Ensures necessary devices have been instantiated"""
+
+    return device_composite_from_context(context, RotationScanComposite)
+
+
+DEFAULT_DIRECTION = RotationDirection.NEGATIVE
+DEFAULT_MAX_VELOCITY = 120
+# Use a slightly larger time to acceleration than EPICS as it's better to be cautious
+ACCELERATION_MARGIN = 1.5
+
+
+@dataclasses.dataclass
+class RotationMotionProfile:
+    start_scan_deg: float
+    start_motion_deg: float
+    scan_width_deg: float
+    shutter_time_s: float
+    direction: RotationDirection
+    speed_for_rotation_deg_s: float
+    acceleration_offset_deg: float
+    shutter_opening_deg: float
+    total_exposure_s: float
+    distance_to_move_deg: float
+    max_velocity_deg_s: float
+
+
+def calculate_motion_profile(
+    params: RotationScan,
+    motor_time_to_speed_s: float,
+    max_velocity_deg_s: float,
+) -> RotationMotionProfile:
+    """Calculates the various numbers needed for motions in the rotation scan.
+    Rotates through "scan width" plus twice an "offset" to take into account
+    acceleration at the start and deceleration at the end, plus the number of extra
+    degrees of rotation needed to make sure the fast shutter has fully opened before the
+    detector trigger is sent.
+    See https://github.com/DiamondLightSource/hyperion/wiki/rotation-scan-geometry
+    for a simple pictorial explanation."""
+
+    direction = params.rotation_direction.multiplier
+    num_images = params.num_images
+    shutter_time_s = params.shutter_opening_time_s
+    image_width_deg = params.rotation_increment_deg
+    exposure_time_s = params.exposure_time_s
+    motor_time_to_speed_s *= ACCELERATION_MARGIN
+    start_scan_deg = params.omega_start_deg
+
+    LOGGER.info("Calculating rotation scan motion profile:")
+    LOGGER.info(
+        f"{num_images=}, {shutter_time_s=}, {image_width_deg=}, {exposure_time_s=}, {direction=}"
+    )
+
+    scan_width_deg = num_images * params.rotation_increment_deg
+    LOGGER.info(f"{scan_width_deg=} = {num_images=} * {params.rotation_increment_deg=}")
+
+    speed_for_rotation_deg_s = image_width_deg / exposure_time_s
+    LOGGER.info("speed_for_rotation_deg_s = image_width_deg / exposure_time_s")
+    LOGGER.info(
+        f"{speed_for_rotation_deg_s=} = {image_width_deg=} / {exposure_time_s=}"
+    )
+
+    acceleration_offset_deg = motor_time_to_speed_s * speed_for_rotation_deg_s
+    LOGGER.info(
+        f"{acceleration_offset_deg=} = {motor_time_to_speed_s=} * {speed_for_rotation_deg_s=}"
+    )
+
+    start_motion_deg = start_scan_deg - (acceleration_offset_deg * direction)
+    LOGGER.info(
+        f"{start_motion_deg=} = {start_scan_deg=} - ({acceleration_offset_deg=} * {direction=})"
+    )
+
+    shutter_opening_deg = speed_for_rotation_deg_s * shutter_time_s
+    LOGGER.info(
+        f"{shutter_opening_deg=} = {speed_for_rotation_deg_s=} * {shutter_time_s=}"
+    )
+
+    shutter_opening_deg = speed_for_rotation_deg_s * shutter_time_s
+    LOGGER.info(
+        f"{shutter_opening_deg=} = {speed_for_rotation_deg_s=} * {shutter_time_s=}"
+    )
+
+    total_exposure_s = num_images * exposure_time_s
+    LOGGER.info(f"{total_exposure_s=} = {num_images=} * {exposure_time_s=}")
+
+    distance_to_move_deg = (
+        scan_width_deg + shutter_opening_deg + acceleration_offset_deg * 2
+    ) * direction
+    LOGGER.info(
+        f"{distance_to_move_deg=} = ({scan_width_deg=} + {shutter_opening_deg=} + {acceleration_offset_deg=} * 2) * {direction=})"
+    )
+
+    return RotationMotionProfile(
+        start_scan_deg=start_scan_deg,
+        start_motion_deg=start_motion_deg,
+        scan_width_deg=scan_width_deg,
+        shutter_time_s=shutter_time_s,
+        direction=params.rotation_direction,
+        speed_for_rotation_deg_s=speed_for_rotation_deg_s,
+        acceleration_offset_deg=acceleration_offset_deg,
+        shutter_opening_deg=shutter_opening_deg,
+        total_exposure_s=total_exposure_s,
+        distance_to_move_deg=distance_to_move_deg,
+        max_velocity_deg_s=max_velocity_deg_s,
+    )
+
+
+def rotation_scan_plan(
+    composite: RotationScanComposite,
+    params: RotationScan,
+    motion_values: RotationMotionProfile,
+):
+    """A stub plan to collect diffraction images from a sample continuously rotating
+    about a fixed axis - for now this axis is limited to omega.
+    Needs additional setup of the sample environment and a wrapper to clean up."""
+
+    @bpp.set_run_key_decorator(CONST.PLAN.ROTATION_MAIN)
+    @bpp.run_decorator(
+        md={
+            "subplan_name": CONST.PLAN.ROTATION_MAIN,
+            "scan_points": [params.scan_points],
+        }
+    )
+    def _rotation_scan_plan(
+        motion_values: RotationMotionProfile,
+        composite: RotationScanComposite,
+    ):
+        axis = composite.smargon.omega
+
+        # can move to start as fast as possible
+        yield from bps.abs_set(
+            axis.velocity, motion_values.max_velocity_deg_s, wait=True
+        )
+        LOGGER.info(f"moving omega to beginning, {motion_values.start_scan_deg=}")
+        yield from bps.abs_set(
+            axis,
+            motion_values.start_motion_deg,
+            group=CONST.WAIT.ROTATION_READY_FOR_DC,
+        )
+
+        yield from setup_zebra_for_rotation(
+            composite.zebra,
+            composite.sample_shutter,
+            start_angle=motion_values.start_scan_deg,
+            scan_width=motion_values.scan_width_deg,
+            direction=motion_values.direction,
+            shutter_opening_deg=motion_values.shutter_opening_deg,
+            shutter_opening_s=motion_values.shutter_time_s,
+            group="setup_zebra",
+        )
+
+        yield from setup_sample_environment(
+            composite.aperture_scatterguard,
+            params.selected_aperture,
+            composite.backlight,
+            group=CONST.WAIT.ROTATION_READY_FOR_DC,
+        )
+
+        LOGGER.info("Wait for any previous moves...")
+        # wait for all the setup tasks at once
+        yield from bps.wait(CONST.WAIT.ROTATION_READY_FOR_DC)
+        yield from bps.wait(CONST.WAIT.MOVE_GONIO_TO_START)
+
+        # get some information for the ispyb deposition and trigger the callback
+        yield from read_hardware_for_zocalo(composite.eiger)
+
+        yield from read_hardware_pre_collection(
+            composite.undulator,
+            composite.synchrotron,
+            composite.s4_slit_gaps,
+            composite.robot,
+            composite.smargon,
+        )
+
+        # Get ready for the actual scan
+        yield from bps.abs_set(
+            axis.velocity, motion_values.speed_for_rotation_deg_s, wait=True
+        )
+
+        yield from bps.wait("setup_zebra")
+        yield from arm_zebra(composite.zebra)
+
+        # Check topup gate
+        yield from check_topup_and_wait_if_necessary(
+            composite.synchrotron,
+            motion_values.total_exposure_s,
+            ops_time=10.0,  # Additional time to account for rotation, is s
+        )  # See #https://github.com/DiamondLightSource/hyperion/issues/932
+
+        LOGGER.info("Executing rotation scan")
+        yield from bps.rel_set(axis, motion_values.distance_to_move_deg, wait=True)
+
+        yield from read_hardware_during_collection(
+            composite.aperture_scatterguard,
+            composite.attenuator,
+            composite.flux,
+            composite.dcm,
+            composite.eiger,
+        )
+
+    yield from _rotation_scan_plan(motion_values, composite)
+
+
+def _cleanup_plan(composite: RotationScanComposite, **kwargs):
+    LOGGER.info("Cleaning up after rotation scan")
+    max_vel = yield from bps.rd(composite.smargon.omega.max_velocity)
+    yield from cleanup_sample_environment(composite.detector_motion, group="cleanup")
+    yield from bps.abs_set(composite.smargon.omega.velocity, max_vel, group="cleanup")
+    yield from tidy_up_zebra_after_rotation_scan(
+        composite.zebra, composite.sample_shutter, group="cleanup", wait=False
+    )
+    yield from bps.wait("cleanup")
+
+
+def _move_and_rotation(
+    composite: RotationScanComposite,
+    params: RotationScan,
+    oav_params: OAVParameters,
+):
+    motor_time_to_speed = yield from bps.rd(composite.smargon.omega.acceleration_time)
+    max_vel = yield from bps.rd(composite.smargon.omega.max_velocity)
+    motion_values = calculate_motion_profile(params, motor_time_to_speed, max_vel)
+
+    def _div_by_1000_if_not_none(num: float | None):
+        return num / 1000 if num else num
+
+    LOGGER.info("moving to position (if specified)")
+    yield from move_x_y_z(
+        composite.smargon,
+        _div_by_1000_if_not_none(params.x_start_um),
+        _div_by_1000_if_not_none(params.y_start_um),
+        _div_by_1000_if_not_none(params.z_start_um),
+        group=CONST.WAIT.MOVE_GONIO_TO_START,
+    )
+    yield from move_phi_chi_omega(
+        composite.smargon,
+        params.phi_start_deg,
+        params.chi_start_deg,
+        group=CONST.WAIT.MOVE_GONIO_TO_START,
+    )
+    if params.take_snapshots:
+        yield from bps.wait(CONST.WAIT.MOVE_GONIO_TO_START)
+        yield from setup_beamline_for_OAV(
+            composite.smargon, composite.backlight, composite.aperture_scatterguard
+        )
+        yield from oav_snapshot_plan(composite, params, oav_params)
+    yield from rotation_scan_plan(
+        composite,
+        params,
+        motion_values,
+    )
+
+
+def rotation_scan(
+    composite: RotationScanComposite,
+    parameters: RotationScan,
+    oav_params: OAVParameters | None = None,
+) -> MsgGenerator:
+    if not oav_params:
+        oav_params = OAVParameters(context="xrayCentring")
+
+    @bpp.set_run_key_decorator("rotation_scan")
+    @bpp.run_decorator(  # attach experiment metadata to the start document
+        md={
+            "subplan_name": CONST.PLAN.ROTATION_OUTER,
+            CONST.TRIGGER.ZOCALO: CONST.PLAN.ROTATION_MAIN,
+            "zocalo_environment": parameters.zocalo_environment,
+            "hyperion_parameters": parameters.model_dump_json(),
+            "activate_callbacks": [
+                "RotationISPyBCallback",
+                "RotationNexusFileCallback",
+            ],
+        }
+    )
+    @transmission_and_xbpm_feedback_for_collection_decorator(
+        composite.xbpm_feedback,
+        composite.attenuator,
+        parameters.transmission_frac,
+    )
+    def rotation_scan_plan_with_stage_and_cleanup(
+        params: RotationScan,
+    ):
+        eiger: EigerDetector = composite.eiger
+        eiger.set_detector_parameters(params.detector_params)
+
+        @bpp.finalize_decorator(lambda: _cleanup_plan(composite))
+        def rotation_with_cleanup_and_stage(params: RotationScan):
+            yield from _move_and_rotation(composite, params, oav_params)
+
+        LOGGER.info("setting up and staging eiger...")
+        yield from start_preparing_data_collection_then_do_plan(
+            eiger,
+            composite.detector_motion,
+            params.detector_distance_mm,
+            rotation_with_cleanup_and_stage(params),
+            group=CONST.WAIT.ROTATION_READY_FOR_DC,
+        )
+        yield from bps.unstage(eiger)
+
+    yield from rotation_scan_plan_with_stage_and_cleanup(parameters)
+
+
+def multi_rotation_scan(
+    composite: RotationScanComposite,
+    parameters: MultiRotationScan,
+    oav_params: OAVParameters | None = None,
+) -> MsgGenerator:
+    if not oav_params:
+        oav_params = OAVParameters(context="xrayCentring")
+    eiger: EigerDetector = composite.eiger
+    eiger.set_detector_parameters(parameters.detector_params)
+
+    @bpp.set_run_key_decorator("multi_rotation_scan")
+    @bpp.run_decorator(
+        md={
+            "subplan_name": CONST.PLAN.ROTATION_MULTI,
+            "full_num_of_images": parameters.num_images,
+            "meta_data_run_number": parameters.detector_params.run_number,
+            "activate_callbacks": [
+                "RotationISPyBCallback",
+                "RotationNexusFileCallback",
+            ],
+        }
+    )
+    @bpp.stage_decorator([eiger])
+    @bpp.finalize_decorator(lambda: _cleanup_plan(composite))
+    def _multi_rotation_scan():
+        for single_scan in parameters.single_rotation_scans:
+
+            @bpp.set_run_key_decorator("rotation_scan")
+            @bpp.run_decorator(  # attach experiment metadata to the start document
+                md={
+                    "subplan_name": CONST.PLAN.ROTATION_OUTER,
+                    CONST.TRIGGER.ZOCALO: CONST.PLAN.ROTATION_MAIN,
+                    "hyperion_parameters": single_scan.model_dump_json(),
+                }
+            )
+            def rotation_scan_core(
+                params: RotationScan,
+            ):
+                yield from _move_and_rotation(composite, params, oav_params)
+
+            yield from rotation_scan_core(single_scan)
+
+    LOGGER.info("setting up and staging eiger...")
+    yield from start_preparing_data_collection_then_do_plan(
+        eiger,
+        composite.detector_motion,
+        parameters.detector_distance_mm,
+        _multi_rotation_scan(),
+        group=CONST.WAIT.ROTATION_READY_FOR_DC,
+    )

mx_bluesky/hyperion/experiment_plans/set_energy_plan.py

@@ -0,0 +1,60 @@
+"""Plan that comprises:
+* Disable feedback
+* Set undulator energy to the requested amount
+* Adjust DCM and mirrors for the new energy
+* reenable feedback
+"""
+
+import dataclasses
+
+from bluesky import plan_stubs as bps
+from dodal.devices.attenuator import Attenuator
+from dodal.devices.dcm import DCM
+from dodal.devices.focusing_mirror import FocusingMirrorWithStripes, VFMMirrorVoltages
+from dodal.devices.undulator_dcm import UndulatorDCM
+from dodal.devices.xbpm_feedback import XBPMFeedback
+
+from mx_bluesky.hyperion.device_setup_plans import dcm_pitch_roll_mirror_adjuster
+from mx_bluesky.hyperion.device_setup_plans.xbpm_feedback import (
+    transmission_and_xbpm_feedback_for_collection_wrapper,
+)
+
+DESIRED_TRANSMISSION_FRACTION = 0.1
+
+UNDULATOR_GROUP = "UNDULATOR_GROUP"
+
+
+@dataclasses.dataclass
+class SetEnergyComposite:
+    vfm: FocusingMirrorWithStripes
+    vfm_mirror_voltages: VFMMirrorVoltages
+    dcm: DCM
+    undulator_dcm: UndulatorDCM
+    xbpm_feedback: XBPMFeedback
+    attenuator: Attenuator
+
+
+def _set_energy_plan(
+    energy_kev,
+    composite: SetEnergyComposite,
+):
+    yield from bps.abs_set(composite.undulator_dcm, energy_kev, group=UNDULATOR_GROUP)
+    yield from dcm_pitch_roll_mirror_adjuster.adjust_dcm_pitch_roll_vfm_from_lut(
+        composite.undulator_dcm,
+        composite.vfm,
+        composite.vfm_mirror_voltages,
+        energy_kev,
+    )
+    yield from bps.wait(group=UNDULATOR_GROUP)
+
+
+def set_energy_plan(
+    energy_kev,
+    composite: SetEnergyComposite,
+):
+    yield from transmission_and_xbpm_feedback_for_collection_wrapper(
+        _set_energy_plan(energy_kev, composite),
+        composite.xbpm_feedback,
+        composite.attenuator,
+        DESIRED_TRANSMISSION_FRACTION,
+    )

mx_bluesky/hyperion/external_interaction/__init__.py

@@ -0,0 +1,9 @@
+"""Provides external interaction functionality to Hyperion, including Nexus file
+creation, ISPyB deposition, and Zocalo processing submissions.
+
+Functionality from this module can/should be used through the callback functions in
+external_interaction.callbacks which can subscribe to the Bluesky RunEngine and handle
+these various interactions based on the documents emitted by the RunEngine during the
+execution of the experimental plan. It's not recommended to use the interaction classes
+here directly in plans except through the use of such callbacks.
+"""

mx_bluesky/hyperion/external_interaction/callbacks/__init__.py

@@ -0,0 +1,10 @@
+"""Callbacks which can be subscribed to by the Bluesky RunEngine in order to perform
+external interactions in response to the 'documents' emitted when events occur in the
+execution of an experimental plan.
+
+Callbacks used for the Hyperion fast grid scan are prefixed with 'FGS'.
+"""
+
+from .__main__ import main
+
+__all__ = ["main"]

mx_bluesky/hyperion/external_interaction/callbacks/__main__.py

@@ -0,0 +1,148 @@
+import logging
+from collections.abc import Callable, Sequence
+from threading import Thread
+from time import sleep
+
+from bluesky.callbacks.zmq import Proxy, RemoteDispatcher
+from dodal.log import LOGGER as dodal_logger
+from dodal.log import set_up_all_logging_handlers
+
+from mx_bluesky.hyperion.external_interaction.callbacks.log_uid_tag_callback import (
+    LogUidTaggingCallback,
+)
+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,
+)
+from mx_bluesky.hyperion.log import (
+    ISPYB_LOGGER,
+    NEXUS_LOGGER,
+    _get_logging_dir,
+    tag_filter,
+)
+from mx_bluesky.hyperion.parameters.cli import parse_callback_dev_mode_arg
+from mx_bluesky.hyperion.parameters.constants import CONST
+
+LIVENESS_POLL_SECONDS = 1
+ERROR_LOG_BUFFER_LINES = 5000
+
+
+def setup_callbacks():
+    zocalo = ZocaloCallback()
+    return [
+        GridscanNexusFileCallback(),
+        GridscanISPyBCallback(emit=zocalo),
+        RotationNexusFileCallback(),
+        RotationISPyBCallback(emit=zocalo),
+        LogUidTaggingCallback(),
+        RobotLoadISPyBCallback(),
+    ]
+
+
+def setup_logging(dev_mode: bool):
+    for logger, filename in [
+        (ISPYB_LOGGER, "hyperion_ispyb_callback.log"),
+        (NEXUS_LOGGER, "hyperion_nexus_callback.log"),
+    ]:
+        if logger.handlers == []:
+            handlers = set_up_all_logging_handlers(
+                logger,
+                _get_logging_dir(),
+                filename,
+                dev_mode,
+                error_log_buffer_lines=ERROR_LOG_BUFFER_LINES,
+                graylog_port=CONST.GRAYLOG_PORT,
+            )
+            handlers["graylog_handler"].addFilter(tag_filter)
+    log_info(f"Loggers initialised with dev_mode={dev_mode}")
+    nexgen_logger = logging.getLogger("nexgen")
+    nexgen_logger.parent = NEXUS_LOGGER
+    dodal_logger.parent = ISPYB_LOGGER
+    log_debug("nexgen logger added to nexus logger")
+
+
+def setup_threads():
+    proxy = Proxy(*CONST.CALLBACK_0MQ_PROXY_PORTS)
+    dispatcher = RemoteDispatcher(f"localhost:{CONST.CALLBACK_0MQ_PROXY_PORTS[1]}")
+    log_debug("Created proxy and dispatcher objects")
+
+    def start_proxy():
+        proxy.start()
+
+    def start_dispatcher(callbacks: list[Callable]):
+        [dispatcher.subscribe(cb) for cb in callbacks]
+        dispatcher.start()
+
+    return proxy, dispatcher, start_proxy, start_dispatcher
+
+
+def log_info(msg, *args, **kwargs):
+    ISPYB_LOGGER.info(msg, *args, **kwargs)
+    NEXUS_LOGGER.info(msg, *args, **kwargs)
+
+
+def log_debug(msg, *args, **kwargs):
+    ISPYB_LOGGER.debug(msg, *args, **kwargs)
+    NEXUS_LOGGER.debug(msg, *args, **kwargs)
+
+
+def wait_for_threads_forever(threads: Sequence[Thread]):
+    alive = [t.is_alive() for t in threads]
+    try:
+        log_debug("Trying to wait forever on callback and dispatcher threads")
+        while all(alive):
+            sleep(LIVENESS_POLL_SECONDS)
+            alive = [t.is_alive() for t in threads]
+    except KeyboardInterrupt:
+        log_info("Main thread received interrupt - exiting.")
+    else:
+        log_info("Proxy or dispatcher thread ended - exiting.")
+
+
+class HyperionCallbackRunner:
+    """Runs Nexus, ISPyB and Zocalo callbacks in their own process."""
+
+    def __init__(self, dev_mode) -> None:
+        setup_logging(dev_mode)
+        log_info("Hyperion callback process started.")
+
+        self.callbacks = setup_callbacks()
+        self.proxy, self.dispatcher, start_proxy, start_dispatcher = setup_threads()
+        log_info("Created 0MQ proxy and local RemoteDispatcher.")
+
+        self.proxy_thread = Thread(target=start_proxy, daemon=True)
+        self.dispatcher_thread = Thread(
+            target=start_dispatcher, args=[self.callbacks], daemon=True
+        )
+
+    def start(self):
+        log_info(f"Launching threads, with callbacks: {self.callbacks}")
+        self.proxy_thread.start()
+        self.dispatcher_thread.start()
+        log_info("Proxy and dispatcher thread launched.")
+        wait_for_threads_forever([self.proxy_thread, self.dispatcher_thread])
+
+
+def main(dev_mode=False) -> None:
+    dev_mode = dev_mode or parse_callback_dev_mode_arg()
+    print(f"In dev mode: {dev_mode}")
+    runner = HyperionCallbackRunner(dev_mode)
+    runner.start()
+
+
+if __name__ == "__main__":
+    main()

mx_bluesky/hyperion/external_interaction/callbacks/aperture_change_callback.py

@@ -0,0 +1,22 @@
+from bluesky.callbacks import CallbackBase
+from event_model.documents.run_start import RunStart
+
+from mx_bluesky.hyperion.log import LOGGER
+
+from .logging_callback import format_doc_for_log
+
+
+class ApertureChangeCallback(CallbackBase):
+    """A callback that's used to send the selected aperture back to GDA"""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.last_selected_aperture: str = "NONE"
+
+    def start(self, doc: RunStart):
+        if doc.get("subplan_name") == "change_aperture":
+            LOGGER.debug(f"START: {format_doc_for_log(doc)}")
+            ap_size = doc.get("aperture_size")
+            assert isinstance(ap_size, str)
+            LOGGER.info(f"Updating most recent in-plan aperture change to {ap_size}.")
+            self.last_selected_aperture = ap_size