opentrons 8.6.0__py3-none-any.whl

opentrons/hardware_control/errors.py

@@ -0,0 +1,43 @@
+from typing import Optional, Dict, Any
+from opentrons_shared_data.errors.exceptions import (
+    MotionPlanningFailureError,
+    InvalidInstrumentData,
+    RobotInUseError,
+)
+
+
+class OutOfBoundsMove(MotionPlanningFailureError):
+    def __init__(self, message: str, detail: Dict[str, Any]):
+        super().__init__(message=message, detail=detail)
+
+
+class InvalidCriticalPoint(MotionPlanningFailureError):
+    def __init__(self, cp_name: str, instr: str, message: Optional[str] = None):
+        super().__init__(
+            message=(message or f"Critical point {cp_name} is invalid for a {instr}."),
+            detail={"instrument": instr, "critical point": cp_name},
+        )
+
+
+class InvalidPipetteName(InvalidInstrumentData):
+    """Raised for an invalid pipette."""
+
+    def __init__(self, name: int, mount: str) -> None:
+        super().__init__(
+            message=f"Invalid pipette name key {name} on mount {mount}",
+            detail={"mount": mount, "name": str(name)},
+        )
+
+
+class InvalidPipetteModel(InvalidInstrumentData):
+    """Raised for a pipette with an unknown model."""
+
+    def __init__(self, name: str, model: str, mount: str) -> None:
+        super().__init__(detail={"mount": mount, "name": name, "model": model})
+
+
+class UpdateOngoingError(RobotInUseError):
+    """Error when an update is already happening."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message=message)

opentrons/hardware_control/execution_manager.py

@@ -0,0 +1,164 @@
+import asyncio
+import functools
+from typing import (
+    Set,
+    TypeVar,
+    Type,
+    cast,
+    Callable,
+    Any,
+    Coroutine,
+    ParamSpec,
+    Concatenate,
+)
+from .types import ExecutionState
+from opentrons_shared_data.errors.exceptions import ExecutionCancelledError
+
+TaskContents = TypeVar("TaskContents")
+
+
+class ExecutionManager:
+    """This class holds onto a flag that is up/set while the hardware
+    hardware controller is running and down/cleared when the hardware
+    controller is "paused".
+
+    It also handles loop clean up through its cancel method.
+    """
+
+    def __init__(self) -> None:
+        self._state: ExecutionState = ExecutionState.RUNNING
+        self._condition = asyncio.Condition()
+        # this Task would technically be parametrized with every different thing
+        # that you could possible call register_cancellable_task on unfortunately
+        # so it's not gonna get typechecked
+        self._cancellable_tasks: Set["asyncio.Task[Any]"] = set()
+
+    async def pause(self) -> None:
+        async with self._condition:
+            if self._state is ExecutionState.CANCELLED:
+                raise ExecutionCancelledError
+            else:
+                self._state = ExecutionState.PAUSED
+
+    async def resume(self) -> None:
+        async with self._condition:
+            if self._state is ExecutionState.CANCELLED:
+                pass
+            else:
+                self._state = ExecutionState.RUNNING
+                self._condition.notify_all()
+
+    async def cancel(self) -> None:
+        async with self._condition:
+            self._state = ExecutionState.CANCELLED
+            self._condition.notify_all()
+            running_task = asyncio.current_task()
+            for t in self._cancellable_tasks:
+                if t is not running_task:
+                    t.cancel()
+
+    async def reset(self) -> None:
+        async with self._condition:
+            self._state = ExecutionState.RUNNING
+            self._condition.notify_all()
+
+    async def get_state(self) -> ExecutionState:
+        async with self._condition:
+            return self._state
+
+    def register_cancellable_task(self, task: "asyncio.Task[TaskContents]") -> None:
+        self._cancellable_tasks.add(task)
+        task.add_done_callback(lambda t: self._cancellable_tasks.discard(t))
+
+    async def wait_for_is_running(self) -> None:
+        async with self._condition:
+            if self._state == ExecutionState.PAUSED:
+                await self._condition.wait()
+                # type-ignore needed because this is a reentrant function and narrowing cannot
+                # apply
+                if self._state == ExecutionState.CANCELLED:  # type: ignore[comparison-overlap]
+                    raise ExecutionCancelledError
+            elif self._state == ExecutionState.CANCELLED:
+                raise ExecutionCancelledError
+            else:
+                pass
+
+
+SubclassInstance = TypeVar("SubclassInstance", bound="ExecutionManagerProvider")
+DecoratedMethodParams = ParamSpec("DecoratedMethodParams")
+DecoratedReturn = TypeVar("DecoratedReturn")
+
+
+class ExecutionManagerProvider:
+    """A mixin that provides an execution manager.
+
+    By inheriting from this class, hardware controller APIs can get an
+    execution manager and implemented methods that provide access to it.
+    """
+
+    def __init__(self, simulator: bool) -> None:
+        self._em_simulate = simulator
+        self._execution_manager = ExecutionManager()
+        self._taskify_movement_execution: bool = False
+
+    @property
+    def taskify_movement_execution(self) -> bool:
+        return self._taskify_movement_execution
+
+    @taskify_movement_execution.setter
+    def taskify_movement_execution(self, cancellable: bool) -> None:
+        self._taskify_movement_execution = cancellable
+
+    @property
+    def execution_manager(self) -> ExecutionManager:
+        return self._execution_manager
+
+    @classmethod
+    def wait_for_running(
+        cls: Type["ExecutionManagerProvider"],
+        decorated: Callable[
+            Concatenate[SubclassInstance, DecoratedMethodParams],
+            Coroutine[Any, Any, DecoratedReturn],
+        ],
+    ) -> Callable[
+        Concatenate[SubclassInstance, DecoratedMethodParams],
+        Coroutine[Any, Any, DecoratedReturn],
+    ]:
+        @functools.wraps(decorated)
+        async def replace(
+            inst: SubclassInstance,
+            *args: DecoratedMethodParams.args,
+            **kwargs: DecoratedMethodParams.kwargs,
+        ) -> DecoratedReturn:
+            if not inst._em_simulate:
+                await inst.execution_manager.wait_for_is_running()
+            if inst.taskify_movement_execution:
+                # Running these functions inside cancellable tasks makes it easier and
+                # faster to cancel protocol runs. In the higher, runner & engine layers,
+                # a cancellation request triggers cancellation of the running move task
+                # and hence, prevents any further communication with hardware.
+                decorated_task: "asyncio.Task[DecoratedReturn]" = asyncio.create_task(
+                    decorated(inst, *args, **kwargs)
+                )
+                inst.execution_manager.register_cancellable_task(decorated_task)
+                return await decorated_task
+            else:
+                return await decorated(inst, *args, **kwargs)
+
+        return cast(
+            Callable[
+                Concatenate[SubclassInstance, DecoratedMethodParams],
+                Coroutine[Any, Any, DecoratedReturn],
+            ],
+            replace,
+        )
+
+    async def do_delay(self, duration_s: float) -> None:
+        if not self._em_simulate:
+
+            async def sleep_for_seconds(seconds: float) -> None:
+                await asyncio.sleep(seconds)
+
+            delay_task = asyncio.create_task(sleep_for_seconds(duration_s))
+            self._execution_manager.register_cancellable_task(delay_task)
+            await delay_task

opentrons/hardware_control/instruments/__init__.py

@@ -0,0 +1,5 @@
+from .instrument_abc import AbstractInstrument
+from .ot3.gripper import Gripper
+
+
+__all__ = ["AbstractInstrument", "Gripper"]

opentrons/hardware_control/instruments/instrument_abc.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Generic, TypeVar, Dict
+
+from opentrons.types import Point
+from opentrons.hardware_control.types import CriticalPoint
+
+
+InstrumentConfig = TypeVar("InstrumentConfig")
+
+
+class AbstractInstrument(ABC, Generic[InstrumentConfig]):
+    """Defines the common methods of an instrument."""
+
+    @property
+    @abstractmethod
+    def model(self) -> str:
+        """Return model of the instrument."""
+        ...
+
+    @property
+    @abstractmethod
+    def config(self) -> InstrumentConfig:
+        """Instrument config in dataclass format."""
+        ...
+
+    @abstractmethod
+    def reload_configurations(self) -> None:
+        """Reset the instrument to default configurations."""
+        ...
+
+    @abstractmethod
+    def update_config_item(self, elements: Dict[str, Any]) -> None:
+        """Update instrument config item."""
+        ...
+
+    @abstractmethod
+    def critical_point(self, cp_override: Optional[CriticalPoint] = None) -> Point:
+        """Computate critical point of an instrument."""
+        ...

opentrons/hardware_control/instruments/ot2/instrument_calibration.py

@@ -0,0 +1,152 @@
+import typing
+from typing_extensions import Literal
+from dataclasses import dataclass
+from datetime import datetime
+from opentrons.config.robot_configs import default_pipette_offset
+
+from opentrons.calibration_storage import ot2 as calibration_storage
+from opentrons.calibration_storage import types, helpers
+from opentrons.types import Mount, Point
+from opentrons.hardware_control.types import OT3Mount
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition2
+
+if typing.TYPE_CHECKING:
+    from opentrons_shared_data.pipette.types import LabwareUri
+    from opentrons_shared_data.labware.types import (
+        LabwareDefinition2 as TypeDictLabwareDef2,
+    )
+
+# These type aliases aid typechecking in tests that work the same on this and
+# the hardware_control.instruments.ot3 variant
+SourceType = types.SourceType
+CalibrationStatus = types.CalibrationStatus
+
+
+@dataclass
+class PipetteOffsetByPipetteMount:
+    """
+    Class to store pipette offset without pipette and mount info
+    """
+
+    offset: Point
+    source: SourceType
+    status: CalibrationStatus
+    tiprack: typing.Optional[str] = None
+    uri: typing.Optional[str] = None
+    last_modified: typing.Optional[datetime] = None
+
+
+@dataclass
+class PipetteOffsetCalibration:
+    """
+    Class to store pipette offset calibration with pipette and mount info
+    """
+
+    pipette: str
+    mount: str
+    offset: Point
+    tiprack: str
+    uri: str
+    last_modified: datetime
+    source: SourceType
+    status: CalibrationStatus
+
+
+@dataclass
+class TipLengthCalibration:
+    tip_length: float
+    source: SourceType
+    status: CalibrationStatus
+    pipette: str
+    tiprack: str
+    last_modified: datetime
+    uri: typing.Union["LabwareUri", Literal[""]]
+
+
+def load_pipette_offset(
+    pip_id: typing.Optional[str], mount: typing.Union[Mount, OT3Mount]
+) -> PipetteOffsetByPipetteMount:
+    # load default if pipette offset data do not exist
+    pip_cal_obj = PipetteOffsetByPipetteMount(
+        offset=Point(*default_pipette_offset()),
+        source=SourceType.default,
+        status=CalibrationStatus(),
+    )
+    # TODO this can be removed once we switch to using
+    # ot3 pipette types in the ot3 hardware controller.
+    if isinstance(mount, OT3Mount):
+        checked_mount = mount.to_mount()
+    else:
+        checked_mount = mount
+    if pip_id:
+        pip_offset_data = calibration_storage.get_pipette_offset(pip_id, checked_mount)
+        if pip_offset_data:
+            return PipetteOffsetByPipetteMount(
+                offset=pip_offset_data.offset,
+                tiprack=pip_offset_data.tiprack,
+                last_modified=pip_offset_data.last_modified,
+                uri=pip_offset_data.uri,
+                source=pip_offset_data.source,
+                status=types.CalibrationStatus(
+                    markedAt=pip_offset_data.status.markedAt,
+                    markedBad=pip_offset_data.status.markedBad,
+                    source=pip_offset_data.status.source,
+                ),
+            )
+    return pip_cal_obj
+
+
+def save_pipette_offset_calibration(
+    pip_id: typing.Optional[str],
+    mount: typing.Union[Mount, OT3Mount],
+    offset: Point,
+    tiprack_hash: str,
+    tiprack_uri: str,
+) -> None:
+    # TODO this can be removed once we switch to using
+    # ot3 pipette types in the ot3 hardware controller.
+    if isinstance(mount, OT3Mount):
+        checked_mount = mount.to_mount()
+    else:
+        checked_mount = mount
+    if pip_id:
+        calibration_storage.save_pipette_calibration(
+            offset, pip_id, checked_mount, tiprack_hash, tiprack_uri
+        )
+
+
+# TODO (lc 09-26-2022) We should ensure that only LabwareDefinition models are passed
+# into this function instead of a mixture of TypeDicts and BaseModels
+def load_tip_length_for_pipette(
+    pipette_id: str, tiprack: typing.Union["TypeDictLabwareDef2", LabwareDefinition2]
+) -> TipLengthCalibration:
+    if isinstance(tiprack, LabwareDefinition2):
+        tiprack = typing.cast(
+            "TypeDictLabwareDef2",
+            tiprack.model_dump(
+                exclude_none=True,
+                exclude_unset=True
+                # todo(mm, 2025-02-13): Do we need by_alias=True here?
+            ),
+        )
+
+    tip_length_data = calibration_storage.load_tip_length_calibration(
+        pipette_id, tiprack
+    )
+
+    tiprack_uri = helpers.uri_from_definition(tiprack)
+
+    return TipLengthCalibration(
+        tip_length=tip_length_data.tipLength,
+        source=tip_length_data.source,
+        pipette=pipette_id,
+        tiprack=tip_length_data.definitionHash,
+        last_modified=tip_length_data.lastModified,
+        uri=tiprack_uri,
+        status=types.CalibrationStatus(
+            markedAt=tip_length_data.status.markedAt,
+            markedBad=tip_length_data.status.markedBad,
+            source=tip_length_data.status.source,
+        ),
+    )