opentrons 8.3.2__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

opentrons/protocol_engine/commands/move_labware.py

@@ -1,7 +1,8 @@
 """Models and implementation for the ``moveLabware`` command."""
 
 from __future__ import annotations
-from typing import TYPE_CHECKING, Optional, Type, Any
+from typing import TYPE_CHECKING, Optional, Type, Any, List
+from typing_extensions import TypedDict  # note: need this instead of typing for py<3.12
 
 from pydantic.json_schema import SkipJsonSchema
 from pydantic import BaseModel, Field
@@ -18,7 +19,7 @@ from opentrons.types import Point
 from ..types import (
     ModuleModel,
     CurrentWell,
-    LabwareLocation,
+    LoadableLabwareLocation,
     DeckSlotLocation,
     ModuleLocation,
     OnLabwareLocation,
@@ -26,6 +27,9 @@ from ..types import (
     LabwareMovementStrategy,
     LabwareOffsetVector,
     LabwareMovementOffsetData,
+    LabwareLocationSequence,
+    NotOnDeckLocationSequenceComponent,
+    OFF_DECK_LOCATION,
 )
 from ..errors import (
     LabwareMovementNotAllowedError,
@@ -64,7 +68,9 @@ class MoveLabwareParams(BaseModel):
     """Input parameters for a ``moveLabware`` command."""
 
     labwareId: str = Field(..., description="The ID of the labware to move.")
-    newLocation: LabwareLocation = Field(..., description="Where to move the labware.")
+    newLocation: LoadableLabwareLocation = Field(
+        ..., description="Where to move the labware."
+    )
     strategy: LabwareMovementStrategy = Field(
         ...,
         description="Whether to use the gripper to perform the labware movement"
@@ -100,6 +106,31 @@ class MoveLabwareResult(BaseModel):
             " so the default of (0, 0, 0) will be used."
         ),
     )
+    eventualDestinationLocationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description=(
+            "The full location in which this labware will eventually reside. This will typically be the same as its "
+            "immediate destination, but if this labware is going to the trash then this field will be off deck."
+        ),
+    )
+    immediateDestinationLocationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description=(
+            "The full location to which this labware is being moved, right now."
+        ),
+    )
+    originLocationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description="The full location down to the deck of the labware before this command.",
+    )
+
+
+class ErrorDetails(TypedDict):
+    """Location details for a failed gripper move."""
+
+    originLocationSequence: LabwareLocationSequence
+    immediateDestinationLocationSequence: LabwareLocationSequence
+    eventualDestinationLocationSequence: LabwareLocationSequence
 
 
 class GripperMovementError(ErrorOccurrence):
@@ -112,6 +143,8 @@ class GripperMovementError(ErrorOccurrence):
 
     errorType: Literal["gripperMovement"] = "gripperMovement"
 
+    errorInfo: ErrorDetails
+
 
 _ExecuteReturn = SuccessData[MoveLabwareResult] | DefinedErrorData[GripperMovementError]
 
@@ -152,6 +185,11 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
                 f"Cannot move fixed trash labware '{current_labware_definition.parameters.loadName}'."
             )
 
+        origin_location_sequence = self._state_view.geometry.get_location_sequence(
+            params.labwareId
+        )
+        eventual_destination_location_sequence: LabwareLocationSequence | None = None
+
         if isinstance(params.newLocation, AddressableAreaLocation):
             area_name = params.newLocation.addressableAreaName
             if (
@@ -181,9 +219,19 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
                     y=0,
                     z=0,
                 )
+                eventual_destination_location_sequence = [
+                    NotOnDeckLocationSequenceComponent(
+                        logicalLocationName=OFF_DECK_LOCATION
+                    )
+                ]
             elif fixture_validation.is_trash(area_name):
                 # When dropping labware in the trash bins we want to ensure they are lids
                 # and enforce a y-axis drop offset to ensure they fall within the trash bin
+                eventual_destination_location_sequence = [
+                    NotOnDeckLocationSequenceComponent(
+                        logicalLocationName=OFF_DECK_LOCATION
+                    )
+                ]
                 if labware_validation.validate_definition_is_lid(
                     self._state_view.labware.get_definition(params.labwareId)
                 ):
@@ -220,7 +268,7 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
         )
 
         # Check that labware and destination do not have labware on top
