docs(api): liquid presence verification

api/docs/v2/basic_commands/liquids.rst

@@ -258,3 +258,68 @@ This example aspirates enough air to fill the remaining volume in a pipette::
 
 .. versionadded:: 2.0
 
+.. _detect-liquid-presence:
+
+Detect Liquids
+==============
+
+The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for the presence of a liquid in a wellplate or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if the sensors do not. It will not raise an error or stop your protocol when the robot detects and empty well. Detection takes place during aspiration, but you don't need to aspirate to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. See also :ref:`lpd`. 
+
+.. code-block:: python
+
+    pipette.detect_liquid_presence()
+
+In cases where you need records that are more informative than ``true`` or ``false``, you can write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. Here's one way to do this in the ``run():`` function of our Flex :ref:`protocol template <protocol-template>`:
+
+.. code-block:: python
+
+    tip_index = 0 # tracks how many tips are used.
+    plate_index = 0 # tracks the wells dispensed to. Increments after dispense.
+
+    for name, well in reservoir.items():
+        pipette.pick_up_tip(tiprack[tipIndex])
+        has_liquid = pipette.detect_liquid_presence(well)
+        pipette.drop_tip(trash)
+        tip_index+=1
+
+        cur_index = 0 # counts aspirate/dispense cycles from a reservoir well.
+        while has_liquid:
+            pipette.pick_up_tip(tiprack[tipIndex])
+            pipette.aspirate(250, well)
+            pipette.dispense(250, plate[plateIndex])
+            pipette.drop_tip(trash)
+            tip_index+=1
+            plate_index+=1
+
+            pipette.pick_up_tip(tiprack[tipIndex])
+            has_liquid = pipette.detect_liquid_presence(well)
+            pipette.drop_tip(trash)
+            tip_index+=1
+
+            cur_index+=1
+
+        # Add a helpful record to the run log when a well runs dry or is empty.
+        protocol.comment(
+            f"Found liquid and aspirated from well {name} {curIndex} times. Well is now empty."
+        )
+
+    # Add a helpful record to the run log when all source wells are empty.
+    protocol.comment("Exhausted all wells in reservoir.") 
+
+Now the Flex records an entry in the run log that includes the well's name (e.g. ``A1``, ``A2``, ``B1`` etc.) and how many times the pipette aspirated from that well before it ran dry. If a protocol uses all the liquid in its source wells, the robot records that too.
+
+.. versionadded:: 2.20
+
+.. _require-liquid-presence:
+
+Require Liquids
+===============
+
+The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. When the robot does not detect liquid, it raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log.
+Detection takes place during aspiration, but you don't need to aspirate to use ``require_liquid_presence``. It's a standalone method that can be called when you want to detect liquids only. See also :ref:`lpd`.
+
+.. code-block:: python
+
+    pipette.require_liquid_presence()
+
+.. versionadded:: 2.20

api/docs/v2/pipettes/loading.rst

@@ -215,3 +215,74 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only
 .. versionadded:: 2.0
 .. versionchanged:: 2.16
     Added support for ``TrashBin`` and ``WasteChute`` objects.
