docs(api): lids updates in 8.4 #17914

emilyburghardt · 2025-03-27T22:58:44Z

Overview

API docs update for new lids methods in API 2.23: load_lid_stack, move_lid, and lids loaded onto labware.

Test Plan and Hands on Testing

sandbox: http://sandbox.docs.opentrons.com/docs-lids-in-8.4/v2/

Changelog

light editing to API reference entries; including removing a TODO
Loading Labware section: updating well plate used throughout the section so we can demonstrate loading a lid onto it; adding a new "Loading Lids" subsection
Moving Labware section: new "Moving Lids" section that can grow as we add more lids, like cell culture lids, compatible with move_lid

Review requests

Code blocks correct? Anything missing? Do we like where new information was added?

Maybe update the Auto-Sealing Lids section for the Thermocycler module example?

Risk assessment

Low.

CaseyBatten

Looking good so far, some comments below regarding a few edge cases.

CaseyBatten · 2025-03-28T19:23:11Z

api/docs/v2/moving_labware.rst

+Use ``move_lid()`` again to move a used ``opentrons_tough_pcr_auto_sealing_lid`` to a ``WasteChute`` or ``TrashBin`` loaded in your protocol. 
+
+.. note::
+    You can only move an ``opentrons_flex_tip_rack_lid`` from a new tip rack to the ``WasteChute`` or ``TrashBin``, either manually or with the Flex gripper. The tip rack lid must be defined in your protocol using the ``lid`` parameter of ``load_labware``. For more, see :ref:`loading-lids`.


You can also move them onto another tip rack which does not currently have a lid. The example case being, you load one tiprack with a lid and one tiprack without a lid. On step two, you move the lid from tiprack A to tiprack B.

CaseyBatten · 2025-03-28T19:34:05Z

api/src/opentrons/protocol_api/protocol_context.py

@@ -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.


Load lid stack can in theory be used by any stackable lids (of which only the auto-sealing lids apply), so we might want to use more general terminology.

I like limiting it to what's possible now — we can always update when we add more labware and this becomes a more broadly applicable feature.

emilyburghardt · 2025-03-28T17:55:06Z

api/docs/v2/moving_labware.rst

