docs(api): liquid presence verification (#15695) (#16033)

# Cherry Pick the LLD docs

Co-authored-by: Joe Wojak <[email protected]>
Co-authored-by: Edward Cormany <[email protected]>

api/docs/v2/basic_commands/liquids.rst

@@ -258,3 +258,38 @@ 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 liquid in a well. It returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. 
+
+Aspiration isn't required to use ``detect_liquid_presence()``. This is a standalone method that can be called when you want the robot to record the presence or absence of a liquid. When ``detect_liquid_presence()`` finds an empty well it won't raise an error or stop your protocol.
+
+A potential use of liquid detection is to try aspirating from another well if the first well is found to contain no liquid.
+
+.. code-block:: python
+    
+    if pipette.detect_liquid_presence(reservoir["A1"]):
+        pipette.aspirate(100, reservoir["A1"])
+    else:
+        pipette.aspirate(100, reservoir["A2"])
+
+.. 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` liquid in a well. 
+
+Aspiration isn't required to use ``require_liquid_presence()``. This is a standalone method that can be called when you want the robot to react to a missing liquid or empty well. When ``require_liquid_presence()`` finds an empty well, it raises an error and pauses the protocol to let you resolve the problem. See also :ref:`lpd`.
+
+.. code-block:: python
+
+    pipette.require_liquid_presence(reservoir["A1"])
+    pipette.aspirate(100, reservoir["A1"])  # only occurs if liquid found
+
+.. versionadded:: 2.20

api/docs/v2/pipettes/loading.rst

@@ -215,3 +215,73 @@ 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, tube, or other container. It 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 is disabled by default.
+
+Pipette Compatibility
+---------------------
+
+Liquid presence detection works with Flex 1-, 8-, and 96-channel pipettes only. 1-channel pipettes have one pressure sensor. The 8-channel pipette pressure sensors are on channels 1 and 8 (positions A1 and H1). The 96-channel pipette pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.
+
+.. add text with link to revised pipette sensor section in manual?
+
+Enabling Globally
+-----------------
+
+To automatically use liquid presence detection, add the optional Boolean argument  ``liquid_presence_detection=True`` to :py:meth:`.ProtocolContext.load_instrument` in your protocol. 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 enables liquid presence detection on 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 clean tip, aspirate 100 µL from a reservoir, and dispense that volume into a well plate.
+
+.. code-block:: python
+    
+    right.pick_up_tip()
+    right.aspirate(100, reservoir["A1"])  # checks for liquid
+    right.dispense(100, plate["A1"])
+
+Liquid detection takes place 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 using it. If Flex doesn't detect liquid, it raises an error and stops the protocol until the problem is resolved.
+
+However, aspiration isn't required for liquid level detection. Two standalone methods, :py:meth:`.detect_liquid_presence` and :py:meth:`.require_liquid_presence`, let you add liquid detection to a protocol with or without aspirating. Automatic detection is the same as calling ``require_liquid_presence()`` before every aspiration. See :ref:`detect-liquid-presence` and :ref:`require-liquid-presence` for details.
+
+.. versionadded:: 2.20
+
+Activating and Deactivating
+---------------------------
+
+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  after picking up a new tip. 
+
+.. code-block:: python
+    
+    right.pick_up_tip()
+    right.liquid_presence_detection = False  # Turns off liquid presence detection.
+    right.aspirate(100, reservoir["A2"])     # Aspirates immediately.
+
+From now on, the pipette will not check for liquid until you turn this feature back on. 
+
+To reactivate, set ``liquid_presence_detection=True`` at the point later in the protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid.
+
+.. code-block:: python
+
+    right.pick_up_tip()
+    right.liquid_presence_detection = True  # Turns on liquid presence detection.
+    right.aspirate(100, reservoir["A3"])    # Detects liquid before aspirating.
+
+The robot will continue to check for liquid until this feature is disabled again, or an empty well is detected (and the robot raises an error), or the protocol completes.
+
+.. 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"
@@ -1688,12 +1688,10 @@ def tip_racks(self, racks: List[labware.Labware]) -> None:
     @requires_version(2, 20)
     def liquid_presence_detection(self) -> bool:
         """
-        Gets the global setting for liquid level detection.
+        Whether the pipette will perform automatic liquid presence detection.
 
-        When True, `liquid_probe` will be called before
-        aspirates and dispenses to bring the tip to the liquid level.
-
-        The default value is False.
+        When ``True``, the pipette will check for liquid on every aspiration.
+        Defaults to ``False``. See :ref:`lpd`.
         """
         return self._core.get_liquid_presence_detection()
 
@@ -2136,19 +2134,25 @@ 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 for liquid in a well.
+
+        Returns ``True`` if liquid is present and ``False`` if liquid is not present. Will not raise an error if it does not detect liquid. When simulating a protocol, the check always succeeds (returns ``True``). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`detect-liquid-presence`.
 
-        :returns: A boolean.
+        .. note::
+            The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.
         """
         loc = well.top()
         self._96_tip_config_valid()
         return self._core.detect_liquid_presence(well._core, loc)
 
     @requires_version(2, 20)
     def require_liquid_presence(self, well: labware.Well) -> None:
-        """If there is no liquid in a well, raise an error.
+        """Check for liquid in a well and raises an error if none is detected.
 
-        :returns: None.
+        When this method raises an error, Flex will offer the opportunity to enter recovery mode. In recovery mode, you can manually add liquid to resolve the error. When simulating a protocol, the check always succeeds (does not raise an error). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`lpd` and :ref:`require-liquid-presence`.
+
+        .. note::
+            The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.
         """
         loc = well.top()
         self._96_tip_config_valid()

api/src/opentrons/protocol_api/protocol_context.py

@@ -913,7 +913,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``, enable automatic
+            :ref:`liquid presence detection <lpd>` for Flex 1-, 8-, or 96-channel pipettes.
+            .. versionadded:: 2.20
         """
         instrument_name = validation.ensure_lowercase_name(instrument_name)
         checked_instrument_name = validation.ensure_pipette_name(instrument_name)