docs(api): lids updates in 8.4

abr-testing/abr_testing/protocols/active_protocols/9_Magmax_RNA_Cells_Flex.py

@@ -91,8 +91,7 @@ def run(protocol: ProtocolContext) -> None:
     deactivate_modules_bool = protocol.params.deactivate_modules  # type: ignore[attr-defined]
     plate_type = protocol.params.labware_plate_reader_compatible  # type: ignore [attr-defined]
     plate_orientation = protocol.params.plate_orientation  # type: ignore[attr-defined]
-    helpers.comment_protocol_version(protocol, "01")
-
+    helpers.comment_protocol_version(protocol, "02")
     plate_name_str = "hellma_plate_" + str(plate_orientation)
 
     # Protocol Parameters
@@ -335,6 +334,8 @@ def mixing(well: Well, pip: InstrumentContext, mvol: float, reps: int = 8) -> No
 
         pip.flow_rate.aspirate = 300
         pip.flow_rate.dispense = 300
+        if m1000.current_volume > 0.0:
+            m1000.dispense(m1000.current_volume, waste)
 
     def lysis(vol: float, source: List[Well]) -> None:
         """Lysis Steps."""
@@ -512,7 +513,6 @@ def stop_reaction(vol: float, source: Well) -> None:
             m1000.blow_out(m.top(-3))
             m1000.prepare_to_aspirate()
             m1000.air_gap(20)
-
         m1000.drop_tip() if TIP_TRASH else m1000.return_tip()
 
         # Shake for 3 minutes to mix wash with beads
@@ -559,6 +559,7 @@ def elute(vol: float) -> None:
                     m1000.aspirate(elution_vol - 10, samples_m[i])
                     m1000.dispense(elution_vol - 10, samples_m[i].bottom(10))
                     m1000.flow_rate.dispense = 300
+            m1000.dispense(m1000.current_volume, waste)
             m1000.drop_tip() if TIP_TRASH else m1000.return_tip()
 
         # Shake for 3 minutes to mix wash with beads

abr-testing/abr_testing/protocols/liquid_setups/All_Liquid_Set_ups.py

@@ -221,7 +221,7 @@ def run(protocol: ProtocolContext) -> None:
             "nest_96_wellplate_2ml_deep", str(SLOTS["LABWARE"][0]), "Reservoir 1"
         )  # Reservoir
         sample_plate_2 = protocol.load_labware(
-            "thermoscientificnunc_96_wellplate_1300ul",
+            "nest_96_wellplate_2ml_deep",
             str(SLOTS["LABWARE"][1]),
             "Sample Plate 2",
         )  # Reservoir

api/docs/v2/moving_labware.rst

@@ -93,7 +93,13 @@ You can manually move any standard or custom labware. Using the gripper to move
           * ``opentrons_flex_96_filtertiprack_50ul``
           * ``opentrons_flex_96_filtertiprack_200ul``
           * ``opentrons_flex_96_filtertiprack_1000ul``
+    * - Opentrons labware lids 
+      - 
+          * ``opentrons_tough_pcr_auto_sealing_lid``
+          * ``opentrons_flex_tiprack_lid``
 
+You can move compatible Opentrons lids manually or with the Flex gripper, but some restrictions apply. For more information, see :ref:`moving-lids`. 
+
 The gripper may work with other ANSI/SLAS standard labware, but this is not recommended.
 
 .. note::
@@ -192,3 +198,32 @@ You can also load labware off-deck, in preparation for a ``move_labware()`` comm
             pipette.pick_up_tip()
 
 Using the off-deck location to remove or replace labware lets you continue your workflow in a single protocol, rather than needing to end a protocol, reset the deck, and start a new protocol run.