-        self._state_view.labware.raise_if_labware_has_labware_on_top(
+        self._state_view.labware.raise_if_labware_has_non_lid_labware_on_top(
             labware_id=params.labwareId
         )
 
@@ -282,7 +330,6 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
                 raise LabwareMovementNotAllowedError(
                     f"Cannot move adapter '{current_labware_definition.parameters.loadName}' with gripper."
                 )
-
             validated_current_loc = (
                 self._state_view.geometry.ensure_valid_gripper_location(
                     current_labware.location
@@ -299,6 +346,16 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
             if trash_lid_drop_offset:
                 user_offset_data.dropOffset += trash_lid_drop_offset
 
+            immediate_destination_location_sequence = (
+                self._state_view.geometry.get_predicted_location_sequence(
+                    validated_new_loc
+                )
+            )
+            if eventual_destination_location_sequence is None:
+                eventual_destination_location_sequence = (
+                    immediate_destination_location_sequence
+                )
+
             try:
                 # Skips gripper moves when using virtual gripper
                 await self._labware_movement.move_labware_with_gripper(
@@ -315,20 +372,23 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
                 # todo(mm, 2024-09-26): Catch LabwareNotPickedUpError when that exists and
                 # move_labware_with_gripper() raises it.
             ) as exception:
-                gripper_movement_error: GripperMovementError | None = (
-                    GripperMovementError(
-                        id=self._model_utils.generate_id(),
-                        createdAt=self._model_utils.get_timestamp(),
-                        errorCode=exception.code.value.code,
-                        detail=exception.code.value.detail,
-                        wrappedErrors=[
-                            ErrorOccurrence.from_failed(
-                                id=self._model_utils.generate_id(),
-                                createdAt=self._model_utils.get_timestamp(),
-                                error=exception,
-                            )
-                        ],
-                    )
+                gripper_movement_error: GripperMovementError | None = GripperMovementError(
+                    id=self._model_utils.generate_id(),
+                    createdAt=self._model_utils.get_timestamp(),
+                    errorCode=exception.code.value.code,
+                    detail=exception.code.value.detail,
+                    errorInfo={
+                        "originLocationSequence": origin_location_sequence,
+                        "immediateDestinationLocationSequence": immediate_destination_location_sequence,
+                        "eventualDestinationLocationSequence": eventual_destination_location_sequence,
+                    },
+                    wrappedErrors=[
+                        ErrorOccurrence.from_failed(
+                            id=self._model_utils.generate_id(),
+                            createdAt=self._model_utils.get_timestamp(),
+                            error=exception,
+                        )
+                    ],
                 )
             else:
                 gripper_movement_error = None
@@ -344,7 +404,27 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
 
         elif params.strategy == LabwareMovementStrategy.MANUAL_MOVE_WITH_PAUSE:
             # Pause to allow for manual labware movement
+            immediate_destination_location_sequence = (
+                self._state_view.geometry.get_predicted_location_sequence(
+                    params.newLocation
+                )
+            )
+            if eventual_destination_location_sequence is None:
+                eventual_destination_location_sequence = (
+                    immediate_destination_location_sequence
+                )
+
             await self._run_control.wait_for_resume()
+        else:
+            immediate_destination_location_sequence = (
+                self._state_view.geometry.get_predicted_location_sequence(
+                    params.newLocation
+                )
+            )
+            if eventual_destination_location_sequence is None:
+                eventual_destination_location_sequence = (
+                    immediate_destination_location_sequence
+                )
 
         # We may have just moved the labware that contains the current well out from
         # under the pipette. Clear the current location to reflect the fact that the
@@ -364,8 +444,47 @@ class MoveLabwareImplementation(AbstractCommandImpl[MoveLabwareParams, _ExecuteR
             new_offset_id=new_offset_id,
         )
 
+        if labware_validation.validate_definition_is_lid(
+            definition=self._state_view.labware.get_definition(params.labwareId)
+        ):
+            parent_updates: List[str] = []
+            lid_updates: List[str | None] = []
+            # when moving a lid between locations we need to:
+            if (
+                isinstance(current_labware.location, OnLabwareLocation)
+                and self._state_view.labware.get_lid_by_labware_id(
+                    current_labware.location.labwareId
+                )
+                is not None
+            ):
+                # if the source location was a parent labware and not a lid stack or lid, update the parent labware lid ID to None (no more lid)
+                parent_updates.append(current_labware.location.labwareId)
+                lid_updates.append(None)
+
+            # If we're moving to a non lid object, add to the setlids list of things to do
+            if isinstance(
+                available_new_location, OnLabwareLocation
+            ) and not labware_validation.validate_definition_is_lid(
+                self._state_view.labware.get_definition(
+                    available_new_location.labwareId
+                )
+            ):
+                parent_updates.append(available_new_location.labwareId)
+                lid_updates.append(params.labwareId)
+            # Add to setlids
+            if len(parent_updates) > 0:
+                state_update.set_lids(
+                    parent_labware_ids=parent_updates,
+                    lid_ids=lid_updates,
+                )
+
         return SuccessData(
-            public=MoveLabwareResult(offsetId=new_offset_id),
+            public=MoveLabwareResult(
+                offsetId=new_offset_id,
+                originLocationSequence=origin_location_sequence,
+                immediateDestinationLocationSequence=immediate_destination_location_sequence,
+                eventualDestinationLocationSequence=eventual_destination_location_sequence,
+            ),
             state_update=state_update,
         )
 

opentrons/protocol_engine/commands/move_to_well.py

@@ -8,7 +8,7 @@ from .pipetting_common import (
     PipetteIdMixin,
 )
 from .movement_common import (
-    WellLocationMixin,
+    LiquidHandlingWellLocationMixin,
     MovementMixin,
     DestinationPositionResult,
     StallOrCollisionError,
@@ -21,7 +21,6 @@ from .command import (
     SuccessData,
     DefinedErrorData,
 )
-from ..errors import LabwareIsTipRackError
 
 if TYPE_CHECKING:
     from ..execution import MovementHandler
@@ -31,7 +30,7 @@ if TYPE_CHECKING:
 MoveToWellCommandType = Literal["moveToWell"]
 
 
-class MoveToWellParams(PipetteIdMixin, WellLocationMixin, MovementMixin):
+class MoveToWellParams(PipetteIdMixin, LiquidHandlingWellLocationMixin, MovementMixin):
     """Payload required to move a pipette to a specific well."""
 
     pass
@@ -70,14 +69,9 @@ class MoveToWellImplementation(
         labware_id = params.labwareId
         well_name = params.wellName
         well_location = params.wellLocation
-
-        if (
-            self._state_view.labware.is_tiprack(labware_id)
-            and well_location.volumeOffset
-        ):
-            raise LabwareIsTipRackError(
-                "Cannot specify a WellLocation with a volumeOffset with movement to a tip rack"
-            )
+        # TODO(cm): implement move_to_well with meniscus + volume offset
+        if well_location.volumeOffset and well_location.volumeOffset != 0:
+            raise ValueError("volume offset not supported with MoveToWell")
 
         move_result = await move_to_well(
             model_utils=self._model_utils,

opentrons/protocol_engine/commands/pick_up_tip.py

@@ -150,7 +150,7 @@ class PickUpTipImplementation(AbstractCommandImpl[PickUpTipParams, _ExecuteRetur
                     pipette_id=pipette_id,
                     tip_geometry=e.tip_geometry,
                 )
-                .set_fluid_empty(pipette_id=pipette_id)
+                .set_fluid_empty(pipette_id=pipette_id, clean_tip=True)
                 .mark_tips_as_used(
                     pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
                 )
@@ -188,7 +188,10 @@ class PickUpTipImplementation(AbstractCommandImpl[PickUpTipParams, _ExecuteRetur
                 .mark_tips_as_used(
                     pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
                 )
-                .set_fluid_empty(pipette_id=pipette_id)
+                .set_fluid_empty(pipette_id=pipette_id, clean_tip=True)
+                .set_pipette_ready_to_aspirate(
+                    pipette_id=pipette_id, ready_to_aspirate=True
+                )
             )
             return SuccessData(
                 public=PickUpTipResult(

opentrons/protocol_engine/commands/pipetting_common.py

@@ -1,8 +1,8 @@
 """Common pipetting command base models."""
 
 from __future__ import annotations
-from typing import Literal, Tuple, TYPE_CHECKING
-
+from typing import Literal, Tuple, TYPE_CHECKING, Optional
+import numpy
 from typing_extensions import TypedDict
 from pydantic import BaseModel, Field
 
@@ -20,6 +20,10 @@ if TYPE_CHECKING:
     from ..notes import CommandNoteAdder
 
 
+DEFAULT_CORRECTION_VOLUME = 0.0
+"""Default correction volume (uL) for any aspirate/ dispense volume."""
+
+
 class PipetteIdMixin(BaseModel):
     """Mixin for command requests that take a pipette ID."""
 
@@ -41,6 +45,10 @@ class AspirateVolumeMixin(BaseModel):
         " There is some tolerance for floating point rounding errors.",
         ge=0,
     )
+    correctionVolume: Optional[float] = Field(
+        None,
+        description="The correction volume in uL.",
+    )
 
 
 class DispenseVolumeMixin(BaseModel):
@@ -53,6 +61,10 @@ class DispenseVolumeMixin(BaseModel):
         " There is some tolerance for floating point rounding errors.",
         ge=0,
     )
+    correctionVolume: Optional[float] = Field(
+        None,
+        description="The correction volume in uL.",
+    )
 
 
 class FlowRateMixin(BaseModel):
@@ -168,7 +180,11 @@ async def prepare_for_aspirate(
     else:
         return SuccessData(
             public=EmptyResult(),
-            state_update=StateUpdate().set_fluid_empty(pipette_id=pipette_id),
+            state_update=StateUpdate()
+            .set_fluid_empty(pipette_id=pipette_id)
+            .set_pipette_ready_to_aspirate(
+                pipette_id=pipette_id, ready_to_aspirate=True
+            ),
         )
 
 
@@ -176,18 +192,69 @@ async def aspirate_in_place(
     pipette_id: str,
     volume: float,
     flow_rate: float,
+    correction_volume: float,
     location_if_error: ErrorLocationInfo,
     command_note_adder: CommandNoteAdder,
     pipetting: PipettingHandler,
     model_utils: ModelUtils,
 ) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
-    """Execute an aspirate in place microoperation."""
+    """Execute an aspirate in place micro-operation."""
     try:
         volume_aspirated = await pipetting.aspirate_in_place(
             pipette_id=pipette_id,
             volume=volume,
             flow_rate=flow_rate,
             command_note_adder=command_note_adder,
+            correction_volume=correction_volume,
+        )
+    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 aspirate_while_tracking(
+    pipette_id: str,
+    labware_id: str,
+    well_name: 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 while tracking microoperation."""
+    try:
+        volume_aspirated = await pipetting.aspirate_while_tracking(
+            pipette_id=pipette_id,
+            labware_id=labware_id,
+            well_name=well_name,
+            volume=volume,
+            flow_rate=flow_rate,
+            command_note_adder=command_note_adder,
         )
     except PipetteOverpressureError as e:
         return DefinedErrorData(
@@ -217,22 +284,95 @@ async def aspirate_in_place(
         )
 
 
+async def dispense_while_tracking(
+    pipette_id: str,
+    labware_id: str,
+    well_name: str,
+    volume: float,
+    flow_rate: float,
+    push_out: float | None,
+    location_if_error: ErrorLocationInfo,
+    pipetting: PipettingHandler,
+    model_utils: ModelUtils,
+) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
+    """Execute an dispense while tracking microoperation."""
+    # The current volume won't be none since it passed validation
+    current_volume = (
+        pipetting.get_state_view().pipettes.get_aspirated_volume(pipette_id) or 0.0
+    )
+    is_full_dispense = bool(numpy.isclose(current_volume - volume, 0))
+    ready = push_out == 0 if push_out is not None else not is_full_dispense
+    try:
+        volume_dispensed = await pipetting.dispense_while_tracking(
+            pipette_id=pipette_id,
+            labware_id=labware_id,
+            well_name=well_name,
+            volume=volume,
+            flow_rate=flow_rate,
+            push_out=push_out,
+            is_full_dispense=is_full_dispense,
+        )
+    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)
+            .set_pipette_ready_to_aspirate(
+                pipette_id=pipette_id, ready_to_aspirate=False
+            ),
+        )
+    else:
+        return SuccessData(
+            public=BaseLiquidHandlingResult(
+                volume=volume_dispensed,
+            ),
+            state_update=StateUpdate()
+            .set_fluid_ejected(
+                pipette_id=pipette_id,
+                volume=volume_dispensed,
+            )
+            .set_pipette_ready_to_aspirate(
+                pipette_id=pipette_id, ready_to_aspirate=ready
+            ),
+        )
+
+
 async def dispense_in_place(
     pipette_id: str,
     volume: float,
     flow_rate: float,
     push_out: float | None,
+    correction_volume: float,
     location_if_error: ErrorLocationInfo,
     pipetting: PipettingHandler,
     model_utils: ModelUtils,
 ) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
-    """Dispense-in-place as a microoperation."""
+    """Dispense-in-place as a micro-operation."""
+    # The current volume won't be none since it passed validation
+    current_volume = (
+        pipetting.get_state_view().pipettes.get_aspirated_volume(pipette_id) or 0.0
+    )
+    is_full_dispense = bool(numpy.isclose(current_volume - volume, 0))
+    ready: bool = push_out == 0 if push_out is not None else not is_full_dispense
     try:
         volume = await pipetting.dispense_in_place(
             pipette_id=pipette_id,
             volume=volume,
             flow_rate=flow_rate,
             push_out=push_out,
+            is_full_dispense=is_full_dispense,
+            correction_volume=correction_volume,
         )
     except PipetteOverpressureError as e:
         return DefinedErrorData(
@@ -248,13 +388,19 @@ async def dispense_in_place(
                 ],
                 errorInfo=location_if_error,
             ),
-            state_update=StateUpdate().set_fluid_unknown(pipette_id=pipette_id),
+            state_update=StateUpdate()
+            .set_fluid_unknown(pipette_id=pipette_id)
+            .set_pipette_ready_to_aspirate(
+                pipette_id=pipette_id, ready_to_aspirate=False
+            ),
         )
     else:
         return SuccessData(
             public=BaseLiquidHandlingResult(volume=volume),
-            state_update=StateUpdate().set_fluid_ejected(
-                pipette_id=pipette_id, volume=volume
+            state_update=StateUpdate()
+            .set_fluid_ejected(pipette_id=pipette_id, volume=volume)
+            .set_pipette_ready_to_aspirate(
+                pipette_id=pipette_id, ready_to_aspirate=ready
             ),
         )
 
@@ -290,3 +436,8 @@ async def blow_out_in_place(
             public=EmptyResult(),
             state_update=StateUpdate().set_fluid_empty(pipette_id=pipette_id),
         )
+
+
+async def increase_evo_disp_count(pipette_id: str, pipetting: PipettingHandler) -> None:
+    """Tell a pipette to increase it's evo-tip-dispense-count in eeprom."""
+    await pipetting.increase_evo_disp_count(pipette_id)

opentrons/protocol_engine/commands/prepare_to_aspirate.py

@@ -5,7 +5,11 @@ from pydantic import BaseModel
 from typing import TYPE_CHECKING, Optional, Type, Union
 from typing_extensions import Literal
 
-from .pipetting_common import OverpressureError, PipetteIdMixin, prepare_for_aspirate
+from .pipetting_common import (
+    OverpressureError,
+    PipetteIdMixin,
+    prepare_for_aspirate,
+)
 from .command import (
     AbstractCommandImpl,
     BaseCommand,
@@ -66,6 +70,14 @@ class PrepareToAspirateImplementation(
 
     async def execute(self, params: PrepareToAspirateParams) -> _ExecuteReturn:
         """Prepare the pipette to aspirate."""
+        ready_to_aspirate = self._pipetting_handler.get_is_ready_to_aspirate(
+            pipette_id=params.pipetteId
+        )
+        if ready_to_aspirate:
+            return SuccessData(
+                public=PrepareToAspirateResult(),
+            )
+
         current_position = await self._gantry_mover.get_position(params.pipetteId)
         prepare_result = await prepare_for_aspirate(
             pipette_id=params.pipetteId,
@@ -79,13 +91,11 @@ class PrepareToAspirateImplementation(
                 )
             },
         )
+
         if isinstance(prepare_result, DefinedErrorData):
             return prepare_result
         else:
-            return SuccessData(
-                public=PrepareToAspirateResult(),
-                state_update=prepare_result.state_update,
-            )
+            return self._transform_result(prepare_result)
 
 
 class PrepareToAspirate(