opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/pressure_dispense.py

@@ -0,0 +1,155 @@
+"""Pressure Dispense-in-place command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from .pipetting_common import (
+    PipetteIdMixin,
+    FlowRateMixin,
+    DispenseVolumeMixin,
+    BaseLiquidHandlingResult,
+    dispense_in_place,
+    increase_evo_disp_count,
+    DEFAULT_CORRECTION_VOLUME,
+)
+from .movement_common import (
+    LiquidHandlingWellLocationMixin,
+    StallOrCollisionError,
+    move_to_well,
+)
+
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..state.update_types import StateUpdate
+from ..errors import ProtocolEngineError
+
+if TYPE_CHECKING:
+    from ..execution import PipettingHandler, GantryMover, MovementHandler
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+
+
+PressureDispenseCommandType = Literal["pressureDispense"]
+
+
+class PressureDispenseParams(
+    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, LiquidHandlingWellLocationMixin
+):
+    """Payload required to pressure dispense in place."""
+
+    pass
+
+
+class PressureDispenseResult(BaseLiquidHandlingResult):
+    """Result data from the execution of a PressureDispense command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[PressureDispenseResult],
+    DefinedErrorData[StallOrCollisionError],
+]
+
+
+class PressureDispenseImplementation(
+    AbstractCommandImpl[PressureDispenseParams, _ExecuteReturn]
+):
+    """Pressure dispense command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        state_view: StateView,
+        gantry_mover: GantryMover,
+        model_utils: ModelUtils,
+        movement: MovementHandler,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._gantry_mover = gantry_mover
+        self._model_utils = model_utils
+        self._movement = movement
+
+    async def execute(self, params: PressureDispenseParams) -> _ExecuteReturn:
+        """Move to and pressure dispense to the requested well."""
+        well_location = params.wellLocation
+        labware_id = params.labwareId
+        well_name = params.wellName
+
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+        )
+        if isinstance(move_result, DefinedErrorData):
+            return move_result
+
+        current_position = await self._gantry_mover.get_position(params.pipetteId)
+        await increase_evo_disp_count(
+            pipette_id=params.pipetteId, pipetting=self._pipetting
+        )
+        result = await dispense_in_place(
+            pipette_id=params.pipetteId,
+            volume=params.volume,
+            flow_rate=params.flowRate,
+            push_out=None,
+            location_if_error={
+                "retryLocation": (
+                    current_position.x,
+                    current_position.y,
+                    current_position.z,
+                )
+            },
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+            correction_volume=params.correctionVolume or DEFAULT_CORRECTION_VOLUME,
+        )
+        if isinstance(result, DefinedErrorData):
+            # TODO (chb, 2025-01-29): Remove this and the OverpressureError returns once disabled for this function
+            raise ProtocolEngineError(
+                message="Overpressure Error during Resin Tip Dispense Command."
+            )
+        return SuccessData(
+            public=PressureDispenseResult(volume=result.public.volume),
+            state_update=StateUpdate.reduce(
+                move_result.state_update, result.state_update
+            ),
+        )
+
+
+class PressureDispense(
+    BaseCommand[
+        PressureDispenseParams,
+        PressureDispenseResult,
+        StallOrCollisionError,
+    ]
+):
+    """PressureDispense command model."""
+
+    commandType: PressureDispenseCommandType = "pressureDispense"
+    params: PressureDispenseParams
+    result: Optional[PressureDispenseResult] = None
+
+    _ImplementationCls: Type[
+        PressureDispenseImplementation
+    ] = PressureDispenseImplementation
+
+
+class PressureDispenseCreate(BaseCommandCreate[PressureDispenseParams]):
+    """PressureDispense command request model."""
+
+    commandType: PressureDispenseCommandType = "pressureDispense"
+    params: PressureDispenseParams
+
+    _CommandCls: Type[PressureDispense] = PressureDispense

opentrons/protocol_engine/commands/reload_labware.py

@@ -0,0 +1,90 @@
+"""Reload labware command request, result, and implementation models."""
+
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+
+from .labware_handling_common import LabwarePositionResultMixin
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..state.update_types import StateUpdate
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..execution import EquipmentHandler
+
+
+ReloadLabwareCommandType = Literal["reloadLabware"]
+
+
+class ReloadLabwareParams(BaseModel):
+    """Payload required to load a labware into a slot."""
+
+    labwareId: str = Field(
+        ..., description="The already-loaded labware instance to update."
+    )
+
+
+class ReloadLabwareResult(LabwarePositionResultMixin):
+    """Result data from the execution of a LoadLabware command."""
+
+
+class ReloadLabwareImplementation(
+    AbstractCommandImpl[ReloadLabwareParams, SuccessData[ReloadLabwareResult]]
+):
+    """Reload labware command implementation."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, state_view: StateView, **kwargs: object
+    ) -> None:
+        self._equipment = equipment
+        self._state_view = state_view
+
+    async def execute(
+        self, params: ReloadLabwareParams
+    ) -> SuccessData[ReloadLabwareResult]:
+        """Reload the definition and calibration data for a specific labware."""
+        reloaded_labware = await self._equipment.reload_labware(
+            labware_id=params.labwareId,
+        )
+
+        state_update = StateUpdate()
+
+        state_update.set_labware_location(
+            labware_id=params.labwareId,
+            new_location=reloaded_labware.location,
+            new_offset_id=reloaded_labware.offsetId,
+        )
+
+        return SuccessData(
+            public=ReloadLabwareResult(
+                labwareId=params.labwareId,
+                offsetId=reloaded_labware.offsetId,
+                locationSequence=self._state_view.geometry.get_predicted_location_sequence(
+                    reloaded_labware.location
+                ),
+            ),
+            state_update=state_update,
+        )
+
+
+class ReloadLabware(
+    BaseCommand[ReloadLabwareParams, ReloadLabwareResult, ErrorOccurrence]
+):
+    """Reload labware command resource model."""
+
+    commandType: ReloadLabwareCommandType = "reloadLabware"
+    params: ReloadLabwareParams
+    result: Optional[ReloadLabwareResult] = None
+
+    _ImplementationCls: Type[ReloadLabwareImplementation] = ReloadLabwareImplementation
+
+
+class ReloadLabwareCreate(BaseCommandCreate[ReloadLabwareParams]):
+    """Reload labware command creation request."""
+
+    commandType: ReloadLabwareCommandType = "reloadLabware"
+    params: ReloadLabwareParams
+
+    _CommandCls: Type[ReloadLabware] = ReloadLabware

