fix(api): home before retrieving gantry position for disengaged Z mounts in FLEX

api/src/opentrons/hardware_control/api.py

@@ -762,7 +762,7 @@ async def move_to(
             top_types.Point(0, 0, 0),
         )
 
-        await self._cache_and_maybe_retract_mount(mount)
+        await self.prepare_for_mount_movement(mount)
         await self._move(target_position, speed=speed, max_speeds=max_speeds)
 
     async def move_axes(
@@ -822,7 +822,7 @@ async def move_rel(
                 detail={"mount": str(mount), "unhomed_axes": str(unhomed)},
             )
 
-        await self._cache_and_maybe_retract_mount(mount)
+        await self.prepare_for_mount_movement(mount)
         await self._move(
             target_position,
             speed=speed,
@@ -842,6 +842,9 @@ async def _cache_and_maybe_retract_mount(self, mount: top_types.Mount) -> None:
             await self.retract(self._last_moved_mount, 10)
         self._last_moved_mount = mount
 
+    async def prepare_for_mount_movement(self, mount: top_types.Mount) -> None:
+        await self._cache_and_maybe_retract_mount(mount)
+
     @ExecutionManagerProvider.wait_for_running
     async def _move(
         self,

api/src/opentrons/hardware_control/ot3api.py

@@ -247,6 +247,23 @@ def estop_cb(event: HardwareEvent) -> None:
         OT3RobotCalibrationProvider.__init__(self, self._config)
         ExecutionManagerProvider.__init__(self, isinstance(backend, OT3Simulator))
 
+    def is_idle_mount(self, mount: Union[top_types.Mount, OT3Mount]) -> bool:
+        """Only the gripper mount or the 96-channel pipette mount would be idle
+        (disengaged).
+
+        If gripper mount is NOT the last moved mount, it's idle.
+        If a 96-channel pipette is attached, the mount is idle if it's not
+        the last moved mount.
+        """
+        realmount = OT3Mount.from_mount(mount)
+        if not self._last_moved_mount or realmount == self._last_moved_mount:
+            return False
+
+        return (
+            realmount == OT3Mount.LEFT
+            and self._gantry_load == GantryLoad.HIGH_THROUGHPUT
+        ) or (realmount == OT3Mount.GRIPPER)
+
     @property
     def door_state(self) -> DoorState:
         return self._door_state
@@ -1150,7 +1167,7 @@ async def move_to(
         else:
             checked_max = None
 
-        await self._cache_and_maybe_retract_mount(realmount)
+        await self.prepare_for_mount_movement(realmount)
         await self._move(
             target_position,
             speed=speed,
@@ -1261,7 +1278,8 @@ async def move_rel(
             checked_max: Optional[OT3AxisMap[float]] = max_speeds
         else:
             checked_max = None
-        await self._cache_and_maybe_retract_mount(realmount)
+
+        await self.prepare_for_mount_movement(realmount)
         await self._move(
             target_position,
             speed=speed,
@@ -1271,15 +1289,20 @@ async def move_rel(
         )
 
     async def _cache_and_maybe_retract_mount(self, mount: OT3Mount) -> None:
-        """Retract the 'other' mount if necessary
+        """Retract the 'other' mount if necessary.
 
         If `mount` does not match the value in :py:attr:`_last_moved_mount`
         (and :py:attr:`_last_moved_mount` exists) then retract the mount
         in :py:attr:`_last_moved_mount`. Also unconditionally update
         :py:attr:`_last_moved_mount` to contain `mount`.
 
-        Disengage the 96-channel and gripper mount if retracted.
+        Disengage the 96-channel and gripper mount if retracted. Re-engage
+        the 96-channel or gripper mount if it is about to move.
         """
+        if self.is_idle_mount(mount):
+            # home the left/gripper mount if it is current disengaged
+            await self.home_z(mount)
+
         if mount != self._last_moved_mount and self._last_moved_mount:
             await self.retract(self._last_moved_mount, 10)
 
@@ -1298,8 +1321,16 @@ async def _cache_and_maybe_retract_mount(self, mount: OT3Mount) -> None:
 
         if mount != OT3Mount.GRIPPER:
             await self.idle_gripper()
+
         self._last_moved_mount = mount
 
+    async def prepare_for_mount_movement(
+        self, mount: Union[top_types.Mount, OT3Mount]
+    ) -> None:
+        """Retract the idle mount if necessary."""
+        realmount = OT3Mount.from_mount(mount)
+        await self._cache_and_maybe_retract_mount(realmount)
+
     async def idle_gripper(self) -> None:
         """Move gripper to its idle, gripped position."""
         try:

api/src/opentrons/hardware_control/protocols/motion_controller.py

@@ -226,3 +226,7 @@ def should_taskify_movement_execution(self, taskify: bool) -> None:
     async def cancel_execution_and_running_tasks(self) -> None:
         """Cancel all tasks and set execution manager state to Cancelled."""
         ...
+
+    async def prepare_for_mount_movement(self, mount: MountArgType) -> None:
+        """Retract the other mount if necessary."""
+        ...

api/src/opentrons/protocol_engine/commands/calibration/move_to_maintenance_position.py

@@ -82,10 +82,7 @@ async def execute(
         )
         # the 96-channel mount is disengaged during gripper calibration and
         #  must be homed before the gantry position can be called
-        if ot3_api.encoder_status_ok(Axis.Z_L) and not ot3_api.motor_status_ok(
-            Axis.Z_L
-        ):
-            await ot3_api.home([Axis.Z_L])
+        await ot3_api.prepare_for_mount_movement(Mount.LEFT)
         current_position_mount = await ot3_api.gantry_position(
             Mount.LEFT, critical_point=CriticalPoint.MOUNT
         )
@@ -105,6 +102,7 @@ async def execute(
             Point(x=_ATTACH_POINT.x, y=_ATTACH_POINT.y, z=max_height_z_mount),
         ]
 
+        await ot3_api.prepare_for_mount_movement(Mount.LEFT)
         for movement in movement_points:
             await ot3_api.move_to(
                 mount=Mount.LEFT,

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

@@ -75,6 +75,11 @@ async def home(self, axes: Optional[List[MotorAxis]]) -> None:
 
     async def retract_axis(self, axis: MotorAxis) -> None:
         """Retract the specified axis to its home position."""
+        ...
+
+    async def prepare_for_mount_movement(self, mount: Mount) -> None:
+        """Retract the 'idle' mount if necessary."""
+        ...
 
 
 class HardwareGantryMover(GantryMover):
@@ -211,6 +216,10 @@ async def retract_axis(self, axis: MotorAxis) -> None:
             )
         await self._hardware_api.retract_axis(axis=hardware_axis)
 
+    async def prepare_for_mount_movement(self, mount: Mount) -> None:
+        """Retract the 'idle' mount if necessary."""
+        await self._hardware_api.prepare_for_mount_movement(mount)
+
 
 class VirtualGantryMover(GantryMover):
     """State store based gantry movement handler for simulation/analysis."""
@@ -286,6 +295,10 @@ async def retract_axis(self, axis: MotorAxis) -> None:
         """Retract the specified axis. No-op in virtual implementation."""
         pass
 
+    async def prepare_for_mount_movement(self, mount: Mount) -> None:
+        """Retract the 'idle' mount if necessary."""
+        pass
+
 
 def create_gantry_mover(
     state_view: StateView, hardware_api: HardwareControlAPI

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

@@ -111,6 +111,9 @@ async def move_to_well(
         )
         origin_cp = pipette_location.critical_point
 
+        await self._gantry_mover.prepare_for_mount_movement(
+            pipette_location.mount.to_hw_mount()
+        )
         origin = await self._gantry_mover.get_position(pipette_id=pipette_id)
         max_travel_z = self._gantry_mover.get_max_travel_z(pipette_id=pipette_id)
 
@@ -180,6 +183,9 @@ async def move_to_addressable_area(
         )
         origin_cp = pipette_location.critical_point
 
+        await self._gantry_mover.prepare_for_mount_movement(
+            pipette_location.mount.to_hw_mount()
+        )
         origin = await self._gantry_mover.get_position(pipette_id=pipette_id)
         max_travel_z = self._gantry_mover.get_max_travel_z(pipette_id=pipette_id)
 
@@ -237,6 +243,13 @@ async def move_to_coordinates(
         speed: Optional[float] = None,
     ) -> Point:
         """Move pipette to a given deck coordinate."""
+        # get the pipette's mount, if applicable
+        pipette_location = self._state_store.motion.get_pipette_location(
+            pipette_id=pipette_id
+        )
+        await self._gantry_mover.prepare_for_mount_movement(
+            pipette_location.mount.to_hw_mount()
+        )
         origin = await self._gantry_mover.get_position(pipette_id=pipette_id)
         max_travel_z = self._gantry_mover.get_max_travel_z(pipette_id=pipette_id)