feat(api): store and use disposal locations in the location cache

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

@@ -392,12 +392,7 @@ def dispense(
                     )
                 )
 
-        if isinstance(location, (TrashBin, WasteChute)):
-            self._protocol_core.set_last_location(location=None, mount=self.get_mount())
-        else:
-            self._protocol_core.set_last_location(
-                location=location, mount=self.get_mount()
-            )
+        self._protocol_core.set_last_location(location=location, mount=self.get_mount())
 
     def blow_out(
         self,
@@ -473,12 +468,7 @@ def blow_out(
                 )
             )
 
-        if isinstance(location, (TrashBin, WasteChute)):
-            self._protocol_core.set_last_location(location=None, mount=self.get_mount())
-        else:
-            self._protocol_core.set_last_location(
-                location=location, mount=self.get_mount()
-            )
+        self._protocol_core.set_last_location(location=location, mount=self.get_mount())
 
     def touch_tip(
         self,
@@ -806,12 +796,8 @@ def move_to(
                         speed=speed,
                     )
                 )
-        if isinstance(location, (TrashBin, WasteChute)):
-            self._protocol_core.set_last_location(location=None, mount=self.get_mount())
-        else:
-            self._protocol_core.set_last_location(
-                location=location, mount=self.get_mount()
-            )
+
+        self._protocol_core.set_last_location(location=location, mount=self.get_mount())
 
     def resin_tip_seal(
         self, location: Location, well_core: WellCore, in_place: Optional[bool] = False

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

@@ -112,7 +112,7 @@ def __init__(
         self._engine_client = engine_client
         self._api_version = api_version
         self._sync_hardware = sync_hardware
-        self._last_location: Optional[Location] = None
+        self._last_location: Optional[Union[Location, TrashBin, WasteChute]] = None
         self._last_mount: Optional[Mount] = None
         self._labware_cores_by_id: Dict[str, LabwareCore] = {}
         self._module_cores_by_id: Dict[
@@ -892,7 +892,7 @@ def door_closed(self) -> bool:
     def get_last_location(
         self,
         mount: Optional[Mount] = None,
-    ) -> Optional[Location]:
+    ) -> Optional[Union[Location, TrashBin, WasteChute]]:
         """Get the last accessed location."""
         if mount is None or mount == self._last_mount:
             return self._last_location
@@ -901,7 +901,7 @@ def get_last_location(
 
     def set_last_location(
         self,
-        location: Optional[Location],
+        location: Optional[Union[Location, TrashBin, WasteChute]],
         mount: Optional[Mount] = None,
     ) -> None:
         """Set the last accessed location."""

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

@@ -216,7 +216,7 @@ def door_closed(self) -> bool:
     def get_last_location(
         self,
         mount: Optional[Mount] = None,
-    ) -> Optional[Location]:
+    ) -> Optional[Union[Location, TrashBin, WasteChute]]:
         ...
 
     @abstractmethod

api/src/opentrons/protocol_api/instrument_context.py

@@ -258,7 +258,7 @@ def aspirate(
                 "knows where it is."
             ) from e
 
-        if isinstance(target, (TrashBin, WasteChute)):
+        if isinstance(target, validation.DisposalTarget):
             raise ValueError(
                 "Trash Bin and Waste Chute are not acceptable location parameters for Aspirate commands."
             )
@@ -399,6 +399,10 @@ def dispense(
 
         .. versionchanged:: 2.17
             Behavior of the ``volume`` parameter.
+
+        .. versionchanged:: 2.24
+            ``location`` is no longer required if the pipette just moved to, dispensed, or blew out
+            into a trash bin or waste chute.
         """
         if self.api_version < APIVersion(2, 15) and push_out:
             raise APIVersionError(
@@ -432,24 +436,24 @@ def dispense(
 
         flow_rate = self._core.get_dispense_flow_rate(rate)
 
-        if isinstance(target, (TrashBin, WasteChute)):
+        if isinstance(target, validation.DisposalTarget):
             with publisher.publish_context(
                 broker=self.broker,
                 command=cmds.dispense_in_disposal_location(
                     instrument=self,
                     volume=c_vol,
-                    location=target,
+                    location=target.location,
                     rate=rate,
                     flow_rate=flow_rate,
                 ),
             ):
                 self._core.dispense(
                     volume=c_vol,
                     rate=rate,
-                    location=target,
+                    location=target.location,
                     well_core=None,
                     flow_rate=flow_rate,
-                    in_place=False,
+                    in_place=target.in_place,
                     push_out=push_out,
                     meniscus_tracking=None,
                 )
@@ -656,6 +660,10 @@ def blow_out(
                               without first calling a method that takes a location, like
                               :py:meth:`.aspirate` or :py:meth:`dispense`.
         :returns: This instance.
+
+        .. versionchanged:: 2.24
+            ``location`` is no longer required if the pipette just moved to, dispensed, or blew out
+            into a trash bin or waste chute.
         """
         well: Optional[labware.Well] = None
         move_to_location: types.Location
@@ -696,17 +704,17 @@ def blow_out(
             well = target.well
         elif isinstance(target, validation.PointTarget):
             move_to_location = target.location
-        elif isinstance(target, (TrashBin, WasteChute)):
+        elif isinstance(target, validation.DisposalTarget):
             with publisher.publish_context(
                 broker=self.broker,
                 command=cmds.blow_out_in_disposal_location(
-                    instrument=self, location=target
+                    instrument=self, location=target.location
                 ),
             ):
                 self._core.blow_out(
-                    location=target,
+                    location=target.location,
                     well_core=None,
-                    in_place=False,
+                    in_place=target.in_place,
                 )
             return self
 
@@ -793,8 +801,12 @@ def touch_tip(  # noqa: C901
         # If location is a valid well, move to the well first
         if location is None:
             last_location = self._protocol_core.get_last_location()
-            if not last_location:
-                raise RuntimeError("No valid current location cache present")
+            if last_location is None or isinstance(
+                last_location, (TrashBin, WasteChute)
+            ):
+                raise RuntimeError(
+                    f"Cached location of {last_location} is not valid for touch tip."
+                )
             parent_labware, well = last_location.labware.get_parent_labware_and_well()
             if not well or not parent_labware:
                 raise RuntimeError(
@@ -896,10 +908,10 @@ def air_gap(  # noqa: C901
 
         .. versionchanged:: 2.22
             No longer implemented as an aspirate.
-
         .. versionchanged:: 2.24
             Adds the ``rate`` and ``flow_rate`` parameter. You can only define one or the other. If
             both are unspecified then ``rate`` is by default set to 1.0.
+            Can air gap over a trash bin or waste chute.
         """
         if not self._core.has_tip():
             raise UnexpectedTipRemovalError("air_gap", self.name, self.mount)
@@ -923,10 +935,23 @@ def air_gap(  # noqa: C901
 
         if height is None:
             height = 5
-        loc = self._protocol_core.get_last_location()
-        if not loc or not loc.labware.is_well:
-            raise RuntimeError("No previous Well cached to perform air gap")
-        target = loc.labware.as_well().top(height)
+        last_location = self._protocol_core.get_last_location()
+        if self.api_version < APIVersion(2, 24) and isinstance(
+            last_location, (TrashBin, WasteChute)
+        ):
+            last_location = None
+        if last_location is None or (
+            isinstance(last_location, types.Location)
+            and not last_location.labware.is_well
+        ):
+            raise RuntimeError(
+                f"Cached location of {last_location} is not valid for air gap."
+            )
+        target: Union[types.Location, TrashBin, WasteChute]
+        if isinstance(last_location, types.Location):
+            target = last_location.labware.as_well().top(height)
+        else:
+            target = last_location.top(height)
         self.move_to(target, publish=False)
         if self.api_version >= _AIR_GAP_TRACKING_ADDED_IN:
             self._core.prepare_to_aspirate()
@@ -2583,14 +2608,22 @@ def well_bottom_clearance(self) -> "Clearances":
         """
         return self._well_bottom_clearances
 
-    def _get_last_location_by_api_version(self) -> Optional[types.Location]:
+    def _get_last_location_by_api_version(
+        self,
+    ) -> Optional[Union[types.Location, TrashBin, WasteChute]]:
         """Get the last location accessed by this pipette, if any.
 
         In pre-engine Protocol API versions, this call omits the pipette mount.
+        Between 2.14 (first engine PAPI version) and 2.23 this only returns None or a Location object.
         This is to preserve pre-existing, potentially buggy behavior.
         """
-        if self._api_version >= ENGINE_CORE_API_VERSION:
+        if self._api_version >= APIVersion(2, 24):
             return self._protocol_core.get_last_location(mount=self._core.get_mount())
+        elif self._api_version >= ENGINE_CORE_API_VERSION:
+            last_location = self._protocol_core.get_last_location(
+                mount=self._core.get_mount()
+            )
+            return last_location if isinstance(last_location, types.Location) else None
         else:
             return self._protocol_core.get_last_location()
 
@@ -2646,7 +2679,11 @@ def configure_for_volume(self, volume: float) -> None:
                 actual_value=str(volume),
             )
         last_location = self._get_last_location_by_api_version()
-        if last_location and isinstance(last_location.labware, labware.Well):
+        if (
+            last_location
+            and isinstance(last_location, types.Location)
+            and isinstance(last_location.labware, labware.Well)
+        ):
             self.move_to(last_location.labware.top())
         self._core.configure_for_volume(volume)
 

api/src/opentrons/protocol_api/protocol_context.py

@@ -1190,9 +1190,16 @@ def home(self) -> None:
         self._core.home()
 
     @property
-    def location_cache(self) -> Optional[Location]:
-        """The cache used by the robot to determine where it last was."""
-        return self._core.get_last_location()
+    def location_cache(self) -> Optional[Union[Location, TrashBin, WasteChute]]:
+        """The cache used by the robot to determine where it last was.
+
+        .. versionchanged:: 2.24
+           Can return a ``TrashBin`` or ``WasteChute`` object.
+        """
+        last_loc = self._core.get_last_location()
+        if isinstance(last_loc, Location) or self._api_version >= APIVersion(2, 24):
+            return last_loc
+        return None
 
     @location_cache.setter
     def location_cache(self, loc: Optional[Location]) -> None:

api/src/opentrons/protocol_api/validation.py

@@ -545,6 +545,11 @@ class PointTarget(NamedTuple):
     in_place: bool
 
 
+class DisposalTarget(NamedTuple):
+    location: Union[TrashBin, WasteChute]
+    in_place: bool
+
+
 class NoLocationError(ValueError):
     """Error representing that no location was supplied."""
 
@@ -553,12 +558,12 @@ class LocationTypeError(TypeError):
     """Error representing that the location supplied is of different expected type."""
 
 
-ValidTarget = Union[WellTarget, PointTarget, TrashBin, WasteChute]
+ValidTarget = Union[WellTarget, PointTarget, DisposalTarget]
 
 
 def validate_location(
-    location: Union[Location, Well, TrashBin, WasteChute, None],
-    last_location: Optional[Location],
+    location: Optional[Union[Location, Well, TrashBin, WasteChute]],
+    last_location: Optional[Union[Location, TrashBin, WasteChute]],
 ) -> ValidTarget:
     """Validate a given location for a liquid handling command.
 
@@ -569,9 +574,11 @@ def validate_location(
     Returns:
         A `WellTarget` if the input location represents a well.
         A `PointTarget` if the input location is an x, y, z coordinate.
+        A `TrashBin` if the input location is a trash bin
+        A `WasteChute` if the input location is a waste chute
 
     Raises:
-        NoLocationError: The is no input location and no cached loaction.
+        NoLocationError: There is no input location and no cached location.
         LocationTypeError: The location supplied is of unexpected type.
     """
     from .labware import Well
@@ -586,11 +593,11 @@ def validate_location(
             f"location should be a Well, Location, TrashBin or WasteChute, but it is {location}"
         )
 
-    if isinstance(target_location, (TrashBin, WasteChute)):
-        return target_location
-
     in_place = target_location == last_location
 
+    if isinstance(target_location, (TrashBin, WasteChute)):
+        return DisposalTarget(location=target_location, in_place=in_place)
+
     if isinstance(target_location, Well):
         return WellTarget(well=target_location, location=None, in_place=in_place)