opentrons/protocol_engine/commands/retract_axis.py

@@ -0,0 +1,75 @@
+"""Retract Axis command payload, result, and implementation models."""
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+
+from ..state import update_types
+from ..types import MotorAxis
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler
+
+RetractAxisCommandType = Literal["retractAxis"]
+
+
+class RetractAxisParams(BaseModel):
+    """Payload required for a Retract Axis command."""
+
+    axis: MotorAxis = Field(
+        ...,
+        description=(
+            "Axis to retract to its home position as quickly as safely possible."
+            " The difference between retracting an axis and homing an axis using the"
+            " home command is that a home will always probe the limit switch and"
+            " will work as the first motion command a robot will need to execute;"
+            " On the other hand, retraction will rely on this previously determined "
+            " home position to move to it as fast as safely possible."
+            " So on the Flex, it will move (fast) the axis to the previously recorded home position"
+            " and on the OT2, it will move (fast) the axis a safe distance from the previously"
+            " recorded home position, and then slowly approach the limit switch."
+        ),
+    )
+
+
+class RetractAxisResult(BaseModel):
+    """Result data from the execution of a Rectract Axis command."""
+
+
+class RetractAxisImplementation(
+    AbstractCommandImpl[RetractAxisParams, SuccessData[RetractAxisResult]]
+):
+    """Retract Axis command implementation."""
+
+    def __init__(self, movement: MovementHandler, **kwargs: object) -> None:
+        self._movement = movement
+
+    async def execute(
+        self, params: RetractAxisParams
+    ) -> SuccessData[RetractAxisResult]:
+        """Retract the specified axis."""
+        state_update = update_types.StateUpdate()
+        await self._movement.retract_axis(axis=params.axis)
+        state_update.clear_all_pipette_locations()
+        return SuccessData(public=RetractAxisResult(), state_update=state_update)
+
+
+class RetractAxis(BaseCommand[RetractAxisParams, RetractAxisResult, ErrorOccurrence]):
+    """Command to retract the specified axis to its home position."""
+
+    commandType: RetractAxisCommandType = "retractAxis"
+    params: RetractAxisParams
+    result: Optional[RetractAxisResult] = None
+
+    _ImplementationCls: Type[RetractAxisImplementation] = RetractAxisImplementation
+
+
+class RetractAxisCreate(BaseCommandCreate[RetractAxisParams]):
+    """Data to create a Retract Axis command."""
+
+    commandType: RetractAxisCommandType = "retractAxis"
+    params: RetractAxisParams
+
+    _CommandCls: Type[RetractAxis] = RetractAxis

