From 799ee2958a161b528ccea6a17527d374bac9743d Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 9 Jul 2024 16:31:33 -0400 Subject: [PATCH 01/59] Test push Aa a reminder of how to do this. It's been a while. --- api/docs/v2/pipettes/loading.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 72a13ce3409..ed4a63a16a0 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -7,6 +7,8 @@ Loading Pipettes **************** +Test test test. + When writing a protocol, you must inform the Protocol API about the pipettes you will be using on your robot. The :py:meth:`.ProtocolContext.load_instrument` function provides this information and returns an :py:class:`.InstrumentContext` object. As noted above, you call the :py:meth:`~.ProtocolContext.load_instrument` method to load a pipette. This method also requires the :ref:`pipette's API load name `, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly. From 827e28c82e9d11b3ed17038e0a360e3041b998ff Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 9 Jul 2024 17:09:42 -0400 Subject: [PATCH 02/59] Removing test text, not important --- api/docs/v2/pipettes/loading.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ed4a63a16a0..72a13ce3409 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -7,8 +7,6 @@ Loading Pipettes **************** -Test test test. - When writing a protocol, you must inform the Protocol API about the pipettes you will be using on your robot. The :py:meth:`.ProtocolContext.load_instrument` function provides this information and returns an :py:class:`.InstrumentContext` object. As noted above, you call the :py:meth:`~.ProtocolContext.load_instrument` method to load a pipette. This method also requires the :ref:`pipette's API load name `, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly. From 5116a9cb4183f2c665410860276565f0f329bc98 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 10 Jul 2024 11:58:46 -0400 Subject: [PATCH 03/59] Edit LPD argument definition. Make it clear this is for Flex only and include the version. --- api/src/opentrons/protocol_api/protocol_context.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index ad96e0c3156..19b2fa215e6 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -910,7 +910,9 @@ 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``, 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 a 1-, 8-, or 96-channel pipette. Flex only. + + .. versionadded:: 2.20 """ instrument_name = validation.ensure_lowercase_name(instrument_name) checked_instrument_name = validation.ensure_pipette_name(instrument_name) From e3fd8fd255ac31cf40f647fb08fe50c0f177f341 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 09:53:59 -0400 Subject: [PATCH 04/59] H2 LLD section summary --- api/docs/v2/pipettes/loading.rst | 9 +++++++++ api/src/opentrons/protocol_api/protocol_context.py | 4 ++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 72a13ce3409..6a381f63fb1 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -215,3 +215,12 @@ 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. + +Liquid Level Detection +====================== + +All Opentrons Flex pipettes have pressure sensors that detect the presence or absence of a liquid in a well plate, reservoir, or other types of labware containers. With liquid level detection (LLD) enabled in your protocols, the robot can stop a pipette at at or just below the surface of a liquid sample before aspirating. Also, the various LLD methods described here can help you avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. + +.. note:: + LLD requires a clean, dry pipette tip. This means you must discard a tip after every aspirate/dispsense cycle and pickup a fresh tip before the next cycle. + diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 19b2fa215e6..e74922725bc 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -910,9 +910,9 @@ 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 a 1-, 8-, or 96-channel pipette. Flex only. + :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for a 1-, 8-, or pipette. Flex only. - .. versionadded:: 2.20 + .. versionadded:: 2.20 """ instrument_name = validation.ensure_lowercase_name(instrument_name) checked_instrument_name = validation.ensure_pipette_name(instrument_name) From af41076de7f07e32f8500c8436c93eb7f5ee0a8c Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 12:06:48 -0400 Subject: [PATCH 05/59] LLD intro and global method --- api/docs/v2/pipettes/loading.rst | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 6a381f63fb1..1b5ba4186d2 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -219,8 +219,29 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only Liquid Level Detection ====================== -All Opentrons Flex pipettes have pressure sensors that detect the presence or absence of a liquid in a well plate, reservoir, or other types of labware containers. With liquid level detection (LLD) enabled in your protocols, the robot can stop a pipette at at or just below the surface of a liquid sample before aspirating. Also, the various LLD methods described here can help you avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. +All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires a clean, dry pipette tip. This means you must discard a tip after every aspirate/dispsense cycle and pickup a fresh tip before the next cycle. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must discard the used tip and pick up a new one to perform additional LLD checks. + +Section Needs a Title +--------------------- + +You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also turn this off later, or or make it explicitly ``False`` and activate it later in a protocol. Using sample protocol at the top of the page, this example adds LLD to the left-mounted, 1-Channel pipette. + +.. code-block:: python + + left = protocol.load_instrument( + instrument_name="flex_1channel_1000", + mount="left", + tip_racks=[tiprack1], + liquid_presence_detection=True + ) + +Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. When the pressure sensor detects a liquid the code returns ``True`` and the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + +And remember, LLD requires a fresh tip for every aspiration. To continue LLD throughout the protocol, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments:: + + pipette.drop_tip(trash_bin) + From d4298361bc2f9f6513cf7194f592cdce8e7e1f5e Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 13:18:27 -0400 Subject: [PATCH 06/59] Adding link to drop_tip --- api/docs/v2/pipettes/loading.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 1b5ba4186d2..ec6b4d91048 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -238,10 +238,7 @@ You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:met liquid_presence_detection=True ) -Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. When the pressure sensor detects a liquid the code returns ``True`` and the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. - -And remember, LLD requires a fresh tip for every aspiration. To continue LLD throughout the protocol, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments:: - - pipette.drop_tip(trash_bin) +Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +And remember, LLD always requires a fresh tip. Call :py:meth:`~.InstrumentContext.drop_tip` in your protocol to throw the used tip away and pick up a new tip before every aspiration. From 2fdc24e7f3c6ef4cdacfd02f688c74e6af32d2dc Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 13:29:15 -0400 Subject: [PATCH 07/59] Turning global LLD off --- api/docs/v2/pipettes/loading.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ec6b4d91048..e26cb708309 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,7 +222,7 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must discard the used tip and pick up a new one to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new one to perform additional LLD checks. Section Needs a Title --------------------- @@ -240,5 +240,13 @@ You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:met Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. -And remember, LLD always requires a fresh tip. Call :py:meth:`~.InstrumentContext.drop_tip` in your protocol to throw the used tip away and pick up a new tip before every aspiration. +Turning it off +-------------- +.. + Needs better title +Turn it off + +.. code-block:: python + + pipette.liquid_detection = False From 2363e9146642d2a6026bf830d809b3e4e81920a5 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 17:06:53 -0400 Subject: [PATCH 08/59] End of day save Deve environment conked out. --- api/docs/v2/pipettes/loading.rst | 34 ++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index e26cb708309..6fa93adf660 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,31 +222,49 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new one to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~InstrumentContext.pick_up_tip`) to perform additional LLD checks. Section Needs a Title --------------------- -You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also turn this off later, or or make it explicitly ``False`` and activate it later in a protocol. Using sample protocol at the top of the page, this example adds LLD to the left-mounted, 1-Channel pipette. +LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. .. code-block:: python +def run(protocol: protocol_api.ProtocolContext): + tiprack1 = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", location="D1") + reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") + plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") left = protocol.load_instrument( instrument_name="flex_1channel_1000", mount="left", tip_racks=[tiprack1], liquid_presence_detection=True ) + reservoir.load_liquid(volume=10000) + +Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: + + pipette.pick_up_tip() + +Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: + + pipette.aspirate(100, plate["A1"]) -Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. -Turning it off --------------- + +theLLD occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate` and works as follows: as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + +Did You Try Turing it Off and Then On Again +------------------------------------------- .. - Needs better title -Turn it off + Needs better title. IT Crowd :) + +In the previous example, the robot checks for liquid every single time time. If this is too frequent, you can override the global setting and disable LLD for a particular aspiration. To override the global behavior, set the pipette's `liquid_presence_detection` property to `False`. Let's take a look at this starting from the .. code-block:: python - pipette.liquid_detection = False + pipette.liquid_presence_detection = False From 608a71e1f0cd7cf8983490a8ae1a516b682aeb4d Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 11:18:06 -0400 Subject: [PATCH 09/59] Update loading.rst --- api/docs/v2/pipettes/loading.rst | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 6fa93adf660..e9e1c11fa57 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -250,21 +250,32 @@ Now, let's add some commands and start the cycle. First, tell the robot to pick Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: - pipette.aspirate(100, plate["A1"]) + pipette.aspirate(100, reservoir["A1"]) + pipette.dispense(100, plate["A1"]) -During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. +During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: +pipette.drop_tip() +pipette.pick_up_tip(tiprack1["A2"]) -theLLD occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate` and works as follows: as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +LLD will not work with used tips. Did You Try Turing it Off and Then On Again ------------------------------------------- .. - Needs better title. IT Crowd :) + Needs better title. -In the previous example, the robot checks for liquid every single time time. If this is too frequent, you can override the global setting and disable LLD for a particular aspiration. To override the global behavior, set the pipette's `liquid_presence_detection` property to `False`. Let's take a look at this starting from the +If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's `liquid_presence_detection` property to `False` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. .. code-block:: python + pipette.pick_up_tip(tiprack1["A2"]) pipette.liquid_presence_detection = False + +After this, the pipette will not do LLD check for subsequent aspirations. To re-activate LLD set ``pipette.liquid_presence_detection=True`` later in your protocol. + +Require Liquid Presence +----------------------- + From a491e76a1e08418d2cd3c7a61ff24749a39edf28 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:07:43 -0400 Subject: [PATCH 10/59] Fix shortened API reference Forgot ~. --- api/docs/v2/pipettes/loading.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index e9e1c11fa57..ae03dc4e3a4 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,7 +222,7 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~InstrumentContext.pick_up_tip`) to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~.InstrumentContext.pick_up_tip`) to perform additional LLD checks. Section Needs a Title --------------------- @@ -279,3 +279,4 @@ After this, the pipette will not do LLD check for subsequent aspirations. To re- Require Liquid Presence ----------------------- +The `` just check the liquid status of a well, use From b96d9ddb76249242aaa960d4a83243b9129ea456 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:23:09 -0400 Subject: [PATCH 11/59] Fixing code formatting --- api/docs/v2/pipettes/loading.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ae03dc4e3a4..091912ec5d8 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -230,20 +230,20 @@ Section Needs a Title LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. .. code-block:: python - -def run(protocol: protocol_api.ProtocolContext): - tiprack1 = protocol.load_labware( + + def run(protocol: protocol_api.ProtocolContext): + tiprack1 = protocol.load_labware( load_name="opentrons_flex_96_tiprack_1000ul", location="D1") - reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") - plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") - left = protocol.load_instrument( + reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") + plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") + left = protocol.load_instrument( instrument_name="flex_1channel_1000", mount="left", tip_racks=[tiprack1], liquid_presence_detection=True ) reservoir.load_liquid(volume=10000) - + Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: pipette.pick_up_tip() @@ -257,8 +257,8 @@ During aspiration, as the pipette's pressure sensor detects a liquid, the code r Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: -pipette.drop_tip() -pipette.pick_up_tip(tiprack1["A2"]) + pipette.drop_tip() + pipette.pick_up_tip(tiprack1["A2"]) LLD will not work with used tips. @@ -274,9 +274,9 @@ If using LLD on on every aspirate is too frequent, you can disable and enable it pipette.pick_up_tip(tiprack1["A2"]) pipette.liquid_presence_detection = False -After this, the pipette will not do LLD check for subsequent aspirations. To re-activate LLD set ``pipette.liquid_presence_detection=True`` later in your protocol. +After this, the pipette will not do LLD check during subsequent aspirations. To re-activate LLD, set ``pipette.liquid_presence_detection=True`` later in your protocol. Require Liquid Presence ----------------------- -The `` just check the liquid status of a well, use +The ``foo thing`` just check the liquid status of a well, use From 3f797a74327c08732600abac00242cfcbd621dde Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:59:40 -0400 Subject: [PATCH 12/59] End 'o day commit, will shorten code example --- api/docs/v2/pipettes/loading.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 091912ec5d8..103eed7f447 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -227,20 +227,22 @@ All Opentrons Flex pipettes use pressure sensors to detect the presence or absen Section Needs a Title --------------------- -LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. +LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. + +.. code sample too long, shorten .. code-block:: python def run(protocol: protocol_api.ProtocolContext): tiprack1 = protocol.load_labware( - load_name="opentrons_flex_96_tiprack_1000ul", location="D1") + load_name="opentrons_flex_96_tiprack_1000ul", location="D1") reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") left = protocol.load_instrument( - instrument_name="flex_1channel_1000", - mount="left", - tip_racks=[tiprack1], - liquid_presence_detection=True + instrument_name="flex_1channel_1000", + mount="left", + tip_racks=[tiprack1], + liquid_presence_detection=True ) reservoir.load_liquid(volume=10000) @@ -267,7 +269,7 @@ Did You Try Turing it Off and Then On Again .. Needs better title. -If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's `liquid_presence_detection` property to `False` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. +If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's ``liquid_presence_detection`` property to ``False`` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. .. code-block:: python From 48ae5d5ab580b8df961958dd71bc77770d57a23e Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 16 Jul 2024 15:11:03 -0400 Subject: [PATCH 13/59] Main part decent draft This is the bulk or main part of LLD. The smaller methods, detect_liquid_presence and require_liquid_presence, are not here or in this draft. Those will go in the building block commands doc. --- api/docs/v2/pipettes/loading.rst | 82 +++++++++++++++++--------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 103eed7f447..80a1c773355 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -216,69 +216,73 @@ 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: + Liquid Level Detection ====================== -All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. +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. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~.InstrumentContext.pick_up_tip`) to perform additional LLD checks. - -Section Needs a Title ---------------------- + 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 96-Channel Pipette, the pressure sensors are on channels 1 and 96. -LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. +Enable LLD Globally +------------------- -.. code sample too long, shorten +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. .. code-block:: python - - def run(protocol: protocol_api.ProtocolContext): - tiprack1 = protocol.load_labware( - load_name="opentrons_flex_96_tiprack_1000ul", location="D1") - reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") - plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") - left = protocol.load_instrument( - instrument_name="flex_1channel_1000", - mount="left", - tip_racks=[tiprack1], - liquid_presence_detection=True + + right = protocol.load_instrument( + instrument_name="flex_8channel_1000", + mount="right", + tip_racks=[tiprack2], + liquid_presence_detection=True ) - reservoir.load_liquid(volume=10000) + +.. 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. Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: - pipette.pick_up_tip() + pipette.pick_up_tip(tiprack2) -Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: +.. + 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 - pipette.aspirate(100, reservoir["A1"]) - pipette.dispense(100, plate["A1"]) +Next, tell the robot to aspirate and dispense some liquid from the reservoir:: -During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + pipette.aspirate(100, reservoir["A1"]) #LLD happens during this step + pipette.dispense(100, plate["A1"]) -Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: +Finally, discard the used tip, pick up a new tip, and continue the protocol with LLD enabled:: pipette.drop_tip() - pipette.pick_up_tip(tiprack1["A2"]) + pipette.pick_up_tip(tiprack2) -LLD will not work with used tips. +Remember, LLD will not work with used tips. -Did You Try Turing it Off and Then On Again -------------------------------------------- -.. - Needs better title. - -If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's ``liquid_presence_detection`` property to ``False`` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. +Turing LLD Off and On +--------------------- + +You can turn LLD off and on throughout a protocol. To turn off LLD, 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(tiprack1["A2"]) - pipette.liquid_presence_detection = False + pipette.pick_up_tip(tiprack2) + pipette.liquid_presence_detection=False + pipette.aspirate(100, reservoir["A2"]) + +Going forward, the pipette will not perform an LLD check until you turn this feature back on. -After this, the pipette will not do LLD check during subsequent aspirations. To re-activate LLD, set ``pipette.liquid_presence_detection=True`` later in your protocol. +To reactivate LLD, 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 -Require Liquid Presence ------------------------ + pipette.pick_up_tip(tiprack2) + pipette.liquid_presence_detection=True + pipette.aspirate(100, reservoir["A3"]) -The ``foo thing`` just check the liquid status of a well, use +LLD will resume until it is disabled again, raises an error, or the protocol completes. From 7b1fe385333338131958405b601f7a87cd1aefb3 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 16 Jul 2024 15:47:43 -0400 Subject: [PATCH 14/59] Small changes --- api/docs/v2/pipettes/loading.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 80a1c773355..54965af0893 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -267,7 +267,7 @@ Remember, LLD will not work with used tips. Turing LLD Off and On --------------------- -You can turn LLD off and on throughout a protocol. To turn off LLD, 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 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. .. code-block:: python @@ -275,9 +275,9 @@ You can turn LLD off and on throughout a protocol. To turn off LLD, add ``pipett pipette.liquid_presence_detection=False pipette.aspirate(100, reservoir["A2"]) -Going forward, the pipette will not perform an LLD check until you turn this feature back on. +Going forward, the pipette will not perform LLD until you turn this feature back on. -To reactivate LLD, 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 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. .. code-block:: python From 51d21fb860b172998ee5f1c23d1c2eab95f3f1d0 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 09:44:22 -0400 Subject: [PATCH 15/59] Removed text, added version macro --- api/docs/v2/pipettes/loading.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 54965af0893..c756338cd37 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -257,13 +257,6 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) #LLD happens during this step pipette.dispense(100, plate["A1"]) -Finally, discard the used tip, pick up a new tip, and continue the protocol with LLD enabled:: - - pipette.drop_tip() - pipette.pick_up_tip(tiprack2) - -Remember, LLD will not work with used tips. - Turing LLD Off and On --------------------- @@ -286,3 +279,5 @@ To turn LLD on after deactivating it, add ``pipette.liquid_presence_detection=Tr pipette.aspirate(100, reservoir["A3"]) LLD will resume until it is disabled again, raises an error, or the protocol completes. + +.. versionadded:: 2.20 From 5db9dd0d2a3b138105758e56bd6b72c5baf1b628 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:09:29 -0400 Subject: [PATCH 16/59] Saving because I haven't yet --- api/docs/v2/basic_commands/liquids.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 06f5dfd3bf8..b59b2092891 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -258,3 +258,22 @@ This example aspirates enough air to fill the remaining volume in a pipette:: .. versionadded:: 2.0 +Detect Liquids +============== + +The :py:meth:`.InstrumentContext.detect_liquid_presence` method liquid presence detection to occur and returns the result. It will not raise an error if liquid is not present. +A return-presence command + + +.. versionadded:: 2.20 + +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. + +.. code-block:: python + + pipette.require_liquid_presence() + +.. versionadded:: 2.20 From 5677a16d9a6a4986d8b0d9d925d58647970bed09 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:23:11 -0400 Subject: [PATCH 17/59] Building block commands: detect & require --- api/docs/v2/basic_commands/liquids.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index b59b2092891..61078a175b1 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -261,9 +261,11 @@ This example aspirates enough air to fill the remaining volume in a pipette:: Detect Liquids ============== -The :py:meth:`.InstrumentContext.detect_liquid_presence` method liquid presence detection to occur and returns the result. It will not raise an error if liquid is not present. -A return-presence command +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`. +.. code-block:: python + + pipette.detect_liquid_presence() .. versionadded:: 2.20 From ec25699ebae51e24893d72cee079b6cce2ac580e Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:24:19 -0400 Subject: [PATCH 18/59] Misspellings in commented text Fixing because it raises warnings during docs builds. --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 7f2f86463ea..8e2b310f7af 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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" From 1bfff5070f827e643baecc7c3d55b1ac2ef1f0e1 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 14:50:25 -0400 Subject: [PATCH 19/59] More revisions Name changes and stubs. --- api/docs/v2/basic_commands/liquids.rst | 8 +++- api/docs/v2/pipettes/loading.rst | 39 +++++++++---------- .../protocol_api/instrument_context.py | 4 +- .../protocol_api/protocol_context.py | 2 +- 4 files changed, 27 insertions(+), 26 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 61078a175b1..c4f7dca1682 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -258,10 +258,12 @@ 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 @@ -269,10 +271,12 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells the robot .. 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 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index c756338cd37..0c594260908 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/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 `, 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 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 8e2b310f7af..1818a2ab2a8 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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. """ diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index e74922725bc..607cf9ef9d4 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -910,7 +910,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 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 """ From 8cb74dd857e0fee4d9e5103a98ca10a66fc0f8ca Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 16:55:30 -0400 Subject: [PATCH 20/59] Updating LPV intro - stress Flex only --- api/docs/v2/pipettes/loading.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 0c594260908..fc9fdcb509c 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,10 +221,10 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only 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. +Liquid Presence Verification (LPV) is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence of liquids in a well, reservoir, or other container. With LPV, you have the ability to identify, avoid, and recover from liquid-related protocol errors. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. LPV can be globally activated for the entire protocol run or toggled on and off as required. LPV 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 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 1 and 8. For the Flex 96-Channel Pipette, the pressure sensors are on channels 1 and 96. Enable LPV Globally ------------------- From f786e59dcce5a3bb02e767f828c91e27d09e6065 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 18 Jul 2024 11:07:25 -0400 Subject: [PATCH 21/59] detect_ and require_ revisions Changes to descriptions in Building Block Commands and in the docstring references. --- api/docs/v2/basic_commands/liquids.rst | 4 ++-- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c4f7dca1682..c6c65312443 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,7 +263,7 @@ This example aspirates enough air to fill the remaining volume in a pipette:: 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`. +Using 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpv`. .. code-block:: python @@ -276,7 +276,7 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells the robot 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. +Using the :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpv`. .. code-block:: python diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 1818a2ab2a8..82a66340b89 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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. See :ref:`detect-liquid-presence`. + """Checks if there is liquid in a well. Will not raise an error if it does not detect liquid. Flex pipettes only. 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. See :ref:`require-liquid-presence`. + """Checks for liquid in a well. Raises an error if no liquid is detected. Flex pipettes only. See :ref:`require-liquid-presence`. :returns: None. """ From bb661f115295cc54981920ece49368da8648caad Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 11:55:10 -0400 Subject: [PATCH 22/59] Reviewer changes and feature name change Changes from Ed's recommendations (Slack) and change name to "Liquid Presence Detection" from "Liquid Presence Verification." Some outstanding issues: code sample. Will get help w/ this. --- api/docs/v2/basic_commands/liquids.rst | 4 +- api/docs/v2/pipettes/loading.rst | 42 +++++++++++-------- .../protocol_api/instrument_context.py | 4 +- .../protocol_api/protocol_context.py | 2 +- 4 files changed, 30 insertions(+), 22 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c6c65312443..c8db1151b6b 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,7 +263,7 @@ This example aspirates enough air to fill the remaining volume in a pipette:: Detect Liquids ============== -Using 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpv`. +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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpd`. .. code-block:: python @@ -276,7 +276,7 @@ Using the :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Fl Require Liquids =============== -Using the :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpv`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpd`. .. code-block:: python diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index fc9fdcb509c..22348c4a62b 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -216,20 +216,24 @@ 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. -.. _lpv: +.. _lpd: -Liquid Presence Verification -============================ +Liquid Presence Detection +========================= -Liquid Presence Verification (LPV) is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence of liquids in a well, reservoir, or other container. With LPV, you have the ability to identify, avoid, and recover from liquid-related protocol errors. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. LPV can be globally activated for the entire protocol run or toggled on and off as required. LPV works with Flex pipettes only and is disabled by default. +Liquid Presence Detection is a pressure-based feature that allows Opentrons Flex pipettes to detect 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. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. You can enable liquid detection 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. -Enable LPV Globally -------------------- +.. versionadded:: 2.20 + +.. Ed: Enabling instead of Enable? + +Enable Liquid Presence Detection +-------------------------------- -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. +The easiest, and recommended, way to use Liquid Presence Detection 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 check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example adds Liquid Presence Detection to the 8-Channel Pipette used in the sample protocol at the top of the page. .. code-block:: python @@ -241,7 +245,7 @@ The easiest, and recommended, way to use LPV is by adding the optional Boolean a ) .. 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. + 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 new, clean tip:: @@ -252,29 +256,33 @@ 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. +Liquid detection takes place immediately prior to 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 ---------------------- +.. versionadded:: 2.20 + +Turning Liquid Presence Detection 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. +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 starting after picking up a new tip. .. code-block:: python pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=False #LPV off + pipette.liquid_presence_detection=False #Liquid Presence Detection off pipette.aspirate(100, reservoir["A2"]) -Going forward, the pipette will not perform LPV until you turn this feature back on. +Going forward, the pipette will not perform a liquid check 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. +To reactivate, 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.liquid_presence_detection=True #Liquid detection active again pipette.aspirate(100, reservoir["A3"]) -LPV will resume until it is disabled again, raises an error, or the protocol completes. +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. + +See also :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`. .. versionadded:: 2.20 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 82a66340b89..90b5c0d8127 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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: - """Checks if there is liquid in a well. Will not raise an error if it does not detect liquid. Flex pipettes only. See :ref:`detect-liquid-presence`. + """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`. :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: - """Checks for liquid in a well. Raises an error if no liquid is detected. Flex pipettes only. See :ref:`require-liquid-presence`. + """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`. :returns: None. """ diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 607cf9ef9d4..88f2b4b56a4 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -910,7 +910,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:`lpv`. + :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`. .. versionadded:: 2.20 """ From 5920bad80b602b464ef0de77a18a886381de0847 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 13:39:08 -0400 Subject: [PATCH 23/59] Small intro changes and to some how it works text --- api/docs/v2/pipettes/loading.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 22348c4a62b..302f5f76e25 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,7 +221,7 @@ 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 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. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. You can enable liquid detection 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. +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. @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately prior to 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. +Liquid detection takes place immediately 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 the presence or absence of a liquid adds time to your protocol run, so be aware of that before you use it. 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. .. versionadded:: 2.20 @@ -273,12 +273,12 @@ You can turn Liquid Presence Detection off and on throughout a protocol. To turn 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 in a protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid. +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. .. code-block:: python pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=True #Liquid detection active again + pipette.liquid_presence_detection=True #Liquid Presence Detection on again pipette.aspirate(100, reservoir["A3"]) 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. From a4f757741a7a905ca2c21358e85ab725676502c0 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 16:45:41 -0400 Subject: [PATCH 24/59] Explain using LLD requires extra time to execute --- api/docs/v2/pipettes/loading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 302f5f76e25..f1493b497e7 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately 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 the presence or absence of a liquid adds time to your protocol run, so be aware of that before you use it. 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. +Liquid detection takes place immediately 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 you use it. 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. .. versionadded:: 2.20 From 12f34e5ec2abc72be63b861d5f972efb8f76fd7a Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 26 Jul 2024 16:17:12 -0400 Subject: [PATCH 25/59] Not ready yet. More TK Monday. I'm a bit burned out. Saving to save. --- api/docs/v2/basic_commands/liquids.rst | 64 +++++++++++++++++++++++++- api/docs/v2/pipettes/loading.rst | 2 +- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c8db1151b6b..c2ecc3d88c0 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,12 +263,72 @@ 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. 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 wellplate or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration, but you don't need to call :py:meth:`~.InstrumentContext.aspirate` to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. See also :ref:`lpd`. .. code-block:: python pipette.detect_liquid_presence() +.. + Sample and text is longer than what we usually do. Trying it anyway. + Maybe do the labware and reservoir in text only and just show the for/while loop. + +This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. For example, let's create a protocol that includes a tiprack, a 12-well reservoir, a 96-well plate, a single-channel pipette, and the waste bin. + +.. code-block:: python + + def run(protocol: protocol_api.ProtocolContext): + tiprack = (protocol.load_labware(TIPRACK_NAME, 'D1')).wells() + reservoir = (protocol.load_labware(RESERVOIR_NAME, 'C2')).wells_by_name() + plate = (protocol.load_labware(PLATE_NAME, 'D2')).wells() + trash_bin = protocol.load_trash_bin('B3') + pipette = protocol.load_instrument(PIPETTE_SINGLE_CHANNEL_NAME, mount="left", liquid_presence_detection=False) + +Next, we'll add water to the reservoir as our test liquid:: + + water = protocol.define_liquid(name="water", description="Normal water", display_color="#42AB2D") + reservoir["A1"].load_liquid(liquid=water, volume=1000) + reservoir["A2"].load_liquid(liquid=water, volume=500) + reservoir["A3"].load_liquid(liquid=water, volume=850) + ... + reservoir["A11"].load_liquid(liquid=water, volume=0) + reservoir["A12"].load_liquid(liquid=water, volume=250) + +Now include some indexing to keep track of how many tips were used and which well plates received liquid:: + + tipIndex = 0 + plateIndex = 0 + +And finish up with ``for`` and ``while`` loops to perform liquid handling:: + + for name, well in reservoir.items(): + + pipette.pick_up_tip(tiprack[tipIndex]) + hasLiquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash_bin) + tipIndex+=1 + + curIndex = 0 + while hasLiquid: + pipette.pick_up_tip(tiprack[tipIndex]) + pipette.aspirate(250, well) + pipette.dispense(250, plate[plateIndex]) + pipette.drop_tip(trash_bin) + tipIndex+=1 + plateIndex+=1 + + pipette.pick_up_tip(tiprack[tipIndex]) + hasLiquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash_bin) + tipIndex+=1 + + curIndex+=1 + protocol.comment(f"Found liquid and aspirated from well {name} {curIndex} times. It is now empty.") + + protocol.comment("Exhausted all wells in reservoir.") + +When the robot uses all the liquid in a well, or finds an empty well, it will write a message to the robot's run log that records the well's name (e.g. ``A1``, ``A2``, etc.) and how many times it aspirated from that well before it ran dry. Then, it checks the next well for liquid. If the robot doesn't find liquid in the next well, it keeps checking each well until it does find liquid and starts the aspiration/dispense cycle again. If the protocol uses all the liquid in its wells, the robot records that too. + .. versionadded:: 2.20 .. _require-liquid-presence: @@ -276,7 +336,7 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pip Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. See also :ref:`lpd`. .. code-block:: python diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index f1493b497e7..b60a0cda1d0 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately 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 you use it. 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. +Liquid detection takes place immediately 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 you use it. When the robot doesn't detect liquid during an aspiration, it raises an error and stops the protocol until the problem is resolved. .. versionadded:: 2.20 From c6a6fde8892ba7082c7aadd3dd896c8e0d731d90 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 29 Jul 2024 12:00:42 -0400 Subject: [PATCH 26/59] Shorten code sample, revise explanation --- api/docs/v2/basic_commands/liquids.rst | 70 +++++++++----------------- 1 file changed, 25 insertions(+), 45 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c2ecc3d88c0..8eee424497c 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,71 +263,50 @@ 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 liquid if the sensors do not. Detection takes place during aspiration, but you don't need to call :py:meth:`~.InstrumentContext.aspirate` to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. 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 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`. .. code-block:: python pipette.detect_liquid_presence() -.. - Sample and text is longer than what we usually do. Trying it anyway. - Maybe do the labware and reservoir in text only and just show the for/while loop. - -This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. For example, let's create a protocol that includes a tiprack, a 12-well reservoir, a 96-well plate, a single-channel pipette, and the waste bin. +In cases where you need records that are more informative than ``true`` or ``false``, you can write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. Here's one way to do this in the ``run():`` function of our Flex :ref:`protocol template `: .. code-block:: python - def run(protocol: protocol_api.ProtocolContext): - tiprack = (protocol.load_labware(TIPRACK_NAME, 'D1')).wells() - reservoir = (protocol.load_labware(RESERVOIR_NAME, 'C2')).wells_by_name() - plate = (protocol.load_labware(PLATE_NAME, 'D2')).wells() - trash_bin = protocol.load_trash_bin('B3') - pipette = protocol.load_instrument(PIPETTE_SINGLE_CHANNEL_NAME, mount="left", liquid_presence_detection=False) - -Next, we'll add water to the reservoir as our test liquid:: - - water = protocol.define_liquid(name="water", description="Normal water", display_color="#42AB2D") - reservoir["A1"].load_liquid(liquid=water, volume=1000) - reservoir["A2"].load_liquid(liquid=water, volume=500) - reservoir["A3"].load_liquid(liquid=water, volume=850) - ... - reservoir["A11"].load_liquid(liquid=water, volume=0) - reservoir["A12"].load_liquid(liquid=water, volume=250) - -Now include some indexing to keep track of how many tips were used and which well plates received liquid:: - - tipIndex = 0 - plateIndex = 0 - -And finish up with ``for`` and ``while`` loops to perform liquid handling:: + tip_index = 0 # tracks how many tips are used. + plate_index = 0 # tracks the wells dispensed to. Increments after dispense. for name, well in reservoir.items(): - pipette.pick_up_tip(tiprack[tipIndex]) - hasLiquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash_bin) - tipIndex+=1 + has_liquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash) + tip_index+=1 - curIndex = 0 - while hasLiquid: + cur_index = 0 # counts aspirate/dispense cycles from a reservoir well. + while has_liquid: pipette.pick_up_tip(tiprack[tipIndex]) pipette.aspirate(250, well) pipette.dispense(250, plate[plateIndex]) - pipette.drop_tip(trash_bin) - tipIndex+=1 - plateIndex+=1 + pipette.drop_tip(trash) + tip_index+=1 + plate_index+=1 pipette.pick_up_tip(tiprack[tipIndex]) - hasLiquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash_bin) - tipIndex+=1 + has_liquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash) + tip_index+=1 + + cur_index+=1 - curIndex+=1 - protocol.comment(f"Found liquid and aspirated from well {name} {curIndex} times. It is now empty.") + # Add a helpful record to the run log when a well runs dry or is empty. + protocol.comment( + f"Found liquid and aspirated from well {name} {curIndex} times. Well is now empty." + ) + # Add a helpful record to the run log when all source wells are empty. protocol.comment("Exhausted all wells in reservoir.") -When the robot uses all the liquid in a well, or finds an empty well, it will write a message to the robot's run log that records the well's name (e.g. ``A1``, ``A2``, etc.) and how many times it aspirated from that well before it ran dry. Then, it checks the next well for liquid. If the robot doesn't find liquid in the next well, it keeps checking each well until it does find liquid and starts the aspiration/dispense cycle again. If the protocol uses all the liquid in its wells, the robot records that too. +Now the Flex records an entry in the run log that includes the well's name (e.g. ``A1``, ``A2``, ``B1`` etc.) and how many times the pipette aspirated from that well before it ran dry. If a protocol uses all the liquid in its source wells, the robot records that too. .. versionadded:: 2.20 @@ -336,7 +315,8 @@ When the robot uses all the liquid in a well, or finds an empty well, it will wr Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. When the robot does not detect liquid, it raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. +Detection takes place during aspiration, but you don't need to aspirate to use ``require_liquid_presence``. It's a standalone method that can be called when you want to detect liquids only. See also :ref:`lpd`. .. code-block:: python From d8b5d7f3315fca99cd9765a3add1ed9186adb45e Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 9 Jul 2024 16:31:33 -0400 Subject: [PATCH 27/59] Test push Aa a reminder of how to do this. It's been a while. --- api/docs/v2/pipettes/loading.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 72a13ce3409..ed4a63a16a0 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -7,6 +7,8 @@ Loading Pipettes **************** +Test test test. + When writing a protocol, you must inform the Protocol API about the pipettes you will be using on your robot. The :py:meth:`.ProtocolContext.load_instrument` function provides this information and returns an :py:class:`.InstrumentContext` object. As noted above, you call the :py:meth:`~.ProtocolContext.load_instrument` method to load a pipette. This method also requires the :ref:`pipette's API load name `, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly. From dbb62f97ec707f0c7935696d1e19094565404ff8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 9 Jul 2024 17:09:42 -0400 Subject: [PATCH 28/59] Removing test text, not important --- api/docs/v2/pipettes/loading.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ed4a63a16a0..72a13ce3409 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -7,8 +7,6 @@ Loading Pipettes **************** -Test test test. - When writing a protocol, you must inform the Protocol API about the pipettes you will be using on your robot. The :py:meth:`.ProtocolContext.load_instrument` function provides this information and returns an :py:class:`.InstrumentContext` object. As noted above, you call the :py:meth:`~.ProtocolContext.load_instrument` method to load a pipette. This method also requires the :ref:`pipette's API load name `, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly. From 6aeb47d3149b22645036a50296746a799e3f6410 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 10 Jul 2024 11:58:46 -0400 Subject: [PATCH 29/59] Edit LPD argument definition. Make it clear this is for Flex only and include the version. --- api/src/opentrons/protocol_api/protocol_context.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index ad1f326b40e..60cef65cd94 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -906,7 +906,9 @@ 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``, 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 a 1-, 8-, or 96-channel pipette. Flex only. + + .. versionadded:: 2.20 """ instrument_name = validation.ensure_lowercase_name(instrument_name) checked_instrument_name = validation.ensure_pipette_name(instrument_name) From b6d3160ba3fa8f3fc8906a773d6ffa1c5fc2bb03 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 09:53:59 -0400 Subject: [PATCH 30/59] H2 LLD section summary --- api/docs/v2/pipettes/loading.rst | 9 +++++++++ api/src/opentrons/protocol_api/protocol_context.py | 4 ++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 72a13ce3409..6a381f63fb1 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -215,3 +215,12 @@ 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. + +Liquid Level Detection +====================== + +All Opentrons Flex pipettes have pressure sensors that detect the presence or absence of a liquid in a well plate, reservoir, or other types of labware containers. With liquid level detection (LLD) enabled in your protocols, the robot can stop a pipette at at or just below the surface of a liquid sample before aspirating. Also, the various LLD methods described here can help you avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. + +.. note:: + LLD requires a clean, dry pipette tip. This means you must discard a tip after every aspirate/dispsense cycle and pickup a fresh tip before the next cycle. + diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 60cef65cd94..fa286f0f3b8 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -906,9 +906,9 @@ 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 a 1-, 8-, or 96-channel pipette. Flex only. + :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for a 1-, 8-, or pipette. Flex only. - .. versionadded:: 2.20 + .. versionadded:: 2.20 """ instrument_name = validation.ensure_lowercase_name(instrument_name) checked_instrument_name = validation.ensure_pipette_name(instrument_name) From b38a28948826ae88f2d943bde6e63668533765a3 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 12:06:48 -0400 Subject: [PATCH 31/59] LLD intro and global method --- api/docs/v2/pipettes/loading.rst | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 6a381f63fb1..1b5ba4186d2 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -219,8 +219,29 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only Liquid Level Detection ====================== -All Opentrons Flex pipettes have pressure sensors that detect the presence or absence of a liquid in a well plate, reservoir, or other types of labware containers. With liquid level detection (LLD) enabled in your protocols, the robot can stop a pipette at at or just below the surface of a liquid sample before aspirating. Also, the various LLD methods described here can help you avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. +All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires a clean, dry pipette tip. This means you must discard a tip after every aspirate/dispsense cycle and pickup a fresh tip before the next cycle. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must discard the used tip and pick up a new one to perform additional LLD checks. + +Section Needs a Title +--------------------- + +You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also turn this off later, or or make it explicitly ``False`` and activate it later in a protocol. Using sample protocol at the top of the page, this example adds LLD to the left-mounted, 1-Channel pipette. + +.. code-block:: python + + left = protocol.load_instrument( + instrument_name="flex_1channel_1000", + mount="left", + tip_racks=[tiprack1], + liquid_presence_detection=True + ) + +Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. When the pressure sensor detects a liquid the code returns ``True`` and the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + +And remember, LLD requires a fresh tip for every aspiration. To continue LLD throughout the protocol, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments:: + + pipette.drop_tip(trash_bin) + From e40a07bc4a5a1176229df73df09e61367a7bcef1 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 13:18:27 -0400 Subject: [PATCH 32/59] Adding link to drop_tip --- api/docs/v2/pipettes/loading.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 1b5ba4186d2..ec6b4d91048 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -238,10 +238,7 @@ You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:met liquid_presence_detection=True ) -Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. When the pressure sensor detects a liquid the code returns ``True`` and the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. - -And remember, LLD requires a fresh tip for every aspiration. To continue LLD throughout the protocol, call the :py:meth:`~.InstrumentContext.drop_tip` method with no arguments:: - - pipette.drop_tip(trash_bin) +Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +And remember, LLD always requires a fresh tip. Call :py:meth:`~.InstrumentContext.drop_tip` in your protocol to throw the used tip away and pick up a new tip before every aspiration. From 2fcc41c06b020fb116610be77077946ee73914c9 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 13:29:15 -0400 Subject: [PATCH 33/59] Turning global LLD off --- api/docs/v2/pipettes/loading.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ec6b4d91048..e26cb708309 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,7 +222,7 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must discard the used tip and pick up a new one to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new one to perform additional LLD checks. Section Needs a Title --------------------- @@ -240,5 +240,13 @@ You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:met Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. -And remember, LLD always requires a fresh tip. Call :py:meth:`~.InstrumentContext.drop_tip` in your protocol to throw the used tip away and pick up a new tip before every aspiration. +Turning it off +-------------- +.. + Needs better title +Turn it off + +.. code-block:: python + + pipette.liquid_detection = False From 07fddd390306a94e98395af01fb2f0644ba06c6f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 12 Jul 2024 17:06:53 -0400 Subject: [PATCH 34/59] End of day save Deve environment conked out. --- api/docs/v2/pipettes/loading.rst | 34 ++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index e26cb708309..6fa93adf660 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,31 +222,49 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new one to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~InstrumentContext.pick_up_tip`) to perform additional LLD checks. Section Needs a Title --------------------- -You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also turn this off later, or or make it explicitly ``False`` and activate it later in a protocol. Using sample protocol at the top of the page, this example adds LLD to the left-mounted, 1-Channel pipette. +LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. .. code-block:: python +def run(protocol: protocol_api.ProtocolContext): + tiprack1 = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", location="D1") + reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") + plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") left = protocol.load_instrument( instrument_name="flex_1channel_1000", mount="left", tip_racks=[tiprack1], liquid_presence_detection=True ) + reservoir.load_liquid(volume=10000) + +Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: + + pipette.pick_up_tip() + +Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: + + pipette.aspirate(100, plate["A1"]) -Liquid presence detection occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate`. As the pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. -Turning it off --------------- + +theLLD occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate` and works as follows: as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + +Did You Try Turing it Off and Then On Again +------------------------------------------- .. - Needs better title -Turn it off + Needs better title. IT Crowd :) + +In the previous example, the robot checks for liquid every single time time. If this is too frequent, you can override the global setting and disable LLD for a particular aspiration. To override the global behavior, set the pipette's `liquid_presence_detection` property to `False`. Let's take a look at this starting from the .. code-block:: python - pipette.liquid_detection = False + pipette.liquid_presence_detection = False From 00aaf919888300425000e7704783f8c7abbf989d Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 11:18:06 -0400 Subject: [PATCH 35/59] Update loading.rst --- api/docs/v2/pipettes/loading.rst | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 6fa93adf660..e9e1c11fa57 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -250,21 +250,32 @@ Now, let's add some commands and start the cycle. First, tell the robot to pick Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: - pipette.aspirate(100, plate["A1"]) + pipette.aspirate(100, reservoir["A1"]) + pipette.dispense(100, plate["A1"]) -During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. +During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: +pipette.drop_tip() +pipette.pick_up_tip(tiprack1["A2"]) -theLLD occurs when your protocol calls :py:meth:`.InstrumentContext.aspirate` and works as follows: as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. +LLD will not work with used tips. Did You Try Turing it Off and Then On Again ------------------------------------------- .. - Needs better title. IT Crowd :) + Needs better title. -In the previous example, the robot checks for liquid every single time time. If this is too frequent, you can override the global setting and disable LLD for a particular aspiration. To override the global behavior, set the pipette's `liquid_presence_detection` property to `False`. Let's take a look at this starting from the +If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's `liquid_presence_detection` property to `False` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. .. code-block:: python + pipette.pick_up_tip(tiprack1["A2"]) pipette.liquid_presence_detection = False + +After this, the pipette will not do LLD check for subsequent aspirations. To re-activate LLD set ``pipette.liquid_presence_detection=True`` later in your protocol. + +Require Liquid Presence +----------------------- + From 3292b61529bdd6c2804892f73570be421152e931 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:07:43 -0400 Subject: [PATCH 36/59] Fix shortened API reference Forgot ~. --- api/docs/v2/pipettes/loading.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index e9e1c11fa57..ae03dc4e3a4 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -222,7 +222,7 @@ Liquid Level Detection All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~InstrumentContext.pick_up_tip`) to perform additional LLD checks. + LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~.InstrumentContext.pick_up_tip`) to perform additional LLD checks. Section Needs a Title --------------------- @@ -279,3 +279,4 @@ After this, the pipette will not do LLD check for subsequent aspirations. To re- Require Liquid Presence ----------------------- +The `` just check the liquid status of a well, use From 8560aa2f8627d8b1eafaae8e51538bfa1264fe2c Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:23:09 -0400 Subject: [PATCH 37/59] Fixing code formatting --- api/docs/v2/pipettes/loading.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index ae03dc4e3a4..091912ec5d8 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -230,20 +230,20 @@ Section Needs a Title LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. .. code-block:: python - -def run(protocol: protocol_api.ProtocolContext): - tiprack1 = protocol.load_labware( + + def run(protocol: protocol_api.ProtocolContext): + tiprack1 = protocol.load_labware( load_name="opentrons_flex_96_tiprack_1000ul", location="D1") - reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") - plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") - left = protocol.load_instrument( + reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") + plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") + left = protocol.load_instrument( instrument_name="flex_1channel_1000", mount="left", tip_racks=[tiprack1], liquid_presence_detection=True ) reservoir.load_liquid(volume=10000) - + Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: pipette.pick_up_tip() @@ -257,8 +257,8 @@ During aspiration, as the pipette's pressure sensor detects a liquid, the code r Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: -pipette.drop_tip() -pipette.pick_up_tip(tiprack1["A2"]) + pipette.drop_tip() + pipette.pick_up_tip(tiprack1["A2"]) LLD will not work with used tips. @@ -274,9 +274,9 @@ If using LLD on on every aspirate is too frequent, you can disable and enable it pipette.pick_up_tip(tiprack1["A2"]) pipette.liquid_presence_detection = False -After this, the pipette will not do LLD check for subsequent aspirations. To re-activate LLD set ``pipette.liquid_presence_detection=True`` later in your protocol. +After this, the pipette will not do LLD check during subsequent aspirations. To re-activate LLD, set ``pipette.liquid_presence_detection=True`` later in your protocol. Require Liquid Presence ----------------------- -The `` just check the liquid status of a well, use +The ``foo thing`` just check the liquid status of a well, use From 29b0dc7e06b74994c00e87a7995a8d5646ff3bc4 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 15 Jul 2024 16:59:40 -0400 Subject: [PATCH 38/59] End 'o day commit, will shorten code example --- api/docs/v2/pipettes/loading.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 091912ec5d8..103eed7f447 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -227,20 +227,22 @@ All Opentrons Flex pipettes use pressure sensors to detect the presence or absen Section Needs a Title --------------------- -LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. +LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. + +.. code sample too long, shorten .. code-block:: python def run(protocol: protocol_api.ProtocolContext): tiprack1 = protocol.load_labware( - load_name="opentrons_flex_96_tiprack_1000ul", location="D1") + load_name="opentrons_flex_96_tiprack_1000ul", location="D1") reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") left = protocol.load_instrument( - instrument_name="flex_1channel_1000", - mount="left", - tip_racks=[tiprack1], - liquid_presence_detection=True + instrument_name="flex_1channel_1000", + mount="left", + tip_racks=[tiprack1], + liquid_presence_detection=True ) reservoir.load_liquid(volume=10000) @@ -267,7 +269,7 @@ Did You Try Turing it Off and Then On Again .. Needs better title. -If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's `liquid_presence_detection` property to `False` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. +If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's ``liquid_presence_detection`` property to ``False`` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. .. code-block:: python From bb36fa3606cfd798d075c1ba4616ab5dac0c8147 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 16 Jul 2024 15:11:03 -0400 Subject: [PATCH 39/59] Main part decent draft This is the bulk or main part of LLD. The smaller methods, detect_liquid_presence and require_liquid_presence, are not here or in this draft. Those will go in the building block commands doc. --- api/docs/v2/pipettes/loading.rst | 82 +++++++++++++++++--------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 103eed7f447..80a1c773355 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -216,69 +216,73 @@ 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: + Liquid Level Detection ====================== -All Opentrons Flex pipettes use pressure sensors to detect the presence or absence of a liquid in a well plate or reservoir. When added to a protocol, liquid level detection (LLD) stops the pipette tip at the surface of a liquid sample before aspirating. You can use LLD to avoid and recover from protocol errors or just check for the presence or absence of a fluid with or without interrupting a protocol run. For Opentrons Flex 8-Channel pipettes, the sensors are located in channels 1 and 8. For Opentrons Flex 96-Channel pipettes, the sensors are located in channels 1 and 96. +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. .. note:: - LLD requires fresh, clean, and dry pipette tips. After aspirating, your pipette must always discard the used tip (call :py:meth:`~.InstrumentContext.drop_tip`) and pick up a new tip (call :py:meth:`~.InstrumentContext.pick_up_tip`) to perform additional LLD checks. - -Section Needs a Title ---------------------- + 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 96-Channel Pipette, the pressure sensors are on channels 1 and 96. -LLD is disabled by default. You enable LLD globally by setting ``liquid_presence_detection=True`` in :py:meth:`.ProtocolContext.load_instrument`. You can also deactivate LLD for individual aspirations, or or make it globally ``False`` and activate it later in a protocol. This example modifies the sample protocol used at the top of the page by adding some additional labware and enables LLD on the left-mounted, 1-Channel pipette. +Enable LLD Globally +------------------- -.. code sample too long, shorten +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. .. code-block:: python - - def run(protocol: protocol_api.ProtocolContext): - tiprack1 = protocol.load_labware( - load_name="opentrons_flex_96_tiprack_1000ul", location="D1") - reservoir = protocol.load_labware("nest_12_reservoir_15ml", location="D2") - plate = protocol.load_labware("nest_96_wellplate_200ul_flat", location="D3") - left = protocol.load_instrument( - instrument_name="flex_1channel_1000", - mount="left", - tip_racks=[tiprack1], - liquid_presence_detection=True + + right = protocol.load_instrument( + instrument_name="flex_8channel_1000", + mount="right", + tip_racks=[tiprack2], + liquid_presence_detection=True ) - reservoir.load_liquid(volume=10000) + +.. 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. Now, let's add some commands and start the cycle. First, tell the robot to pick up a new, clean tip:: - pipette.pick_up_tip() + pipette.pick_up_tip(tiprack2) -Next, tell the robot to aspirate some liquid from the reservoir. LLD takes place during this step:: +.. + 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 - pipette.aspirate(100, reservoir["A1"]) - pipette.dispense(100, plate["A1"]) +Next, tell the robot to aspirate and dispense some liquid from the reservoir:: -During aspiration, as the pipette's pressure sensor detects a liquid, the code returns ``True``, the pipette pauses, raises itself slightly above the surface of the liquid, and then moves into the liquid to continue the aspiration. If a pipette doesn't detect a liquid, it returns ``False``, raises an error, and stops the protocol. + pipette.aspirate(100, reservoir["A1"]) #LLD happens during this step + pipette.dispense(100, plate["A1"]) -Finally, be sure to dispose of the tip and pick up a new one after each aspiration/dispense cycle:: +Finally, discard the used tip, pick up a new tip, and continue the protocol with LLD enabled:: pipette.drop_tip() - pipette.pick_up_tip(tiprack1["A2"]) + pipette.pick_up_tip(tiprack2) -LLD will not work with used tips. +Remember, LLD will not work with used tips. -Did You Try Turing it Off and Then On Again -------------------------------------------- -.. - Needs better title. - -If using LLD on on every aspirate is too frequent, you can disable and enable it as required. To do this, set the pipette's ``liquid_presence_detection`` property to ``False`` for one or more aspirations. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's take a look at this starting after picking up a new tip. +Turing LLD Off and On +--------------------- + +You can turn LLD off and on throughout a protocol. To turn off LLD, 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(tiprack1["A2"]) - pipette.liquid_presence_detection = False + pipette.pick_up_tip(tiprack2) + pipette.liquid_presence_detection=False + pipette.aspirate(100, reservoir["A2"]) + +Going forward, the pipette will not perform an LLD check until you turn this feature back on. -After this, the pipette will not do LLD check during subsequent aspirations. To re-activate LLD, set ``pipette.liquid_presence_detection=True`` later in your protocol. +To reactivate LLD, 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 -Require Liquid Presence ------------------------ + pipette.pick_up_tip(tiprack2) + pipette.liquid_presence_detection=True + pipette.aspirate(100, reservoir["A3"]) -The ``foo thing`` just check the liquid status of a well, use +LLD will resume until it is disabled again, raises an error, or the protocol completes. From 883ed721e09361dcafbcbd69b8c68a1f8a3f7dd8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 16 Jul 2024 15:47:43 -0400 Subject: [PATCH 40/59] Small changes --- api/docs/v2/pipettes/loading.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 80a1c773355..54965af0893 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -267,7 +267,7 @@ Remember, LLD will not work with used tips. Turing LLD Off and On --------------------- -You can turn LLD off and on throughout a protocol. To turn off LLD, 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 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. .. code-block:: python @@ -275,9 +275,9 @@ You can turn LLD off and on throughout a protocol. To turn off LLD, add ``pipett pipette.liquid_presence_detection=False pipette.aspirate(100, reservoir["A2"]) -Going forward, the pipette will not perform an LLD check until you turn this feature back on. +Going forward, the pipette will not perform LLD until you turn this feature back on. -To reactivate LLD, 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 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. .. code-block:: python From 0710757a7b0e15a58952516f23c499d8a51e9b9b Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 09:44:22 -0400 Subject: [PATCH 41/59] Removed text, added version macro --- api/docs/v2/pipettes/loading.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 54965af0893..c756338cd37 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -257,13 +257,6 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) #LLD happens during this step pipette.dispense(100, plate["A1"]) -Finally, discard the used tip, pick up a new tip, and continue the protocol with LLD enabled:: - - pipette.drop_tip() - pipette.pick_up_tip(tiprack2) - -Remember, LLD will not work with used tips. - Turing LLD Off and On --------------------- @@ -286,3 +279,5 @@ To turn LLD on after deactivating it, add ``pipette.liquid_presence_detection=Tr pipette.aspirate(100, reservoir["A3"]) LLD will resume until it is disabled again, raises an error, or the protocol completes. + +.. versionadded:: 2.20 From 8031d972d356e02ebb7868005c654450bdcbe4c2 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:09:29 -0400 Subject: [PATCH 42/59] Saving because I haven't yet --- api/docs/v2/basic_commands/liquids.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 06f5dfd3bf8..b59b2092891 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -258,3 +258,22 @@ This example aspirates enough air to fill the remaining volume in a pipette:: .. versionadded:: 2.0 +Detect Liquids +============== + +The :py:meth:`.InstrumentContext.detect_liquid_presence` method liquid presence detection to occur and returns the result. It will not raise an error if liquid is not present. +A return-presence command + + +.. versionadded:: 2.20 + +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. + +.. code-block:: python + + pipette.require_liquid_presence() + +.. versionadded:: 2.20 From 458d46a539dd3e1213f412b8ec2a8a72397cca8b Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:23:11 -0400 Subject: [PATCH 43/59] Building block commands: detect & require --- api/docs/v2/basic_commands/liquids.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index b59b2092891..61078a175b1 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -261,9 +261,11 @@ This example aspirates enough air to fill the remaining volume in a pipette:: Detect Liquids ============== -The :py:meth:`.InstrumentContext.detect_liquid_presence` method liquid presence detection to occur and returns the result. It will not raise an error if liquid is not present. -A return-presence command +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`. +.. code-block:: python + + pipette.detect_liquid_presence() .. versionadded:: 2.20 From 16b50c565e988ecad7c3958900d8068f48f62acf Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 11:24:19 -0400 Subject: [PATCH 44/59] Misspellings in commented text Fixing because it raises warnings during docs builds. --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c39a4aba2ac..191e9702054 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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" From 9e1b8b6eac9b2300ae26d7f8d6e876a12064a1fa Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 14:50:25 -0400 Subject: [PATCH 45/59] More revisions Name changes and stubs. --- api/docs/v2/basic_commands/liquids.rst | 8 +++- api/docs/v2/pipettes/loading.rst | 39 +++++++++---------- .../protocol_api/instrument_context.py | 4 +- .../protocol_api/protocol_context.py | 2 +- 4 files changed, 27 insertions(+), 26 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 61078a175b1..c4f7dca1682 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -258,10 +258,12 @@ 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 @@ -269,10 +271,12 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells the robot .. 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 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index c756338cd37..0c594260908 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/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 `, 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 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 191e9702054..c8ebe89dafc 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2120,7 +2120,7 @@ def configure_nozzle_layout( # noqa: C901 @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. """ @@ -2130,7 +2130,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. """ diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index fa286f0f3b8..e131be7a9ce 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 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 """ From c4f001228c65f656a87390104630271f96053725 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 17 Jul 2024 16:55:30 -0400 Subject: [PATCH 46/59] Updating LPV intro - stress Flex only --- api/docs/v2/pipettes/loading.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 0c594260908..fc9fdcb509c 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,10 +221,10 @@ Another example is a Flex protocol that uses a waste chute. Say you want to only 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. +Liquid Presence Verification (LPV) is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence of liquids in a well, reservoir, or other container. With LPV, you have the ability to identify, avoid, and recover from liquid-related protocol errors. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. LPV can be globally activated for the entire protocol run or toggled on and off as required. LPV 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 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 1 and 8. For the Flex 96-Channel Pipette, the pressure sensors are on channels 1 and 96. Enable LPV Globally ------------------- From ab4219031fe3318f4fd9cf301d2ab060c5ce819d Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 18 Jul 2024 11:07:25 -0400 Subject: [PATCH 47/59] detect_ and require_ revisions Changes to descriptions in Building Block Commands and in the docstring references. --- api/docs/v2/basic_commands/liquids.rst | 4 ++-- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c4f7dca1682..c6c65312443 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,7 +263,7 @@ This example aspirates enough air to fill the remaining volume in a pipette:: 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`. +Using 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpv`. .. code-block:: python @@ -276,7 +276,7 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells the robot 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. +Using the :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpv`. .. code-block:: python diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c8ebe89dafc..e15f463ffb7 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2120,7 +2120,7 @@ def configure_nozzle_layout( # noqa: C901 @requires_version(2, 20) def detect_liquid_presence(self, well: labware.Well) -> bool: - """Check if there is liquid in a well. See :ref:`detect-liquid-presence`. + """Checks if there is liquid in a well. Will not raise an error if it does not detect liquid. Flex pipettes only. See :ref:`detect-liquid-presence`. :returns: A boolean. """ @@ -2130,7 +2130,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. See :ref:`require-liquid-presence`. + """Checks for liquid in a well. Raises an error if no liquid is detected. Flex pipettes only. See :ref:`require-liquid-presence`. :returns: None. """ From a283b30d83329effb89d26802ecf79b838e7b908 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 11:55:10 -0400 Subject: [PATCH 48/59] Reviewer changes and feature name change Changes from Ed's recommendations (Slack) and change name to "Liquid Presence Detection" from "Liquid Presence Verification." Some outstanding issues: code sample. Will get help w/ this. --- api/docs/v2/basic_commands/liquids.rst | 4 +- api/docs/v2/pipettes/loading.rst | 42 +++++++++++-------- .../protocol_api/instrument_context.py | 4 +- .../protocol_api/protocol_context.py | 2 +- 4 files changed, 30 insertions(+), 22 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c6c65312443..c8db1151b6b 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,7 +263,7 @@ This example aspirates enough air to fill the remaining volume in a pipette:: Detect Liquids ============== -Using 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpv`. +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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. See also :ref:`lpd`. .. code-block:: python @@ -276,7 +276,7 @@ Using the :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Fl Require Liquids =============== -Using the :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpv`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpd`. .. code-block:: python diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index fc9fdcb509c..22348c4a62b 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -216,20 +216,24 @@ 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. -.. _lpv: +.. _lpd: -Liquid Presence Verification -============================ +Liquid Presence Detection +========================= -Liquid Presence Verification (LPV) is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence of liquids in a well, reservoir, or other container. With LPV, you have the ability to identify, avoid, and recover from liquid-related protocol errors. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. LPV can be globally activated for the entire protocol run or toggled on and off as required. LPV works with Flex pipettes only and is disabled by default. +Liquid Presence Detection is a pressure-based feature that allows Opentrons Flex pipettes to detect 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. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. You can enable liquid detection 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. -Enable LPV Globally -------------------- +.. versionadded:: 2.20 + +.. Ed: Enabling instead of Enable? + +Enable Liquid Presence Detection +-------------------------------- -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. +The easiest, and recommended, way to use Liquid Presence Detection 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 check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example adds Liquid Presence Detection to the 8-Channel Pipette used in the sample protocol at the top of the page. .. code-block:: python @@ -241,7 +245,7 @@ The easiest, and recommended, way to use LPV is by adding the optional Boolean a ) .. 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. + 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 new, clean tip:: @@ -252,29 +256,33 @@ 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. +Liquid detection takes place immediately prior to 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 ---------------------- +.. versionadded:: 2.20 + +Turning Liquid Presence Detection 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. +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 starting after picking up a new tip. .. code-block:: python pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=False #LPV off + pipette.liquid_presence_detection=False #Liquid Presence Detection off pipette.aspirate(100, reservoir["A2"]) -Going forward, the pipette will not perform LPV until you turn this feature back on. +Going forward, the pipette will not perform a liquid check 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. +To reactivate, 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.liquid_presence_detection=True #Liquid detection active again pipette.aspirate(100, reservoir["A3"]) -LPV will resume until it is disabled again, raises an error, or the protocol completes. +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. + +See also :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`. .. versionadded:: 2.20 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index e15f463ffb7..96922f12ab6 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2120,7 +2120,7 @@ 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:`detect-liquid-presence`. + """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`. :returns: A boolean. """ @@ -2130,7 +2130,7 @@ 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:`require-liquid-presence`. + """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`. :returns: None. """ diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index e131be7a9ce..0d46804fdab 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:`lpv`. + :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`. .. versionadded:: 2.20 """ From 378c96b2bfe707b5eb105b1019db2ff6d47277b8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 13:39:08 -0400 Subject: [PATCH 49/59] Small intro changes and to some how it works text --- api/docs/v2/pipettes/loading.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 22348c4a62b..302f5f76e25 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,7 +221,7 @@ 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 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. Additionally, you can use it to check for the presence or absence of a fluid, all without interrupting a protocol run. You can enable liquid detection 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. +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. @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately prior to 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. +Liquid detection takes place immediately 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 the presence or absence of a liquid adds time to your protocol run, so be aware of that before you use it. 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. .. versionadded:: 2.20 @@ -273,12 +273,12 @@ You can turn Liquid Presence Detection off and on throughout a protocol. To turn 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 in a protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid. +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. .. code-block:: python pipette.pick_up_tip(tiprack2) - pipette.liquid_presence_detection=True #Liquid detection active again + pipette.liquid_presence_detection=True #Liquid Presence Detection on again pipette.aspirate(100, reservoir["A3"]) 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. From fd5b72e005862906eb8c3e1c820318b2c4921fa8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 24 Jul 2024 16:45:41 -0400 Subject: [PATCH 50/59] Explain using LLD requires extra time to execute --- api/docs/v2/pipettes/loading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 302f5f76e25..f1493b497e7 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately 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 the presence or absence of a liquid adds time to your protocol run, so be aware of that before you use it. 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. +Liquid detection takes place immediately 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 you use it. 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. .. versionadded:: 2.20 From 6a17891ba6bd182a052edba13917246c90f362f8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 26 Jul 2024 16:17:12 -0400 Subject: [PATCH 51/59] Not ready yet. More TK Monday. I'm a bit burned out. Saving to save. --- api/docs/v2/basic_commands/liquids.rst | 64 +++++++++++++++++++++++++- api/docs/v2/pipettes/loading.rst | 2 +- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c8db1151b6b..c2ecc3d88c0 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,12 +263,72 @@ 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 liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. 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 wellplate or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration, but you don't need to call :py:meth:`~.InstrumentContext.aspirate` to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. See also :ref:`lpd`. .. code-block:: python pipette.detect_liquid_presence() +.. + Sample and text is longer than what we usually do. Trying it anyway. + Maybe do the labware and reservoir in text only and just show the for/while loop. + +This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. For example, let's create a protocol that includes a tiprack, a 12-well reservoir, a 96-well plate, a single-channel pipette, and the waste bin. + +.. code-block:: python + + def run(protocol: protocol_api.ProtocolContext): + tiprack = (protocol.load_labware(TIPRACK_NAME, 'D1')).wells() + reservoir = (protocol.load_labware(RESERVOIR_NAME, 'C2')).wells_by_name() + plate = (protocol.load_labware(PLATE_NAME, 'D2')).wells() + trash_bin = protocol.load_trash_bin('B3') + pipette = protocol.load_instrument(PIPETTE_SINGLE_CHANNEL_NAME, mount="left", liquid_presence_detection=False) + +Next, we'll add water to the reservoir as our test liquid:: + + water = protocol.define_liquid(name="water", description="Normal water", display_color="#42AB2D") + reservoir["A1"].load_liquid(liquid=water, volume=1000) + reservoir["A2"].load_liquid(liquid=water, volume=500) + reservoir["A3"].load_liquid(liquid=water, volume=850) + ... + reservoir["A11"].load_liquid(liquid=water, volume=0) + reservoir["A12"].load_liquid(liquid=water, volume=250) + +Now include some indexing to keep track of how many tips were used and which well plates received liquid:: + + tipIndex = 0 + plateIndex = 0 + +And finish up with ``for`` and ``while`` loops to perform liquid handling:: + + for name, well in reservoir.items(): + + pipette.pick_up_tip(tiprack[tipIndex]) + hasLiquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash_bin) + tipIndex+=1 + + curIndex = 0 + while hasLiquid: + pipette.pick_up_tip(tiprack[tipIndex]) + pipette.aspirate(250, well) + pipette.dispense(250, plate[plateIndex]) + pipette.drop_tip(trash_bin) + tipIndex+=1 + plateIndex+=1 + + pipette.pick_up_tip(tiprack[tipIndex]) + hasLiquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash_bin) + tipIndex+=1 + + curIndex+=1 + protocol.comment(f"Found liquid and aspirated from well {name} {curIndex} times. It is now empty.") + + protocol.comment("Exhausted all wells in reservoir.") + +When the robot uses all the liquid in a well, or finds an empty well, it will write a message to the robot's run log that records the well's name (e.g. ``A1``, ``A2``, etc.) and how many times it aspirated from that well before it ran dry. Then, it checks the next well for liquid. If the robot doesn't find liquid in the next well, it keeps checking each well until it does find liquid and starts the aspiration/dispense cycle again. If the protocol uses all the liquid in its wells, the robot records that too. + .. versionadded:: 2.20 .. _require-liquid-presence: @@ -276,7 +336,7 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pip Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol, writes a warning to the run log, and lets you recover from the error through your own error handling code. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. See also :ref:`lpd`. .. code-block:: python diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index f1493b497e7..b60a0cda1d0 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -256,7 +256,7 @@ Next, tell the robot to aspirate and dispense some liquid from the reservoir:: pipette.aspirate(100, reservoir["A1"]) pipette.dispense(100, plate["A1"]) -Liquid detection takes place immediately 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 you use it. 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. +Liquid detection takes place immediately 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 you use it. When the robot doesn't detect liquid during an aspiration, it raises an error and stops the protocol until the problem is resolved. .. versionadded:: 2.20 From 36aea237e9ad07773628e461a94fef1cbe2d62e3 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 29 Jul 2024 12:00:42 -0400 Subject: [PATCH 52/59] Shorten code sample, revise explanation --- api/docs/v2/basic_commands/liquids.rst | 70 +++++++++----------------- 1 file changed, 25 insertions(+), 45 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index c2ecc3d88c0..8eee424497c 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,71 +263,50 @@ 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 liquid if the sensors do not. Detection takes place during aspiration, but you don't need to call :py:meth:`~.InstrumentContext.aspirate` to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. 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 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`. .. code-block:: python pipette.detect_liquid_presence() -.. - Sample and text is longer than what we usually do. Trying it anyway. - Maybe do the labware and reservoir in text only and just show the for/while loop. - -This method will not raise an error or stop your protocol if the Flex pipette does not detect a liquid. You can write your own code to respond to the output of this method. For example, let's create a protocol that includes a tiprack, a 12-well reservoir, a 96-well plate, a single-channel pipette, and the waste bin. +In cases where you need records that are more informative than ``true`` or ``false``, you can write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. Here's one way to do this in the ``run():`` function of our Flex :ref:`protocol template `: .. code-block:: python - def run(protocol: protocol_api.ProtocolContext): - tiprack = (protocol.load_labware(TIPRACK_NAME, 'D1')).wells() - reservoir = (protocol.load_labware(RESERVOIR_NAME, 'C2')).wells_by_name() - plate = (protocol.load_labware(PLATE_NAME, 'D2')).wells() - trash_bin = protocol.load_trash_bin('B3') - pipette = protocol.load_instrument(PIPETTE_SINGLE_CHANNEL_NAME, mount="left", liquid_presence_detection=False) - -Next, we'll add water to the reservoir as our test liquid:: - - water = protocol.define_liquid(name="water", description="Normal water", display_color="#42AB2D") - reservoir["A1"].load_liquid(liquid=water, volume=1000) - reservoir["A2"].load_liquid(liquid=water, volume=500) - reservoir["A3"].load_liquid(liquid=water, volume=850) - ... - reservoir["A11"].load_liquid(liquid=water, volume=0) - reservoir["A12"].load_liquid(liquid=water, volume=250) - -Now include some indexing to keep track of how many tips were used and which well plates received liquid:: - - tipIndex = 0 - plateIndex = 0 - -And finish up with ``for`` and ``while`` loops to perform liquid handling:: + tip_index = 0 # tracks how many tips are used. + plate_index = 0 # tracks the wells dispensed to. Increments after dispense. for name, well in reservoir.items(): - pipette.pick_up_tip(tiprack[tipIndex]) - hasLiquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash_bin) - tipIndex+=1 + has_liquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash) + tip_index+=1 - curIndex = 0 - while hasLiquid: + cur_index = 0 # counts aspirate/dispense cycles from a reservoir well. + while has_liquid: pipette.pick_up_tip(tiprack[tipIndex]) pipette.aspirate(250, well) pipette.dispense(250, plate[plateIndex]) - pipette.drop_tip(trash_bin) - tipIndex+=1 - plateIndex+=1 + pipette.drop_tip(trash) + tip_index+=1 + plate_index+=1 pipette.pick_up_tip(tiprack[tipIndex]) - hasLiquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash_bin) - tipIndex+=1 + has_liquid = pipette.detect_liquid_presence(well) + pipette.drop_tip(trash) + tip_index+=1 + + cur_index+=1 - curIndex+=1 - protocol.comment(f"Found liquid and aspirated from well {name} {curIndex} times. It is now empty.") + # Add a helpful record to the run log when a well runs dry or is empty. + protocol.comment( + f"Found liquid and aspirated from well {name} {curIndex} times. Well is now empty." + ) + # Add a helpful record to the run log when all source wells are empty. protocol.comment("Exhausted all wells in reservoir.") -When the robot uses all the liquid in a well, or finds an empty well, it will write a message to the robot's run log that records the well's name (e.g. ``A1``, ``A2``, etc.) and how many times it aspirated from that well before it ran dry. Then, it checks the next well for liquid. If the robot doesn't find liquid in the next well, it keeps checking each well until it does find liquid and starts the aspiration/dispense cycle again. If the protocol uses all the liquid in its wells, the robot records that too. +Now the Flex records an entry in the run log that includes the well's name (e.g. ``A1``, ``A2``, ``B1`` etc.) and how many times the pipette aspirated from that well before it ran dry. If a protocol uses all the liquid in its source wells, the robot records that too. .. versionadded:: 2.20 @@ -336,7 +315,8 @@ When the robot uses all the liquid in a well, or finds an empty well, it will wr Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. Detection takes place during aspiration. As the Flex pipette detects a liquid, it stops, raises itself above the liquid's surface, and then resumes aspiration. If the Flex pipette does not detect liquid, the robot raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. When the robot does not detect liquid, it raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. +Detection takes place during aspiration, but you don't need to aspirate to use ``require_liquid_presence``. It's a standalone method that can be called when you want to detect liquids only. See also :ref:`lpd`. .. code-block:: python From 7f4ffbeaaccb7ae70851ef126d2cffd203b8e4c5 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Fri, 2 Aug 2024 13:25:37 -0400 Subject: [PATCH 53/59] add behavior in simulation to API ref entries --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 96922f12ab6..68e9ac99860 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2122,6 +2122,8 @@ def configure_nozzle_layout( # noqa: C901 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`. + When simulating a protocol, the check always succeeds (returns ``True``). + :returns: A boolean. """ loc = well.top() @@ -2132,6 +2134,8 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: 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`. + When simulating a protocol, the check always succeeds (does not raise an error). + :returns: None. """ loc = well.top() From 28fb7ae42117ed8f0719703199c5e3b05dc8718f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 8 Aug 2024 09:13:50 -0400 Subject: [PATCH 54/59] 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 """ From 5cd4ae082d9d4c2f65bbd063a08273735045ecf2 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 8 Aug 2024 16:28:16 -0400 Subject: [PATCH 55/59] Revisions from reviewers Made changes based on Ed's comments and our meeting today. Got many, but not all. More to come. --- api/docs/v2/pipettes/loading.rst | 45 +++++++++---------- .../protocol_api/instrument_context.py | 15 ++----- 2 files changed, 25 insertions(+), 35 deletions(-) diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 6ce4a99634f..019cde2c561 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,19 +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, 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. +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. 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 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 A1 and H1. For the Flex 96-Channel Pipette, the pressure sensors are on channels A1 and H12. + 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 -.. Ed: Enabling instead of Enable? +Enabling Globally +----------------- -Enable Liquid Presence Detection --------------------------------- - -The easiest, and recommended, way to use Liquid Presence Detection 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 check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example adds Liquid Presence Detection to the 8-Channel Pipette used in the sample protocol at the top of the page. +The easiest, and recommended, way to use liquid presence detection 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 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 @@ -247,41 +245,40 @@ The easiest, and recommended, way to use Liquid Presence Detection is by adding .. 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 new, clean tip:: - - pipette.pick_up_tip(tiprack2) - -Next, tell the robot to aspirate and dispense some liquid from the reservoir:: +Let's take a look at how all this works. First, tell the robot to pick up a new, clean tip, aspirate 100 ul from a reservoir, and dispense that volume into a well plate. - pipette.aspirate(100, reservoir["A1"]) - pipette.dispense(100, plate["A1"]) +.. code-block:: python + + right.pick_up_tip(tiprack2) + right.aspirate(100, reservoir["A1"]) + right.dispense(100, plate["A1"]) -Liquid detection takes place immediately 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 you use it. When the robot doesn't detect liquid during an aspiration, it raises an error and stops the protocol until the problem is resolved. +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 you use it. If Flex doesn't detect liquid, it raises an error and stops the protocol until the problem is resolved. .. versionadded:: 2.20 -Turning Liquid Presence Detection Off and On ---------------------------------------------- +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 starting after picking up a new tip. +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 starting after picking up a new tip. .. code-block:: python pipette.pick_up_tip() - pipette.liquid_presence_detection=False # liquid presence detection off - pipette.aspirate(100, reservoir["A2"]) # aspirates immediately + pipette.liquid_presence_detection=False + pipette.aspirate(100, reservoir["A2"]) -Going forward, the pipette will not perform a liquid check until you turn this feature back on. +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 pipette.pick_up_tip() - pipette.liquid_presence_detection=True # liquid presence detection on again - pipette.aspirate(100, reservoir["A3"]) # detects liquid before aspirating + pipette.liquid_presence_detection=True # Turns 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. +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. See also :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`. diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 2eb112dd50c..3016c6796b0 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2120,13 +2120,8 @@ def configure_nozzle_layout( # noqa: C901 @requires_version(2, 20) def detect_liquid_presence(self, well: labware.Well) -> bool: - """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``). - - :returns: A boolean. + """Checks for liquid in a well and 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``). Applies to Flex pipettes only. See :ref:`detect-liquid-presence`. + """ loc = well.top() self._96_tip_config_valid() @@ -2138,11 +2133,9 @@ def require_liquid_presence(self, well: labware.Well) -> 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. - 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). - - :returns: None. + + Works with Flex pipettes only. See :ref:`lpd` and :ref:`require-liquid-presence`. """ loc = well.top() self._96_tip_config_valid() From 0e7d19c3ac3d8bf6d98de7935e57f33da2794d4b Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 12 Aug 2024 13:26:37 -0400 Subject: [PATCH 56/59] Another round of reviewer comments and changes --- api/docs/v2/basic_commands/liquids.rst | 21 ++++++++--------- api/docs/v2/pipettes/loading.rst | 23 ++++++++----------- .../protocol_api/instrument_context.py | 15 ++++++------ .../protocol_api/protocol_context.py | 2 +- 4 files changed, 27 insertions(+), 34 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 0a56ee0fe8a..be786ebe657 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -270,10 +270,9 @@ You should generally detect liquid immediately after picking up a tip and before .. note:: Accurate liquid detection requires fresh, dry pipette tips. - .. code-block:: python - pipette.detect_liquid_presence() + pipette.detect_liquid_presence(well) In cases where you need records that are more informative than ``true`` or ``false``, you can write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. Here's one way to do this in the ``run():`` function of our Flex :ref:`protocol template `: @@ -290,23 +289,23 @@ In cases where you need records that are more informative than ``true`` or ``fal cur_index = 0 # counts aspirate/dispense cycles from a reservoir well. while has_liquid: - pipette.pick_up_tip(tiprack[tipIndex]) + pipette.pick_up_tip(tiprack[tip_index]) pipette.aspirate(250, well) - pipette.dispense(250, plate[plateIndex]) + pipette.dispense(250, plate[plate_index]) pipette.drop_tip(trash) - tip_index+=1 - plate_index+=1 + tip_index += 1 + plate_index += 1 - pipette.pick_up_tip(tiprack[tipIndex]) + pipette.pick_up_tip(tiprack[tip_index]) has_liquid = pipette.detect_liquid_presence(well) pipette.drop_tip(trash) - tip_index+=1 + tip_index += 1 - cur_index+=1 + cur_index += 1 # Add a helpful record to the run log when a well runs dry or is empty. protocol.comment( - f"Found liquid and aspirated from well {name} {curIndex} times. Well is now empty." + f"Found liquid and aspirated from well {name} {cur_index} times. Well is now empty." ) # Add a helpful record to the run log when all source wells are empty. @@ -326,6 +325,6 @@ Detection takes place during aspiration, but you don't need to aspirate to use ` .. code-block:: python - pipette.require_liquid_presence() + pipette.require_liquid_presence(well) .. versionadded:: 2.20 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 019cde2c561..0d3a699a4e4 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -223,11 +223,6 @@ 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. 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 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 A1 and H1. For the Flex 96-channel pipette, the pressure sensors are on channels A1 and H12. - -.. versionadded:: 2.20 - Enabling Globally ----------------- @@ -253,7 +248,9 @@ Let's take a look at how all this works. First, tell the robot to pick up a new, right.aspirate(100, reservoir["A1"]) 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 you use it. If Flex doesn't detect liquid, it raises an error and stops the protocol until the problem is resolved. +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, :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`, let you add liquid detection to a protocol with or without aspirating. The former checks for liquid and returns ``True`` if it finds liquid or ``False`` if it does not. It won't raise an error or stop a protocol. The latter checks for liquid and raises an error if it does not detect liquid. It will stop a protocol until the error is resolved. .. versionadded:: 2.20 @@ -264,9 +261,9 @@ You can turn liquid presence detection off and on throughout a protocol. To turn .. code-block:: python - pipette.pick_up_tip() - pipette.liquid_presence_detection=False - pipette.aspirate(100, reservoir["A2"]) + right.pick_up_tip() + right.liquid_presence_detection=False + right.aspirate(100, reservoir["A2"]) From now on, the pipette will not check for liquid until you turn this feature back on. @@ -274,12 +271,10 @@ To reactivate, set ``liquid_presence_detection=True`` at the point later in the .. code-block:: python - pipette.pick_up_tip() - pipette.liquid_presence_detection=True # Turns liquid presence detection on again. - pipette.aspirate(100, reservoir["A3"]) # Detects liquid before aspirating. + 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. -See also :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`. - .. versionadded:: 2.20 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 3016c6796b0..7571eaa3614 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 for liquid in a well and 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``). Applies to Flex pipettes only. See :ref:`detect-liquid-presence`. + """Checks for liquid in a well and 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:`lpd` and :ref:`detect-liquid-presence` + + 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. """ loc = well.top() @@ -2129,13 +2131,10 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: @requires_version(2, 20) def require_liquid_presence(self, well: labware.Well) -> None: - """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. - - When simulating a protocol, the check always succeeds (does not raise an error). - - Works with 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. 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`. + + 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. + """ loc = well.top() self._96_tip_config_valid() diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index d5cc8b164c2..6f37aa678a1 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``, enable liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`. + :param bool liquid_presence_detection: If ``True``, enable :ref:`liquid presence detection` for Flex 1-, 8-, or 96-channel pipettes. 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. .. versionadded:: 2.20 """ From 7f993b27c93b9d1219efaa069fd88b8aaf60da67 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 13 Aug 2024 15:51:56 -0400 Subject: [PATCH 57/59] Removed code sample, revise method text --- api/docs/v2/basic_commands/liquids.rst | 51 +++----------------------- 1 file changed, 5 insertions(+), 46 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index be786ebe657..5c32246bb2c 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,55 +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 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. +The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for liquid in a well plate or reservoir. It returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but 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. See also :ref:`lpd`. .. code-block:: python - + pipette.detect_liquid_presence(well) -In cases where you need records that are more informative than ``true`` or ``false``, you can write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. Here's one way to do this in the ``run():`` function of our Flex :ref:`protocol template `: - -.. code-block:: python - - tip_index = 0 # tracks how many tips are used. - plate_index = 0 # tracks the wells dispensed to. Increments after dispense. - - for name, well in reservoir.items(): - pipette.pick_up_tip(tiprack[tipIndex]) - has_liquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash) - tip_index+=1 - - cur_index = 0 # counts aspirate/dispense cycles from a reservoir well. - while has_liquid: - pipette.pick_up_tip(tiprack[tip_index]) - pipette.aspirate(250, well) - pipette.dispense(250, plate[plate_index]) - pipette.drop_tip(trash) - tip_index += 1 - plate_index += 1 - - pipette.pick_up_tip(tiprack[tip_index]) - has_liquid = pipette.detect_liquid_presence(well) - pipette.drop_tip(trash) - tip_index += 1 - - cur_index += 1 - - # Add a helpful record to the run log when a well runs dry or is empty. - protocol.comment( - f"Found liquid and aspirated from well {name} {cur_index} times. Well is now empty." - ) - - # Add a helpful record to the run log when all source wells are empty. - protocol.comment("Exhausted all wells in reservoir.") +.. removed code sample. maybe some text advice could help? -Now the Flex records an entry in the run log that includes the well's name (e.g. ``A1``, ``A2``, ``B1`` etc.) and how many times the pipette aspirated from that well before it ran dry. If a protocol uses all the liquid in its source wells, the robot records that too. +In cases where you need more information than ``true`` or ``false``, you could write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. .. versionadded:: 2.20 @@ -320,8 +280,7 @@ Now the Flex records an entry in the run log that includes the well's name (e.g. Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require a liquid in a well or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if liquid if the sensors do not. When the robot does not detect liquid, it raises an error, stops the protocol to let you resolve the problem, and writes a warning to the run log. -Detection takes place during aspiration, but you don't need to aspirate to use ``require_liquid_presence``. It's a standalone method that can be called when you want to detect liquids only. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require liquid in a well plate or reservoir. It returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but 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 stops the protocol to let you resolve the problem. See also :ref:`lpd`. .. code-block:: python From 9ef431deb6192d38b673c3168ddbbb4a6a76ee2d Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 15 Aug 2024 13:56:37 -0400 Subject: [PATCH 58/59] More reviewer changes -- removed code sample -- added text about pressure sensor locations -- ready for review again --- api/docs/v2/basic_commands/liquids.rst | 4 +--- api/docs/v2/pipettes/loading.rst | 9 ++++++++- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 5c32246bb2c..408183b8f59 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -269,9 +269,7 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pip pipette.detect_liquid_presence(well) -.. removed code sample. maybe some text advice could help? - -In cases where you need more information than ``true`` or ``false``, you could write your own code to handle the output of this method. For example, by adding some indexing along with ``for`` and ``while`` loops, your protocol could count how many aspirations a robot performed before a source well ran out of liquid. +.. removed code sample. .. versionadded:: 2.20 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 0d3a699a4e4..4753a72f4a7 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -221,7 +221,14 @@ 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, 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 works with Flex pipettes only and 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. 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 ----------------- diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 7571eaa3614..5319b8f7ce4 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2122,7 +2122,7 @@ def configure_nozzle_layout( # noqa: C901 def detect_liquid_presence(self, well: labware.Well) -> bool: """Checks for liquid in a well and 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:`lpd` and :ref:`detect-liquid-presence` - 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. + If your protocol uses :ref:`partial tip pickup `, 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() @@ -2131,9 +2131,9 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: @requires_version(2, 20) def require_liquid_presence(self, well: labware.Well) -> None: - """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. 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`. + """Check for liquid in a well and raises 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. 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`. - 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. + If your protocol uses :ref:`partial tip pickup `, 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() From c4106bf9d3e42a17aa520364d438d15944923704 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Fri, 16 Aug 2024 01:00:06 -0400 Subject: [PATCH 59/59] review and edits --- api/docs/v2/basic_commands/liquids.rst | 20 +++++++++++----- api/docs/v2/pipettes/loading.rst | 20 ++++++++-------- .../protocol_api/instrument_context.py | 24 ++++++++++--------- .../protocol_api/protocol_context.py | 6 ++--- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 408183b8f59..9e2e4ff8782 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,13 +263,18 @@ 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 plate or reservoir. It returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but 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. See also :ref:`lpd`. +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 - pipette.detect_liquid_presence(well) - -.. removed code sample. + if pipette.detect_liquid_presence(reservoir["A1"]): + pipette.aspirate(100, reservoir["A1"]) + else: + pipette.aspirate(100, reservoir["A2"]) .. versionadded:: 2.20 @@ -278,10 +283,13 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pip Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require liquid in a well plate or reservoir. It returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but 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 stops the protocol to let you resolve the problem. See also :ref:`lpd`. +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(well) + pipette.require_liquid_presence(reservoir["A1"]) + pipette.aspirate(100, reservoir["A1"]) # only occurs if liquid found .. versionadded:: 2.20 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 4753a72f4a7..e97eb78592b 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -233,7 +233,7 @@ Liquid presence detection works with Flex 1-, 8-, and 96-channel pipettes only. Enabling Globally ----------------- -The easiest, and recommended, way to use liquid presence detection 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 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. +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 @@ -247,30 +247,30 @@ The easiest, and recommended, way to use liquid presence detection is by adding .. 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 new, clean tip, aspirate 100 ul from a reservoir, and dispense that volume into a well plate. +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(tiprack2) - right.aspirate(100, reservoir["A1"]) + 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, :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`, let you add liquid detection to a protocol with or without aspirating. The former checks for liquid and returns ``True`` if it finds liquid or ``False`` if it does not. It won't raise an error or stop a protocol. The latter checks for liquid and raises an error if it does not detect liquid. It will stop a protocol until the error 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 starting after picking up a new tip. +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 - right.aspirate(100, reservoir["A2"]) + 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. @@ -279,8 +279,8 @@ To reactivate, set ``liquid_presence_detection=True`` at the point later in the .. 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. + 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. diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 5319b8f7ce4..7b3251cc3cf 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -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() @@ -2120,10 +2118,12 @@ def configure_nozzle_layout( # noqa: C901 @requires_version(2, 20) def detect_liquid_presence(self, well: labware.Well) -> bool: - """Checks for liquid in a well and 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:`lpd` and :ref:`detect-liquid-presence` - - If your protocol uses :ref:`partial tip pickup `, 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. - + """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`. + + .. 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() @@ -2131,10 +2131,12 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: @requires_version(2, 20) def require_liquid_presence(self, well: labware.Well) -> None: - """Check for liquid in a well and raises 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. 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`. + """Check for liquid in a well and raises an error if none is detected. - If your protocol uses :ref:`partial tip pickup `, 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. + 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() diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 6f37aa678a1..ca2bc55874f 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -906,9 +906,9 @@ 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``, enable :ref:`liquid presence detection` for Flex 1-, 8-, or 96-channel pipettes. 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. All other channels for these pipettes cannot detect the presence/absence of a liquid. - - .. versionadded:: 2.20 + :param bool liquid_presence_detection: If ``True``, enable automatic + :ref:`liquid presence detection ` 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)