fix(api): Add ready-to-aspirate into engine state so analysis correctly fails (#17636)

<!--
Thanks for taking the time to open a Pull Request (PR)! Please make sure
you've read the "Opening Pull Requests" section of our Contributing
Guide:


https://github.com/Opentrons/opentrons/blob/edge/CONTRIBUTING.md#opening-pull-requests

GitHub provides robust markdown to format your PR. Links, diagrams,
pictures, and videos along with text formatting make it possible to
create a rich and informative PR. For more information on GitHub
markdown, see:


https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

To ensure your code is reviewed quickly and thoroughly, please fill out
the sections below to the best of your ability!
-->

# Overview

The "ready to aspirate" state was previously only known to the hardware
control layer, this adds the state updates to the protocol engine so
that commands will fail analysis when steps would produce an error at
runtime without removing any of the hardware layer checks.

This stems from a scenario where the following steps would produce a
"not ready to aspirate" error at runtime but pass analysis.

1. Pipette picks up tips
2. Does an air gap
3. Does an aspirate
4. does a dispense with push out
5. does an airgap command

Since we automatically do a prepare-to-aspirate as part of the aspirate
command and the pick up tip, it successfully passes step 2 but we don't
automatically do it during dispense or air gap so when the hardware
attempts to start step 5, and step 4 leaves it in an "not-ready" state
the hardware controller fails at runtime.

This PR updates all of the various protocol engine command that effect
the "ready" state to have a new StateUpdate element that stores the
current state in the state view. this way analysis will fail when a
particular order of calls would result in an illegal move.

<!--
Describe your PR at a high level. State acceptance criteria and how this
PR fits into other work. Link issues, PRs, and other relevant resources.
-->

## Test Plan and Hands on Testing

<!--
Describe your testing of the PR. Emphasize testing not reflected in the
code. Attach protocols, logs, screenshots and any other assets that
support your testing.
-->

## Changelog

<!--
List changes introduced by this PR considering future developers and the
end user. Give careful thought and clear documentation to breaking
changes.
-->

## Review requests

<!--
- What do you need from reviewers to feel confident this PR is ready to
merge?
- Ask questions.
-->

## Risk assessment

<!--
- Indicate the level of attention this PR needs.
- Provide context to guide reviewers.
- Discuss trade-offs, coupling, and side effects.
- Look for the possibility, even if you think it's small, that your
change may affect some other part of the system.
- For instance, changing return tip behavior may also change the
behavior of labware calibration.
- How do your unit tests and on hands on testing mitigate this PR's
risks and the risk of future regressions?
- Especially in high risk PRs, explain how you know your testing is
enough.
-->

Author: ryanthecoder

api/src/opentrons/hardware_control/api.py

@@ -1077,6 +1077,7 @@ async def dispense(
         rate: float = 1.0,
         push_out: Optional[float] = None,
         correction_volume: float = 0.0,
+        is_full_dispense: bool = False,
     ) -> None:
         """
         Dispense a volume of liquid in microliters(uL) using this pipette.

api/src/opentrons/hardware_control/instruments/ot3/pipette_handler.py

@@ -607,6 +607,7 @@ def plan_check_dispense(
         volume: Optional[float],
         rate: float,
         push_out: Optional[float],
+        is_full_dispense: bool,
         correction_volume: float = 0.0,
     ) -> Optional[LiquidActionSpec]:
         """Check preconditions for dispense, parse args, and calculate positions.
@@ -644,7 +645,21 @@ def plan_check_dispense(
         # of the OT-2 version of this class. Protocol Engine does its own clamping,
         # so we don't expect this to trigger in practice.
         disp_vol = min(instrument.current_volume, disp_vol)
-        is_full_dispense = numpy.isclose(instrument.current_volume - disp_vol, 0)
+
+        # TODO (Ryan): Remove this check in the future.
+        # we moved this logic up to protocol_engine but replacing with this check to make sure
+        # we don't accidentally call this incorrectly from somewhere else.
+        if not is_full_dispense and numpy.isclose(
+            instrument.current_volume - disp_vol, 0
+        ):
+            raise CommandPreconditionViolated(
+                message="Command created a full-dispense without the full dispense argument",
+                detail={
+                    "command": "dispense",
+                    "current-volume": str(instrument.current_volume),
+                    "dispense-volume": str(disp_vol),
+                },
+            )
 
         if disp_vol == 0:
             return None

api/src/opentrons/hardware_control/ot3api.py

@@ -2100,6 +2100,7 @@ async def dispense(
         rate: float = 1.0,
         push_out: Optional[float] = None,
         correction_volume: float = 0.0,
+        is_full_dispense: bool = False,
     ) -> None:
         """
         Dispense a volume of liquid in microliters(uL) using this pipette."""
@@ -2109,6 +2110,7 @@ async def dispense(
             volume=volume,
             rate=rate,
             push_out=push_out,
+            is_full_dispense=is_full_dispense,
             correction_volume=correction_volume,
         )
         if not dispense_spec:
@@ -3049,6 +3051,7 @@ async def dispense_while_tracking(
         volume: float,
         push_out: Optional[float],
         flow_rate: float = 1.0,
+        is_full_dispense: bool = False,
     ) -> None:
         """
         Dispense a volume of liquid (in microliters/uL) while moving the z axis synchronously.
@@ -3060,7 +3063,7 @@ async def dispense_while_tracking(
         """
         realmount = OT3Mount.from_mount(mount)
         dispense_spec = self._pipette_handler.plan_check_dispense(
-            realmount, volume, flow_rate, push_out
+            realmount, volume, flow_rate, push_out, is_full_dispense
         )
         if not dispense_spec:
             return

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

@@ -146,6 +146,7 @@ async def dispense(
         rate: float = 1.0,
         push_out: Optional[float] = None,
         correction_volume: float = 0.0,
+        is_full_dispense: bool = False,
     ) -> None:
         """
         Dispense a volume of liquid in microliters(uL) using this pipette
@@ -167,6 +168,7 @@ async def dispense_while_tracking(
         volume: float,
         push_out: Optional[float],
         flow_rate: float = 1.0,
+        is_full_dispense: bool = False,
     ) -> None:
         """
         Dispense a volume of liquid (in microliters/uL) while moving the z axis synchronously.

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

@@ -85,9 +85,8 @@ async def execute(self, params: AirGapInPlaceParams) -> _ExecuteReturn:
             PipetteNotReadyToAirGapError: pipette plunger is not ready.
         """
         ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
-            pipette_id=params.pipetteId,
+            pipette_id=params.pipetteId
         )
-
         if not ready_to_aspirate:
             raise PipetteNotReadyToAspirateError(
                 "Pipette cannot air gap in place because of a previous blow out."

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

@@ -83,7 +83,7 @@ async def execute(self, params: AspirateInPlaceParams) -> _ExecuteReturn:
             PipetteNotReadyToAspirateError: pipette plunger is not ready.
         """
         ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
-            pipette_id=params.pipetteId,
+            pipette_id=params.pipetteId
         )
         if not ready_to_aspirate:
             raise PipetteNotReadyToAspirateError(

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

@@ -91,8 +91,8 @@ async def execute(self, params: AspirateWhileTrackingParams) -> _ExecuteReturn:
             TipNotAttachedError: if no tip is attached to the pipette.
             PipetteNotReadyToAspirateError: pipette plunger is not ready.
         """
-        ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
-            pipette_id=params.pipetteId,
+        ready_to_aspirate = self._state_view.pipettes.get_ready_to_aspirate(
+            pipette_id=params.pipetteId
         )
         if not ready_to_aspirate:
             raise PipetteNotReadyToAspirateError(

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

@@ -115,6 +115,8 @@ async def execute(self, params: BlowOutParams) -> _ExecuteReturn:
                 public=BlowOutResult(position=move_result.public.position),
                 state_update=StateUpdate.reduce(
                     move_result.state_update, blow_out_result.state_update
+                ).set_pipette_ready_to_aspirate(
+                    pipette_id=params.pipetteId, ready_to_aspirate=False
                 ),
             )
 

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

@@ -89,7 +89,10 @@ async def execute(self, params: BlowOutInPlaceParams) -> _ExecuteReturn:
         if isinstance(result, DefinedErrorData):
             return result
         return SuccessData(
-            public=BlowOutInPlaceResult(), state_update=result.state_update
+            public=BlowOutInPlaceResult(),
+            state_update=result.state_update.set_pipette_ready_to_aspirate(
+                pipette_id=params.pipetteId, ready_to_aspirate=False
+            ),
         )
 
 

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

@@ -74,6 +74,9 @@ async def execute(
             config=pipette_result.static_config,
             serial_number=pipette_result.serial_number,
         )
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_result.pipette_id, ready_to_aspirate=False
+        )
 
         return SuccessData(
             public=ConfigureForVolumeResult(),

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

@@ -4,7 +4,6 @@
 from typing import TYPE_CHECKING, Optional, Type, Union, Any
 from typing_extensions import Literal
 
-
 from pydantic import Field
 from pydantic.json_schema import SkipJsonSchema
 

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, Type, Union, Any
 from typing_extensions import Literal
+
 from pydantic import Field
 from pydantic.json_schema import SkipJsonSchema
 

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

@@ -190,6 +190,9 @@ async def _execute_common(  # noqa: C901
             well_location=params.wellLocation,
         )
     except PipetteLiquidNotFoundError as exception:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=exception,
             state_update=move_result.state_update,
@@ -223,6 +226,9 @@ async def _execute_common(  # noqa: C901
             ),
         )
     else:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=z_pos,
             state_update=move_result.state_update,

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

@@ -138,6 +138,9 @@ async def execute(
             config=loaded_pipette.static_config,
         )
         state_update.set_fluid_unknown(pipette_id=loaded_pipette.pipette_id)
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_id=loaded_pipette.pipette_id, ready_to_aspirate=False
+        ),
 
         return SuccessData(
             public=LoadPipetteResult(pipetteId=loaded_pipette.pipette_id),

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

@@ -189,6 +189,9 @@ async def execute(
                     pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
                 )
                 .set_fluid_empty(pipette_id=pipette_id)
+                .set_pipette_ready_to_aspirate(
+                    pipette_id=pipette_id, ready_to_aspirate=True
+                )
             )
             return SuccessData(
                 public=PickUpTipResult(

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

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 from typing import Literal, Tuple, TYPE_CHECKING, Optional
-
+import numpy
 from typing_extensions import TypedDict
 from pydantic import BaseModel, Field
 
@@ -292,6 +292,12 @@ async def dispense_while_tracking(
     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,
@@ -300,6 +306,7 @@ async def dispense_while_tracking(
             volume=volume,
             flow_rate=flow_rate,
             push_out=push_out,
+            is_full_dispense=is_full_dispense,
         )
     except PipetteOverpressureError as e:
         return DefinedErrorData(
@@ -315,16 +322,24 @@ async def dispense_while_tracking(
                 ],
                 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_dispensed,
             ),
-            state_update=StateUpdate().set_fluid_ejected(
+            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
             ),
         )
 
@@ -340,12 +355,19 @@ async def dispense_in_place(
     model_utils: ModelUtils,
 ) -> SuccessData[BaseLiquidHandlingResult] | DefinedErrorData[OverpressureError]:
     """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:
@@ -362,13 +384,20 @@ 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:
+        print(f"Volume {volume}")
         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
             ),
         )
 

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

@@ -84,7 +84,9 @@ async def execute(self, params: PrepareToAspirateParams) -> _ExecuteReturn:
         else:
             return SuccessData(
                 public=PrepareToAspirateResult(),
-                state_update=prepare_result.state_update,
+                state_update=prepare_result.state_update.set_pipette_ready_to_aspirate(
+                    pipette_id=params.pipetteId, ready_to_aspirate=True
+                ),
             )
 
 

api/src/opentrons/protocol_engine/commands/unsafe/unsafe_blow_out_in_place.py

@@ -69,7 +69,9 @@ async def execute(
         )
         state_update = update_types.StateUpdate()
         state_update.set_fluid_empty(pipette_id=params.pipetteId)
-
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_id=params.pipetteId, ready_to_aspirate=False
+        )
         return SuccessData(
             public=UnsafeBlowOutInPlaceResult(), state_update=state_update
         )