opentrons/protocol_engine/commands/robot/__init__.py

@@ -0,0 +1,70 @@
+"""Robot movement commands."""
+
+from .move_to import (
+    MoveTo,
+    MoveToCreate,
+    MoveToParams,
+    MoveToResult,
+    MoveToCommandType,
+)
+from .move_axes_to import (
+    MoveAxesTo,
+    MoveAxesToCreate,
+    MoveAxesToParams,
+    MoveAxesToResult,
+    MoveAxesToCommandType,
+)
+from .move_axes_relative import (
+    MoveAxesRelative,
+    MoveAxesRelativeCreate,
+    MoveAxesRelativeParams,
+    MoveAxesRelativeResult,
+    MoveAxesRelativeCommandType,
+)
+from .open_gripper_jaw import (
+    OpenGripperJaw,
+    OpenGripperJawCreate,
+    OpenGripperJawParams,
+    OpenGripperJawResult,
+    OpenGripperJawCommandType,
+)
+from .close_gripper_jaw import (
+    CloseGripperJaw,
+    CloseGripperJawCreate,
+    CloseGripperJawParams,
+    CloseGripperJawResult,
+    CloseGripperJawCommandType,
+)
+
+__all__ = [
+    # robot/moveTo
+    "MoveTo",
+    "MoveToCreate",
+    "MoveToParams",
+    "MoveToResult",
+    "MoveToCommandType",
+    # robot/moveAxesTo
+    "MoveAxesTo",
+    "MoveAxesToCreate",
+    "MoveAxesToParams",
+    "MoveAxesToResult",
+    "MoveAxesToCommandType",
+    # robot/moveAxesRelative
+    "MoveAxesRelative",
+    "MoveAxesRelativeCreate",
+    "MoveAxesRelativeParams",
+    "MoveAxesRelativeResult",
+    "MoveAxesRelativeCommandType",
+    # robot/openGripperJaw
+    "OpenGripperJaw",
+    "OpenGripperJawCreate",
+    "OpenGripperJawParams",
+    "OpenGripperJawResult",
+    "OpenGripperJawCommandType",
+    # robot/closeGripperJaw
+    "CloseGripperJaw",
+    "CloseGripperJawCreate",
+    "CloseGripperJawParams",
+    "CloseGripperJawResult",
+    "CloseGripperJawCommandType",
+]

opentrons/protocol_engine/commands/robot/close_gripper_jaw.py

