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

opentrons/protocol_engine/execution/task_handler.py

@@ -0,0 +1,157 @@
+"""Task handling."""
+
+from __future__ import annotations
+import logging
+from typing import Protocol, AsyncIterator
+from ..state.state import StateStore
+from ..resources import ModelUtils, ConcurrencyProvider
+from ..types import Task
+import asyncio
+import contextlib
+from ..actions import ActionDispatcher, FinishTaskAction, StartTaskAction
+from ..errors import ErrorOccurrence
+from opentrons_shared_data.errors.exceptions import EnumeratedError, PythonException
+
+log = logging.getLogger(__name__)
+
+
+class TaskFunction(Protocol):
+    """The function run inside a task protocol."""
+
+    async def __call__(self, task_handler: TaskHandler) -> None:
+        """The function called inside a task."""
+        ...
+
+
+class TaskHandler:
+    """Implementation logic for fast concurrency."""
+
+    _state_store: StateStore
+    _model_utils: ModelUtils
+    _concurrency_provider: ConcurrencyProvider
+
+    def __init__(
+        self,
+        state_store: StateStore,
+        action_dispatcher: ActionDispatcher,
+        model_utils: ModelUtils | None = None,
+        concurrency_provider: ConcurrencyProvider | None = None,
+    ) -> None:
+        """Initialize a TaskHandler instance."""
+        self._state_store = state_store
+        self._model_utils = model_utils or ModelUtils()
+        self._concurrency_provider = concurrency_provider or ConcurrencyProvider()
+        self._action_dispatcher = action_dispatcher
+
+    async def create_task(
+        self, task_function: TaskFunction, id: str | None = None
+    ) -> Task:
+        """Create a task and immediately schedules it."""
+        task_id = self._model_utils.ensure_id(id)
+        asyncio_task = asyncio.create_task(
+            task_function(task_handler=self), name=f"engine-task-{task_id}"
+        )
+
+        def _done_callback(task: asyncio.Task[None]) -> None:
+            try:
+                maybe_exception = task.exception()
+            except asyncio.CancelledError as e:
+                maybe_exception = e
+            if isinstance(maybe_exception, EnumeratedError):
+                occurence: ErrorOccurrence | None = ErrorOccurrence.from_failed(
+                    id=self._model_utils.generate_id(),
+                    createdAt=self._model_utils.get_timestamp(),
+                    error=maybe_exception,
+                )
+            elif isinstance(maybe_exception, BaseException):
+                occurence = ErrorOccurrence.from_failed(
+                    id=self._model_utils.generate_id(),
+                    createdAt=self._model_utils.get_timestamp(),
+                    error=PythonException(maybe_exception),
+                )
+            else:
+                occurence = None
+            try:
+                self._action_dispatcher.dispatch(
+                    FinishTaskAction(
+                        task_id=task_id,
+                        finished_at=self._model_utils.get_timestamp(),
+                        error=occurence,
+                    ),
+                )
+            except BaseException:
+                log.exception("Exception in task finish dispatch.")
+
+        asyncio_task.add_done_callback(_done_callback)
+        task = Task(
+            id=task_id,
+            createdAt=self._model_utils.get_timestamp(),
+            asyncioTask=asyncio_task,
+        )
+        self._action_dispatcher.dispatch(StartTaskAction(task))
+        return task
+
+    @staticmethod
+    def _empty_queue(
+        queue: "asyncio.Queue[asyncio.Task[None]]", this_task: asyncio.Task[None]
+    ) -> None:
+        """Empties the queue."""
+        try:
+            while True:
+                task = queue.get_nowait()
+                if task is this_task:
+                    break
+        except asyncio.QueueEmpty:
+            pass
+
+    @contextlib.asynccontextmanager
+    async def synchronize_cancel_latest(self, group_id: str) -> AsyncIterator[None]:
+        """Cancel current task."""
+        lock = self._concurrency_provider.lock_for_group(group_id)
+        if lock.locked():
+            raise asyncio.CancelledError()
+        async with lock:
+            yield
+
+    @contextlib.asynccontextmanager
+    async def synchronize_cancel_previous(self, group_id: str) -> AsyncIterator[None]:
+        """Cancel previous run."""
+        queue = self._concurrency_provider.queue_for_group(group_id)
+        while not queue.empty():
+            task = queue.get_nowait()
+            task.cancel()
+        this_task = asyncio.current_task()
+        assert this_task is not None
+        queue.put_nowait(this_task)
+        try:
+            yield
+        except asyncio.CancelledError:
+            raise
+        except BaseException:
+            self._empty_queue(queue, this_task)
+            raise
+        else:
+            self._empty_queue(queue, this_task)
+
+    @contextlib.asynccontextmanager
+    async def synchronize_sequential(self, group_id: str) -> AsyncIterator[None]:
+        """Run tasks one after the other."""
+        lock = self._concurrency_provider.lock_for_group(group_id)
+        async with lock:
+            yield
+
+    @contextlib.asynccontextmanager
+    async def synchronize_concurrent(self, group_id: str) -> AsyncIterator[None]:
+        """Run a list of tasks at the same time."""
+        yield
+
+    def cancel_all(self, message: str | None = None) -> None:
+        """Cancel all asyncio tasks immediately.
+
+        Do not call this more than once synchronously because
+        that could lead to tasks cancelling more than once.
+        It can be called if there are no current tasks. In that case
+        nothing will happen.
+        """
+        for task in self._state_store.tasks.get_all_current():
+            task.asyncioTask.cancel(msg=message)

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,11 +57,11 @@ from .actions import (
     AddLabwareOffsetAction,
     AddLabwareDefinitionAction,
     AddLiquidAction,
+    AddCameraSettingsAction,
     SetDeckConfigurationAction,
     AddAddressableAreaAction,
     AddModuleAction,
     HardwareStoppedAction,
-    ResetTipsAction,
     SetPipetteMovementSpeedAction,
 )
 
