Ultimate Opentrons Framework

Automate liquid handling and laboratory workflows using Opentrons robots through the Opentrons Python API. This skill covers protocol development, labware configuration, pipetting operations, multi-step assay automation, and integration with lab information management systems.

When to Use This Skill

Choose Ultimate Opentrons Framework when you need to:

• Write Python protocols for Opentrons OT-2 or Flex liquid handling robots
• Automate repetitive pipetting tasks (serial dilutions, plate transfers, sample prep)
• Build multi-step assay protocols with complex liquid handling logic
• Integrate robot operations with upstream sample tracking or LIMS systems

Consider alternatives when:

• You need high-throughput screening with 1536-well plates (use specialized HTS platforms)
• You need centrifugation or thermal cycling integrated with liquid handling (add modules or use integrated platforms)
• You need manual protocol documentation without automation (use electronic lab notebooks)

Quick Start

Copy
# Install Opentrons API
pip install opentrons

Copy
from opentrons import protocol_api

metadata = {
    "protocolName": "Simple Plate Transfer",
    "author": "Lab Automation",
    "apiLevel": "2.15"
}

def run(protocol: protocol_api.ProtocolContext):
    # Load labware
    source_plate = protocol.load_labware("corning_96_wellplate_360ul_flat", 1)
    dest_plate = protocol.load_labware("corning_96_wellplate_360ul_flat", 2)
    tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", 3)

    # Load pipette
    pipette = protocol.load_instrument(
        "p300_single_gen2", "left", tip_racks=[tiprack]
    )

    # Transfer 100 µL from each well in column 1
    for i in range(8):
        pipette.transfer(
            100,
            source_plate.wells()[i],
            dest_plate.wells()[i]
        )

Core Concepts

API Components

Component	Description	Example
ProtocolContext	Main protocol interface	protocol.load_labware()
Labware	Plates, reservoirs, tip racks	corning_96_wellplate_360ul_flat
InstrumentContext	Pipette controller	p300_single_gen2, p20_multi_gen2
ModuleContext	Hardware modules	Temperature, magnetic, thermocycler
transfer()	High-level liquid transfer	Source → destination with options
aspirate()/dispense()	Low-level pipetting control	Fine-tuned liquid handling

Complex Protocol: Serial Dilution

Copy
from opentrons import protocol_api

metadata = {"protocolName": "Serial Dilution", "apiLevel": "2.15"}

def run(protocol: protocol_api.ProtocolContext):
    # Labware
    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", 1)
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", 2)
    tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", 3)

    # Pipette
    p300 = protocol.load_instrument("p300_multi_gen2", "left",
                                     tip_racks=[tiprack])

    # Step 1: Add diluent to columns 2-12
    p300.transfer(
        200,
        reservoir.wells()[0],
        plate.columns()[1:12],
        new_tip="once"
    )

    # Step 2: Serial dilution across columns
    p300.transfer(
        100,
        plate.columns()[:11],  # source: columns 1-11
        plate.columns()[1:12],  # dest: columns 2-12
        mix_after=(3, 100),     # mix 3 times with 100 µL
        new_tip="always"
    )

    # Step 3: Remove excess from last column
    p300.transfer(
        100,
        plate.columns()[11],
        reservoir.wells()[1],  # waste
        new_tip="once"
    )

Module Integration

Copy
from opentrons import protocol_api

metadata = {"protocolName": "Temperature-Controlled Assay", "apiLevel": "2.15"}

def run(protocol: protocol_api.ProtocolContext):
    # Load temperature module
    temp_module = protocol.load_module("temperature module gen2", 4)
    temp_plate = temp_module.load_labware(
        "opentrons_96_aluminumblock_nest_wellplate_100ul"
    )

    # Load magnetic module
    mag_module = protocol.load_module("magnetic module gen2", 6)
    mag_plate = mag_module.load_labware(
        "nest_96_wellplate_2ml_deep"
    )

    tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", 3)
    p300 = protocol.load_instrument("p300_single_gen2", "left",
                                     tip_racks=[tiprack])

    # Set temperature
    temp_module.set_temperature(4)
    protocol.comment("Cooling to 4°C...")

    # Add reagents at controlled temperature
    for well in temp_plate.wells()[:8]:
        p300.transfer(50, temp_plate.wells()[0], well)

    # Magnetic bead separation
    mag_module.engage(height_from_base=5)
    protocol.delay(minutes=2)

    # Remove supernatant
    for well in mag_plate.wells()[:8]:
        p300.transfer(150, well, mag_plate.wells()[-1], rate=0.5)

    mag_module.disengage()
    temp_module.deactivate()

Configuration

Parameter	Description	Default
apiLevel	Opentrons API version	"2.15"
pipette_model	Pipette type and generation	Varies by setup
tip_racks	Tip rack labware definitions	Required
labware_offsets	Calibration offsets per slot	From calibration
aspirate_rate	Aspiration speed multiplier	1.0
dispense_rate	Dispensing speed multiplier	1.0

Best Practices

1. Simulate before running on hardware — Use opentrons_simulate protocol.py to verify your protocol logic, check for labware conflicts, and ensure tip usage doesn't exceed tip rack capacity. Simulation catches errors that would waste reagents on the actual robot.

2. Use transfer() over manual aspirate/dispense — The high-level transfer() method handles tip management, air gaps, blow-out, and touch-tip automatically. Only use low-level aspirate()/dispense() when you need custom liquid handling behavior like partial dispensing or multi-dispense from a single aspiration.

3. Set appropriate flow rates for viscous liquids — Glycerol, cell suspensions, and other viscous liquids require slower aspiration: pipette.flow_rate.aspirate = 50 (default is 150 µL/s). Fast aspiration of viscous liquids causes inaccurate volumes and air bubbles.

4. Use new_tip="always" for cross-contamination-sensitive steps — Default tip behavior reuses tips. For PCR setup, cell culture, or any protocol where sample cross-contamination matters, explicitly set new_tip="always" and verify you have enough tip racks loaded.

5. Add protocol comments for traceability — Use protocol.comment("Step 3: Adding enzyme mix") to annotate key steps. These comments appear in the run log and help troubleshoot when results don't match expectations.

Common Issues

Protocol fails with "labware not found" error — Custom labware definitions must be uploaded to the robot before use. Use the Opentrons Labware Creator to define new labware and import it via the app. For standard labware, check the exact string name against the Opentrons Labware Library — typos in labware names are the most common cause.

Pipette picks up but doesn't aspirate liquid — The tip is not reaching the liquid surface. Adjust the aspiration height with pipette.well_bottom_clearance.aspirate = 1.0 (mm from well bottom). For partially filled wells, calculate liquid height dynamically based on the volume remaining.

Inconsistent volumes across wells — Pipette calibration drift or incorrect tip seating causes volume variation. Run the pipette calibration procedure through the Opentrons app, ensure tips are seated firmly (listen for the click), and verify performance with a gravimetric test (weigh water dispensed across multiple wells).