feat(api): add latch_clearance param to the store_labware and dispense_labware commands.

Author: vegano1

api/src/opentrons/hardware_control/modules/flex_stacker.py

@@ -428,6 +428,9 @@ async def move_axis(
             max_speed=speed, acceleration=acceleration
         )
         distance = direction.distance(distance)
+        log.warning(
+            f"MOVE: Axis {axis} {distance} mm in the {direction} direction speed={speed} accel={acceleration}"
+        )
         res = await self._driver.move_in_mm(axis, distance, params=motion_params)
         if res == MoveResult.STALL_ERROR:
             self._stall_detected = True
@@ -458,6 +461,9 @@ async def home_axis(
         motion_params = default.move_params.update(
             max_speed=speed, acceleration=acceleration
         )
+        log.warning(
+            f"HOME: Axis {axis} in the {direction} direction speed={speed} accel={acceleration}"
+        )
         success = await self._driver.move_to_limit_switch(
             axis=axis, direction=direction, params=motion_params
         )
@@ -513,8 +519,10 @@ async def dispense_labware(
         labware_height: float,
         enforce_hopper_lw_sensing: bool = True,
         enforce_shuttle_lw_sensing: bool = True,
+        latch_clearance: Optional[float] = None,
     ) -> None:
         """Dispenses the next labware in the stacker."""
+        log.warning(f"DISPENSE: {labware_height}")
         self.verify_labware_height(labware_height)
         await self._prepare_for_action()
         if enforce_hopper_lw_sensing:
@@ -526,7 +534,8 @@ async def dispense_labware(
 
         # Transfer
         await self.open_latch()
-        latch_clear_distance = labware_height + PLATFORM_OFFSET - LATCH_CLEARANCE
+        latch_clearance = latch_clearance or LATCH_CLEARANCE
+        latch_clear_distance = labware_height + PLATFORM_OFFSET - latch_clearance
         await self.move_axis(StackerAxis.Z, Direction.RETRACT, latch_clear_distance)
         await self.close_latch()
 
@@ -543,8 +552,10 @@ async def store_labware(
         self,
         labware_height: float,
         enforce_shuttle_lw_sensing: bool = True,
+        latch_clearance: Optional[float] = None,
     ) -> None:
         """Stores a labware in the stacker."""
+        log.warning(f"STORE: {labware_height}")
         self.verify_labware_height(labware_height)
         await self._prepare_for_action()
 
@@ -554,7 +565,8 @@ async def store_labware(
             await self.verify_shuttle_labware_presence(Direction.RETRACT, True)
 
         # Move the Z so the labware sits right under any labware already stored
-        latch_clear_distance = labware_height + PLATFORM_OFFSET + LATCH_CLEARANCE
+        latch_clearance = latch_clearance or LATCH_CLEARANCE
+        latch_clear_distance = labware_height + PLATFORM_OFFSET + latch_clearance
         distance = MAX_TRAVEL[StackerAxis.Z] - latch_clear_distance
         await self.move_axis(StackerAxis.Z, Direction.EXTEND, distance)
 

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

@@ -724,14 +724,15 @@ class FlexStackerCore(ModuleCore, AbstractFlexStackerCore[LabwareCore]):
 
     _sync_module_hardware: SynchronousAdapter[hw_modules.FlexStacker]
 
-    def retrieve(self) -> LabwareCore:
+    def retrieve(self, latch_clearance: Optional[float] = None) -> LabwareCore:
         """Retrieve a labware from the Flex Stacker's hopper.
 
         Returns the primary labware.
         """
         self._engine_client.execute_command(
             cmd.flex_stacker.RetrieveParams(
                 moduleId=self.module_id,
+                latchClearance=latch_clearance,
             )
         )
         base = self._protocol_core.get_labware_on_module(self)
@@ -742,11 +743,12 @@ def retrieve(self) -> LabwareCore:
                 return primary
         return base
 
-    def store(self) -> None:
+    def store(self, latch_clearance: Optional[float] = None) -> None:
         """Store a labware into Flex Stacker's hopper."""
         self._engine_client.execute_command(
             cmd.flex_stacker.StoreParams(
                 moduleId=self.module_id,
+                latchClearance=latch_clearance,
             )
         )
 

api/src/opentrons/protocol_api/core/module.py

@@ -407,14 +407,14 @@ def get_serial_number(self) -> str:
         """Get the module's unique hardware serial number."""
 
     @abstractmethod
-    def retrieve(self) -> AbstractLabware[Any]:
+    def retrieve(self, latch_clearance: Optional[float] = None) -> AbstractLabware[Any]:
         """Release a labware from the hopper to the staging slot.
 
         Returns the retreived primary labware.
         """
 
     @abstractmethod
-    def store(self) -> None:
+    def store(self, latch_clearance: Optional[float] = None) -> None:
         """Store a labware in the stacker hopper."""
 
     @abstractmethod

api/src/opentrons/protocol_api/module_contexts.py

@@ -1130,15 +1130,15 @@ def serial_number(self) -> str:
         return self._core.get_serial_number()
 
     @requires_version(2, 25)
-    def retrieve(self) -> Labware:
+    def retrieve(self, latch_clearance: Optional[float] = None) -> Labware:
         """Retrieve a labware from the Flex Stacker and place it on the shuttle.
 
         :returns: The retrieved :py:class:`Labware` object. This will always be the main labware,
                   even if the Flex Stacker contains labware on an adapter. To get the adapter object,
                   call :py:class:`Labware.parent` on the returned labware.
 
         """
-        labware_core = self._core.retrieve()
+        labware_core = self._core.retrieve(latch_clearance=latch_clearance)
 
         return self._core_map.get_or_add(
             labware_core,
@@ -1148,9 +1148,9 @@ def retrieve(self) -> Labware:
         )
 
     @requires_version(2, 25)
-    def store(self) -> None:
+    def store(self, latch_clearance: Optional[float] = None) -> None:
         """Move the labware currently on the Flex Stacker shuttle into the Flex Stacker."""
-        self._core.store()
+        self._core.store(latch_clearance=latch_clearance)
 
     def _labware_to_cores(self, labware: Sequence[Labware]) -> list[LabwareCore]:
         return [labware._core for labware in labware]

api/src/opentrons/protocol_engine/commands/flex_stacker/retrieve.py

@@ -91,6 +91,10 @@ class RetrieveParams(BaseModel):
         description="Do not use. Present for internal backward compatibility.",
         json_schema_extra=_remove_default,
     )
+    latchClearance: float | SkipJsonSchema[None] = Field(
+        None,
+        description="optional latch clearance",
+    )
 
 
 class RetrieveResult(BaseModel):
@@ -269,7 +273,8 @@ async def execute(self, params: RetrieveParams) -> _ExecuteReturn:
             try:
                 stacker_hw.set_stacker_identify(True)
                 await stacker_hw.dispense_labware(
-                    labware_height=stacker_state.get_pool_height_minus_overlap()
+                    labware_height=stacker_state.get_pool_height_minus_overlap(),
+                    latch_clearance=params.latchClearance,
                 )
             except (
                 FlexStackerStallError,

api/src/opentrons/protocol_engine/commands/flex_stacker/store.py

@@ -59,6 +59,10 @@ class StoreParams(BaseModel):
         ...,
         description="Unique ID of the flex stacker.",
     )
+    latchClearance: float | SkipJsonSchema[None] = Field(
+        None,
+        description="optional latch clearance",
+    )
 
 
 class StoreResult(BaseModel):
@@ -205,7 +209,8 @@ async def execute(self, params: StoreParams) -> _ExecuteReturn:
             if stacker_hw is not None:
                 stacker_hw.set_stacker_identify(True)
                 await stacker_hw.store_labware(
-                    labware_height=stacker_state.get_pool_height_minus_overlap()
+                    labware_height=stacker_state.get_pool_height_minus_overlap(),
+                    latch_clearance=params.latchClearance,
                 )
         except FlexStackerStallError as e:
             return DefinedErrorData(