@@ -97,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.
@@ -108,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
@@ -322,24 +326,10 @@ class ProtocolEngine:
         )
         return completed_command
 
-    def estop(self) -> None:
-        """Signal to the engine that an E-stop event occurred.
-
-        If an estop happens while the robot is moving, lower layers physically stop
-        motion and raise the event as an exception, which fails the Protocol Engine
-        command. No action from the `ProtocolEngine` caller is needed to handle that.
-
-        However, if an estop happens in between commands, or in the middle of
-        a command like `comment` or `waitForDuration` that doesn't access the hardware,
-        `ProtocolEngine` needs to be told about it so it can interrupt the command
-        and stop executing any more. This method is how to do that.
-
-        This acts roughly like `request_stop()`. After calling this, you should call
-        `finish()` with an EStopActivatedError.
-        """
+    def _stop_from_asynchronous_error(self) -> None:
         try:
             action = self._state_store.commands.validate_action_allowed(
-                StopAction(from_estop=True)
+                StopAction(from_asynchronous_error=True)
             )
         except Exception:  # todo(mm, 2024-04-16): Catch a more specific type.
             # This is likely called from some hardware API callback that doesn't care
@@ -358,9 +348,112 @@ class ProtocolEngine:
         # do this because we want to make sure non-hardware commands, like
         # `waitForDuration`, are also interrupted.
         self._get_queue_worker.cancel()
+
+    def estop(self) -> None:
+        """Signal to the engine that an E-stop event occurred.
+
+        If an estop happens while the robot is moving, lower layers physically stop
+        motion and raise the event as an exception, which fails the Protocol Engine
+        command. No action from the `ProtocolEngine` caller is needed to handle that.
+
+        However, if an estop happens in between commands, or in the middle of
+        a command like `comment` or `waitForDuration` that doesn't access the hardware,
+        `ProtocolEngine` needs to be told about it so it can interrupt the command
+        and stop executing any more. This method is how to do that.
+
+        This acts roughly like `request_stop()`. After calling this, you should call
+        `finish()` with an EStopActivatedError.
+        """
         # Unlike self.request_stop(), we don't need to do
         # self._hardware_api.cancel_execution_and_running_tasks(). Since this was an
         # E-stop event, the hardware API already knows.
+        self._stop_from_asynchronous_error()
+
+    async def async_module_error(
+        self, module_model: ModuleModel, serial: str | None
+    ) -> bool:
+        """Signal to the engine that an asynchronous module error occured.
+
+        The return value of this function signals whether the error is relevant to the protocol
+        or not. If the function returns True, the error is relevant. The engine will stop, and
+        the caller should call `finish()` with the error object that signaled the error. If
+        the function returns False, the error is not relevant. The engine will not stop, and the
+        caller should not call `finish()`.
+
+        Asynchronous module errors are signaled when a module enters a hardware error state
+        - for instance, a thermocycler's thermistors fail because of condensation, or a
+        heater-shaker's wires fray and snap, or a module is accidentally disconnected. 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
+
+        if self._state_store.commands.get_is_terminal():
+            # Do not stop multiple times; it will be common for this action to fire
+            # many times when a module enters an error state, and we don't want to do
+            # the stop behavior over and over
+            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 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():
+            # We 'taskify' hardware controller movement functions when running protocols
+            # that are not backed by the engine. Such runs cannot be stopped by cancelling
+            # the queue worker and hence need to be stopped via the execution manager.
+            # `cancel_execution_and_running_tasks()` sets the execution manager in a CANCELLED state
+            # and cancels the running tasks, which raises an error and gets us out of the
+            # run function execution, just like `_queue_worker.cancel()` does for
+            # engine-backed runs.
+            await self._hardware_api.cancel_execution_and_running_tasks()
 
     async def request_stop(self) -> None:
         """Make command execution stop soon.
