fix(api): Limit how far up the gripper moves on the Z when opening/closing the plate reader lid. (#19118)

Author: vegano1

analyses-snapshot-testing/tests/__snapshots__/analyses_snapshot_test/test_analysis_snapshot[34f32336bc][Flex_X_v2_21_plate_reader_wrong_plate2].json

@@ -2437,7 +2437,7 @@
       "createdAt": "TIMESTAMP",
       "error": {
         "createdAt": "TIMESTAMP",
-        "detail": "Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16mm.",
+        "detail": "Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16.0mm.",
         "errorCode": "4000",
         "errorInfo": {},
         "errorType": "LabwareMovementNotAllowedError",
@@ -2477,7 +2477,7 @@
   "errors": [
     {
       "createdAt": "TIMESTAMP",
-      "detail": "ProtocolCommandFailedError [line 23]: Error 4000 GENERAL_ERROR (ProtocolCommandFailedError): LabwareMovementNotAllowedError: Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16mm.",
+      "detail": "ProtocolCommandFailedError [line 23]: Error 4000 GENERAL_ERROR (ProtocolCommandFailedError): LabwareMovementNotAllowedError: Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16.0mm.",
       "errorCode": "4000",
       "errorInfo": {},
       "errorType": "ExceptionInProtocolError",
@@ -2486,7 +2486,7 @@
       "wrappedErrors": [
         {
           "createdAt": "TIMESTAMP",
-          "detail": "LabwareMovementNotAllowedError: Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16mm.",
+          "detail": "LabwareMovementNotAllowedError: Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16.0mm.",
           "errorCode": "4000",
           "errorInfo": {},
           "errorType": "ProtocolCommandFailedError",
@@ -2495,7 +2495,7 @@
           "wrappedErrors": [
             {
               "createdAt": "TIMESTAMP",
-              "detail": "Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16mm.",
+              "detail": "Cannot move 'thermoscientificnunc_96_wellplate_2000ul' into plate reader because the maximum allowed labware height is 16.0mm.",
               "errorCode": "4000",
               "errorInfo": {},
               "errorType": "LabwareMovementNotAllowedError",

api/src/opentrons/motion_planning/waypoints.py

@@ -127,6 +127,7 @@ def get_gripper_labware_movement_waypoints(
     gripper_home_z: float,
     offset_data: LabwareMovementOffsetData,
     post_drop_slide_offset: Optional[Point],
+    gripper_home_z_offset: Optional[float] = None,
 ) -> List[GripperMovementWaypointsWithJawStatus]:
     """Get waypoints for moving labware using a gripper."""
     pick_up_offset = offset_data.pickUpOffset
@@ -139,6 +140,8 @@ def get_gripper_labware_movement_waypoints(
         drop_offset.x, drop_offset.y, drop_offset.z
     )
 
+    gripper_max_z_home = gripper_home_z - (gripper_home_z_offset or 0)
+
     post_drop_home_pos = Point(drop_location.x, drop_location.y, gripper_home_z)
 
     waypoints_with_jaw_status = [
@@ -152,12 +155,12 @@ def get_gripper_labware_movement_waypoints(
         ),
         # Gripper grips the labware here
         GripperMovementWaypointsWithJawStatus(
-            position=Point(pick_up_location.x, pick_up_location.y, gripper_home_z),
+            position=Point(pick_up_location.x, pick_up_location.y, gripper_max_z_home),
             jaw_open=False,
             dropping=False,
         ),
         GripperMovementWaypointsWithJawStatus(
-            position=Point(drop_location.x, drop_location.y, gripper_home_z),
+            position=Point(drop_location.x, drop_location.y, gripper_max_z_home),
             jaw_open=False,
             dropping=False,
         ),

api/src/opentrons/protocol_engine/commands/absorbance_reader/close_lid.py

@@ -12,10 +12,13 @@
 
 from ...state.update_types import StateUpdate
 
+from .common import LID_Z_CLEARANCE
+
 from opentrons.types import Point
 
 from opentrons.drivers.types import AbsorbanceReaderLidStatus
 
+
 if TYPE_CHECKING:
     from opentrons.protocol_engine.state.state import StateView
     from opentrons.protocol_engine.execution import (
@@ -119,6 +122,7 @@ async def execute(self, params: CloseLidParams) -> SuccessData[CloseLidResult]:
                 ),
                 user_drop_offset=Point.from_xyz_attrs(lid_gripper_offsets.dropOffset),
                 post_drop_slide_offset=None,
+                gripper_z_offset=LID_Z_CLEARANCE,
             )
             state_update.set_absorbance_reader_lid(
                 module_id=mod_substate.module_id,

api/src/opentrons/protocol_engine/commands/absorbance_reader/common.py

@@ -0,0 +1,6 @@
+"""Common absorbance reader defines."""
+
+# This needs to be re-defined because of circular imports
+_PLATE_READER_MAX_LABWARE_Z_MM = 16.0
+# Distance to home the gripper when moving the plate reader lid to/from the dock.
+LID_Z_CLEARANCE = _PLATE_READER_MAX_LABWARE_Z_MM + 40.0

api/src/opentrons/protocol_engine/commands/absorbance_reader/open_lid.py

@@ -14,6 +14,8 @@
 
 from opentrons.drivers.types import AbsorbanceReaderLidStatus
 
+from .common import LID_Z_CLEARANCE
+
 from ...state.update_types import StateUpdate
 
 
@@ -121,6 +123,7 @@ async def execute(self, params: OpenLidParams) -> SuccessData[OpenLidResult]:
                 ),
                 user_drop_offset=Point.from_xyz_attrs(lid_gripper_offsets.dropOffset),
                 post_drop_slide_offset=None,
+                gripper_z_offset=LID_Z_CLEARANCE,
             )
             state_update.set_absorbance_reader_lid(
                 module_id=mod_substate.module_id, is_lid_on=False

api/src/opentrons/protocol_engine/execution/labware_movement.py

@@ -111,6 +111,7 @@ async def move_labware_with_gripper(
         user_pick_up_offset: Point,
         user_drop_offset: Point,
         post_drop_slide_offset: Optional[Point],
+        gripper_z_offset: Optional[float],
     ) -> None:
         ...
 
@@ -124,6 +125,7 @@ async def move_labware_with_gripper(  # noqa: C901
         user_pick_up_offset: Point,
         user_drop_offset: Point,
         post_drop_slide_offset: Optional[Point],
+        gripper_z_offset: Optional[float] = None,
     ) -> None:
         """Physically move a labware from one location to another using the gripper.
 
@@ -206,6 +208,7 @@ async def move_labware_with_gripper(  # noqa: C901
                 gripper_home_z=gripper_homed_position.z,
                 offset_data=final_offsets,
                 post_drop_slide_offset=post_drop_slide_offset,
+                gripper_home_z_offset=gripper_z_offset,
             )
             labware_grip_force = self._state_store.labware.get_grip_force(
                 labware_definition

api/src/opentrons/protocol_engine/state/labware.py

@@ -93,7 +93,7 @@
 
 
 # The max height of the labware that can fit in a plate reader
-_PLATE_READER_MAX_LABWARE_Z_MM = 16
+_PLATE_READER_MAX_LABWARE_Z_MM = 16.0
 
 
 _WellDefinition = WellDefinition2 | WellDefinition3