K-Dense-AI/scientific-agent-skills / skills/opentrons-integration
opentrons-integration
VerifiedAuthors, reviews, migrates, simulates, and troubleshoots official Opentrons Python Protocol API v2 protocols for Flex and OT-2 robots. Use for robot-specific liquid handling, deck and labware setup, pipettes, modules, runtime parameters, liquid classes, and Opentrons App analysis. Use pylabrobot instead when one workflow must support multiple robot vendors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.9 KB |
| references/api_reference.md | markdown | 12.6 KB |
| references/liquid_handling.md | markdown | 12.9 KB |
| references/migration-api-2-19-to-2-29.md | markdown | 8.5 KB |
| references/modules_and_deck.md | markdown | 11.9 KB |
| references/protocol_authoring.md | markdown | 11.4 KB |
| references/sources.md | markdown | 9.1 KB |
| references/validation_and_operations.md | markdown | 10.2 KB |
| requirements-flex.txt | markdown | 18 B |
| requirements-ot2.txt | markdown | 17 B |
| scripts/absorbance_reader_template.py | script | 2.3 KB |
| scripts/basic_protocol_template.py | script | 1.8 KB |
| scripts/ot2_basic_protocol_template.py | script | 1.7 KB |
| scripts/pcr_setup_template.py | script | 4.7 KB |
| scripts/runtime_parameters_template.py | script | 3.2 KB |
| scripts/serial_dilution_template.py | script | 3.3 KB |
references/migration-api-2-19-to-2-29.md
View on GitHub# Migrating API 2.19 Protocols to the Current Baseline
This guide updates protocols written around robot software 7.3.1 and Protocol
API 2.19 to the 2026-10-01 baseline:
- Flex: documented maximum Protocol API 2.30; bundled templates retain 2.29.
- OT-2: Protocol API 2.28.
- Flex local simulator: `opentrons==10.0.0`.
- OT-2 local compatibility simulator: `opentrons==9.0.0`, followed by analysis
in the current OT-2 App.
Do not mechanically change only the API string. Newer levels can change command
validation and behavior.
## 1. Identify the Target Robot
API 2.29 and later are not supported on OT-2 at this baseline.
```python
# Flex
requirements = {"robotType": "Flex", "apiLevel": "2.29"}
# OT-2
requirements = {"robotType": "OT-2", "apiLevel": "2.28"}
```
Use one `apiLevel` declaration. Older files often put it in both `metadata` and
`requirements`; current analysis rejects that.
Before:
```python
metadata = {"apiLevel": "2.19", "protocolName": "Example"}
requirements = {"robotType": "Flex", "apiLevel": "2.19"}
```
After:
```python
metadata = {"protocolName": "Example"}
requirements = {"robotType": "Flex", "apiLevel": "2.29"}
```
If the protocol must remain compatible with older robot software, keep 2.19 and
apply only changes available at that level.
## 2. Replace Incorrect Flex Pipette Names
Current Flex load names describe channels and range:
| Old or incorrect pattern | Current choice |
| --- | --- |
| `p50_single_flex` | `flex_1channel_50` |
| `p50_multi_flex` | `flex_8channel_50` |
| `p1000_single_flex` | `flex_1channel_1000` |
| `p1000_multi_flex` | `flex_8channel_1000` |
| `p300_single_flex` | No direct equivalent; choose `flex_1channel_50` or `flex_1channel_1000` from validated volume needs |
| `p300_multi_flex` | No direct equivalent; choose `flex_8channel_50` or `flex_8channel_1000` |
Also available:
- `flex_96channel_200` — API 2.25+.
- `flex_96channel_1000`.
Do not choose solely by the largest transfer. Check every operation against the
pipette's lower and upper range and compatible tip capacities.
OT-2 GEN2 names remain `p20_*_gen2`, `p300_*_gen2`, and
`p1000_single_gen2`.
## 3. Make Flex Trash Explicit
Flex API 2.16+ protocols should load the fixture actually installed:
```python
trash = protocol.load_trash_bin("A3")
```
Or:
```python
chute = protocol.load_waste_chute()
```
OT-2 keeps its fixed trash in slot 12 and does not call `load_trash_bin()`.
If both a trash bin and waste chute exist, set the intended pipette trash
container or pass the documented `trash_location` to complex commands.
## 4. Update Liquid Loading, API 2.22+
`Well.load_liquid()` is deprecated, and `Well.load_empty()` does not exist in
the current package.
Before:
```python
reservoir["A1"].load_liquid(liquid=buffer, volume=10_000)
plate["A1"].load_empty()
```
After:
```python
reservoir.load_liquid(
wells=["A1"],
volume=10_000,
liquid=buffer,
)
plate.load_empty(wells=["A1"])
```
For varying volumes:
```python
plate.load_liquid_by_well(
volumes={"A1": 20, "B1": 30},
liquid=sample,
)
```
## 5. Update Adapter Loading
`ProtocolContext.load_labware_on_adapter()` is not a current method.
Load the adapter, then call the adapter's method:
```python
adapter = protocol.load_adapter(
"opentrons_96_well_aluminum_block",
"D1",
)
plate = adapter.load_labware(
"opentrons_96_wellplate_200ul_pcr_full_skirt"
)
```
Some `load_labware()` calls also accept an `adapter=` load name for supported
stacks. Use the pattern shown for the exact hardware in current documentation.
## 6. Fix Flex Magnetic Workflows
The powered Magnetic Module is OT-2-only.
Old Flex pattern:
```python
magnetic_module = protocol.load_module(
"magnetic module gen2",
"C2",
)
magnetic_module.engage(height_from_base=6.5)
```
Current Flex pattern:
```python
magnetic_block = protocol.load_module("magneticBlockV1", "C2")
protocol.move_labware(
labware=plate,
new_location=magnetic_block,
use_gripper=True,
)
protocol.delay(minutes=5)
protocol.move_labware(
labware=plate,
new_location="B2",
use_gripper=True,
)
```
The Magnetic Block is passive and has no `engage()` or `disengage()` method.
## 7. Fix Absorbance Plate Reader Calls
The reader was added in API 2.21 and is Flex-only. It does not accept
`read(wavelengths=[...])`.
Incorrect:
```python
result = plate_reader.read(wavelengths=[450, 650])
```
Correct sequence:
```python
reader = protocol.load_module("absorbanceReaderV1", "D3")
reader.close_lid()
reader.initialize(mode="multi", wavelengths=[450, 650])
reader.open_lid()
protocol.move_labware(
labware=plate,
new_location=reader,
use_gripper=True,
)
reader.close_lid()
result = reader.read(export_filename="absorbance")
```
The plate reader returns zeros during simulation. Avoid divide-by-zero logic in
the simulation branch.
## 8. Remove Unsupported Complex-Command Options
Do not preserve options merely because an old reference listed them.
For example, `gradient=(start, end)` is not a supported generic `transfer()`
option in the current API. Build a validated volume list explicitly:
```python
volumes = [10, 20, 30, 40]
pipette.transfer(
volume=volumes,
source=reservoir["A1"],
dest=plate.wells()[:4],
new_tip="always",
)
```
Check uncommon options against the exact current method and API level. The
supported options for standard and liquid-class commands are not identical.
## 9. Revisit Behavior Changes
### API 2.20
- Liquid presence detection.
- CSV runtime parameters.
- Expanded partial-nozzle layouts.
### API 2.21
- Absorbance Plate Reader.
- Liquid presence checks only the first aspiration of a `mix()` cycle.
### API 2.22
- Labware-level liquid loading.
- `Well.load_liquid()` deprecated.
- Low-level robot motor control.
### API 2.23
- Meniscus locations.
- Labware lids and lid moves.
- Labware offset behavior aligned with newer App checks.
### API 2.24
- Verified and custom liquid classes.
- `transfer_with_liquid_class()`, `distribute_with_liquid_class()`, and
`consolidate_with_liquid_class()`.
- Additional flow, delay, position, and push-out options.
### API 2.25
- Flex Stacker.
- Flex 96-Channel 200 µL pipette.
### API 2.26
- Liquid-class support for the 96-channel 200 µL pipette.
### API 2.27
- Concurrent module tasks.
- Dynamic aspirate, dispense, and mix paths.
- Built-in camera capture.
- Explicit tips for liquid-class transfers.
### API 2.28
- Flex 20 µL tips.
- Improved return of partially picked-up tips.
- Absolute blowout customization.
- Thermocycler ramp-rate control.
- `set_empty()` tip-rack state.
- Errors for unsafe `touch_tip()` use in large spaces.
### API 2.29
- Step grouping in source and protocol visualization.
- Flex-only at this migration baseline.
### API 2.30
- Aspirating at `well.meniscus(target="start")` without an `end_location` is
supported. Older API levels reject that pattern.
- The 10.0.0 package exposes `MAX_SUPPORTED_VERSION=2.31`, while the official
robot support table stops at 2.30. Check the target robot; do not adopt 2.31
from the local constant.
## 10. Revisit Module and Deck Assumptions
Check for:
- Flex trash or waste chute not represented in old code.
- Staging area and column-3 conflicts.
- New Gripper or lid moves.
- Heater-Shaker latch state.
- Thermocycler generation and footprint.
- Plate-reader caddy and lid travel.
- Stacker shuttle paths.
- Tip-rack adapter requirements for full versus partial 96-channel pickup.
API analysis has improved, so a newly raised deck-conflict error may reveal an
old protocol assumption that was never physically safe.
## 11. Revalidate Tip and Volume Policies
Do not assume newer pipetting behavior produces assay-equivalent results.
- Recalculate tip count.
- Recalculate source and dead volume.
- Confirm complex-command expansion in the run log.
- Requalify flow rates, mix behavior, bottom clearances, air gaps, and blowout.
- Recheck contamination policy.
- Recheck multi-channel and partial-nozzle well targeting.
## 12. Migration Test Plan
1. Preserve the original protocol and expected run log.
2. Update declarations and load names.
3. Replace deprecated or invalid calls.
4. Simulate with the robot-specific pin: `opentrons==10.0.0` for Flex or
`opentrons==9.0.0` for OT-2.
5. Compare command order, tip use, source/destination mapping, and module states.
6. Test every runtime parameter branch.
7. Import into the correct App and target robot.
8. Resolve every analysis warning and error.
9. Perform a nonhazardous dry run.
10. Requalify assay performance before production use.
Do not claim a migration is equivalent solely from a successful simulation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |