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

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,
@@ -36,6 +39,7 @@ 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__)
@@ -75,6 +79,7 @@ class CommandExecutor:
         self,
         hardware_api: HardwareControlAPI,
         file_provider: FileProvider,
+        camera_provider: CameraProvider,
         state_store: StateStore,
         action_dispatcher: ActionDispatcher,
         equipment: EquipmentHandler,
@@ -93,6 +98,7 @@ class CommandExecutor:
         """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
@@ -123,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,
@@ -148,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]
@@ -171,6 +179,7 @@ class CommandExecutor:
                 running_command,
                 None,
             )
+
             note_tracker(make_error_recovery_debug_note(error_recovery_type))
             self._action_dispatcher.dispatch(
                 FailCommandAction(
@@ -183,6 +192,7 @@ class CommandExecutor:
                     type=error_recovery_type,
                 )
             )
+            error_occurred = True
 
         else:
             if isinstance(result, SuccessData):
@@ -218,7 +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
@@ -23,6 +23,7 @@ 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]],
@@ -32,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.
@@ -85,6 +87,7 @@ def create_queue_worker(
     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,

opentrons/protocol_engine/execution/labware_movement.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Optional, TYPE_CHECKING, overload
 
-from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition, Quirks
 
 from opentrons.types import Point
 
@@ -32,6 +32,7 @@ from ..types import (
     LabwareLocation,
     OnDeckLabwareLocation,
     GripperMoveType,
+    AccessibleByGripperLocation,
 )
 
 if TYPE_CHECKING:
@@ -95,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],
@@ -108,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],
@@ -122,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],
@@ -235,6 +236,13 @@ class LabwareMovementHandler:
                             labware_definition=labware_definition
                         )
 
+                        disable_geometry_grip_check = False
+                        if labware_definition.parameters.quirks is not None:
+                            disable_geometry_grip_check = (
+                                Quirks.disableGeometryBasedGripCheck.value
+                                in labware_definition.parameters.quirks
+                            )
+
                         # todo(mm, 2024-09-26): This currently raises a lower-level 2015 FailedGripperPickupError.
                         # Convert this to a higher-level 3001 LabwareDroppedError or 3002 LabwareNotPickedUpError,
                         # depending on what waypoint we're at, to propagate a more specific error code to users.
@@ -242,6 +250,7 @@ class LabwareMovementHandler:
                             expected_grip_width=grip_specs.targetY,
                             grip_width_uncertainty_wider=grip_specs.uncertaintyWider,
                             grip_width_uncertainty_narrower=grip_specs.uncertaintyNarrower,
+                            disable_geometry_grip_check=disable_geometry_grip_check,
                         )
                 await ot3api.move_to(
                     mount=gripper_mount, abs_position=waypoint_data.position

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/protocol_engine.py

@@ -13,6 +13,7 @@ from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons.hardware_control.modules import AbstractModule as HardwareModuleAPI
 from opentrons.hardware_control.types import PauseType as HardwarePauseType
+from opentrons.system import camera
 
 from .actions.actions import (
     ResumeFromRecoveryAction,
@@ -22,7 +23,8 @@ from .errors import ProtocolCommandFailedError, ErrorOccurrence, CommandNotAllow
 from .errors.exceptions import EStopActivatedError
 from .error_recovery_policy import ErrorRecoveryPolicy
 from . import commands, slot_standardization, labware_offset_standardization
-from .resources import ModelUtils, ModuleDataProvider, FileProvider
+from .resources import ModelUtils, ModuleDataProvider, FileProvider, CameraProvider
+from .resources.camera_provider import CameraSettings
 from .types import (
     LabwareOffset,
     LabwareOffsetCreate,
@@ -55,6 +57,7 @@ from .actions import (
     AddLabwareOffsetAction,
     AddLabwareDefinitionAction,
     AddLiquidAction,
+    AddCameraSettingsAction,
     SetDeckConfigurationAction,
     AddAddressableAreaAction,
     AddModuleAction,
@@ -96,6 +99,7 @@ class ProtocolEngine:
         door_watcher: DoorWatcher,
         module_data_provider: ModuleDataProvider,
         file_provider: FileProvider,
+        camera_provider: CameraProvider,
         queue_worker: Optional[QueueWorker] = None,
     ) -> None:
         """Initialize a ProtocolEngine instance.