+
+.. _moving-lids:
+
+Moving Lids 
+===========
+
+Lids on well plates or tip racks can help prevent contamination on the deck and are required for use with some modules, like the Thermocycler. You can use :py:meth:`.ProtocolContext.move_lid` to move an Opentrons Tough PCR Auto-Sealing Lid or Opentrons Flex Tiprack Lid manually or using the Flex gripper. 
+
+An Opentrons Tough PCR Auto-Sealing Lid can be moved between deck slots, lid stacks, or compatible labware, modules, and adapters loaded in your protocol. 
+
+.. code-block:: python
+
+    ## load lid stack on the Flex deck 
+
+    lid_stack = protocol.load_lid_stack(
+        load_name="opentrons_tough_pcr_auto_sealing_lid",
+        location="B2", 
+        quantity="4")
+
+    ## move an Opentrons Tough PCR Auto-Sealing Lid to a compatible well plate in the Thermocycler
+    protocol.move_lid(
+        source_location=("lid_stack", "B2"),
+        new_location=("opentrons_96_wellplate_200ul_pcr_full_skirt", "tcmod"),
+        use_gripper= "True")
+
+Use ``move_lid()`` again to move a used Opentrons Tough PCR Auto-Sealing Lid to a waste chute or trash bin loaded in your protocol. 
+
+.. note::
+    You can move an Opentrons Flex Tiprack Lid from a new tip rack to a second tip rack without a lid or to a waste chute or trash bin on the deck, either manually or using the Flex gripper. The tip rack lid must be defined in your protocol using the ``lid`` parameter of ``load_labware``. For more information, see :ref:`loading-lids`.

api/docs/v2/new_labware.rst

@@ -48,7 +48,7 @@ Throughout this section, we'll use the labware listed in the following table.
       - Labware name
       - API load name
     * - Well plate
-      - `Corning 96 Well Plate 360 µL Flat <https://labware.opentrons.com/corning_96_wellplate_360ul_flat/>`_
+      - `Opentrons Tough 96 Well Plate 200 µL PCR Full Skirt <https://labware.opentrons.com/opentrons_96_wellplate_200ul_pcr_full_skirt/>`_
       - ``corning_96_wellplate_360ul_flat``
     * - Flex tip rack
       - `Opentrons Flex 96 Tips 200 µL <https://shop.opentrons.com/opentrons-flex-tips-200-l/>`_
@@ -63,13 +63,13 @@ Similar to the code sample in :ref:`overview-section-v2`, here's how you use the
 
     #Flex
     tiprack = protocol.load_labware("opentrons_flex_96_tiprack_200ul", "D1")
-    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "D2")
+    plate = protocol.load_labware("opentrons_96_wellplate_200ul_pcr_full_skirt", "D2")
 
 .. code-block:: python
 
     #OT-2
     tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
-    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "2")
+    plate = protocol.load_labware("opentrons_96_wellplate_200ul_pcr_full_skirt", "2")
 
 .. versionadded:: 2.0
 
@@ -82,10 +82,47 @@ When the ``load_labware`` method loads labware into your protocol, it returns a
     The ``load_labware`` method includes an optional ``label`` argument. You can use it to identify labware with a descriptive name. If used, the label value is displayed in the Opentrons App. For example::
 
         tiprack = protocol.load_labware(
-            load_name="corning_96_wellplate_360ul_flat",
+            load_name="opentrons_flex_96_tiprack_200ul",
             location="D1",
             label="any-name-you-want")
 
+
+.. _loading-lids:
+
+Loading Lids 
+============
+
+You can load lids on compatible plates or tip racks. Use the optional ``lid`` parameter of ``load_labware`` to add an Opentrons Tough Auto-Sealing Lid to a PCR plate, or load a new tip rack's lid in your protocol. 
+
+.. code-block:: python
+
+    plate = protocol.load_labware(
+        load_name="opentrons_96_wellplate_200ul_pcr_full_skirt", 
+        location="D2",
+        lid="opentrons_tough_pcr_auto_sealing_lid")
+
+
+.. code-block:: python
+
+    tiprack = protocol.load_labware(
+        load_name="opentrons_flex_96_tiprack_200ul",
+        location="D1",
+        lid="opentrons_flex_tiprack_lid")
+
+
+You might need multiple lids during your protocol. Use ``load_lid_stack`` to stack up to five Opentrons Tough Auto-Sealing Lids on a deck slot, riser, or compatible adapter. 
+
+.. code-block:: python
+
+    def load_lid_stack(
+        load_name="opentrons_tough_pcr_auto_sealing_lid", 
+        location="B2",
+        quantity="4")
+
+Tip rack lids can't be stacked or placed on the deck. 
+
+.. versionadded:: 2.23
+
 .. _labware-on-adapters:
 
 Loading Labware on Adapters

api/src/opentrons/hardware_control/modules/flex_stacker.py

@@ -36,7 +36,10 @@
     FlexStackerData,
 )
 
