opentrons-integration

Opentrons インテグレーション

概要

Opentrons Flex および OT-2 向けに、実運用を意識した Python Protocol API v2 プロトコルを作成します。このスキルでは、プロトコル構造、ハードウェアとデッキの構成、液体の取り扱い、実行時のカスタマイズ、モジュール制御、シミュレーション、安全なデプロイを扱います。

2026-07-23 時点で確認済みの基準は次のとおりです。

• 再現可能な Flex シミュレーションには opentrons==9.1.1 を使用します。
• ローカルで OT-2 API 2.28 との互換性をシミュレーションするには opentrons==9.0.0 を使用します。
• 現行ソフトウェアでは、Flex は API レベル 2.15～2.29 をサポートします。
• 現行ソフトウェアでは、OT-2 は API レベル 2.0～2.28 をサポートします。
• この基準では、API 2.29 は Flex 専用です。OT-2 プロトコルに 2.29 を指定しないでください。

このスナップショットで使用した上流ドキュメントについては、references/sources.md を参照してください。新しいロボットソフトウェアを対象とする場合は、公式のバージョン管理ページを再確認してください。

安全上の制約

Opentrons プロトコルは物理機器を制御します。Python の構文が正しいことやローカルシミュレーションが成功したことを、ロボットで実行する許可と見なしてはなりません。

実機で実行する前に、次のことを行ってください。

1. 作成時に使用したものと同じバージョンの opentrons を使って、ローカルでシミュレーションします。
2. 正しい Opentrons App にプロトコルをインポートし、解析が成功することを確認します。
3. ロボットのモデル、ソフトウェア、ピペット、マウント、モジュール、アダプター、ラボウェア定義、デッキの固定具、チップ数、ソースの容量、デッドボリューム、分注先の容量を確認します。
4. 実行プレビューとデッキマップをオペレーターと一緒に確認します。
5. 新しい形状、カスタムラボウェア、部分的なチップピックアップ、またはグリッパーの動作を含む場合は、危険性のない液体を使って、ゆっくりとしたドライランを実施します。
6. 緊急停止ボタンをすぐに操作できる状態にし、施設固有のバイオセーフティ、化学物質の安全、および汚染管理の手順に従います。

シミュレーションでは、物理的なキャリブレーション、液体の特性、メニスカスの挙動、ラボウェアの製造公差、キャップやシールの取り外し、チューブ、または起こり得るすべての衝突を検証できません。

適切なインターフェースを選択する

このスキルは、Opentrons App にインポートし、Protocol API を介して実行する Python ファイル向けです。

• 対応するノーコードのワークフローには Protocol Designer を使用します。
• 複数のベンダーにまたがるハードウェア非依存のワークフローには PyLabRobot を使用します。
• ロボットの HTTP API は、別個のインテグレーションインターフェースとして扱います。HTTP による直接制御が明示的に必要な場合は、対象のロボットが提供する OpenAPI ドキュメントを使用し、Protocol API のメソッドからエンドポイントを推測しないでください。

必要な事前情報

次の情報が判明するまで、最終的なプロトコルコードを書かないでください。

• ロボット：Flex または OT-2、およびインストール済みのロボットソフトウェア。
• ピペットのモデル、容量範囲、チャンネル数、マウント。
• モジュールと世代、Flex Gripper または Stacker の有無。
• 正確なラボウェア API のロード名と、該当する場合はカスタム定義ファイル。
• デッキの固定具：Flex のゴミ箱、廃液シュート、ステージングスロット、または Stackers。
• ソース容量、分注先容量、デッドボリューム、混合の必要性、液体の特性。
• チップの方針：汚染境界、再利用方針、フィルターの有無、部分的なピックアップ、チップの総数。
• オペレーターの介入、インキュベーション時間、実行時パラメーター、出力ファイル。
• 受け入れ基準：許容される容量誤差、必要なコントロール、ドライランの計画。

物理的な構成に不明な点がある場合は、推測するのではなく、パラメーター化したドラフトと、前提条件の明示的な一覧を作成してください。

インストールとシミュレーション

Flex：

uv run --with "opentrons==9.1.1" opentrons_simulate protocol.py

OT-2 API 2.28：

uv run --with "opentrons==9.0.0" opentrons_simulate protocol.py

9.1.1 パッケージは、Flex と OT-2 のリリース系列が分離された後の OT-2 プロトコルを意図的に拒否します。OT-2 の解析は必ず現行の OT-2 App で完了してください。

Flex 専用の環境を用意する場合：

uv venv --python 3.10
uv pip install --python .venv/bin/python -r skills/opentrons-integration/requirements-flex.txt
.venv/bin/opentrons_simulate protocol.py