@@ -107,6 +111,7 @@ class ProtocolEngine:
         """
         self._hardware_api = hardware_api
         self._file_provider = file_provider
+        self._camera_provider = camera_provider
         self._state_store = state_store
         self._model_utils = model_utils
         self._action_dispatcher = action_dispatcher
@@ -405,6 +410,39 @@ class ProtocolEngine:
         await self._do_hardware_stop()
         return True
 
+    async def module_disconnected(
+        self, module_model: ModuleModel, serial: str | None
+    ) -> bool:
+        """Signal to the engine that a module has disconnected.
+
+        The return value of this function signals whether the module was relevant to this
+        protocol or not. If the function returns True, the module was relevant. The engine
+        will stop, and the caller should call `finish()` with an appropriate error to indicate
+        the missing module. If the function returns False, the error is not relevant. The engine
+        will not stop, and the caller should not call `finish()`.
+
+        Module disconnects are signaled when a hardware module's status poller indicates that the
+        module is no logner connected - for instance, someone unplugs the module, or it crashes.
+        These errors are not related to a particular command, even a currently-happening module
+        control command for the module in the error state.
+
+        Similar to an estop error, the error can occur at any time relative to the lifecycle
+        of the engine run or of any particular command.
+
+        Unlike an estop, the motion control hardware will not be raising an error and will not
+        stop on its own; the stop action derived from this call will do that.
+        """
+        if not self._state_store.modules.get_has_module_probably_matching_hardware_details(
+            module_model, serial
+        ):
+            return False
+        self._stop_from_asynchronous_error()
+        # like self.request_stop, and unlike self.estop(), we must explicitly request that the
+        # hardware stops execution, since not all asynchronous errors will cause the hardware
+        # to know that it should stop.
+        await self._do_hardware_stop()
+        return True
+
     async def _do_hardware_stop(self) -> None:
         """Make the hardware stop now."""
         if self._hardware_api.is_movement_execution_taskified():
@@ -445,7 +483,7 @@ class ProtocolEngine:
         )
         self._state_store.commands.raise_fatal_command_error()
 
-    async def finish(
+    async def finish(  # noqa: C901
         self,
         error: Optional[Exception] = None,
         drop_tips_after_run: bool = True,
@@ -559,6 +597,16 @@ class ProtocolEngine:
         else:
             finish_error_details = None
 
+        try:
+            await camera.update_live_stream_status(
+                self.state_view.config.robot_type,
+                False,
+                self._camera_provider,
+                self.state_view.camera.get_enablement_settings(),
+            )
+        except Exception as e:
+            _log.exception(f"Exception during live stream post-run cleanup: {e}")
+
         self._action_dispatcher.dispatch(
             HardwareStoppedAction(
                 completed_at=self._model_utils.get_timestamp(),
@@ -596,6 +644,17 @@ class ProtocolEngine:
             labware_offset_id=labware_offset_id
         )
 
+    def add_camera_enablement_settings(
+        self, enablement_settings: CameraSettings
+    ) -> CameraSettings:
+        """Add new camera enablement settings."""
+        self._action_dispatcher.dispatch(
+            AddCameraSettingsAction(enablement_settings=enablement_settings)
+        )
+        camera_settings = self.state_view.camera.get_enablement_settings()
+        assert camera_settings is not None
+        return camera_settings
+
     def add_labware_definition(self, definition: LabwareDefinition) -> LabwareUri:
         """Add a labware definition to the state for subsequent labware loads."""
         self._action_dispatcher.dispatch(
@@ -676,6 +735,7 @@ class ProtocolEngine:
         self._queue_worker = create_queue_worker(
             hardware_api=self._hardware_api,
             file_provider=self._file_provider,
+            camera_provider=self._camera_provider,
             state_store=self._state_store,
             action_dispatcher=self._action_dispatcher,
             command_generator=command_generator,

opentrons/protocol_engine/resources/__init__.py

@@ -10,6 +10,7 @@ from .deck_data_provider import DeckDataProvider, DeckFixedLabware
 from .labware_data_provider import LabwareDataProvider
 from .module_data_provider import ModuleDataProvider
 from .file_provider import FileProvider
+from .camera_provider import CameraProvider
 from .ot3_validation import ensure_ot3_hardware
 from .concurrency_provider import ConcurrencyProvider
 
@@ -22,6 +23,7 @@ __all__ = [
     "ConcurrencyProvider",
     "ModuleDataProvider",
     "FileProvider",
+    "CameraProvider",
     "ensure_ot3_hardware",
     "pipette_data_provider",
     "labware_validation",

opentrons/protocol_engine/resources/camera_provider.py

@@ -0,0 +1,110 @@
+"""Camera interaction resource provider."""
+from typing import Optional, Callable, Tuple, Awaitable
+from pydantic import BaseModel, Field
+from ..errors import CameraCaptureError, CameraSettingsInvalidError
+import logging
+
+from opentrons_shared_data.robot.types import RobotType
+
+log = logging.getLogger(__name__)
+
+
+class CameraError(BaseModel):
+    """Generic base class for Camera errors that occur on entities handled through the Camera Provider."""
+
+    message: str = Field(..., description="Description of error content.")
+    code: str | None = Field(
+        ..., description="Return code, if any, that was paired with the error."
+    )
+
+
+class CameraSettings(BaseModel):
+    """Camera API settings for general enablement and use."""
+
+    cameraEnabled: bool = Field(
+        ..., description="Enablement status for general camera use."
+    )
+    liveStreamEnabled: bool = Field(
+        ..., description="Enablement status for the Opentrons Live Stream service."
+    )
+    errorRecoveryEnabled: bool = Field(
+        ..., description="Enablement status for camera usage with Error Recovery."
+    )
+
+
+class ImageParameters(BaseModel):
+    """Parameters for an Image Capture to determine filters. These are the inputs as expected by FFMPEG."""
+
+    resolution: Optional[Tuple[int, int]] = Field(
+        None,
+        description="Width by height resolution in pixels for the image to be captured with.",
+    )
+    zoom: Optional[float] = Field(
+        None,
+        description="Multiplier to use when cropping and scaling a captured image.",
+    )
+    pan: Optional[Tuple[int, int]] = Field(
+        None,
+        description="Position to pan to for a given zoom. Format is X and Y coordinates (in pixels) to the bottom left of a frame.",
+    )
+    contrast: Optional[float] = Field(
+        None, description="The contrast to use when processing an image."
+    )
+    brightness: Optional[int] = Field(
+        None, description="The brightness to use when processing an image."
+    )
+    saturation: Optional[float] = Field(
+        None, description="The saturation to use when processing an image."
+    )
+
+
+class CameraProvider:
+    """Provider class to wrap camera interactions between the server and the engine."""
+
+    def __init__(
+        self,
+        camera_settings_callback: Optional[Callable[[], CameraSettings]] = None,
+        image_capture_callback: Optional[
+            Callable[[RobotType, ImageParameters], Awaitable[bytes | CameraError]]
+        ] = None,
+    ) -> None:
+        """Initialize the interface callbacks of the Camera Provider within the Protocol Engine.
+
+        Params:
+            camera_settings_callback: Callback to query the Camera Enablement settings from the Boolean Settings table.
+            image_capture_callback: Callback to process an image capture request and return a bytestream of image data in response.
+        """
+        self._camera_settings_callback = camera_settings_callback
+        self._image_capture_callback = image_capture_callback
+
+    async def get_camera_settings(self) -> CameraSettings:
+        """Query the Robot Server for the current Camera Enablement settings."""
+        if self._camera_settings_callback is not None:
+            return self._camera_settings_callback()
+        # If we are in analysis or simulation, return as if the camera is enabled
+        return CameraSettings(
+            cameraEnabled=True, liveStreamEnabled=True, errorRecoveryEnabled=True
+        )
+
+    async def capture_image(
+        self, robot_type: RobotType, parameters: ImageParameters
+    ) -> bytes | None:
+        """Process through the Camera Executor on robot server an image capture request with a given set of filters.
+
+        Returns a bytesteam of image data upon success. Raises an error if an error occurred during capture.
+        Conditionally returns None if an image capture callback does not exist (simulation).
+        """
+        if self._image_capture_callback is not None:
+            capture_result = await self._image_capture_callback(robot_type, parameters)
+            if not isinstance(capture_result, CameraError):
+                return capture_result
+            else:
+                if capture_result.code == "IMAGE_SETTINGS":
+                    raise CameraSettingsInvalidError(message=capture_result.message)
+                elif capture_result.code is not None:
+                    error_str = f"Camera capture has failed to return an image with return code {capture_result.code}: {capture_result.message}"
+                else:
+                    error_str = f"Camera capture has failed with exception: {capture_result.message}"
+                raise CameraCaptureError(message=error_str)
+        # Return None if the image capture callback is unavailable (simulation)
+        return None