feat(api): add WellVolumeOffset to WellLocation

api/src/opentrons/protocol_api/core/engine/instrument.py

@@ -146,12 +146,10 @@ def aspirate(
             well_name = well_core.get_name()
             labware_id = well_core.labware_id
 
-            well_location = (
-                self._engine_client.state.geometry.get_relative_well_location(
-                    labware_id=labware_id,
-                    well_name=well_name,
-                    absolute_point=location.point,
-                )
+            well_location = self._engine_client.state.geometry.get_relative_liquid_handling_well_location(
+                labware_id=labware_id,
+                well_name=well_name,
+                absolute_point=location.point,
             )
             pipette_movement_conflict.check_safe_for_pipette_movement(
                 engine_state=self._engine_client.state,
@@ -237,12 +235,10 @@ def dispense(
             well_name = well_core.get_name()
             labware_id = well_core.labware_id
 
-            well_location = (
-                self._engine_client.state.geometry.get_relative_well_location(
-                    labware_id=labware_id,
-                    well_name=well_name,
-                    absolute_point=location.point,
-                )
+            well_location = self._engine_client.state.geometry.get_relative_liquid_handling_well_location(
+                labware_id=labware_id,
+                well_name=well_name,
+                absolute_point=location.point,
             )
             pipette_movement_conflict.check_safe_for_pipette_movement(
                 engine_state=self._engine_client.state,
@@ -314,12 +310,10 @@ def blow_out(
             well_name = well_core.get_name()
             labware_id = well_core.labware_id
 
-            well_location = (
-                self._engine_client.state.geometry.get_relative_well_location(
-                    labware_id=labware_id,
-                    well_name=well_name,
-                    absolute_point=location.point,
-                )
+            well_location = self._engine_client.state.geometry.get_relative_liquid_handling_well_location(
+                labware_id=labware_id,
+                well_name=well_name,
+                absolute_point=location.point,
             )
             pipette_movement_conflict.check_safe_for_pipette_movement(
                 engine_state=self._engine_client.state,
@@ -416,10 +410,12 @@ def pick_up_tip(
         well_name = well_core.get_name()
         labware_id = well_core.labware_id
 
-        well_location = self._engine_client.state.geometry.get_relative_well_location(
-            labware_id=labware_id,
-            well_name=well_name,
-            absolute_point=location.point,
+        well_location = (
+            self._engine_client.state.geometry.get_relative_pick_up_tip_well_location(
+                labware_id=labware_id,
+                well_name=well_name,
+                absolute_point=location.point,
+            )
         )
         pipette_movement_conflict.check_safe_for_tip_pickup_and_return(
             engine_state=self._engine_client.state,

api/src/opentrons/protocol_api/core/engine/pipette_movement_conflict.py

@@ -19,6 +19,8 @@
     DeckSlotLocation,
     OnLabwareLocation,
     WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
     DropTipWellLocation,
 )
 from opentrons.protocol_engine.types import (
@@ -66,7 +68,12 @@ def check_safe_for_pipette_movement(
     pipette_id: str,
     labware_id: str,
     well_name: str,
-    well_location: Union[WellLocation, DropTipWellLocation],
+    well_location: Union[
+        WellLocation,
+        LiquidHandlingWellLocation,
+        PickUpTipWellLocation,
+        DropTipWellLocation,
+    ],
 ) -> None:
     """Check if the labware is safe to move to with a pipette in partial tip configuration.
 

api/src/opentrons/protocol_engine/__init__.py

@@ -47,6 +47,8 @@
     LoadedPipette,
     MotorAxis,
     WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
     DropTipWellLocation,
     WellOrigin,
     DropTipWellOrigin,
@@ -109,6 +111,8 @@
     "LoadedPipette",
     "MotorAxis",
     "WellLocation",
+    "LiquidHandlingWellLocation",
+    "PickUpTipWellLocation",
     "DropTipWellLocation",
     "WellOrigin",
     "DropTipWellOrigin",

api/src/opentrons/protocol_engine/commands/aspirate.py

@@ -9,7 +9,7 @@
     PipetteIdMixin,
     AspirateVolumeMixin,
     FlowRateMixin,
-    WellLocationMixin,
+    LiquidHandlingWellLocationMixin,
     BaseLiquidHandlingResult,
     DestinationPositionResult,
 )
@@ -21,6 +21,7 @@
     SuccessData,
 )
 from ..errors.error_occurrence import ErrorOccurrence
+from ..errors import InvalidAspirateLocationError
 
 from opentrons.hardware_control import HardwareControlAPI
 
@@ -38,7 +39,7 @@
 
 
 class AspirateParams(
-    PipetteIdMixin, AspirateVolumeMixin, FlowRateMixin, WellLocationMixin
+    PipetteIdMixin, AspirateVolumeMixin, FlowRateMixin, LiquidHandlingWellLocationMixin
 ):
     """Parameters required to aspirate from a specific well."""
 
@@ -112,12 +113,21 @@ async def execute(self, params: AspirateParams) -> _ExecuteReturn:
                 well_name=well_name,
             )
 
+        well_location = params.wellLocation
+        if well_location.origin == WellOrigin.MENISCUS:
+            well_location.volumeOffset = "operationVolume"
+            if well_location.offset.z > 0.0:
+                raise InvalidAspirateLocationError(
+                    f"Cannot specify a meniscus-relative Aspirate with a positive z-offset (specified {well_location.offset.z})"
+                )
+
         position = await self._movement.move_to_well(
             pipette_id=pipette_id,
             labware_id=labware_id,
             well_name=well_name,
-            well_location=params.wellLocation,
+            well_location=well_location,
             current_well=current_well,
+            operation_volume=-params.volume,
         )
         deck_point = DeckPoint.construct(x=position.x, y=position.y, z=position.z)
         state_update.set_pipette_location(

api/src/opentrons/protocol_engine/commands/blow_out.py

@@ -9,7 +9,7 @@
 from .pipetting_common import (
     PipetteIdMixin,
     FlowRateMixin,
-    WellLocationMixin,
+    LiquidHandlingWellLocationMixin,
     DestinationPositionResult,
 )
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
@@ -25,7 +25,7 @@
 BlowOutCommandType = Literal["blowout"]
 
 
-class BlowOutParams(PipetteIdMixin, FlowRateMixin, WellLocationMixin):
+class BlowOutParams(PipetteIdMixin, FlowRateMixin, LiquidHandlingWellLocationMixin):
     """Payload required to blow-out a specific well."""
 
     pass

api/src/opentrons/protocol_engine/commands/dispense.py

@@ -7,13 +7,13 @@
 
 from pydantic import Field
 
-from ..types import DeckPoint
+from ..types import DeckPoint, WellOrigin
 from ..state.update_types import StateUpdate
 from .pipetting_common import (
     PipetteIdMixin,
     DispenseVolumeMixin,
     FlowRateMixin,
-    WellLocationMixin,
+    LiquidHandlingWellLocationMixin,
     BaseLiquidHandlingResult,
     DestinationPositionResult,
     OverpressureError,
@@ -30,13 +30,14 @@
 if TYPE_CHECKING:
     from ..execution import MovementHandler, PipettingHandler
     from ..resources import ModelUtils
+    from ..state.state import StateView
 
 
 DispenseCommandType = Literal["dispense"]
 
 
 class DispenseParams(
-    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, WellLocationMixin
+    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, LiquidHandlingWellLocationMixin
 ):
     """Payload required to dispense to a specific well."""
 
@@ -63,37 +64,52 @@ class DispenseImplementation(AbstractCommandImpl[DispenseParams, _ExecuteReturn]
 
     def __init__(
         self,
+        state_view: StateView,
         movement: MovementHandler,
         pipetting: PipettingHandler,
         model_utils: ModelUtils,
         **kwargs: object,
     ) -> None:
+        self._state_view = state_view
         self._movement = movement
         self._pipetting = pipetting
         self._model_utils = model_utils
 
     async def execute(self, params: DispenseParams) -> _ExecuteReturn:
         """Move to and dispense to the requested well."""
         state_update = StateUpdate()
+        well_location = params.wellLocation
+        labware_id = params.labwareId
+        well_name = params.wellName
+        volume = params.volume
+
+        if well_location.origin == WellOrigin.MENISCUS:
+            well_location.volumeOffset = 0.0
+        self._state_view.geometry.validate_dispense_volume_into_well(
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+            volume=volume,
+        )
 
         position = await self._movement.move_to_well(
             pipette_id=params.pipetteId,
-            labware_id=params.labwareId,
-            well_name=params.wellName,
-            well_location=params.wellLocation,
+            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=params.pipetteId,
-            new_labware_id=params.labwareId,
-            new_well_name=params.wellName,
+            new_labware_id=labware_id,
+            new_well_name=well_name,
             new_deck_point=deck_point,
         )
 
         try:
             volume = await self._pipetting.dispense_in_place(
                 pipette_id=params.pipetteId,
-                volume=params.volume,
+                volume=volume,
                 flow_rate=params.flowRate,
                 push_out=params.pushOut,
             )

api/src/opentrons/protocol_engine/commands/move_to_well.py

@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING, Optional, Type
 from typing_extensions import Literal
 
-from ..types import DeckPoint
+from ..types import DeckPoint, WellOrigin
 from .pipetting_common import (
     PipetteIdMixin,
     WellLocationMixin,
@@ -13,9 +13,11 @@
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
 from ..state import update_types
+from ..errors import LabwareIsTipRackError
 
 if TYPE_CHECKING:
     from ..execution import MovementHandler
+    from ..state.state import StateView
 
 MoveToWellCommandType = Literal["moveToWell"]
 
@@ -37,29 +39,44 @@ class MoveToWellImplementation(
 ):
     """Move to well command implementation."""
 
-    def __init__(self, movement: MovementHandler, **kwargs: object) -> None:
+    def __init__(
+        self, state_view: StateView, movement: MovementHandler, **kwargs: object
+    ) -> None:
+        self._state_view = state_view
         self._movement = movement
 
     async def execute(
         self, params: MoveToWellParams
     ) -> SuccessData[MoveToWellResult, None]:
         """Move the requested pipette to the requested well."""
+        pipette_id = params.pipetteId
+        labware_id = params.labwareId
+        well_name = params.wellName
+        well_location = params.wellLocation
+
         state_update = update_types.StateUpdate()
 
+        if (self._state_view.labware.is_tiprack(labware_id)) and (
+            well_location.origin == WellOrigin.MENISCUS or well_location.volumeOffset
+        ):
+            raise LabwareIsTipRackError(
+                "Cannot specify a WellLocation with an origin of MENISCUS or any volumeOffset with movement to a tip rack"
+            )
+
         x, y, z = await self._movement.move_to_well(
-            pipette_id=params.pipetteId,
-            labware_id=params.labwareId,
-            well_name=params.wellName,
-            well_location=params.wellLocation,
+            pipette_id=pipette_id,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
             force_direct=params.forceDirect,
             minimum_z_height=params.minimumZHeight,
             speed=params.speed,
         )
         deck_point = DeckPoint.construct(x=x, y=y, z=z)
         state_update.set_pipette_location(
-            pipette_id=params.pipetteId,
-            new_labware_id=params.labwareId,
-            new_well_name=params.wellName,
+            pipette_id=pipette_id,
+            new_labware_id=labware_id,
+            new_well_name=well_name,
             new_deck_point=deck_point,
         )
 

api/src/opentrons/protocol_engine/commands/pick_up_tip.py

@@ -9,10 +9,9 @@
 from ..errors import ErrorOccurrence, TipNotAttachedError
 from ..resources import ModelUtils
 from ..state import update_types
-from ..types import DeckPoint
+from ..types import PickUpTipWellLocation, DeckPoint
 from .pipetting_common import (
     PipetteIdMixin,
-    WellLocationMixin,
     DestinationPositionResult,
 )
 from .command import (
@@ -31,10 +30,15 @@
 PickUpTipCommandType = Literal["pickUpTip"]
 
 
-class PickUpTipParams(PipetteIdMixin, WellLocationMixin):
+class PickUpTipParams(PipetteIdMixin):
     """Payload needed to move a pipette to a specific well."""
 
-    pass
+    labwareId: str = Field(..., description="Identifier of labware to use.")
+    wellName: str = Field(..., description="Name of well to use in labware.")
+    wellLocation: PickUpTipWellLocation = Field(
+        default_factory=PickUpTipWellLocation,
+        description="Relative well location at which to pick up the tip.",
+    )
 
 
 class PickUpTipResult(DestinationPositionResult):
@@ -106,10 +110,12 @@ async def execute(
         pipette_id = params.pipetteId
         labware_id = params.labwareId
         well_name = params.wellName
-        well_location = params.wellLocation
 
         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(
             pipette_id=pipette_id,
             labware_id=labware_id,