opentrons 8.7.0a9__py3-none-any.whl → 8.8.0a7__py3-none-any.whl

opentrons/protocol_engine/errors/exceptions.py

@@ -413,6 +413,36 @@ class WellDoesNotExistError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class NoTaskFoundError(ProtocolEngineError):
+    """Raised when referencing a task that does not exist.
+
+    This error could be raised if a protocol references a task before it
+    has been created.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a NoTaskFoundError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class TaskFailedError(ProtocolEngineError):
+    """Raised when waiting on a task that failed."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a TaskFailedError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class PipetteNotLoadedError(ProtocolEngineError):
     """Raised when referencing a pipette that has not been loaded."""
 
@@ -825,6 +855,19 @@ class InvalidTargetTemperatureError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class InvalidRampRateError(ProtocolEngineError):
+    """Raised when attempting to set an invalid ramp rate."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a InvalidRampRateError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class InvalidBlockVolumeError(ProtocolEngineError):
     """Raised when attempting to set an invalid block max volume."""
 
@@ -1248,6 +1291,19 @@ class StorageLimitReachedError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, detail, wrapping)
 
 
+class FileNameInvalidError(ProtocolEngineError):
+    """Raised to indicate that a file cannot be saved with a given name."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, str]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an FileNameInvalidError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, detail, wrapping)
+
+
 class LiquidClassDoesNotExistError(ProtocolEngineError):
     """Raised when referencing a liquid class that has not been loaded."""
 
@@ -1296,6 +1352,18 @@ class FlexStackerLabwarePoolNotYetDefinedError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class LabwarePoolNotCompatibleWithModuleError(ProtocolEngineError):
+    """Raised when attempting to use a labware pool that is incompatible with a module."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class InvalidLabwarePositionError(ProtocolEngineError):
     """Raised when a labware position is internally invalid."""
 
@@ -1306,3 +1374,54 @@ class InvalidLabwarePositionError(ProtocolEngineError):
         wrapping: Optional[Sequence[EnumeratedError]] = None,
     ) -> None:
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class InvalidModuleOrientation(ProtocolEngineError):
+    """Raised when a module orientation is invalid for a slot id."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class CameraCaptureError(ProtocolEngineError):
+    """Raised when an Camera Capture attempt fails."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a CameraCaptureError."""
+        super().__init__(ErrorCodes.CAMERA_ERROR, message, details, wrapping)
+
+
+class CameraDisabledError(ProtocolEngineError):
+    """Raised when a Camera was referenced while cameras are disabled."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a CameraDisabledError."""
+        super().__init__(ErrorCodes.CAMERA_ERROR, message, details, wrapping)
+
+
+class CameraSettingsInvalidError(ProtocolEngineError):
+    """Raised when a Camera was given invalid settings."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a CameraSettingsInvalidError."""
+        super().__init__(ErrorCodes.CAMERA_ERROR, message, details, wrapping)

opentrons/protocol_engine/execution/__init__.py

@@ -21,7 +21,9 @@ from .run_control import RunControlHandler
 from .hardware_stopper import HardwareStopper
 from .door_watcher import DoorWatcher
 from .status_bar import StatusBarHandler
+from .task_handler import TaskHandler
 from ..resources.file_provider import FileProvider
+from ..resources.camera_provider import CameraProvider
 
 # .thermocycler_movement_flagger omitted from package's public interface.
 
@@ -46,5 +48,7 @@ __all__ = [
     "DoorWatcher",
     "RailLightsHandler",
     "StatusBarHandler",
+    "TaskHandler",
     "FileProvider",
+    "CameraProvider",
 ]

opentrons/protocol_engine/execution/command_executor.py

@@ -10,12 +10,15 @@ from opentrons_shared_data.errors.exceptions import (
     EnumeratedError,
     PythonException,
 )
+from opentrons_shared_data.data_files import MimeType
 
 from opentrons.protocol_engine.commands.command import SuccessData
 from opentrons.protocol_engine.notes import make_error_recovery_debug_note
 
 from ..state.state import StateStore
