Opentrons importer — user reference¶

End-user documentation for the Opentrons Protocol API (.py) importer. Contributor / architecture notes live in opentrons-architecture.md.

Quickstart — try it in 30 seconds¶

Save the following as trivial.py (a working 4-step Opentrons protocol):

metadata = {
    'protocolName': 'Trivial single-aspirate-and-dispense',
    'apiLevel': '2.13',
}

def run(protocol):
    tips = protocol.load_labware('opentrons_96_tiprack_300ul', 1)
    plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 2)
    pipette = protocol.load_instrument('p300_single_gen2', 'left',
                                       tip_racks=[tips])

    pipette.pick_up_tip()
    pipette.aspirate(100, plate['A1'])
    pipette.dispense(100, plate['B1'])
    pipette.drop_tip()

Three ways to import it — pick whichever fits:

1. Web app (no install)¶

1. Go to kitchen.rhylthyme.com.
2. In the left sidebar, expand Upload Program.
3. Drag your trivial.py onto the drop zone (or click the zone and pick the file). .py files are listed alongside .json, .yaml, .pptx, and .cook as accepted formats.
4. The visualization appears in the main pane: one Left: P300 single-channel track with four steps — Pickup Tip → Aspirate → Dispense → Drop Tip.

2. CLI¶

pip install rhylthyme
rhylthyme import trivial.py -o trivial.json     # or: rhylthyme-import-opentrons trivial.py | jq .

Prints the same program JSON the web upload renders.

3. MCP (Claude Desktop and other agents)¶

Once the Rhylthyme MCP connector is wired into your client, call the import_from_source tool with:

{ "source": "opentrons", "action": "import", "text": "<your .py source>" }

Pass a public .py URL via "query": "<url>" instead of "text" if you'd rather not paste the source.

Larger example protocols live in the worked examples section below — those .py files double as the importer's golden-fixture test inputs, so they stay in sync with the code.

Supported features¶

The importer parses a protocol's run(protocol) body and emits one Rhylthyme step per recognised method call. Anything the simulator can't execute falls through to a static AST parser, which is more conservative (no helper expansion, no mount/module awareness) but lets you import protocols that reference labware definitions the importer doesn't ship.

Status: ✅ supported · 🚧 partial (AST-only or unexpanded) · ⏳ planned.

Pipettes & mounts¶

Pipette commands¶

Each row maps to one CommandEvent per call.

Protocol-level¶

Modules¶

Each loaded module gets its own track + a maxConcurrent: 1 resource constraint. Module commands map to the same task vocabulary as the protocols.io importer (heating, incubation, mixing, measurement).

Background timing model. Module commands run on their own track so the pipette track can continue in parallel — the visualiser shows the robot doing other work during a shake or thermocycler profile. The duration of thermocycler.execute_profile(steps=..., repetitions=N) is computed exactly: sum(step.hold_time_seconds) * N. Set-and-wait / deactivate commands fall back to static estimates; later phases may extend the model with volume / temperature awareness.

Entry points¶

Worked examples¶

The four files below are both the golden-fixture inputs for the test suite and the worked-example reference protocols for these docs — single source of truth. CI fails when one exists without the other.

Each fixture lives at rhylthyme-importers/tests/fixtures/opentrons/<name>.py. Run the CLI on any of them to see exactly what an import produces:

rhylthyme-import-opentrons rhylthyme-importers/tests/fixtures/opentrons/<name>.py | jq .

Troubleshooting (error catalog)¶

Every error string the importer can emit, with the most likely cause and how to fix it.

Any of the above errors are importer-side — the importer never gets to the program builder when they fire. Once the import succeeds you might still see a soft warning surfaced in the web UI:

⚠️ This protocol was parsed statically; some steps may be missing.

That means the simulator hit something it couldn't execute and the AST fallback ran. The visualization is real but conservative — helper methods (transfer / distribute / consolidate) appear as single steps instead of expanded into low-level pipette calls. To get full fidelity, run the protocol against the simulator locally (rhylthyme-import-opentrons <file> will print the simulator error on stderr) and fix the issue.

Limitations¶

• API version: Protocol API v2 only. v1 (legacy) and Protocol Designer JSON exports are out of scope. See the PRD for rationale.
• Duration estimates are static lookups, not volume- or distance-aware. Expect ±20% vs. wall-clock for now; the model lives behind a one-function seam, so a more accurate model can be swapped in without touching the parser or builder.
• AST fallback is conservative: helper methods (transfer, distribute, consolidate) appear as single events (not expanded), and the parser can't tell which mount a pipette is on. Any AST-parsed result carries a WARNING event the web UI surfaces as a banner.
• Dynamic control flow that depends on runtime values (e.g. conditionals reading a CSV during run()) is handled best-effort by the simulator's stubbed labware (which returns sensible defaults so the protocol doesn't crash). When that's not enough, the AST fallback kicks in.

Duration model reference (auto-generated)¶

Regenerate with make docs after editing DURATION_SECONDS in opentrons/duration_model.py.