opentrons 8.2.0a3__py2.py3-none-any.whl → 8.3.0__py2.py3-none-any.whl

opentrons/protocol_engine/commands/pick_up_tip.py

@@ -1,4 +1,5 @@
 """Pick up tip command request, result, and implementation models."""
+
 from __future__ import annotations
 from opentrons_shared_data.errors import ErrorCodes
 from pydantic import Field
@@ -9,10 +10,14 @@ from typing_extensions import Literal
 from ..errors import ErrorOccurrence, PickUpTipTipNotAttachedError
 from ..resources import ModelUtils
 from ..state import update_types
-from ..types import PickUpTipWellLocation, DeckPoint
+from ..types import PickUpTipWellLocation
 from .pipetting_common import (
     PipetteIdMixin,
+)
+from .movement_common import (
     DestinationPositionResult,
+    StallOrCollisionError,
+    move_to_well,
 )
 from .command import (
     AbstractCommandImpl,
@@ -87,7 +92,8 @@ class TipPhysicallyMissingError(ErrorOccurrence):
 
 _ExecuteReturn = Union[
     SuccessData[PickUpTipResult],
-    DefinedErrorData[TipPhysicallyMissingError],
+    DefinedErrorData[TipPhysicallyMissingError]
+    | DefinedErrorData[StallOrCollisionError],
 ]
 
 
@@ -115,24 +121,19 @@ class PickUpTipImplementation(AbstractCommandImpl[PickUpTipParams, _ExecuteRetur
         labware_id = params.labwareId
         well_name = params.wellName
 
-        state_update = update_types.StateUpdate()
-
         well_location = self._state_view.geometry.convert_pick_up_tip_well_location(
             well_location=params.wellLocation
         )
-        position = await self._movement.move_to_well(
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
             pipette_id=pipette_id,
             labware_id=labware_id,
             well_name=well_name,
             well_location=well_location,
         )
-        deck_point = DeckPoint.construct(x=position.x, y=position.y, z=position.z)
-        state_update.set_pipette_location(
-            pipette_id=pipette_id,
-            new_labware_id=labware_id,
-            new_well_name=well_name,
-            new_deck_point=deck_point,
-        )
+        if isinstance(move_result, DefinedErrorData):
+            return move_result
 
         try:
             tip_geometry = await self._tip_handler.pick_up_tip(
@@ -141,13 +142,27 @@ class PickUpTipImplementation(AbstractCommandImpl[PickUpTipParams, _ExecuteRetur
                 well_name=well_name,
             )
         except PickUpTipTipNotAttachedError as e:
-            state_update_if_false_positive = update_types.StateUpdate()
-            state_update_if_false_positive.update_pipette_tip_state(
-                pipette_id=pipette_id,
-                tip_geometry=e.tip_geometry,
+            state_update_if_false_positive = (
+                update_types.StateUpdate.reduce(
+                    update_types.StateUpdate(), move_result.state_update
+                )
+                .update_pipette_tip_state(
+                    pipette_id=pipette_id,
+                    tip_geometry=e.tip_geometry,
+                )
+                .set_fluid_empty(pipette_id=pipette_id)
+                .mark_tips_as_used(
+                    pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
+                )
             )
-            state_update.mark_tips_as_used(
-                pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
+            state_update = (
+                update_types.StateUpdate.reduce(
+                    update_types.StateUpdate(), move_result.state_update
+                )
+                .mark_tips_as_used(
+                    pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
+                )
+                .set_fluid_unknown(pipette_id=pipette_id)
             )
             return DefinedErrorData(
                 public=TipPhysicallyMissingError(
@@ -165,32 +180,39 @@ class PickUpTipImplementation(AbstractCommandImpl[PickUpTipParams, _ExecuteRetur
                 state_update_if_false_positive=state_update_if_false_positive,
             )
         else:
-            state_update.update_pipette_tip_state(
-                pipette_id=pipette_id,
-                tip_geometry=tip_geometry,
-            )
-            state_update.mark_tips_as_used(
-                pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
+            state_update = (
+                move_result.state_update.update_pipette_tip_state(
+                    pipette_id=pipette_id,
+                    tip_geometry=tip_geometry,
+                )
+                .mark_tips_as_used(
+                    pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
+                )
+                .set_fluid_empty(pipette_id=pipette_id)
             )
             return SuccessData(
                 public=PickUpTipResult(
                     tipVolume=tip_geometry.volume,
                     tipLength=tip_geometry.length,
                     tipDiameter=tip_geometry.diameter,
-                    position=deck_point,
+                    position=move_result.public.position,
                 ),
                 state_update=state_update,
             )
 
 
 class PickUpTip(
-    BaseCommand[PickUpTipParams, PickUpTipResult, TipPhysicallyMissingError]
+    BaseCommand[
+        PickUpTipParams,
+        PickUpTipResult,
+        TipPhysicallyMissingError | StallOrCollisionError,
+    ]
 ):
     """Pick up tip command model."""
 
     commandType: PickUpTipCommandType = "pickUpTip"
     params: PickUpTipParams
-    result: Optional[PickUpTipResult]
+    result: Optional[PickUpTipResult] = None
 
     _ImplementationCls: Type[PickUpTipImplementation] = PickUpTipImplementation
 

opentrons/protocol_engine/commands/pipetting_common.py

@@ -1,11 +1,23 @@
 """Common pipetting command base models."""
-from opentrons_shared_data.errors import ErrorCodes
+
+from __future__ import annotations
+from typing import Literal, Tuple, TYPE_CHECKING
+
+from typing_extensions import TypedDict
 from pydantic import BaseModel, Field
-from typing import Literal, Optional, Tuple, TypedDict
 
+from opentrons_shared_data.errors import ErrorCodes
 from opentrons.protocol_engine.errors.error_occurrence import ErrorOccurrence
+from opentrons.protocol_engine.types import AspiratedFluid, FluidKind
+from opentrons_shared_data.errors.exceptions import PipetteOverpressureError
+from .command import DefinedErrorData, SuccessData
+from opentrons.protocol_engine.state.update_types import StateUpdate
 
-from ..types import WellLocation, LiquidHandlingWellLocation, DeckPoint
+
+if TYPE_CHECKING:
+    from ..execution.pipetting import PipettingHandler
+    from ..resources import ModelUtils
+    from ..notes import CommandNoteAdder
 
 
 class PipetteIdMixin(BaseModel):
@@ -51,72 +63,6 @@ class FlowRateMixin(BaseModel):
     )
 
 
-class WellLocationMixin(BaseModel):
-    """Mixin for command requests that take a location that's somewhere in a well."""
-
-    labwareId: str = Field(
-        ...,
-        description="Identifier of labware to use.",
-    )
-    wellName: str = Field(
-        ...,
-        description="Name of well to use in labware.",
-    )
-    wellLocation: WellLocation = Field(
-        default_factory=WellLocation,
-        description="Relative well location at which to perform the operation",
-    )
-
-
-class LiquidHandlingWellLocationMixin(BaseModel):
-    """Mixin for command requests that take a location that's somewhere in a well."""
-
-    labwareId: str = Field(
-        ...,
-        description="Identifier of labware to use.",
-    )
-    wellName: str = Field(
-        ...,
-        description="Name of well to use in labware.",
-    )
-    wellLocation: LiquidHandlingWellLocation = Field(
-        default_factory=LiquidHandlingWellLocation,
-        description="Relative well location at which to perform the operation",
-    )
-
-
-class MovementMixin(BaseModel):
-    """Mixin for command requests that move a pipette."""
-
-    minimumZHeight: Optional[float] = Field(
-        None,
-        description=(
-            "Optional minimal Z margin in mm."
-            " If this is larger than the API's default safe Z margin,"
-            " it will make the arc higher. If it's smaller, it will have no effect."
-        ),
-    )
-
-    forceDirect: bool = Field(
-        False,
-        description=(
-            "If true, moving from one labware/well to another"
-            " will not arc to the default safe z,"
-            " but instead will move directly to the specified location."
-            " This will also force the `minimumZHeight` param to be ignored."
-            " A 'direct' movement is in X/Y/Z simultaneously."
-        ),
-    )
-
-    speed: Optional[float] = Field(
-        None,
-        description=(
-            "Override the travel speed in mm/s."
-            " This controls the straight linear speed of motion."
-        ),
-    )
-
-
 class BaseLiquidHandlingResult(BaseModel):
     """Base properties of a liquid handling result."""
 
@@ -127,24 +73,8 @@ class BaseLiquidHandlingResult(BaseModel):
     )
 
 
-class DestinationPositionResult(BaseModel):
-    """Mixin for command results that move a pipette."""
-
-    # todo(mm, 2024-08-02): Consider deprecating or redefining this.
-    #
-    # This is here because opentrons.protocol_engine needed it for internal bookkeeping
-    # and, at the time, we didn't have a way to do that without adding this to the
-    # public command results. Its usefulness to callers outside
-    # opentrons.protocol_engine is questionable because they would need to know which
-    # critical point is in play, and I think that can change depending on obscure
-    # things like labware quirks.
-    position: DeckPoint = Field(
-        DeckPoint(x=0, y=0, z=0),
-        description=(
-            "The (x,y,z) coordinates of the pipette's critical point in deck space"
-            " after the move was completed."
-        ),
-    )
+class EmptyResult(BaseModel):
+    """A result with no data."""
 
 
 class ErrorLocationInfo(TypedDict):
@@ -208,3 +138,155 @@ class TipPhysicallyAttachedError(ErrorOccurrence):
     detail: str = ErrorCodes.TIP_DROP_FAILED.value.detail
 
     errorInfo: ErrorLocationInfo
+
+
+async def prepare_for_aspirate(
+    pipette_id: str,
+    pipetting: PipettingHandler,
+    model_utils: ModelUtils,
+    location_if_error: ErrorLocationInfo,
+) -> SuccessData[EmptyResult] | DefinedErrorData[OverpressureError]:
+    """Execute pipetting.prepare_for_aspirate, handle errors, and marshal success."""
+    try:
+        await pipetting.prepare_for_aspirate(pipette_id)
+    except PipetteOverpressureError as e:
+        return DefinedErrorData(
+            public=OverpressureError(
+                id=model_utils.generate_id(),
+                createdAt=model_utils.get_timestamp(),
+                wrappedErrors=[
+                    ErrorOccurrence.from_failed(
+                        id=model_utils.generate_id(),
+                        createdAt=model_utils.get_timestamp(),
+                        error=e,
+                    )
+                ],
+                errorInfo=location_if_error,
+            ),
+            state_update=StateUpdate().set_fluid_unknown(pipette_id=pipette_id),
+        )
+    else:
+        return SuccessData(
+            public=EmptyResult(),
+            state_update=StateUpdate().set_fluid_empty(pipette_id=pipette_id),
+        )
+
+
+async def aspirate_in_place(
+    pipette_id: str,
+    volume: float,
+    flow_rate: float,
+    location_if_error: ErrorLocationInfo,
+    command_note_adder: CommandNoteAdder,
+    pipetting: PipettingHandler,
+    model_utils: ModelUtils,
+) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
+    """Execute an aspirate in place microoperation."""
+    try:
+        volume_aspirated = await pipetting.aspirate_in_place(
+            pipette_id=pipette_id,
+            volume=volume,
+            flow_rate=flow_rate,
+            command_note_adder=command_note_adder,
+        )
+    except PipetteOverpressureError as e:
+        return DefinedErrorData(
+            public=OverpressureError(
+                id=model_utils.generate_id(),
+                createdAt=model_utils.get_timestamp(),
+                wrappedErrors=[
+                    ErrorOccurrence.from_failed(
+                        id=model_utils.generate_id(),
+                        createdAt=model_utils.get_timestamp(),
+                        error=e,
+                    )
+                ],
+                errorInfo=location_if_error,
+            ),
+            state_update=StateUpdate().set_fluid_unknown(pipette_id=pipette_id),
+        )
+    else:
+        return SuccessData(
+            public=BaseLiquidHandlingResult(
+                volume=volume_aspirated,
+            ),
+            state_update=StateUpdate().set_fluid_aspirated(
+                pipette_id=pipette_id,
+                fluid=AspiratedFluid(kind=FluidKind.LIQUID, volume=volume_aspirated),
+            ),
+        )
+
+
+async def dispense_in_place(
+    pipette_id: str,
+    volume: float,
+    flow_rate: float,
+    push_out: float | None,
+    location_if_error: ErrorLocationInfo,
+    pipetting: PipettingHandler,
+    model_utils: ModelUtils,
+) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
+    """Dispense-in-place as a microoperation."""
+    try:
+        volume = await pipetting.dispense_in_place(
+            pipette_id=pipette_id,
+            volume=volume,
+            flow_rate=flow_rate,
+            push_out=push_out,
+        )
+    except PipetteOverpressureError as e:
+        return DefinedErrorData(
+            public=OverpressureError(
+                id=model_utils.generate_id(),
+                createdAt=model_utils.get_timestamp(),
+                wrappedErrors=[
+                    ErrorOccurrence.from_failed(
+                        id=model_utils.generate_id(),
+                        createdAt=model_utils.get_timestamp(),
+                        error=e,
+                    )
+                ],
+                errorInfo=location_if_error,
+            ),
+            state_update=StateUpdate().set_fluid_unknown(pipette_id=pipette_id),
+        )
+    else:
+        return SuccessData(
+            public=BaseLiquidHandlingResult(volume=volume),
+            state_update=StateUpdate().set_fluid_ejected(
+                pipette_id=pipette_id, volume=volume
+            ),
+        )
+
+
+async def blow_out_in_place(
+    pipette_id: str,
+    flow_rate: float,
+    location_if_error: ErrorLocationInfo,
+    pipetting: PipettingHandler,
+    model_utils: ModelUtils,
+) -> SuccessData[EmptyResult] | DefinedErrorData[OverpressureError]:
+    """Execute a blow-out-in-place micro-operation."""
+    try:
+        await pipetting.blow_out_in_place(pipette_id=pipette_id, flow_rate=flow_rate)
+    except PipetteOverpressureError as e:
+        return DefinedErrorData(
+            public=OverpressureError(
+                id=model_utils.generate_id(),
+                createdAt=model_utils.get_timestamp(),
+                wrappedErrors=[
+                    ErrorOccurrence.from_failed(
+                        id=model_utils.generate_id(),
+                        createdAt=model_utils.get_timestamp(),
+                        error=e,
+                    )
+                ],
+                errorInfo=location_if_error,
+            ),
+            state_update=StateUpdate().set_fluid_unknown(pipette_id=pipette_id),
+        )
+    else:
+        return SuccessData(
+            public=EmptyResult(),
+            state_update=StateUpdate().set_fluid_empty(pipette_id=pipette_id),
+        )

opentrons/protocol_engine/commands/prepare_to_aspirate.py

@@ -1,15 +1,11 @@
 """Prepare to aspirate command request, result, and implementation models."""
 
 from __future__ import annotations
-from opentrons_shared_data.errors.exceptions import PipetteOverpressureError
 from pydantic import BaseModel
 from typing import TYPE_CHECKING, Optional, Type, Union
 from typing_extensions import Literal
 
-from .pipetting_common import (
-    OverpressureError,
-    PipetteIdMixin,
-)
+from .pipetting_common import OverpressureError, PipetteIdMixin, prepare_for_aspirate
 from .command import (
     AbstractCommandImpl,
     BaseCommand,
@@ -61,39 +57,34 @@ class PrepareToAspirateImplementation(
         self._model_utils = model_utils
         self._gantry_mover = gantry_mover
 
+    def _transform_result(
+        self, result: SuccessData[BaseModel]
+    ) -> SuccessData[PrepareToAspirateResult]:
+        return SuccessData(
+            public=PrepareToAspirateResult(), state_update=result.state_update
+        )
+
     async def execute(self, params: PrepareToAspirateParams) -> _ExecuteReturn:
         """Prepare the pipette to aspirate."""
         current_position = await self._gantry_mover.get_position(params.pipetteId)
-        try:
-            await self._pipetting_handler.prepare_for_aspirate(
-                pipette_id=params.pipetteId,
-            )
-        except PipetteOverpressureError as e:
-            return DefinedErrorData(
-                public=OverpressureError(
-                    id=self._model_utils.generate_id(),
-                    createdAt=self._model_utils.get_timestamp(),
-                    wrappedErrors=[
-                        ErrorOccurrence.from_failed(
-                            id=self._model_utils.generate_id(),
-                            createdAt=self._model_utils.get_timestamp(),
-                            error=e,
-                        )
-                    ],
-                    errorInfo=(
-                        {
-                            "retryLocation": (
-                                current_position.x,
-                                current_position.y,
-                                current_position.z,
-                            )
-                        }
-                    ),
-                ),
-            )
+        prepare_result = await prepare_for_aspirate(
+            pipette_id=params.pipetteId,
+            pipetting=self._pipetting_handler,
+            model_utils=self._model_utils,
+            location_if_error={
+                "retryLocation": (
+                    current_position.x,
+                    current_position.y,
+                    current_position.z,
+                )
+            },
+        )
+        if isinstance(prepare_result, DefinedErrorData):
+            return prepare_result
         else:
             return SuccessData(
                 public=PrepareToAspirateResult(),
+                state_update=prepare_result.state_update,
             )
 
 
@@ -104,7 +95,7 @@ class PrepareToAspirate(
 
     commandType: PrepareToAspirateCommandType = "prepareToAspirate"
     params: PrepareToAspirateParams
-    result: Optional[PrepareToAspirateResult]
+    result: Optional[PrepareToAspirateResult] = None
 
     _ImplementationCls: Type[
         PrepareToAspirateImplementation

opentrons/protocol_engine/commands/reload_labware.py

@@ -89,7 +89,7 @@ class ReloadLabware(
 
     commandType: ReloadLabwareCommandType = "reloadLabware"
     params: ReloadLabwareParams
-    result: Optional[ReloadLabwareResult]
+    result: Optional[ReloadLabwareResult] = None
 
     _ImplementationCls: Type[ReloadLabwareImplementation] = ReloadLabwareImplementation
 

opentrons/protocol_engine/commands/retract_axis.py

@@ -61,7 +61,7 @@ class RetractAxis(BaseCommand[RetractAxisParams, RetractAxisResult, ErrorOccurre
 
     commandType: RetractAxisCommandType = "retractAxis"
     params: RetractAxisParams
-    result: Optional[RetractAxisResult]
+    result: Optional[RetractAxisResult] = None
 
     _ImplementationCls: Type[RetractAxisImplementation] = RetractAxisImplementation
 

opentrons/protocol_engine/commands/robot/__init__.py

@@ -1 +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,86 @@
+"""Command models for opening a gripper jaw."""
+from __future__ import annotations
+from typing import Literal, Type, Optional, 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 ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+from opentrons.protocol_engine.errors.error_occurrence import ErrorOccurrence
+
+
+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,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: closeGripperJawParams
+    ) -> SuccessData[closeGripperJawResult]:
+        """Release the gripper."""
+        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