From 28fb7ae42117ed8f0719703199c5e3b05dc8718f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 8 Aug 2024 09:13:50 -0400 Subject: [PATCH] Apply suggestions from code review Committing recommended changes. Will continue to work on others. Co-authored-by: Ed Cormany --- api/docs/v2/basic_commands/liquids.rst | 8 +++++++- api/docs/v2/pipettes/loading.rst | 16 ++++++++-------- .../opentrons/protocol_api/instrument_context.py | 10 ++++++++-- .../opentrons/protocol_api/protocol_context.py | 2 +- 4 files changed, 24 insertions(+), 12 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 8eee424497c..0a56ee0fe8a 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,7 +263,13 @@ 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 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 the sensors do not. It will not raise an error or stop your protocol when the robot detects and empty well. Detection takes place during aspiration, but you don't need to aspirate to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for the presence of a liquid in a well plate or reservoir. This method returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. It will not raise an error or stop your protocol when the robot detects an empty well. + +You should generally detect liquid immediately after picking up a tip and before aspirating, but you don't need to aspirate to use ``detect_liquid_presence()``. It's a standalone method that can be called when you only want to detect liquid. + +.. note:: + Accurate liquid detection requires fresh, dry pipette tips. + .. code-block:: python diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index b60a0cda1d0..6ce4a99634f 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -224,7 +224,7 @@ 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 `, 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. + If your protocol uses :ref:`partial tip pickup `, the pressure sensors for the Flex 8-Channel pipette are on channels A1 and H1. For the Flex 96-Channel Pipette, the pressure sensors are on channels A1 and H12. .. versionadded:: 2.20 @@ -267,19 +267,19 @@ You can turn Liquid Presence Detection off and on throughout a protocol. To turn .. code-block:: python - pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=False #Liquid Presence Detection off - pipette.aspirate(100, reservoir["A2"]) + pipette.pick_up_tip() + pipette.liquid_presence_detection=False # liquid presence detection off + pipette.aspirate(100, reservoir["A2"]) # aspirates immediately 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. +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 - pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=True #Liquid Presence Detection on again - pipette.aspirate(100, reservoir["A3"]) + pipette.pick_up_tip() + pipette.liquid_presence_detection=True # liquid presence detection on again + pipette.aspirate(100, reservoir["A3"]) # detects liquid before aspirating 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. diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 68e9ac99860..2eb112dd50c 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2120,7 +2120,9 @@ def configure_nozzle_layout( # noqa: C901 @requires_version(2, 20) def detect_liquid_presence(self, well: labware.Well) -> bool: - """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`. + """Check if there is 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. Flex pipettes only. See :ref:`detect-liquid-presence`. When simulating a protocol, the check always succeeds (returns ``True``). @@ -2132,7 +2134,11 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: @requires_version(2, 20) def require_liquid_presence(self, well: labware.Well) -> None: - """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`. + """Check for liquid in a well and raise an error if none is detected. + + 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. + + Works with Flex pipettes only. See :ref:`lpd` and :ref:`require-liquid-presence`. When simulating a protocol, the check always succeeds (does not raise an error). diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 0d46804fdab..d5cc8b164c2 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -906,7 +906,7 @@ def load_instrument( 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 Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`. + :param bool liquid_presence_detection: If ``True``, enable liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`. .. versionadded:: 2.20 """