@@ -378,15 +471,7 @@ class ProtocolEngine:
         action = self._state_store.commands.validate_action_allowed(StopAction())
         self._action_dispatcher.dispatch(action)
         self._get_queue_worker.cancel()
-        if self._hardware_api.is_movement_execution_taskified():
-            # We 'taskify' hardware controller movement functions when running protocols
-            # that are not backed by the engine. Such runs cannot be stopped by cancelling
-            # the queue worker and hence need to be stopped via the execution manager.
-            # `cancel_execution_and_running_tasks()` sets the execution manager in a CANCELLED state
-            # and cancels the running tasks, which raises an error and gets us out of the
-            # run function execution, just like `_queue_worker.cancel()` does for
-            # engine-backed runs.
-            await self._hardware_api.cancel_execution_and_running_tasks()
+        await self._do_hardware_stop()
 
     async def wait_until_complete(self) -> None:
         """Wait until there are no more commands to execute.
@@ -398,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,
@@ -429,13 +514,13 @@ class ProtocolEngine:
             post_run_hardware_state: The state in which to leave the gantry and motors in
                 after the run is over.
         """
-        if self._state_store.commands.get_is_stopped_by_estop():
+        if self._state_store.commands.get_is_stopped_by_async_error():
             # This handles the case where the E-stop was pressed while we were *not* in the middle
             # of some hardware interaction that would raise it as an exception. For example, imagine
             # we were paused between two commands, or imagine we were executing a waitForDuration.
             drop_tips_after_run = False
             post_run_hardware_state = PostRunHardwareState.DISENGAGE_IN_PLACE
-            if error is None:
+            if error is None and self._state_store.commands.get_error() is None:
                 error = EStopActivatedError()
 
         if error:
@@ -512,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(),
@@ -549,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(
@@ -586,12 +692,6 @@ class ProtocolEngine:
             AddAddressableAreaAction(addressable_area_name)
         )
 
-    def reset_tips(self, labware_id: str) -> None:
-        """Reset the tip state of a given labware."""
-        # TODO(mm, 2023-03-10): Safely raise an error if the given labware isn't a
-        # tip rack?
-        self._action_dispatcher.dispatch(ResetTipsAction(labware_id=labware_id))
-
     # TODO(mm, 2022-11-10): This is a method on ProtocolEngine instead of a command
     # as a quick hack to support Python protocols. We should consider making this a
     # command, or adding speed parameters to existing commands.
@@ -635,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,7 +10,9 @@ 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
 
 
 __all__ = [
@@ -18,8 +20,10 @@ __all__ = [
     "LabwareDataProvider",
     "DeckDataProvider",
     "DeckFixedLabware",
+    "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

opentrons/protocol_engine/resources/concurrency_provider.py

@@ -0,0 +1,27 @@
+"""Concurrency primitives providers."""
+import asyncio
+
+
+class ConcurrencyProvider:
+    """Concurrency primitives for engine tasks."""
+
+    def __init__(self) -> None:
+        """Build a concurrency provider."""
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._queues: dict[str, "asyncio.Queue[asyncio.Task[None]]"] = {}
+
+    def lock_for_group(self, group_id: str) -> asyncio.Lock:
+        """Returns the lock for specified group id."""
+        try:
+            return self._locks[group_id]
+        except KeyError:
+            self._locks[group_id] = asyncio.Lock()
+            return self._locks[group_id]
+
+    def queue_for_group(self, group_id: str) -> "asyncio.Queue[asyncio.Task[None]]":
+        """Returns the queue for specified group id."""
+        try:
+            return self._queues[group_id]
+        except KeyError:
+            self._queues[group_id] = asyncio.Queue()
+            return self._queues[group_id]

opentrons/protocol_engine/resources/deck_configuration_provider.py

@@ -2,6 +2,7 @@
 
 from typing import List, Set, Tuple
 
+from opentrons_shared_data.module.types import ModuleOrientation
 from opentrons_shared_data.deck.types import (
     DeckDefinitionV5,
     CutoutFixture,
@@ -124,6 +125,11 @@ def get_addressable_area_from_name(
                 z=addressable_area["boundingBox"]["zDimension"],
             )
             features = addressable_area["features"]
+            orientation = (
+                addressable_area["orientation"]
+                if addressable_area["orientation"]
+                else ModuleOrientation.NOT_APPLICABLE
+            )
             mating_surface_unit_vector = addressable_area.get("matingSurfaceUnitVector")
 
             return AddressableArea(
@@ -138,6 +144,7 @@ def get_addressable_area_from_name(
                     "compatibleModuleTypes", []
                 ),
                 features=features,
+                orientation=orientation,
             )
     raise AddressableAreaDoesNotExistError(
         f"Could not find addressable area with name {addressable_area_name}"