More revisions

Name changes and stubs.

api/docs/v2/basic_commands/liquids.rst

@@ -258,21 +258,25 @@ 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:`lld`.
+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:`lld` 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.
+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
 

api/docs/v2/pipettes/loading.rst

@@ -216,20 +216,20 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only
 .. versionchanged:: 2.16
     Added support for ``TrashBin`` and ``WasteChute`` objects.
 
-.. _lld:
+.. _lpv:
 
-Liquid Level Detection
-======================
+Liquid Presence Verification
+============================
 
-All Opentrons Flex pipettes can sense liquids in a well plate or reservoir. Known as liquid level detection (LLD), this feature uses pressure sensors inside each pipette to detect the presence or absence of liquid in a well, reservoir, or other type of container. You can use LLD to avoid and recover from liquid-related protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. LLD is disabled by default.
+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 LLD Globally
+Enable LPV Globally
 -------------------
 
-The easiest, and recommended, way to use LLD is by adding the optional Boolean argument, ``liquid_presence_detection=True`` to :py:meth:`.ProtocolContext.load_instrument`. When ``True``, the robot will perform LLD on every aspiration. You can also turn LLD off and back on again later in a protocol. This example adds LLD to the 8-Channel Pipette used in the sample protocol at the top of the page.
+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
 
@@ -241,43 +241,40 @@ The easiest, and recommended, way to use LLD is by adding the optional Boolean a
     )
 
 .. note::
-    LLD requires fresh, dry pipette tips. Protocols using LLD must discard used tips after aspirating and dispensing and pick up new tips before the next cycle. The API will raise an error if LLD is active and your protocol attempts to reuse a pipette tip.
+    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.
 
-Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean 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)
 
-..
-    2 tipracks in the page example: tiprack1 & tiprack2
-    the 8-channel uses tiprack2
-    does this need to specify the tip coords each time? e.g. (tiprack2["A1"]), (tiprack2["A2"]) etc
-
 Next, tell the robot to aspirate and dispense some liquid from the reservoir::
 
-    pipette.aspirate(100, reservoir["A1"])  #LLD happens during this step
+    pipette.aspirate(100, reservoir["A1"])
     pipette.dispense(100, plate["A1"])
 
-Turing LLD Off and On
+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 LLD off and on throughout a protocol. To turn LLD 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. 
+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
+    pipette.liquid_presence_detection=False  #LPV off
     pipette.aspirate(100, reservoir["A2"])
 
-Going forward, the pipette will not perform LLD until you turn this feature back on. 
+Going forward, the pipette will not perform LPV until you turn this feature back on. 
 
-To turn LLD on after deactivating it, 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.
+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
+    pipette.liquid_presence_detection=True  #LPV on again
     pipette.aspirate(100, reservoir["A3"])
 
-LLD will resume until it is disabled again, raises an error, or the protocol completes.
+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

@@ -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,7 @@ 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``, enables liquid presence detection for a 1-, 8-, or pipette. Flex only.
+        :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
         """