+
+.. _lpd:
+
+Liquid Presence Detection
+=========================
+
+Liquid Presence Detection is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence or absence of liquids in a well, reservoir, or other container. Liquid Presence Detection gives you the ability to identify, avoid, and recover from liquid-related protocol errors. You can enable this feature for an entire protocol run or toggle it on and off as required. Liquid Presence Detection works with Flex pipettes only and is disabled by default.
+
+.. note::
+    If your protocol uses :ref:`partial tip pickup <partial-tip-pickup>`, the pressure sensors for the Flex 8-Channel pipette are on channels 1 and 8. For the Flex 96-Channel Pipette, the pressure sensors are on channels 1 and 96.
+
+.. versionadded:: 2.20
+
+.. Ed: Enabling instead of Enable?
+
+Enable Liquid Presence Detection
+--------------------------------
+
+The easiest, and recommended, way to use Liquid Presence Detection is by adding the optional Boolean argument, ``liquid_presence_detection=True`` to :py:meth:`.ProtocolContext.load_instrument` in your protocol. When ``True``, the robot will check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example adds Liquid Presence Detection to the 8-Channel Pipette used in the sample protocol at the top of the page.
+
+.. code-block:: python
+
+    right = protocol.load_instrument(
+        instrument_name="flex_8channel_1000",
+        mount="right",
+        tip_racks=[tiprack2],
+        liquid_presence_detection=True
+    )
+
+.. note::
+    Accurate liquid detection requires fresh, dry pipette tips. Protocols using this feature must discard used tips after an aspirate/dispense cycle and pick up new tips before the next cycle. The API will raise an error if liquid detection is active and your protocol attempts to reuse a pipette tip or if the robot thinks the tip is wet.
+
+Let's take a look at how all this works. First, tell the robot to pick up a new, clean tip::
+
+    pipette.pick_up_tip(tiprack2)
+
+Next, tell the robot to aspirate and dispense some liquid from the reservoir::
+
+    pipette.aspirate(100, reservoir["A1"])
+    pipette.dispense(100, plate["A1"])
+
+Liquid detection takes place immediately prior to aspiration. Upon detecting a liquid, the pipette stops, raises itself above the liquid's surface, and then aspirates according to your protocol. Checking for a liquid adds time to your protocol run, so be aware of that before you use it. When the robot doesn't detect liquid during an aspiration, it raises an error and stops the protocol until the problem is resolved.
+
+.. versionadded:: 2.20
+
+Turning Liquid Presence Detection Off and On
+---------------------------------------------
+
+You can turn Liquid Presence Detection off and on throughout a protocol. To turn it off, set ``pipette.liquid_presence_detection=False`` at the point in a protocol where it needs to be disabled, usually between picking up a new tip and aspirating a liquid. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's try this starting after picking up a new tip. 
+
+.. code-block:: python
+
+    pipette.pick_up_tip(tiprack2)
+    pipette.liquid_presence_detection=False  #Liquid Presence Detection off
+    pipette.aspirate(100, reservoir["A2"])
+
+Going forward, the pipette will not perform a liquid check until you turn this feature back on. 
+
+To reactivate, add ``pipette.liquid_presence_detection=True`` at the point later in a protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid.
+
+.. code-block:: python
+
+    pipette.pick_up_tip(tiprack2)
+    pipette.liquid_presence_detection=True  #Liquid Presence Detection on again
+    pipette.aspirate(100, reservoir["A3"])
+
+The robot will continue to check for a liquid until this feature is disabled again, or an empty well is detected (and the robot raises an error), or the protocol completes.
+
+See also :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`.
+
+.. versionadded:: 2.20

api/src/opentrons/protocol_api/instrument_context.py

@@ -945,8 +945,8 @@ def pick_up_tip(  # noqa: C901
                 # in which self.starting_tip consumes tips. It would currently vary
                 # depending on the configuration layout of a pipette at a given
                 # time, which means that some combination of starting tip and partial
-                # configuraiton are incompatible under the current understanding of
-                # starting tip behavior. Replacing starting_tip with an undeprecated
+                # configuration are incompatible under the current understanding of
+                # starting tip behavior. Replacing starting_tip with an un-deprecated
                 # Labware.has_tip may solve this.
                 raise CommandPreconditionViolated(
                     "Automatic tip tracking is not available when using a partial pipette"
@@ -2120,7 +2120,7 @@ def configure_nozzle_layout(  # noqa: C901
 
     @requires_version(2, 20)
     def detect_liquid_presence(self, well: labware.Well) -> bool:
-        """Check if there is liquid in a well.
+        """Checks if there is liquid in a well. Will not raise an error if it does not detect liquid. Flex pipettes only. See :ref:`lpd` and :ref:`detect-liquid-presence`.
 
         :returns: A boolean.
         """
@@ -2130,7 +2130,7 @@ def detect_liquid_presence(self, well: labware.Well) -> bool:
 
     @requires_version(2, 20)
     def require_liquid_presence(self, well: labware.Well) -> None:
-        """If there is no liquid in a well, raise an error.
+        """Checks for liquid in a well. Raises an error if no liquid is detected. Flex pipettes only. See :ref:`lpd` and :ref:`require-liquid-presence`.
 
         :returns: None.
         """

api/src/opentrons/protocol_api/protocol_context.py

@@ -906,7 +906,9 @@ def load_instrument(
                              control <advanced-control>` applications. You cannot
                              replace an instrument in the middle of a protocol being run
                              from the Opentrons App or touchscreen.
-        :param bool liquid_presence_detection: If ``True``, enable liquid presence detection for instrument. Only available on Flex robots in API Version 2.20 and above.
+        :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`.
+
+                    .. versionadded:: 2.20
         """
         instrument_name = validation.ensure_lowercase_name(instrument_name)
         checked_instrument_name = validation.ensure_pipette_name(instrument_name)