Merge branch 'edge' into EXEC-709-put-command-implementations-in-char…

…ge-of-labware-store-updates

api/docs/v2/basic_commands/liquids.rst

@@ -263,14 +263,15 @@ This example aspirates enough air to fill the remaining volume in a pipette::
 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. 
+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. When ``detect_liquid_presence()`` finds an empty well it won't raise an error or stop your protocol. 
 
-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.
+``detect_liquid_presence()`` is a standalone method to record the presence or absence of a liquid. You don't have to aspirate after detecting liquid presence. However, you should always pick up a tip immediately prior to checking for liquid, and either aspirate or drop the tip immediately after. This ensures that the pipette uses a clean, dry tip to check for liquid, and prevents cross-contamination.
 
 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
     
+    pipette.pick_up_tip()
     if pipette.detect_liquid_presence(reservoir["A1"]):
         pipette.aspirate(100, reservoir["A1"])
     else:
@@ -283,13 +284,16 @@ A potential use of liquid detection is to try aspirating from another well if th
 Require Liquids
 ===============
 
-The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for `and require` liquid in a well. 
+The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for `and require` liquid in a well. When ``require_liquid_presence()`` finds an empty well, it raises an error and pauses the protocol to let you resolve the problem.
 
-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`.
+``require_liquid_presence()`` is a standalone method to react to a missing liquid or empty well. You don't have to aspirate after requiring liquid presence. However, you should always pick up a tip immediately prior to checking for liquid, and either aspirate or drop the tip immediately after. This ensures that the pipette uses a clean, dry tip to check for liquid, and prevents cross-contamination.
 
 .. code-block:: python
 
+    pipette.pick_up_tip()
     pipette.require_liquid_presence(reservoir["A1"])
     pipette.aspirate(100, reservoir["A1"])  # only occurs if liquid found
 
+You can also require liquid presence for all aspirations performed with a given pipette. See :ref:`lpd`.
+
 .. versionadded:: 2.20

api/docs/v2/pipettes/loading.rst

@@ -221,15 +221,17 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only
 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.
+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.
+
+When detecting liquid, the pipette slowly moves a fresh, empty tip downward from the top of the well until it contacts the liquid. The downward probing motion can take anywhere from 5 to 50 seconds, depending on the depth of the well and how much liquid it contains. For example, it will take much less time to detect liquid in a full flat well plate than in an empty (or nearly empty) large tube.
+
+You can enable this feature for an entire protocol run or toggle it on and off as required. Consider the amount of time automatic detection will add to your protocol. If you only need to detect liquid infrequently, use the :ref:`corresponding building block commands <detect-liquid-presence>` instead. Automatic 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
 -----------------
 
@@ -245,9 +247,11 @@ To automatically use liquid presence detection, add the optional Boolean argumen
     )
 
 .. 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.
+    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. :ref:`Complex commands <v2-complex-commands>` may include aspirate steps after a tip is already wet. When global liquid detection is enabled, use :ref:`building block commands <v2-atomic-commands>` to ensure that your protocol picks up a tip immediately before aspiration.
+
+    The API will not raise an error during liquid detection if a tip is empty but wet. It will raise an error if liquid detection is active and your protocol attempts to aspirate with liquid in the tip.
 
-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.
+Let's take a look at how all this works. With automatic liquid detection enabled, 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
     

api/src/opentrons/drivers/absorbance_reader/abstract.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 from opentrons.drivers.types import (
+    ABSMeasurementMode,
     AbsorbanceReaderLidStatus,
     AbsorbanceReaderDeviceState,
     AbsorbanceReaderPlatePresence,
@@ -32,11 +33,18 @@ async def get_available_wavelengths(self) -> List[int]:
         ...
 
     @abstractmethod
-    async def get_single_measurement(self, wavelength: int) -> List[float]:
+    async def initialize_measurement(
+        self,
+        wavelengths: List[int],
+        mode: ABSMeasurementMode = ABSMeasurementMode.SINGLE,
+        reference_wavelength: Optional[int] = None,
+    ) -> None:
+        """Initialize measurement for the device in single or multi mode for the given wavelengths"""
         ...
 
     @abstractmethod
-    async def initialize_measurement(self, wavelength: int) -> None:
+    async def get_measurement(self) -> List[List[float]]:
+        """Gets one or more measurements based on the current configuration."""
         ...
 
     @abstractmethod