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 the robot to check for a liquid and return the results. It returns ``True`` if liquid is detected and ``False`` if liquid is not detected. It will not raise an error or stop your protocol if a liquid is not present in a well or reservoir. See also :ref:`lpv`.
+
+.. code-block:: python
+
+    pipette.detect_liquid_presence()
+
+.. versionadded:: 2.20
+
+.. _require-liquid-presence:
+
+Require Liquids
+===============
+
+The :py:meth:`.InstrumentContext.require_liquid_presence` method forces the robot to check for the presence of a liquid, even when :ref:`lpv` is specifically disabled. When using this method, the robot will raise an error that stops a protocol, writes a warning to the run logs, and also lets you recover from the error through your own error handling code.
+
+.. code-block:: python
+
+    pipette.require_liquid_presence()
+
+.. versionadded:: 2.20

api/docs/v2/pipettes/loading.rst

@@ -215,3 +215,66 @@ 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.
+
+.. _lpv:
+
+Liquid Presence Verification
+============================
+
+Liquid Presence Verification (LPV) is a pressure-based feature that gives all Opentrons pipettes the ability to detect the presence or absence of a liquid in a well or reservoir. You can use LPV to identify, avoid, and recover from liquid-related protocol errors or just check for the presence or absence of a fluid---all with or without interrupting a protocol run. You can activate LPV globally for an entire protocol run, or turn it on and off as needed. LPV 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 96-Channel Pipette, the pressure sensors are on channels 1 and 96.
+
+Enable LPV Globally
+-------------------
+
+The easiest, and recommended, way to use LPV 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 perform LPV on every aspiration. You can also turn LPV off and back on again later in a protocol. This example adds LPV 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::
+    LPV requires fresh, dry pipette tips. Protocols using LPV 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 LPV is active and your protocol attempts to reuse a pipette tip.
+
+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"])
+
+LPV takes place during aspiration. 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.
+
+Turing LPV Off and On
+---------------------
+
+You can turn LPV off and on throughout a protocol. To turn LPV off, add ``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  #LPV off
+    pipette.aspirate(100, reservoir["A2"])
+
+Going forward, the pipette will not perform LPV until you turn this feature back on. 
+
+To reactivate LPV, add ``pipette.liquid_presence_detection=True`` at the point 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  #LPV on again
+    pipette.aspirate(100, reservoir["A3"])
+
+LPV will resume until it is disabled again, raises an error, or the protocol completes.
+
+.. 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.
+        """Check if there is liquid in a well. See :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.
+        """If there is no liquid in a well, raise an error. See :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:`lpv`.
+
+                    .. versionadded:: 2.20
         """
         instrument_name = validation.ensure_lowercase_name(instrument_name)
         checked_instrument_name = validation.ensure_pipette_name(instrument_name)