@@ -0,0 +1,96 @@
+"""Command models for opening a gripper jaw."""
+
+from __future__ import annotations
+from typing import Literal, Type, Optional, Any, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.resources import ensure_ot3_hardware
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+from opentrons.protocol_engine.errors.error_occurrence import ErrorOccurrence
+
+if TYPE_CHECKING:
+    from ...state.state import StateView
+
+
+CloseGripperJawCommandType = Literal["robot/closeGripperJaw"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class CloseGripperJawParams(BaseModel):
+    """Payload required to close a gripper."""
+
+    force: float | SkipJsonSchema[None] = Field(
+        default=None,
+        description="The force the gripper should use to hold the jaws, falls to default if none is provided.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class CloseGripperJawResult(BaseModel):
+    """Result data from the execution of a CloseGripperJaw command."""
+
+    pass
+
+
+class CloseGripperJawImplementation(
+    AbstractCommandImpl[CloseGripperJawParams, SuccessData[CloseGripperJawResult]]
+):
+    """CloseGripperJaw command implementation."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        state_view: StateView,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+        self._state_view = state_view
+
+    async def execute(
+        self, params: CloseGripperJawParams
+    ) -> SuccessData[CloseGripperJawResult]:
+        """Release the gripper."""
+        if self._state_view.config.use_virtual_gripper:
+            return SuccessData(
+                public=CloseGripperJawResult(),
+            )
+        ot3_hardware_api = ensure_ot3_hardware(self._hardware_api)
+        await ot3_hardware_api.grip(force_newtons=params.force)
+        return SuccessData(
+            public=CloseGripperJawResult(),
+        )
+
+
+class CloseGripperJaw(
+    BaseCommand[CloseGripperJawParams, CloseGripperJawResult, ErrorOccurrence]
+):
+    """CloseGripperJaw command model."""
+
+    commandType: CloseGripperJawCommandType = "robot/closeGripperJaw"
+    params: CloseGripperJawParams
+    result: Optional[CloseGripperJawResult] = None
+
+    _ImplementationCls: Type[
+        CloseGripperJawImplementation
+    ] = CloseGripperJawImplementation
+
+
+class CloseGripperJawCreate(BaseCommandCreate[CloseGripperJawParams]):
+    """CloseGripperJaw command request model."""
+
+    commandType: CloseGripperJawCommandType = "robot/closeGripperJaw"
+    params: CloseGripperJawParams
+
+    _CommandCls: Type[CloseGripperJaw] = CloseGripperJaw

opentrons/protocol_engine/commands/robot/common.py

@@ -0,0 +1,18 @@
+"""Shared result types for robot API commands."""
+from pydantic import BaseModel, Field
+
+from typing import Dict
+from opentrons.protocol_engine.types import MotorAxis
+
+
+MotorAxisMapType = Dict[MotorAxis, float]
+default_position = {ax: 0.0 for ax in MotorAxis}
+
+
+class DestinationRobotPositionResult(BaseModel):
+    """The result dictionary of `MotorAxis` type."""
+
+    position: MotorAxisMapType = Field(
+        default=default_position,
+        description="The position of all axes on the robot. If no mount was provided, the last moved mount is used to determine the location.",
+    )

opentrons/protocol_engine/commands/robot/move_axes_relative.py

@@ -0,0 +1,101 @@
+"""Command models for moving any robot axis relative."""
+
+from __future__ import annotations
+from typing import Literal, Type, Optional, TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.resources import ensure_ot3_hardware
+
+from .common import MotorAxisMapType, DestinationRobotPositionResult
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+from ...errors.error_occurrence import ErrorOccurrence
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.execution import GantryMover
+
+
+MoveAxesRelativeCommandType = Literal["robot/moveAxesRelative"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class MoveAxesRelativeParams(BaseModel):
+    """Payload required to move axes relative to position."""
+
+    axis_map: MotorAxisMapType = Field(
+        ..., description="A dictionary mapping axes to relative movements in mm."
+    )
+    speed: float | SkipJsonSchema[None] = Field(
+        default=None,
+        description="The max velocity to move the axes at. Will fall to hardware defaults if none provided.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class MoveAxesRelativeResult(DestinationRobotPositionResult):
+    """Result data from the execution of a MoveAxesRelative command."""
+
+    pass
+
+
+class MoveAxesRelativeImplementation(
+    AbstractCommandImpl[MoveAxesRelativeParams, SuccessData[MoveAxesRelativeResult]]
+):
+    """MoveAxesRelative command implementation."""
+
+    def __init__(
+        self,
+        gantry_mover: GantryMover,
+        hardware_api: HardwareControlAPI,
+        **kwargs: object,
+    ) -> None:
+        self._gantry_mover = gantry_mover
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: MoveAxesRelativeParams
+    ) -> SuccessData[MoveAxesRelativeResult]:
+        """Move the axes on a flex a relative distance."""
+        # TODO (lc 08-16-2024) implement `move_axes` for OT 2 hardware controller
+        # and then we can remove this validation.
+        ensure_ot3_hardware(self._hardware_api)
+
+        current_position = await self._gantry_mover.move_axes(
+            axis_map=params.axis_map, speed=params.speed, relative_move=True
+        )
+        return SuccessData(
+            public=MoveAxesRelativeResult(position=current_position),
+        )
+
+
+class MoveAxesRelative(
+    BaseCommand[MoveAxesRelativeParams, MoveAxesRelativeResult, ErrorOccurrence]
+):
+    """MoveAxesRelative command model."""
+
+    commandType: MoveAxesRelativeCommandType = "robot/moveAxesRelative"
+    params: MoveAxesRelativeParams
+    result: Optional[MoveAxesRelativeResult] = None
+
+    _ImplementationCls: Type[
+        MoveAxesRelativeImplementation
+    ] = MoveAxesRelativeImplementation
+
+
+class MoveAxesRelativeCreate(BaseCommandCreate[MoveAxesRelativeParams]):
+    """MoveAxesRelative command request model."""
+
+    commandType: MoveAxesRelativeCommandType = "robot/moveAxesRelative"
+    params: MoveAxesRelativeParams
+
+    _CommandCls: Type[MoveAxesRelative] = MoveAxesRelative