-from opentrons_shared_data.errors.exceptions import FlexStackerStallError
+from opentrons_shared_data.errors.exceptions import (
+    FlexStackerStallError,
+    FlexStackerShuttleMissingError,
+)
 
 log = logging.getLogger(__name__)
 
@@ -414,6 +417,7 @@ async def _prepare_for_action(self) -> bool:
         await self.home_axis(StackerAxis.X, Direction.EXTEND)
         await self.home_axis(StackerAxis.Z, Direction.RETRACT)
         await self.close_latch()
+        await self.verify_shuttle_location(PlatformState.EXTENDED)
         return True
 
     async def home_all(self, ignore_latch: bool = False) -> None:
@@ -436,6 +440,14 @@ async def home_all(self, ignore_latch: bool = False) -> None:
         await self.home_axis(StackerAxis.Z, Direction.RETRACT)
         await self.home_axis(StackerAxis.X, Direction.EXTEND)
 
+    async def verify_shuttle_location(self, expected: PlatformState) -> None:
+        """Verify the shuttle is present and in the expected location."""
+        await self._reader.read()
+        if self.platform_state != expected:
+            raise FlexStackerShuttleMissingError(
+                self.device_info["serial"], expected, self.platform_state
+            )
+
 
 class FlexStackerReader(Reader):
     error: Optional[str]

api/src/opentrons/protocol_api/protocol_context.py