-from ..resources import ModelUtils, FileProvider
+from ..resources import ModelUtils, FileProvider, CameraProvider
+from ..resources.file_provider import ImageCaptureCmdFileNameMetadata
+from ..resources.camera_provider import ImageParameters
 from ..commands import CommandStatus
 from ..actions import (
     ActionDispatcher,
@@ -35,6 +38,8 @@ from .tip_handler import TipHandler
 from .run_control import RunControlHandler
 from .rail_lights import RailLightsHandler
 from .status_bar import StatusBarHandler
+from .task_handler import TaskHandler
+from ..commands import Command
 
 
 log = getLogger(__name__)
@@ -74,6 +79,7 @@ class CommandExecutor:
         self,
         hardware_api: HardwareControlAPI,
         file_provider: FileProvider,
+        camera_provider: CameraProvider,
         state_store: StateStore,
         action_dispatcher: ActionDispatcher,
         equipment: EquipmentHandler,
@@ -85,12 +91,14 @@ class CommandExecutor:
         run_control: RunControlHandler,
         rail_lights: RailLightsHandler,
         status_bar: StatusBarHandler,
+        task_handler: TaskHandler,
         model_utils: Optional[ModelUtils] = None,
         command_note_tracker_provider: Optional[CommandNoteTrackerProvider] = None,
     ) -> None:
         """Initialize the CommandExecutor with access to its dependencies."""
         self._hardware_api = hardware_api
         self._file_provider = file_provider
+        self._camera_provider = camera_provider
         self._state_store = state_store
         self._action_dispatcher = action_dispatcher
         self._equipment = equipment
@@ -106,6 +114,7 @@ class CommandExecutor:
         self._command_note_tracker_provider = (
             command_note_tracker_provider or _NoteTracker
         )