+        quantity="4")
+
+    ## move an Opentrons Tough PCR Auto-Sealing Lid to a compatible well plate in the Thermocycler
+    protocol.move_lid(


@CaseyBatten do we not specify the load name for the lid being moved?

emilyburghardt · 2025-03-28T17:55:59Z

api/docs/v2/new_labware.rst

+        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. 


@CaseyBatten is there a maximum of 5? I can't find where I read this originally. If true, should also maybe add to API reference.

Its a maximum of 5 based on the stackLimit in the labware definition for the Tough Auto-Sealing lids. Technically a labware could have a stack limit of any number, so long as we define it as such. The auto sealing lids become unstable after 5 lids, so we limit them to 5.

jwwojak

Left some comments on the use of code formatting vs regular text formatting. My main takeaway:

When referring to literal code, use the code formatting.
When referring to an actual thing or general concepts or to enhance readability, sometimes plain text/regular text is better.

PS I have probably used the wrong full name for the auto-sealing PCR plate. I'm not really sure what that thing is called, its full, formal name.

jwwojak · 2025-03-31T13:12:20Z

api/docs/v2/moving_labware.rst


+You can move compatible Opentrons lids manually or with the Flex gripper, but some restrictions apply. For more, see :ref:`moving-lids`. 


This is minor, the "For more" perhaps should be:

Suggested change

You can move compatible Opentrons lids manually or with the Flex gripper, but some restrictions apply. For more, see :ref:`moving-lids`.

You can move compatible Opentrons lids manually or with the Flex gripper, but some restrictions apply. For more information, see :ref:`moving-lids`.

or just "See moving-lids"

jwwojak · 2025-03-31T13:21:54Z

api/docs/v2/moving_labware.rst

+
+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. 


Sometimes, a bit of text can read easer if the noun is referred to by name rather than by code. If you're explicitly referring to a code example, then I'd use the code typeface, but this seems more like a "general" type example so I'd suggest regular text because the sentence is about the actual object, not the code.

Suggested change

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.

An Opentrons Tough PCR lid can be moved between deck slots, lid stacks, or compatible labware, modules, and adapters loaded in your protocol.

I agree in general, prefer plain English names unless directly referring to something in a code block.

jwwojak · 2025-03-31T13:26:36Z

api/docs/v2/moving_labware.rst

+Use ``move_lid()`` again to move a used ``opentrons_tough_pcr_auto_sealing_lid`` to a ``WasteChute`` or ``TrashBin`` loaded in your protocol. 
+
+.. note::
+    You can only move an ``opentrons_flex_tip_rack_lid`` from a new tip rack to the ``WasteChute`` or ``TrashBin``, either manually or with the Flex gripper. The tip rack lid must be defined in your protocol using the ``lid`` parameter of ``load_labware``. For more, see :ref:`loading-lids`.


I would suggest the same thing as my comment above, though this might be an ambiguous case. Consider this:

Suggested change

Use ``move_lid()`` again to move a used ``opentrons_tough_pcr_auto_sealing_lid`` to a ``WasteChute`` or ``TrashBin`` loaded in your protocol.

.. note::

You can only move an ``opentrons_flex_tip_rack_lid`` from a new tip rack to the ``WasteChute`` or ``TrashBin``, either manually or with the Flex gripper. The tip rack lid must be defined in your protocol using the ``lid`` parameter of ``load_labware``. For more, see :ref:`loading-lids`.

Use ``move_lid()`` again to move a used Opentrons Tough PCR lid to a waste chute or trash bin loaded in your protocol.

.. note::

You can only move an Opentrons Tough PCR lid from a new tip rack to the waste chute or trans bin, either manually or with 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`.

The "note" is a good example here. You're moving a lid not a piece of code to other real, physical objects.

Now the last sentence of the note is ok because it is talking about code.

codecov · 2025-03-31T15:22:59Z

Codecov Report

Attention: Patch coverage is 33.53214% with 1003 lines in your changes missing coverage. Please review.

Project coverage is 26.47%. Comparing base (f134eb4) to head (de110bb).
Report is 12 commits behind head on chore_release-8.4.0.

Files with missing lines	Patch %	Lines
.../ErrorRecoveryFlows/hooks/useFailedLabwareUtils.ts	0.00%	128 Missing ⚠️
protocol-designer/src/steplist/formLevel/errors.ts	7.69%	96 Missing ⚠️
...organisms/ODD/QuickTransferFlow/utils/pythonDef.ts	0.00%	87 Missing ⚠️
protocol-designer/src/steplist/formLevel/index.ts	6.41%	73 Missing ⚠️
...rotocol-designer/src/step-forms/selectors/index.ts	0.00%	68 Missing ⚠️
app/src/organisms/ErrorRecoveryFlows/constants.ts	0.00%	63 Missing ⚠️
.../organisms/ErrorRecoveryFlows/RecoveryDoorOpen.tsx	0.00%	57 Missing ⚠️
step-generation/src/utils/misc.ts	51.00%	49 Missing ⚠️
...yFlows/RecoveryOptions/ManualReplaceLwAndRetry.tsx	0.00%	48 Missing ⚠️
...rrorRecoveryFlows/shared/LeftColumnLabwareInfo.tsx	0.00%	41 Missing ⚠️
... and 37 more

Additional details and impacted files

@@                   Coverage Diff                   @@
##           chore_release-8.4.0   #17914      +/-   ##
=======================================================
- Coverage                26.55%   26.47%   -0.08%     
=======================================================
  Files                     3111     3115       +4     
  Lines                   236772   237781    +1009     
  Branches                 19221    19194      -27     
=======================================================
+ Hits                     62880    62958      +78     
- Misses                  173870   174801     +931     
  Partials                    22       22

Flag	Coverage Δ
protocol-designer	`18.73% <23.26%> (-0.09%)`	⬇️
step-generation	`4.46% <26.17%> (+0.11%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...anisms/ErrorRecoveryFlows/hooks/useShowDoorInfo.ts	`0.00% <ø> (ø)`
...orRecoveryFlows/shared/RecoveryDoorOpenSpecial.tsx	`0.00% <ø> (ø)`
...c/components/organisms/AnnouncementModal/index.tsx	`96.77% <100.00%> (+0.94%)`	⬆️
...gner/src/components/organisms/Navigation/index.tsx	`91.07% <ø> (-0.46%)`	⬇️
...src/file-data/__fixtures__/createFile/v7Fixture.ts	`100.00% <100.00%> (ø)`
...ol-designer/src/file-data/selectors/fileCreator.ts	`84.33% <ø> (ø)`
protocol-designer/src/file-data/selectors/utils.ts	`78.91% <ø> (-0.67%)`	⬇️
protocol-designer/src/form-types.ts	`80.64% <ø> (ø)`
.../pages/Designer/DeckSetup/Overlays/BlockedSlot.tsx	`100.00% <100.00%> (ø)`
...src/pages/Designer/ProtocolSteps/Timeline/utils.ts	`20.37% <100.00%> (ø)`
... and 74 more

... and 11 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Since we have isolated Robot Stack release 8.4 into `chore_release-8.4.0` we must lock down command schema 12 for that Robot Stack Release. If changes are needed to command schema 12 they must first be done in `chore_release-8.4.0` then incorporated in `edge` via a merge back.

…17886) closes AUTH-1544

…17888) closes RQA-3668

