opentrons 8.2.0a4__py2.py3-none-any.whl → 8.3.0a1__py2.py3-none-any.whl

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]
+
+    _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]
+
+    _ImplementationCls: Type[
+        MoveAxesRelativeImplementation
+    ] = MoveAxesRelativeImplementation
+
+
+class MoveAxesRelativeCreate(BaseCommandCreate[MoveAxesRelativeParams]):
+    """MoveAxesRelative command request model."""
+
+    commandType: MoveAxesRelativeCommandType = "robot/moveAxesRelative"
+    params: MoveAxesRelativeParams
+
+    _CommandCls: Type[MoveAxesRelative] = MoveAxesRelative