+        self._task_handler = task_handler
 
     async def execute(self, command_id: str) -> None:
         """Run a given command's execution procedure.
@@ -120,6 +129,7 @@ class CommandExecutor:
             state_view=self._state_store,
             hardware_api=self._hardware_api,
             file_provider=self._file_provider,
+            camera_provider=self._camera_provider,
             equipment=self._equipment,
             movement=self._movement,
             gantry_mover=self._gantry_mover,
@@ -131,6 +141,7 @@ class CommandExecutor:
             model_utils=self._model_utils,
             status_bar=self._status_bar,
             command_note_adder=note_tracker,
+            task_handler=self._task_handler,
         )
 
         started_at = self._model_utils.get_timestamp()
@@ -144,6 +155,7 @@ class CommandExecutor:
         log.debug(
             f"Executing {running_command.id}, {running_command.commandType}, {running_command.params}"
         )
+        error_occurred = False
         try:
             result = await command_impl.execute(
                 running_command.params  # type: ignore[arg-type]
@@ -167,6 +179,7 @@ class CommandExecutor:
                 running_command,
                 None,
             )
+
             note_tracker(make_error_recovery_debug_note(error_recovery_type))
             self._action_dispatcher.dispatch(
                 FailCommandAction(
@@ -179,6 +192,7 @@ class CommandExecutor:
                     type=error_recovery_type,
                 )
             )
+            error_occurred = True
 
         else:
             if isinstance(result, SuccessData):
@@ -214,3 +228,50 @@ class CommandExecutor:
                         type=error_recovery_type,
                     )
                 )
+                error_occurred = True
+        finally:
+            # Handle error image capture if appropriate
+            if error_occurred:
+                await self.capture_error_image(running_command)
+
+    def cancel_tasks(self, message: str | None = None) -> None:
+        """Cancel all concurrent tasks."""
+        self._task_handler.cancel_all(message=message)
+
+    async def capture_error_image(self, running_command: Command) -> None:
+        """Capture an image of an error event."""
+        try:
+            camera_enablement = self._state_store.camera.get_enablement_settings()
+            if camera_enablement is None:
+                # Utilize the global camera settings
+                camera_enablement = await self._camera_provider.get_camera_settings()
+            # Only capture photos of errors if the setting to do so is enabled
+            if (
+                camera_enablement.cameraEnabled
+                and camera_enablement.errorRecoveryEnabled
+            ):
+                # todo(chb, 2025-10-25): Eventually we will need to pass in client provided global settings here
+                image_data = await self._camera_provider.capture_image(
+                    self._state_store.config.robot_type, ImageParameters()
+                )
+                commands = self._state_store.commands.get_all()
+                prev_command_id = commands[-2].id if len(commands) > 1 else ""
+                if image_data:
+                    write_result = await self._file_provider.write_file(
+                        data=image_data,
+                        mime_type=MimeType.IMAGE_JPEG,
+                        command_metadata=ImageCaptureCmdFileNameMetadata(
+                            command_id=running_command.id,
+                            prev_command_id=prev_command_id,
+                            step_number=len(commands),
+                            base_filename=None,
+                            command_timestamp=running_command.createdAt,
+                        ),
+                    )
+                    log.info(
+                        f"Image captured of error event with file name: {write_result.name}"
+                    )
+        except Exception as e:
+            log.info(
+                f"Failed to capture image of error with the following exception: {e}"
+            )

opentrons/protocol_engine/execution/create_queue_worker.py

@@ -6,7 +6,7 @@ from opentrons.protocol_engine.execution.rail_lights import RailLightsHandler
 
 from ..state.state import StateStore
 from ..actions import ActionDispatcher
-from ..resources import FileProvider
+from ..resources import FileProvider, CameraProvider
 from .equipment import EquipmentHandler
 from .movement import MovementHandler
 from .gantry_mover import create_gantry_mover
@@ -17,11 +17,13 @@ from .run_control import RunControlHandler
 from .command_executor import CommandExecutor
 from .queue_worker import QueueWorker
 from .status_bar import StatusBarHandler
+from .task_handler import TaskHandler
 
 
 def create_queue_worker(
     hardware_api: HardwareControlAPI,
     file_provider: FileProvider,
+    camera_provider: CameraProvider,
     state_store: StateStore,
     action_dispatcher: ActionDispatcher,
     command_generator: Callable[[], AsyncGenerator[str, None]],
@@ -31,6 +33,7 @@ def create_queue_worker(
     Arguments:
         hardware_api: Hardware control API to pass down to dependencies.
         file_provider: Provides access to robot server file writing procedures for protocol output.
+        camera_provider: Provides access to camera interface with image capture and callbacks.
         state_store: StateStore to pass down to dependencies.
         action_dispatcher: ActionDispatcher to pass down to dependencies.
         error_recovery_policy: ErrorRecoveryPolicy to pass down to dependencies.
@@ -76,12 +79,15 @@ def create_queue_worker(
     rail_lights_handler = RailLightsHandler(
         hardware_api=hardware_api,
     )
-
+    task_handler = TaskHandler(
+        state_store=state_store, action_dispatcher=action_dispatcher
+    )
     status_bar_handler = StatusBarHandler(hardware_api=hardware_api)
 
     command_executor = CommandExecutor(
         hardware_api=hardware_api,
         file_provider=file_provider,
+        camera_provider=camera_provider,
         state_store=state_store,
         action_dispatcher=action_dispatcher,
         equipment=equipment_handler,
@@ -93,6 +99,7 @@ def create_queue_worker(
         run_control=run_control_handler,
         rail_lights=rail_lights_handler,
         status_bar=status_bar_handler,
+        task_handler=task_handler,
     )
 
     return QueueWorker(

opentrons/protocol_engine/execution/labware_movement.py

@@ -31,6 +31,8 @@ from ..types import (
     OnLabwareLocation,
     LabwareLocation,
     OnDeckLabwareLocation,
+    GripperMoveType,
+    AccessibleByGripperLocation,
 )
 
 if TYPE_CHECKING:
@@ -94,7 +96,7 @@ class LabwareMovementHandler:
         *,
         labware_id: str,
         current_location: OnDeckLabwareLocation,
-        new_location: OnDeckLabwareLocation,
+        new_location: AccessibleByGripperLocation,
         user_pick_up_offset: Point,
         user_drop_offset: Point,
         post_drop_slide_offset: Optional[Point],
@@ -107,7 +109,7 @@ class LabwareMovementHandler:
         *,
         labware_definition: LabwareDefinition,
         current_location: OnDeckLabwareLocation,
-        new_location: OnDeckLabwareLocation,
+        new_location: AccessibleByGripperLocation,
         user_pick_up_offset: Point,
         user_drop_offset: Point,
         post_drop_slide_offset: Optional[Point],
@@ -121,7 +123,7 @@ class LabwareMovementHandler:
         labware_id: str | None = None,
         labware_definition: LabwareDefinition | None = None,
         current_location: OnDeckLabwareLocation,
-        new_location: OnDeckLabwareLocation,
+        new_location: AccessibleByGripperLocation,
         user_pick_up_offset: Point,
         user_drop_offset: Point,
         post_drop_slide_offset: Optional[Point],
@@ -141,10 +143,16 @@ class LabwareMovementHandler:
             labware_definition = self._state_store.labware.get_definition(labware_id)
 
         from_labware_center = self._state_store.geometry.get_labware_grip_point(
-            labware_definition=labware_definition, location=current_location
+            labware_definition=labware_definition,
+            location=current_location,
+            move_type=GripperMoveType.PICK_UP_LABWARE,
+            user_additional_offset=user_pick_up_offset,
         )
         to_labware_center = self._state_store.geometry.get_labware_grip_point(
-            labware_definition=labware_definition, location=new_location
+            labware_definition=labware_definition,
+            location=new_location,
+            move_type=GripperMoveType.DROP_LABWARE,
+            user_additional_offset=user_drop_offset,
         )
 
         if use_virtual_gripper:
@@ -193,20 +201,10 @@ class LabwareMovementHandler:
         async with self._thermocycler_plate_lifter.lift_plate_for_labware_movement(
             labware_location=current_location
         ):
-            final_offsets = (
-                self._state_store.geometry.get_final_labware_movement_offset_vectors(
-                    from_location=current_location,
-                    to_location=new_location,
-                    additional_pick_up_offset=user_pick_up_offset,
-                    additional_drop_offset=user_drop_offset,
-                    current_labware=labware_definition,
-                )
-            )
             movement_waypoints = get_gripper_labware_movement_waypoints(
                 from_labware_center=from_labware_center,
                 to_labware_center=to_labware_center,
                 gripper_home_z=gripper_homed_position.z,
-                offset_data=final_offsets,
                 post_drop_slide_offset=post_drop_slide_offset,
                 gripper_home_z_offset=gripper_z_offset,
             )

opentrons/protocol_engine/execution/movement.py

@@ -83,6 +83,7 @@ class MovementHandler:
         minimum_z_height: Optional[float] = None,
         speed: Optional[float] = None,
         operation_volume: Optional[float] = None,
+        offset_pipette_for_reservoir_subwells: bool = False,
     ) -> Point:
         """Move to a specific well."""
         self._state_store.geometry.raise_if_labware_inaccessible_by_pipette(
@@ -143,6 +144,7 @@ class MovementHandler:
             force_direct=force_direct,
             minimum_z_height=minimum_z_height,
             operation_volume=operation_volume,
+            offset_pipette_for_reservoir_subwells=offset_pipette_for_reservoir_subwells,
         )
 
         speed = self._state_store.pipettes.get_movement_speed(

opentrons/protocol_engine/execution/pipetting.py

@@ -13,13 +13,13 @@ from ..errors.exceptions import (
     InvalidAspirateVolumeError,
     InvalidPushOutVolumeError,
     InvalidDispenseVolumeError,
-    InvalidLiquidHeightFound,
 )
 from opentrons.protocol_engine.types import WellLocation
 from opentrons.protocol_engine.types.liquid_level_detection import (
     SimulatedProbeResult,
     LiquidTrackingType,
 )
+from opentrons.types import Point
 
 # 1e-9 µL (1 femtoliter!) is a good value because:
 # * It's large relative to rounding errors that occur in practice in protocols. For
@@ -61,7 +61,9 @@ class PipettingHandler(TypingProtocol):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         command_note_adder: CommandNoteAdder,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Set flow-rate and aspirate while tracking."""
 
