docs(api): section on Position Relative to Trash Containers

api/docs/v2/robot_position.rst

@@ -21,6 +21,8 @@ Top, Bottom, and Center
 
 Every well on every piece of labware has three addressable positions: top, bottom, and center. The position is determined by the labware definition and what the labware is loaded on top of. You can use these positions as-is or calculate other positions relative to them.
 
+.. _well-top:
+
 Top
 ^^^^
 
@@ -116,6 +118,31 @@ All positions relative to labware are adjusted automatically based on labware of
 
 You should only adjust labware offsets in your Python code if you plan to run your protocol in Jupyter Notebook or from the command line. See :ref:`using_lpc` in the Advanced Control article for information.
 
+.. _position-relative-trash:
+
+Position Relative to Trash Containers
+=====================================
+
+In API version 2.15 and earlier, trash containers are :py:class:`.Labware` objects that have a single well. Use the above techniques for labware to adjust position relative to trash containers in protocols specifying these API versions.
+
+Starting in API version 2.16, trash containers are :py:class:`.TrashBin` or :py:class:`.WasteChute` objects. The API calculates movement to these objects based on the horizontal *center* of the pipette, rather than its primary channel (the back channel on 8-channel pipettes, and the back-left channel on 96-channel pipettes in default configuration). This ensures that all tips attached to the pipette are placed over the trash container for blowing out, dropping tips, or other operations.
+
+You can adjust the position of the pipette center with the :py:meth:`.TrashBin.top` and :py:meth:`.WasteChute.top` methods. These methods allow adjustments along the x-, y-, and z-axes. In contrast, ``Well.top()``, :ref:`covered above <well-top>`, only allows z-axis adjustment. With no adjustments, the "top" position is centered on the x- and y-axes and is just below the opening of the trash container.
+
+.. code-block:: python
+
+    trash = protocol.load_trash_bin("A3")
+
+    trash  # pipette center just below trash top center
+    trash.top()  # same position
+    trash.top(z=10)  # 10 mm higher
+    trash.top(y=10)  # 10 mm towards back, default height
+
+.. versionadded:: 2.18
+
+.. note::
+    Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This helps prevent performing undesired actions in trash containers. For example, you can :py:meth:`.aspirate` at a location or from a well, but not from a trash container. On the other hand, you can :py:meth:`.blow_out` at a location, well, trash bin, or waste chute.
+
 .. _protocol-api-deck-coords:
 
 Position Relative to the Deck

api/src/opentrons/protocol_api/instrument_context.py

@@ -306,27 +306,34 @@ def dispense(  # noqa: C901
         :type volume: int or float
 
         :param location: Tells the robot where to dispense liquid held in the pipette.
-                         The location can be a :py:class:`.Well` or a
-                         :py:class:`.Location`.
+            The location can be a :py:class:`.Well`, :py:class:`.Location`,
+            :py:class:`.TrashBin`, or :py:class:`.WasteChute`.
 
-                            - If the location is a ``Well``, the pipette will dispense
+                            - If a ``Well``, the pipette will dispense
                               at or above the bottom center of the well. The distance (in
                               mm) from the well bottom is specified by
                               :py:obj:`well_bottom_clearance.dispense
                               <well_bottom_clearance>`.
 
-                            - If the location is a ``Location`` (e.g., the result of
-                              :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot
-                              will dispense into that specified position.
+                            - If a ``Location`` (e.g., the result of
+                              :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the pipette
+                              will dispense at that specified position.
 
-                            - If the ``location`` is unspecified, the robot will
-                              dispense into its current position.
+                            - If a trash container, the pipette will dispense at a location
+                              relative to its center and the trash container's top center.
+                              See :ref:`position-relative-trash` for details.
+
+                            - If unspecified, the pipette will
+                              dispense at its current position.
 
                             If only a ``location`` is passed (e.g.,
                             ``pipette.dispense(location=plate['A1'])``), all of the
                             liquid aspirated into the pipette will be dispensed (the
                             amount is accessible through :py:attr:`current_volume`).
 
+            .. versionchanged:: 2.18
+                Accepts ``TrashBin`` and ``WasteChute`` values.
+
         :param rate: How quickly a pipette dispenses liquid. The speed in µL/s is
                      calculated as ``rate`` multiplied by :py:attr:`flow_rate.dispense
                      <flow_rate>`. If not specified, defaults to 1.0. See
@@ -543,7 +550,11 @@ def blow_out(
         :ref:`blow-out`.
 
         :param location: The blowout location. If no location is specified, the pipette
-                         will blow out from its current position.
+            will blow out from its current position.
+
+            .. versionchanged:: 2.18
+                Accepts ``TrashBin`` and ``WasteChute`` values.
+
         :type location: :py:class:`.Well` or :py:class:`.Location` or ``None``
 
         :raises RuntimeError: If no location is specified and the location cache is
@@ -1003,7 +1014,11 @@ def drop_tip(
               ``pipette.drop_tip(location=waste_chute)``.
 
         :param location:
-            The location to drop the tip.
+            Where to drop the tip.
+
+            .. versionchanged:: 2.16
+                Accepts ``TrashBin`` and ``WasteChute`` values.
+
         :type location:
             :py:class:`~.types.Location` or :py:class:`.Well` or ``None``
         :param home_after:
@@ -1427,7 +1442,11 @@ def move_to(
 
         See :ref:`move-to` for examples.
 
-        :param location: The location to move to.
+        :param location: Where to move to.
+
+          .. versionchanged:: 2.18
+               Accepts ``TrashBin`` and ``WasteChute`` values.
+
         :type location: :py:class:`~.types.Location`
         :param force_direct: If ``True``, move directly to the destination without arc
                              motion.