OT-2 互換環境では、代わりに requirements-ot2.txt を使用します。Windows では、.venv\Scripts\opentrons_simulate.exe から実行ファイルを呼び出してください。ローカルシミュレーションは Python プロトコル向けです。Protocol Designer の JSON ファイルは、代わりに適切な Opentrons App にインポートしてください。

プロトコルのひな形

Flex、API 2.29

Flex では、requirements が必須です。apiLevel は requirements のみに記述し、metadata と requirements の両方には記述しないでください。

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:
    tips = protocol.load_labware(
        "opentrons_flex_96_tiprack_200ul", "D1"
    )
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "D2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "C2")
    protocol.load_trash_bin("A3")
    pipette = protocol.load_instrument(
        "flex_1channel_1000", "left", tip_racks=[tips]
    )

    pipette.transfer(
        100,
        reservoir["A1"],
        plate["A1"],
        new_tip="always",
    )

OT-2、API 2.28

OT-2 API 2.15 以降では、requirements ブロックを推奨します。OT-2 にはスロット 12 に固定式のトラッシュがあります。load_trash_bin() は呼び出さないでください。

from opentrons import protocol_api

metadata = {
    "protocolName": "OT-2 transfer",
    "author": "Your Name",
}
requirements = {"robotType": "OT-2", "apiLevel": "2.28"}


def run(protocol: protocol_api.ProtocolContext) -> None:
    tips = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "3")
    pipette = protocol.load_instrument(
        "p300_single_gen2", "left", tip_racks=[tips]
    )
    pipette.transfer(100, reservoir["A1"], plate["A1"])

複数のソフトウェアバージョンが混在する環境でプロトコルを実行する必要がある場合は、必要な機能をすべて提供する最も低い API レベルを使用してください。ワークフローでその動作や機能が必要な場合に限り、現在の最大バージョンを使用してください。

作成ワークフロー

1. ロボットと API レベルを選択する

App のロボット詳細設定で、サポートされている API の最大バージョンを確認してください。references/api_reference.md を使って、必要な機能ごとに最小 API レベルを割り当ててください。

重要な対応バージョン：

• 2.20：CSV ランタイムパラメーター、液体有無検出、拡張された部分ノズル配置。
• 2.21：吸光度プレートリーダー。
• 2.22：現在のラボウェアレベルの液体ロードメソッド。
• 2.23：メニスカスの位置とラボウェアのふた。
• 2.24：液体クラスと液体クラスの複合コマンド。
• 2.25：Flex Stacker と Flex 96 チャンネル 200 µL ピペット。
• 2.27：動的ピペッティングとモジュールアクションの同時実行。
• 2.28：Flex 用 20 µL チップ、部分チップ返却の改善、サーモサイクラーのランプ速度。
• 2.29：ステップのグループ化。検証済みのベースラインでは Flex のみ。

2. デッキを明示的に構成する

• 公式 Labware Library にある正確なロード名を使用してください。
• Flex のトラッシュビンまたは廃液シュートを明示的にロードしてください。
• モジュールの占有領域、ステージングスロット、スタッカーのシャトル、グリッパーの経路、高さのあるラボウェアの隣接配置を考慮してください。
• ドキュメントに記載された順序で、アダプターまたはモジュールのコンテキストにラボウェアをロードしてください。
• 名前が似ているラボウェア定義で代用しないでください。形状とオフセットはプロトコルの安全モデルの一部です。

references/modules_and_deck.md を参照してください。

3. ピペットとチップを選択する

現在のロード名は次のとおりです。

• Flex：flex_1channel_50、flex_1channel_1000、 flex_8channel_50、flex_8channel_1000、 flex_96channel_200、flex_96channel_1000。
• OT-2 GEN2：p20_single_gen2、p20_multi_gen2、 p300_single_gen2、p300_multi_gen2、p1000_single_gen2。

指定するすべての容量が、設定したピペットとチップの範囲内にあることを確認してください。100 nL の操作は、Opentrons のピペッティング作業には適しません。

4. 液体ハンドリング層を選択する

• 明示的に制御するには、aspirate()、dispense()、mix()、air_gap()、blow_out()、touch_tip() を使用してください。
• 標準的な移送には、transfer()、distribute()、consolidate() を使用してください。
• Flex では、Opentrons が検証した水溶性、揮発性、または粘性のある液体の動作に、transfer_with_liquid_class()、distribute_with_liquid_class()、または consolidate_with_liquid_class() の使用を検討してください。
• API 2.27 以降で、形状を確認済みの場合に限り、動的な開始／終了位置や dynamic_mix() を使用してください。

チップの使用を最適化する前に、汚染境界をモデル化してください。消耗品を減らすために、無関係なサンプル間でチップを再利用しないでください。references/liquid_handling.md を参照してください。

