domains / science / opentrons-protocol-authoring / opentrons-integration

opentrons-integration

Skill card

combined

The two skills cover the same domain but have significant, non-overlapping material and conflicting technical guidance. The K-Dense skill is a rigorous, version-pinned engineering guide (v2.3) that emphasizes safety, specific library versions (opentrons 10.0.0/9.0.0), and correct API 2.29+ structure (requirements vs metadata). The FreedomIntelligence skill is a broader, more tutorial-like guide that includes specific module loading examples (thermocycler, heater-shaker) and advanced liquid handling techniques (air gaps, flow rates) but uses outdated API patterns (apiLevel in metadata) and generic versioning advice. Crowning one would hide the other's unique value: K-Dense's safety/versioning rigor vs. FreedomIntelligence's module/technique breadth.

Repositories

Other copies

Combined skill

---
name: opentrons-integration
description: Authors, reviews, migrates, simulates, and troubleshoots official Opentrons Python Protocol API v2 protocols for Flex and OT-2 robots. Covers structure, hardware, liquid handling, modules, and safety.
license: MIT
compatibility: Requires Python 3.10+ and uv. Flex targets opentrons 10.0.0 (API 2.29+); OT-2 targets opentrons 9.0.0 (API 2.28).
---

# Opentrons Integration

## Overview
Create production-minded Python Protocol API v2 protocols for Opentrons Flex and OT-2. This skill covers protocol structure, hardware configuration, liquid handling, module control, simulation, and safe deployment.

## Safety Boundary
Opentrons protocols control physical equipment. Never treat successful Python syntax or local simulation as permission to run on a robot.

Before live execution:
1. Simulate locally with the same pinned `opentrons` version used for authoring.
2. Import the protocol into the correct Opentrons App and require successful analysis.
3. Verify robot model, software, pipettes, mounts, modules, adapters, labware definitions, deck fixtures, tip count, source volumes, dead volumes, and destination capacity.
4. Review the run preview and deck map with the operator.
5. Perform a slow dry run with nonhazardous liquid when geometry, custom labware, or gripper moves are new.
6. Keep the emergency stop accessible and follow site-specific safety procedures.

## Versioning and Simulation
- **Flex**: Use `opentrons==10.0.0` for simulation. Supports API 2.15–2.30.
- **OT-2**: Use `opentrons==9.0.0` for simulation. Supports API 2.0–2.28.
- **API Level**: For API 2.29+, `apiLevel` must be in `requirements`, not `metadata`.

Simulate with:
```bash
# Flex
uv run --no-project --isolated --python 3.12 --with "opentrons==10.0.0" opentrons_simulate protocol.py

# OT-2
uv run --no-project --isolated --python 3.12 --with "opentrons==9.0.0" opentrons_simulate protocol.py
```

## Protocol Structure

### Flex (API 2.29+)
```python
from opentrons import protocol_api

metadata = {
    "protocolName": "Flex transfer",
    "author": "Your Name",
    "description": "Transfer buffer into a plate."
}
requirements = {"robotType": "Flex", "apiLevel": "2.29"}

def run(protocol: protocol_api.ProtocolContext) -> None:
    # Protocol logic
    pass
```

### OT-2 (API 2.28)
```python
from opentrons import protocol_api

metadata = {
    "protocolName": "OT-2 transfer",
    "author": "Your Name",
    "description": "Transfer buffer into a plate.",
    "apiLevel": "2.28" # For < 2.29, apiLevel can be in metadata
}

def run(protocol: protocol_api.ProtocolContext) -> None:
    # Protocol logic
    pass
```

## Loading Hardware

### Pipettes
```python
# Flex
pipette = protocol.load_instrument('p1000_single_flex', 'left', tip_racks=[tip_rack])

# OT-2
pipette = protocol.load_instrument('p1000_single_gen2', 'left', tip_racks=[tip_rack])
```

### Labware
```python
# Deck slot
plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D1')

# On module
module = protocol.load_module('temperature module gen2', 'D3')
plate = module.load_labware('corning_96_wellplate_360ul_flat')
```

### Modules
```python
# Temperature
temp_module = protocol.load_module('temperature module gen2', 'D3')

# Heater-Shaker
hs_module = protocol.load_module('heaterShakerModuleV1', 'D1')

# Thermocycler
tc_module = protocol.load_module('thermocyclerModuleV2')
```

## Liquid Handling

### Basic Operations
```python
pipette.pick_up_tip()
pipette.aspirate(100, source['A1'])
pipette.dispense(100, dest['B1'])
pipette.drop_tip()
```

### Composite Operations
```python
# Transfer
pipette.transfer(100, source['A1'], dest['B1'], new_tip='always')

# Distribute
pipette.distribute(50, source['A1'], [dest['A1'], dest['A2']], new_tip='once')

# Consolidate
pipette.consolidate(50, [source['A1'], source['A2']], dest['A1'], new_tip='once')
```

### Advanced Techniques
```python
# Mix
pipette.mix(repetitions=3, volume=50, location=plate['A1'])

# Air Gap
pipette.aspirate(100, source['A1'])
pipette.air_gap(20)
pipette.dispense(120, dest['A1'])

# Flow Rate Control
pipette.flow_rate.aspirate = 150
pipette.flow_rate.dispense = 300
```

## Conflicts
- **FreedomIntelligence/OpenClaw-Medical-Skills** suggests placing `apiLevel` in `metadata` and using the "latest" version. This is incorrect for modern Flex protocols (API 2.29+) where `apiLevel` belongs in `requirements`. Always pin versions and follow the structure defined in the K-Dense skill for API 2.29+.