docs(api): liquid presence verification

api/docs/v2/basic_commands/liquids.rst

@@ -258,3 +258,28 @@ 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpd`.
+
+.. code-block:: python
+
+    pipette.detect_liquid_presence()
+
+.. 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. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. 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. Flex continues to execute your protocol until it no longer detects liquid. When the robot doesn't detect liquid, 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

@@ -937,8 +937,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"
@@ -2055,7 +2055,7 @@ def configure_nozzle_layout(
 
     @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.
         """
@@ -2072,7 +2072,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

@@ -910,7 +910,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)