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/api_reference.md
View on GitHub# Opentrons Protocol API v2 Quick Reference
Verified against `opentrons==10.0.0` and the official documentation on
2026-10-01. This is a curated authoring reference, not a replacement for the
[ProtocolContext API reference](https://docs.opentrons.com/python-api/reference/protocols/)
and its linked class references.
## Version Baseline
| Robot | Supported API range on current software | Documented robot maximum |
| --- | --- | --- |
| Flex | 2.15–2.30 | 2.30 |
| OT-2 | 2.0–2.28 | 2.28 |
API versions are independent of the installed Python package and robot software.
Choose the lowest API level that includes every required feature. A protocol
specifying a higher level than the robot supports will fail analysis.
```python
metadata = {
"protocolName": "Example",
"author": "Your Name",
"description": "Purpose and scope.",
}
requirements = {"robotType": "Flex", "apiLevel": "2.29"}
```
Rules:
- Flex always requires `requirements`.
- `requirements` is recommended for OT-2 protocols using API 2.15+.
- Put `apiLevel` in exactly one place. When using `requirements`, remove it from
`metadata`.
- `run(protocol: protocol_api.ProtocolContext)` is the required entry point.
## Features Added After API 2.19
| API | High-value additions |
| --- | --- |
| 2.20 | CSV runtime parameters; liquid presence detection; row, single, and partial-column nozzle layouts |
| 2.21 | `AbsorbanceReaderContext` and `absorbanceReaderV1` |
| 2.22 | `Labware.load_liquid()`, `load_liquid_by_well()`, and `load_empty()`; robot motor control |
| 2.23 | `Well.meniscus()`; labware lids and lid moves |
| 2.24 | Liquid classes; advanced liquid-class complex commands; absolute flow-rate options |
| 2.25 | `FlexStackerContext`; `flexStackerModuleV1`; `flex_96channel_200` |
| 2.26 | Liquid-class support for `flex_96channel_200` |
| 2.27 | Concurrent module actions; dynamic aspirate, dispense, and mix; `capture_image()`; explicit liquid-class tips |
| 2.28 | Flex 20 µL tips; partial-tip return; thermocycler ramp rate; empty tip-rack tracking |
| 2.29 | Protocol step grouping |
| 2.30 | Start-only meniscus aspiration without an end location |
See
[Versioning](https://docs.opentrons.com/python-api/versioning/) for complete
behavior changes and robot-software mappings.
## Pipette Load Names
### Flex
| Pipette | Nominal range | Load name |
| --- | ---: | --- |
| 1-Channel 50 µL | 1–50 µL | `flex_1channel_50` |
| 1-Channel 1000 µL | 5–1000 µL | `flex_1channel_1000` |
| 8-Channel 50 µL | 1–50 µL | `flex_8channel_50` |
| 8-Channel 1000 µL | 5–1000 µL | `flex_8channel_1000` |
| 96-Channel 200 µL | 1–200 µL | `flex_96channel_200` |
| 96-Channel 1000 µL | 5–1000 µL | `flex_96channel_1000` |
Flex 50 µL pipettes need `configure_for_volume(1)` (or the intended 1–4.9 µL
volume) before low-volume handling. Call it while empty, preferably before tip
pickup. That mode permits 1–30 µL; normal mode permits 5–50 µL. Tip capacity
can impose a lower maximum. These are documented ranges; the simulator's
lower `min_volume` value does not qualify sub-1 µL dispensing. Changing mode
resets flow rates. See the
[volume-mode guide](https://docs.opentrons.com/python-api/pipettes/volume-modes/).
The 96-channel pipette occupies both mounts. From API 2.16 onward its `mount`
argument is optional.
### OT-2 GEN2
| Pipette | Nominal range | Load name |
| --- | ---: | --- |
| P20 single | 1–20 µL | `p20_single_gen2` |
| P20 multi | 1–20 µL | `p20_multi_gen2` |
| P300 single | 20–300 µL | `p300_single_gen2` |
| P300 multi | 20–300 µL | `p300_multi_gen2` |
| P1000 single | 100–1000 µL | `p1000_single_gen2` |
GEN1 OT-2 pipettes have different load names. Check
[Loading Pipettes](https://docs.opentrons.com/python-api/pipettes/loading/)
instead of guessing.
## Flex Tip Compatibility
| Pipette family | Compatible Flex tip-rack capacities |
| --- | --- |
| `flex_1channel_50`, `flex_8channel_50` | 20 µL, 50 µL |
| `flex_96channel_200` | 20 µL, 50 µL, 200 µL |
| `flex_1channel_1000`, `flex_8channel_1000`, `flex_96channel_1000` | 50 µL, 200 µL, 1000 µL |
Filter-tip load names insert `_filtertiprack_`, for example
`opentrons_flex_96_filtertiprack_200ul`.
Full-rack pickup by a Flex 96-channel pipette requires the Flex tip-rack
adapter. Partial pickup by that pipette must use a rack directly on the deck,
without the adapter.
## ProtocolContext
### Hardware and deck
```python
labware = protocol.load_labware(load_name, location, label=None)
adapter = protocol.load_adapter(load_name, location)
module = protocol.load_module(module_name, location=None)
pipette = protocol.load_instrument(
instrument_name,
mount,
tip_racks=[tiprack],
)
trash = protocol.load_trash_bin("A3") # Flex, API 2.16+
chute = protocol.load_waste_chute() # Flex, fixed at D3
```
Useful methods:
- `load_labware_from_definition(definition, location, label=None)`
- `move_labware(labware, new_location, use_gripper=...)`
- `load_lid_stack(load_name, location, quantity)`
- `move_lid(source_location, new_location, use_gripper=...)`
- `define_liquid(name, description=None, display_color=None)`
- `get_liquid_class(name, version=None)` — API 2.24+
- `define_liquid_class(name, properties, base_liquid_class=None, display_name=None)` — API 2.24+
### Execution and organization
- `comment(msg)` — adds analysis-time text to the run log.
- `pause(msg=None)` — waits for the operator to resume in the App/touchscreen.
- `delay(seconds=0, minutes=0, msg=None)` — blocking delay.
- `home()` — homes robot axes.
- `is_simulating()` — identify local or App analysis.
- `group_steps(name, description=None)` — context manager, API 2.29.
- `create_and_start_step_group(name, description=None)` — returns a group whose
`end_group()` method closes it, API 2.29.
- `capture_image()` — captures from the built-in camera, API 2.27.
Step groups only organize source and visualization; they do not change
execution.
## InstrumentContext
### Tips
```python
pipette.pick_up_tip()
pipette.drop_tip()
pipette.return_tip()
pipette.reset_tipracks()
```
In API 2.28+, `tiprack.set_empty()` can mark a rack empty so returned tips may be
tracked there. Only return tips when the protocol's contamination policy allows
it.
### Building-block commands
```python
pipette.aspirate(volume, source)
pipette.dispense(volume, destination, push_out=5)
pipette.air_gap(volume)
pipette.blow_out(destination.top())
pipette.touch_tip(destination)
pipette.mix(repetitions, volume, destination)
pipette.move_to(destination.top())
```
Use `rate=` as a multiplier of the pipette's configured flow rate, or supported
absolute flow-rate arguments when the API level provides them. Do not supply
both forms for the same action.
API 2.27 adds `end_location` and `movement_delay` to aspirate and dispense, plus
`dynamic_mix()` for start-to-end movement during repeated aspiration and
dispensing.
### Complex commands
```python
pipette.transfer(volume, source, destination, new_tip="always")
pipette.distribute(volume, source, destinations, new_tip="once")
pipette.consolidate(volume, sources, destination, new_tip="always")
```
Common options include:
- `new_tip`: `"always"`, `"once"`, or `"never"`; newer API levels add
additional policies for some commands.
- `mix_before=(repetitions, volume)`
- `mix_after=(repetitions, volume)`
- `touch_tip=True`
- `blow_out=True`
- `blowout_location=...`
- `disposal_volume=...`
- `trash_location=...`
Supported options differ by command and API level. Check the exact signature in
the
[Instrument API reference](https://docs.opentrons.com/python-api/reference/instruments/)
before using uncommon options.
### Liquid-class commands, Flex only
```python
water = protocol.get_liquid_class("water")
pipette.transfer_with_liquid_class(
liquid_class=water,
volume=50,
source=reservoir["A1"],
dest=plate["A1"],
new_tip="always",
trash_location=trash,
)
```
Related methods are `distribute_with_liquid_class()` and
`consolidate_with_liquid_class()`. Opentrons-verified classes include water,
80% ethanol, and 50% glycerol. Compatibility depends on the exact Flex pipette
and tip combination. Omitted `version` selects the latest class for the declared
API level; record and pin a qualified class version for assay reproducibility.
## Labware and Wells
### Accessors
```python
plate["A1"]
plate.wells()
plate.wells_by_name()
plate.rows()
plate.rows_by_name()
plate.columns()
plate.columns_by_name()
```
Labware iteration is generally column-major. Use named wells or explicit lists
when order is safety-critical.
### Locations
```python
well.top(z=-1)
well.bottom(z=2)
well.center()
well.meniscus(z=0, target="start") # API 2.23+
```
`meniscus()` depends on declared or measured liquid volume. Start-only aspiration
without `end_location` requires API 2.30; at 2.29 and lower use the documented
end-target or start-to-end pattern. Validate liquid
height behavior on hardware before relying on it for low-volume aspiration.
### Liquid setup visualization, API 2.22+
```python
buffer = protocol.define_liquid(
name="Buffer",
description="Assay buffer",
display_color="#1F77B4",
)
reservoir.load_liquid(
wells=["A1"],
volume=10_000,
liquid=buffer,
)
plate.load_liquid_by_well(
volumes={"A1": 50, "B1": 50},
liquid=buffer,
)
plate.load_empty(wells=["A2", "B2"])
```
`Well.load_liquid()` is deprecated for API 2.22+ protocols.
## Runtime Parameters
Define parameters outside `run()`:
```python
def add_parameters(parameters: protocol_api.ParameterContext) -> None:
parameters.add_int(
variable_name="sample_count",
display_name="Sample count",
default=8,
minimum=1,
maximum=96,
)
parameters.add_bool(
variable_name="dry_run",
display_name="Dry run",
default=False,
)
```
Read them during execution:
```python
sample_count = protocol.params.sample_count
dry_run = protocol.params.dry_run
```
Methods:
- `add_bool(...)`
- `add_int(...)`
- `add_float(...)`
- `add_str(...)`
- `add_csv_file(...)` — API 2.20+, no default, at most one CSV parameter per
run.
Parameter display names are limited to 30 characters and descriptions to 100
characters. Numeric parameters require either a min/max range or fixed choices.
## Liquid Presence and Height
Flex pressure-sensing pipettes support:
- `detect_liquid_presence(well)`
- `require_liquid_presence(well)`
- `measure_liquid_height(well)`
- `liquid_presence_detection=True` in `load_instrument()`
- Runtime toggling with `pipette.liquid_presence_detection`
Detection requires a fresh, dry, empty tip for each check. Global detection plus
a complex command may reuse a wet tip on a refill: use explicit building blocks
with a fresh pickup immediately before each checked aspiration. It can add substantial run time,
and not every channel on a multi-channel pipette contains a pressure sensor.
## Partial Nozzle Layouts
```python
from opentrons.protocol_api import ALL, COLUMN
pipette.configure_nozzle_layout(
style=COLUMN,
start="A12",
tip_racks=[partial_tip_rack],
)
# Restore full-rack pickup later.
pipette.configure_nozzle_layout(
style=ALL,
tip_racks=[full_tip_rack],
)
```
Available constants include `ALL`, `COLUMN`, `ROW`, `SINGLE`, and
`PARTIAL_COLUMN`, subject to pipette and API support. An incorrect target well
can place nozzles outside the labware and cause a physical crash. Follow the
deck-edge and tip-rack-adapter rules in
[Partial Tip Pickup](https://docs.opentrons.com/python-api/pipettes/partial-tip-pickup/).
## Module Load Names
| Module | Load name | Minimum API |
| --- | --- | ---: |
| Temperature Module GEN1 | `temperature module` | 2.0 |
| Temperature Module GEN2 | `temperature module gen2` | 2.3 |
| Thermocycler GEN1 | `thermocycler module` | 2.0 |
| Thermocycler GEN2 | `thermocyclerModuleV2` | 2.13 |
| Heater-Shaker GEN1 | `heaterShakerModuleV1` | 2.13 |
| Magnetic Block GEN1 | `magneticBlockV1` | 2.15 |
| Absorbance Plate Reader | `absorbanceReaderV1` | 2.21 |
| Flex Stacker | `flexStackerModuleV1` | 2.25 |
Module availability also depends on robot model and physical generation. See
`modules_and_deck.md` before choosing a load name.
## Simulation Entrypoints
```bash
# Flex API 2.29
uv run --no-project --isolated --python 3.12 --with "opentrons==10.0.0" opentrons_simulate protocol.py
# OT-2 API 2.28 compatibility simulation
uv run --no-project --isolated --python 3.12 --with "opentrons==9.0.0" opentrons_simulate protocol.py
```
Python integrations may use `opentrons.simulate.simulate()` with an opened
protocol file. `opentrons==10.0.0` rejects OT-2 protocols after the release-line
split, so complete OT-2 validation in the current OT-2 App. Do not use
`opentrons_execute` from a workstation as a substitute for App analysis and
controlled robot operation.
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 |