@@ -72,8 +74,10 @@ class PipettingHandler(TypingProtocol):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         push_out: Optional[float],
         is_full_dispense: bool = False,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Set flow-rate and dispense while tracking."""
 
@@ -184,7 +188,9 @@ class HardwarePipettingHandler(PipettingHandler):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         command_note_adder: CommandNoteAdder,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Set flow-rate and aspirate.
 
@@ -195,22 +201,13 @@ class HardwarePipettingHandler(PipettingHandler):
         hw_pipette, adjusted_volume = self.get_hw_aspirate_params(
             pipette_id, volume, command_note_adder
         )
-        aspirate_z_distance = self._state_view.geometry.get_liquid_handling_z_change(
-            labware_id=labware_id,
-            well_name=well_name,
-            operation_volume=volume * -1,
-            pipette_id=pipette_id,
-        )
-        if isinstance(aspirate_z_distance, SimulatedProbeResult):
-            raise InvalidLiquidHeightFound(
-                "Aspirate distance must be a float in Hardware pipetting handler."
-            )
+
         with self._set_flow_rate(pipette=hw_pipette, aspirate_flow_rate=flow_rate):
             await self._hardware_api.aspirate_while_tracking(
                 mount=hw_pipette.mount,
-                z_distance=aspirate_z_distance,
-                flow_rate=flow_rate,
+                end_point=end_point,
                 volume=adjusted_volume,
+                movement_delay=movement_delay,
             )
         return adjusted_volume
 
@@ -221,8 +218,10 @@ class HardwarePipettingHandler(PipettingHandler):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         push_out: Optional[float],
         is_full_dispense: bool = False,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Set flow-rate and dispense.
 
@@ -231,24 +230,15 @@ class HardwarePipettingHandler(PipettingHandler):
         """
         # get mount and config data from state and hardware controller
         hw_pipette, adjusted_volume = self.get_hw_dispense_params(pipette_id, volume)
-        dispense_z_distance = self._state_view.geometry.get_liquid_handling_z_change(
-            labware_id=labware_id,
-            well_name=well_name,
-            operation_volume=volume,
-            pipette_id=pipette_id,
-        )
-        if isinstance(dispense_z_distance, SimulatedProbeResult):
-            raise InvalidLiquidHeightFound(
-                "Dispense distance must be a float in Hardware pipetting handler."
-            )
+
         with self._set_flow_rate(pipette=hw_pipette, dispense_flow_rate=flow_rate):
             await self._hardware_api.dispense_while_tracking(
                 mount=hw_pipette.mount,
-                z_distance=dispense_z_distance,
-                flow_rate=flow_rate,
+                end_point=end_point,
                 volume=adjusted_volume,
                 push_out=push_out,
                 is_full_dispense=is_full_dispense,
+                movement_delay=movement_delay,
             )
         return adjusted_volume
 
@@ -476,7 +466,9 @@ class VirtualPipettingHandler(PipettingHandler):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         command_note_adder: CommandNoteAdder,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Virtually aspirate (no-op)."""
         self._validate_tip_attached(pipette_id=pipette_id, command_name="aspirate")
@@ -495,8 +487,10 @@ class VirtualPipettingHandler(PipettingHandler):
         well_name: str,
         volume: float,
         flow_rate: float,
+        end_point: Point,
         push_out: Optional[float],
         is_full_dispense: bool = False,
+        movement_delay: Optional[float] = None,
     ) -> float:
         """Virtually dispense (no-op)."""
         # TODO (tz, 8-23-23): add a check for push_out not larger that the max volume allowed when working on this https://opentrons.atlassian.net/browse/RSS-329

opentrons/protocol_engine/execution/queue_worker.py

@@ -51,6 +51,7 @@ class QueueWorker:
         """
         if self._worker_task:
             self._worker_task.cancel()
+            self._command_executor.cancel_tasks("Engine cancelled")
 
     async def join(self) -> None:
         """Wait for the worker to finish, propagating any errors."""
@@ -65,7 +66,10 @@ class QueueWorker:
                 pass
             except Exception as e:
                 log.error("Unhandled exception in QueueWorker job", exc_info=e)
+                self._command_executor.cancel_tasks("Engine failed")
                 raise e
+            else:
+                self._command_executor.cancel_tasks("Engine commands complete")
 
     async def _run_commands(self) -> None:
         async for command_id in self._command_generator():

opentrons/protocol_engine/execution/run_control.py

@@ -31,3 +31,11 @@ class RunControlHandler:
         """Delay protocol execution for a duration."""
         if not self._state_store.config.ignore_pause:
             await asyncio.sleep(seconds)
+
+    async def wait_for_tasks(self, tasks: list[str]) -> None:
+        """Wait for concurrent tasks to complete."""
+        await self._state_store.wait_for(
+            condition=lambda: self._state_store.tasks.all_tasks_finished_or_any_task_failed(
+                task_ids=tasks
+            )
+        )