5. セットアップ情報とランタイム制御を追加する

define_liquid() とラボウェアレベルの load_liquid() または load_liquid_by_well() を使用して、セットアップの可視化を改善してください。新しい API 2.22 以降のプロトコルでは、非推奨の Well.load_liquid() を使用しないでください。

オペレーターが制御する値は add_parameters() で定義し、protocol.params から読み取ってください。範囲を検証し、安全で意味のあるシミュレーションができるデフォルト値を使用してください。CSV パラメーターにデフォルト値はなく、1 回の実行で選択できる CSV パラメーターは 1 つだけです。

6. リソースを見積もる

シミュレーションの前に、次の項目を計算してください。

• すべての分岐で必要となるチップまたはチップセット。
• ソース量 ＝ 分注量 ＋ 混合による損失 ＋ 廃棄量 ＋ デッドボリューム ＋ 妥当な予備量。
• 添加および混合のたびにおける、デスティネーションの最大容量。
• モジュール、アダプター、トラッシュ、ステージング位置の数。
• 同時実行タスクを含む、インキュベーションとモジュールの所要時間。

7. 段階的に検証する

1. コンパイルします：python -m py_compile protocol.py。
2. 固定したパッケージを使用してシミュレーションします。
3. 実行ログでコマンド数、チップの交換、停止、予期しない位置を確認します。
4. 適切なアプリにインポートし、解析が正常に完了することを確認します。
5. プロトコルの可視化、ランタイムパラメーターのデフォルト値、デッキマップ、モジュールのセットアップ、ラボウェアのオフセットを確認します。
6. 初回使用前に、オペレーターがレビューしたドライランを実施します。

references/validation_and_operations.mdを参照してください。

よくある失敗例

• p300_single_flexなどの古い名前を使用する。現在のflex_*ロード名を使用してください。
• metadataとrequirementsの両方でapiLevelを宣言する。
• OT-2でAPI 2.29を使用する。
• Flexのゴミ箱または廃液シュートを忘れる。
• FlexでMagnetic Moduleをロードする。対応するFlex用磁気ハードウェアを使用してください。
• プレートリーダーでread(wavelengths=...)を呼び出す。まずinitialize()を呼び出し、その後read()を呼び出してください。
• ラボウェアレベルのメソッドではなく、非推奨のWell.load_liquid()を使用する。
• シミュレーションでキャリブレーション、液面の高さ、または物理的なクリアランスを検証できると思い込む。
• 部分ノズルのピペットに安全でないウェルを渡す。チップがラボウェアの外に配置され、クラッシュするおそれがあります。
• 汚染要件が異なるサンプル間でnew_tip="once"を使用する。

同梱テンプレート

ファイル	用途
scripts/basic_protocol_template.py	現行の名前を使用した、Flex 2.29用の最小限の分注
scripts/ot2_basic_protocol_template.py	OT-2 2.28用の最小限の分注
scripts/serial_dilution_template.py	8チャンネルFlexピペットを使用した、プレート全体の1:2希釈
scripts/pcr_setup_template.py	FlexのPCRセットアップとサーモサイクラーによるサイクリング
scripts/runtime_parameters_template.py	安全な数値およびブール値のランタイムパラメーター
scripts/absorbance_reader_template.py	Flexプレートリーダーの正しい初期化と読み取りのワークフロー

テンプレートは出発点であり、検証済みのアッセイではありません。ハードウェアとの互換性とウェットラボの手法を確認してから、容量、ラボウェア、液体、タイミング、チップのポリシーを変更してください。

リファレンスガイド

リファレンス	用途
references/api_reference.md	現行のロード名、バージョン要件、高価値メソッドの確認
references/protocol_authoring.md	要件、ラボウェア、ランタイムパラメーター、設計ワークフローの確認
references/liquid_handling.md	コマンド選択、液体クラス、液面検知、部分チップの確認
references/modules_and_deck.md	モジュール互換性、デッキ用フィクスチャー、グリッパー、Stackerの確認
references/validation_and_operations.md	シミュレーション、アプリでの解析、ドライラン、トラブルシューティングの確認
references/migration-api-2-19-to-2-29.md	古いプロトコルと、このスキルの以前のパターンの更新
references/sources.md	公式ドキュメントとリリース情報の参照

関連スキル

• pylabrobot：PyLabRobotのラボ自動化リソース、液体処理計画、オフラインシミュレーション、対応デバイスの連携を開発し、レビューします。
• protocolsio-integration：文書化されたREST v3/v4エンドポイントと公式MCPエンドポイントを使用してprotocols.ioのデータを読み取り、検証、エクスポートし、非exe…を構築します。