@@ -451,14 +451,14 @@ def load_labware(
             choose the adapter's version automatically.
 
                         .. versionadded:: 2.15
+        :param lid: A lid to load on the top of the main labware. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
+            lid will use the same namespace as the labware, and the API will
+            choose the adapter's version automatically.
+
+                        .. versionadded:: 2.23
         """
-        # TODO: re-include in docstring when 2.23 is ready
-        #         :param lid: A lid to load the on top of the main labware. Accepts the same
-        #             values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
-        #             lid will use the same namespace as the labware, and the API will
-        #             choose the lid's version automatically.
-        #
-        #                         .. versionadded:: 2.23
+
         if isinstance(location, OffDeckType) and self._api_version < APIVersion(2, 15):
             raise APIVersionError(
                 api_element="Loading a labware off-deck",
@@ -1391,13 +1391,13 @@ def load_lid_stack(
         version: Optional[int] = None,
     ) -> Labware:
         """
-        Load a stack of Lids onto a valid Deck Location or Adapter.
+        Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.
 
         :param str load_name: A string to use for looking up a lid definition.
-            You can find the ``load_name`` for any standard lid on the Opentrons
+            You can find the ``load_name`` for any compatible lid on the Opentrons
             `Labware Library <https://labware.opentrons.com>`_.
         :param location: Either a :ref:`deck slot <deck-slots>`,
-            like ``1``, ``"1"``, or ``"D1"``, or the a valid Opentrons Adapter.
+            like ``1``, ``"1"``, or ``"D1"``, or a valid Opentrons Adapter.
         :param int quantity: The quantity of lids to be loaded in the stack.
         :param adapter: An adapter to load the lid stack on top of. Accepts the same
             values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
@@ -1418,9 +1418,10 @@ def load_lid_stack(
             leave this unspecified to let ``load_lid_stack()`` choose a version
             automatically.
 
-        :return:  The initialized and loaded labware object representing the Lid Stack.
+        :return:  The initialized and loaded labware object representing the lid stack.
+
+        .. versionadded:: 2.23
 
-        :meta private:
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -1479,9 +1480,9 @@ def move_lid(
         pick_up_offset: Optional[Mapping[str, float]] = None,
         drop_offset: Optional[Mapping[str, float]] = None,
     ) -> Labware | None:
-        """Move a lid from a valid source to a new location. Can return a Lid Stack if one is created.
+        """Move a compatible lid from a valid source to a new location. Can return a lid stack if one is created.
 
-        :param source_location: Where to take the lid from. This is either:
+        :param source_location: The lid's starting location. This is either:
 
                 * A deck slot like ``1``, ``"1"``, or ``"D1"``. See :ref:`deck-slots`.
                 * A labware or adapter that's already been loaded on the deck
@@ -1498,7 +1499,7 @@ def move_lid(
                   with :py:meth:`load_labware` or :py:meth:`load_adapter`.
                 * The special constant :py:obj:`OFF_DECK`.
 
-        :param use_gripper: Whether to use the Flex Gripper for this movement.
+        :param use_gripper: Whether to use the Flex Gripper to move the lid.
 
                 * If ``True``, use the gripper to perform an automatic
                   movement. This will raise an error in an OT-2 protocol.
@@ -1515,7 +1516,8 @@ def move_lid(
         labware's current and new locations are accessible, i.e., open the Thermocycler lid
         or open the Heater-Shaker's labware latch.
 
-        :meta private:
+        .. versionadded:: 2.23
+
         """
         source: Union[LabwareCore, DeckSlotName, StagingSlotName]
         if isinstance(source_location, Labware):

api/src/opentrons/protocol_engine/commands/command_unions.py

@@ -14,7 +14,10 @@
     TipPhysicallyAttachedError,
 )
 from .movement_common import StallOrCollisionError
-from .flex_stacker.common import FlexStackerStallOrCollisionError
+from .flex_stacker.common import (
+    FlexStackerStallOrCollisionError,
+    FlexStackerShuttleError,
+)
 
 from . import absorbance_reader
 from . import flex_stacker
@@ -920,6 +923,7 @@
     DefinedErrorData[GripperMovementError],
     DefinedErrorData[StallOrCollisionError],
     DefinedErrorData[FlexStackerStallOrCollisionError],
+    DefinedErrorData[FlexStackerShuttleError],
 ]
 
 

api/src/opentrons/protocol_engine/commands/flex_stacker/common.py

@@ -13,3 +13,13 @@ class FlexStackerStallOrCollisionError(ErrorOccurrence):
 
     errorCode: str = ErrorCodes.FLEX_STACKER_STALL_OR_COLLISION_DETECTED.value.code
     detail: str = ErrorCodes.FLEX_STACKER_STALL_OR_COLLISION_DETECTED.value.detail
+
+
+class FlexStackerShuttleError(ErrorOccurrence):
+    """Returned when the Flex Stacker Shuttle is not in the correct location."""
+
+    isDefined: bool = True
+    errorType: Literal["flexStackerShuttleMissing"] = "flexStackerShuttleMissing"
+
+    errorCode: str = ErrorCodes.FLEX_STACKER_SHUTTLE_MISSING.value.code
+    detail: str = ErrorCodes.FLEX_STACKER_SHUTTLE_MISSING.value.detail

api/src/opentrons/protocol_engine/commands/flex_stacker/retrieve.py

@@ -14,7 +14,10 @@
     SuccessData,
     DefinedErrorData,
 )
-from ..flex_stacker.common import FlexStackerStallOrCollisionError
+from ..flex_stacker.common import (
+    FlexStackerStallOrCollisionError,
+    FlexStackerShuttleError,
+)
 from ...errors import (
     ErrorOccurrence,
     CannotPerformModuleAction,
@@ -31,7 +34,10 @@
     LoadedLabware,
 )
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
-from opentrons_shared_data.errors.exceptions import FlexStackerStallError
+from opentrons_shared_data.errors.exceptions import (
+    FlexStackerStallError,
+    FlexStackerShuttleMissingError,
+)
 from opentrons.calibration_storage.helpers import uri_from_details
 
 if TYPE_CHECKING:
@@ -120,7 +126,8 @@ class RetrieveResult(BaseModel):
 
 _ExecuteReturn = Union[
     SuccessData[RetrieveResult],
-    DefinedErrorData[FlexStackerStallOrCollisionError],
+    DefinedErrorData[FlexStackerStallOrCollisionError]
+    | DefinedErrorData[FlexStackerShuttleError],
 ]
 
 
@@ -354,6 +361,20 @@ async def execute(self, params: RetrieveParams) -> _ExecuteReturn:
                     ],
                 ),
             )
+        except FlexStackerShuttleMissingError as e:
+            return DefinedErrorData(
+                public=FlexStackerShuttleError(
+                    id=self._model_utils.generate_id(),
+                    createdAt=self._model_utils.get_timestamp(),
+                    wrappedErrors=[
+                        ErrorOccurrence.from_failed(
+                            id=self._model_utils.generate_id(),
+                            createdAt=self._model_utils.get_timestamp(),
+                            error=e,
+                        )
+                    ],
+                ),
+            )
 
         # Update the state to reflect the labware is now in the Flex Stacker slot
         # todo(chb, 2025-02-19): This ModuleLocation piece should probably instead be an AddressableAreaLocation