This PR adds the ability to generate python for quick transfer behind a feature flag. It also logs it in devtools so you can view the actual python file, otherwise there is no other way to view the file.

…#17878) closes AUTH-1423

…nds (#17881) # Overview We want to enable error recovery during a protocol if the Flex Stacker shuttle is not detected. This PR does the first step, which is to catch this error. The hardware controller layer now checks for the platform status before executing dispense and store labware, and raises the appropriate error. closes EXEC-1287, EXEC-1200

…o stall obstruction (#17773)

…with liquid (#17818)  # Overview Removing instances where tips were returning with liquid in them ## Test Plan and Hands on Testing Ran protocols and checked tip rack bases upon completion to ensure they were empty. ## Changelog  ## Review requests  ## Risk assessment

…17899)  # Overview DVT Flex Stacker Accelerated Lifetime Test ## Test Plan and Hands on Testing Ran in SZ ## Changelog  ## Review requests  ## Risk assessment

…ime Test (#17898)  # Overview DVT Flex Stacker Labware Compatibility Lifetime Test ## Test Plan and Hands on Testing - Ran in SZ ## Changelog  ## Review requests  ## Risk assessment  --------- Co-authored-by: Carlos <[email protected]>

…uipment up in invariantContext (#17865) Pretty big refactor with step-generation in particular (but also touched a few files in PD and the app for quick transfer) where the `invariantContext` type key `additionalEquipmentEntities` is split up to 4 separate keys. The total `InvariantContext` looks like this: ``` export interface InvariantContext { labwareEntities: LabwareEntities moduleEntities: ModuleEntities pipetteEntities: PipetteEntities wasteChuteEntities: WasteChuteEntities trashBinEntities: TrashBinEntities stagingAreaEntities: StagingAreaEntities gripperEntities: GripperEntities liquidEntities: LiquidEntities config: Config }

… errors & warnings (#17893)

#17903) …etLoadAdapters

…Props (#17843) This PR utilizes the existing `propsForFields` structure to pass all necessary fields to `CheckboxExpandStepFormField` for the implicated checkbox stepform field. Instead of individually passing values for the field props `value`, `updateValue`, `isChecked`, `tooltipText`, and `disabled`, we can simply pass that field's `propsForFields`, and destructure inside the checkbox expand component.

Covers EXEC-1266 Updates the Max pool limit to accounts for the overlap of the last labware within a given pool over the first.

ecormany · 2025-04-03T13:20:04Z

This PR is stuck in branch h*ck. Closing in favor of #17972, which is freshly branched from chore_release-8.4.0.

Replacing #17914 Below description from that PR. # Overview API docs update for new lids methods in API 2.23: `load_lid_stack`, `move_lid`, and lids loaded onto labware. ## Test Plan and Hands on Testing sandbox: http://sandbox.docs.opentrons.com/docs-lids-in-8.4/v2/ ## Changelog - light editing to API reference entries; including removing a TODO - Loading Labware section: updating well plate used throughout the section so we can demonstrate loading a lid onto it; adding a new "Loading Lids" subsection - Moving Labware section: new "Moving Lids" section that can grow as we add more lids, like cell culture lids, compatible with `move_lid` ## Review requests Code blocks correct? Anything missing? Do we like where new information was added? Maybe update the Auto-Sealing Lids section for the [Thermocycler module example](https://docs.opentrons.com/v2/modules/thermocycler.html)? ## Risk assessment Low. --------- Co-authored-by: emilyburghardt <[email protected]>

emilyburghardt requested a review from a team as a code owner March 27, 2025 22:58

emilyburghardt requested review from ecormany, smb2268, CaseyBatten and jwwojak March 28, 2025 17:53

CaseyBatten reviewed Mar 28, 2025

View reviewed changes

emilyburghardt commented Mar 28, 2025

View reviewed changes

emilyburghardt changed the base branch from edge to chore_release-8.4.0 March 28, 2025 20:51

emilyburghardt requested review from a team as code owners March 28, 2025 20:51

jwwojak reviewed Mar 31, 2025

View reviewed changes

emilyburghardt force-pushed the docs-lids-in-8.4 branch from 26a88b0 to f188a10 Compare March 31, 2025 15:16

ecormany force-pushed the docs-lids-in-8.4 branch from f188a10 to ab6fb90 Compare March 31, 2025 15:50

ecormany removed request for a team and smb2268 March 31, 2025 15:52

ecormany added docs papi-v2 Python API V2 labels Apr 2, 2025

emilyburghardt force-pushed the docs-lids-in-8.4 branch from ab6fb90 to 41bf7e5 Compare April 2, 2025 17:33

y3rsh and others added 10 commits April 2, 2025 11:33

fix(protocol-designer): remove PD version number from navigation bar (#…

a8105b2

…17886) closes AUTH-1544

refactor(protocol-designer): use windows vs mac symbols for hot keys (#…

04199aa

…17888) closes RQA-3668

feat(app): generate python file for quick transfer (#17880)

26144c4

This PR adds the ability to generate python for quick transfer behind a feature flag. It also logs it in devtools so you can view the actual python file, otherwise there is no other way to view the file.

feat(protocol-designer): add release notes link to announcement modal (…

e434647

…#17878) closes AUTH-1423

feature(app): ER for transporter unable to reach final position due t…

72e8c2c

…o stall obstruction (#17773)

fix(api): clamp erroneous negative absorbance values to 0. (#17812)

013492c

rclarke0 and others added 9 commits April 2, 2025 11:33

refactor(protocol-designer): use HydratedFormData union type for form…

2ab75dc

… errors & warnings (#17893)

refactor(step-generation): show location string for location arg in g… (

058f6c9

#17903) …etLoadAdapters

feat(api): Implement stacker pool specific overlap offsets (#17794)

b1462fe

Covers EXEC-1266 Updates the Max pool limit to accounts for the overlap of the last labware within a given pool over the first.

docs(api): lids updates in 8.4

ca4b0e8

moving lids section

253a5d1

changes to moving lids section

41bf7e5

ecormany force-pushed the docs-lids-in-8.4 branch from 41bf7e5 to 361ce3e Compare April 2, 2025 19:36

emilyburghardt force-pushed the docs-lids-in-8.4 branch from 361ce3e to de110bb Compare April 2, 2025 20:57

updates to moving lids section

de110bb

ecormany mentioned this pull request Apr 3, 2025

docs(api): lids updates in app 8.4 / PAPI 2.23 #17972

Merged

ecormany closed this Apr 3, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): lids updates in 8.4 #17914

docs(api): lids updates in 8.4 #17914

emilyburghardt commented Mar 27, 2025 •

edited

Loading

CaseyBatten left a comment

CaseyBatten Mar 28, 2025

CaseyBatten Mar 28, 2025

ecormany Mar 28, 2025

emilyburghardt Mar 28, 2025

emilyburghardt Mar 28, 2025

CaseyBatten Mar 28, 2025 •

edited

Loading

jwwojak left a comment

jwwojak Mar 31, 2025

jwwojak Mar 31, 2025

ecormany Mar 31, 2025

jwwojak Mar 31, 2025

codecov bot commented Mar 31, 2025 •

edited

Loading

ecormany commented Apr 3, 2025

		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.


		You can move compatible Opentrons lids manually or with the Flex gripper, but some restrictions apply. For more, see :ref:`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.

	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.
	An Opentrons Tough PCR lid can be moved between deck slots, lid stacks, or compatible labware, modules, and adapters loaded in your protocol.

docs(api): lids updates in 8.4 #17914

docs(api): lids updates in 8.4 #17914

Conversation

emilyburghardt commented Mar 27, 2025 • edited Loading

Overview

Test Plan and Hands on Testing

Changelog

Review requests

Risk assessment

CaseyBatten left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CaseyBatten Mar 28, 2025 • edited Loading

Choose a reason for hiding this comment

jwwojak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 31, 2025 • edited Loading

Codecov Report

ecormany commented Apr 3, 2025

emilyburghardt commented Mar 27, 2025 •

edited

Loading

CaseyBatten Mar 28, 2025 •

edited

Loading

codecov bot commented Mar 31, 2025 •

edited

Loading