⚡

OpentronsPythonAPIv2自动化实验室协议开发Skill opentrons

这个技能提供使用Python API v2控制Opentrons液体处理机器人的全面指南，包括协议开发、硬件集成和自动化工作流。关键词：Opentrons, Python API, 液体处理, 实验室自动化, OT-2, Flex, 温度模块, 磁分离, 协议编程。

嵌入式软件 0 次安装 0 次浏览 更新于 3/12/2026

name: opentrons description: Opentrons Python API v2 的专家指导 - 自动化液体处理、协议开发、实验室管理以及OT-2和Flex机器人的硬件模块集成 allowed-tools: [“*”]

Opentrons Python API v2

概述

Opentrons Python API v2 通过Python协议控制液体处理机器人（OT-2和Flex）实现实验室自动化。编写协议以自动化移液、温度控制、磁分离、板读取和复杂多步骤工作流，具有可重复的精度。

核心价值： 将手动、易出错的移液工作流转化为自动化、可重复的协议。一个100行的协议可以用精确、文档化的液体处理替换数小时的手动工作。

何时使用

在以下情况下使用Opentrons技能：

  • 编写自动化液体处理协议
  • 设置系列稀释、板复制或试剂分配
  • 将温度控制、磁分离或板读取集成到工作流中
  • 适配OT-2协议用于Opentrons Flex
  • 故障排除协议执行或硬件集成
  • 优化移液参数（流速、吸头位置、混合）

可用专门子技能：

  • heater-shaker - 带轨道混合的温度控制
  • absorbance-reader - 微板分光光度法
  • gripper - 自动化实验室移动（仅Flex）
  • thermocycler - PCR热循环
  • temperature-module - 精确加热/冷却（4-95°C）
  • magnetic-block - 磁珠分离（仅Flex）

不使用时：

  • 使用非Opentrons液体处理器
  • 编写与实验室自动化无关的通用Python代码
  • 需要详细模块特定指导（使用专门子技能）

机器人平台

Opentrons Flex

现代平台，具有高级功能：

  • 抓取器用于自动化实验室移动
  • 96通道移液
  • 基于坐标的甲板插槽（A1-D3）
  • 更大的工作体积和甲板空间
  • 垃圾桶需要显式加载（API 2.16+）
  • 第4列的暂存区域插槽

OT-2

成熟平台：

  • 数字甲板插槽（1-12）
  • 固定垃圾桶在插槽12
  • 1通道和8通道吸头
  • 标准协议的可靠性能

两个平台使用相同的API语法，带有平台特定参数。

协议结构

每个Opentrons协议遵循此框架：

from opentrons import protocol_api

# 1. 元数据 - 协议标识
metadata = {
    'protocolName': '我的协议',
    'author': '姓名 <email@example.com>',
    'description': '简要描述此协议的功能',
    'apiLevel': '2.19'
}

# 2. 要求 - 机器人规范（Flex）
requirements = {"robotType": "Flex", "apiLevel": "2.19"}

# 3. 主函数 - 设置和命令
def run(protocol: protocol_api.ProtocolContext):
    # 设置：加载实验室、吸头、模块
    tips = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "A1")
    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "B1")
    pipette = protocol.load_instrument("flex_1channel_1000", "left", tip_racks=[tips])

    # 命令：顺序机器人指令
    pipette.pick_up_tip()
    pipette.aspirate(100, plate["A1"])
    pipette.dispense(100, plate["B1"])
    pipette.drop_tip()

关键原则：

  • 协议完全线性执行 - 逐行遵循以理解机器人动作
  • 使用描述性变量名称，反映实验室术语
  • 添加注释以记录工作流步骤
  • 逻辑分组相关操作

核心API组件

1. 加载设备

实验室 - 板、管、储液器：

# 从注册表加载标准实验室
plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "B1")
tips = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "A1")

# 加载自定义实验室（需要JSON定义）
custom = protocol.load_labware("custom_24_tuberack_1500ul", "C1")

吸头 - 单通道、8通道或96通道：

# Flex吸头
left_pip = protocol.load_instrument("flex_1channel_1000", "left", tip_racks=[tips])
right_pip = protocol.load_instrument("flex_8channel_1000", "right", tip_racks=[tips])

# OT-2吸头
p300 = protocol.load_instrument("p300_single_gen2", "left", tip_racks=[tips])

模块 - 温度、磁、热循环：

# 加载模块到特定甲板插槽
temp_mod = protocol.load_module("temperature module gen2", "D1")
# 在模块上加载实验室
temp_plate = temp_mod.load_labware("opentrons_96_aluminumblock_generic_pcr_strip_200ul")

垃圾桶（Flex, API 2.16+）：

trash = protocol.load_trash_bin("A3")

2. 访问孔

单个孔：

plate["A1"]           # 按名称的单孔
plate.wells()[0]      # 按索引的第一个孔
plate.wells_by_name()["A1"]  # 字典访问

孔范围和组：

plate.wells()[:8]     # 第一行（A1-H1）
plate.rows()[0]       # 行A中的所有孔
plate.columns()[0]    # 列1中的所有孔
plate.wells("A1", "H12")  # 从A1到H12的范围

8通道移液模式：

# 使用8通道移液到整个列
pipette.transfer(100, reservoir["A1"], plate.columns()[0])

3. 液体处理命令

基本操作：

pipette.pick_up_tip()
pipette.aspirate(volume=100, location=plate["A1"], rate=1.0)
pipette.dispense(volume=100, location=plate["B1"], rate=1.0)
pipette.blow_out(location=plate["B1"])
pipette.mix(repetitions=3, volume=50, location=plate["B1"])
pipette.drop_tip()  # 或 pipette.return_tip()

复杂转移：

# 单源到多目标
pipette.distribute(
    volume=50,
    source=reservoir["A1"],
    dest=[plate.wells()[i] for i in range(8)],
    new_tip="once"
)

# 多源到单目标（合并）
pipette.consolidate(
    volume=20,
    source=plate.rows()[0],
    dest=reservoir["A2"],
    new_tip="always"
)

# 一对一转移带混合
pipette.transfer(
    volume=100,
    source=plate.columns()[0],
    dest=plate.columns()[1],
    mix_after=(3, 50),
    new_tip="always"
)

4. 位置控制

孔位置：

# 孔顶部（默认：顶部下方1mm）
location = plate["A1"].top()
location = plate["A1"].top(z=-2)  # 顶部下方2mm

# 孔底部（默认：底部上方1mm）
location = plate["A1"].bottom()
location = plate["A1"].bottom(z=2)  # 底部上方2mm

# 孔中心
location = plate["A1"].center()

移动：

# 移动到位置，无液体操作
pipette.move_to(plate["A1"].top())

# 当前位置延迟
protocol.delay(seconds=5)
protocol.delay(minutes=2)

5. 吸头管理

灵活拾取策略：

# 从特定吸头架位置拾取
pipette.pick_up_tip(tips["A1"])

# 自动吸头跟踪
pipette.pick_up_tip()  # 使用下一个可用吸头

# 重置吸头跟踪
tips.reset()  # 标记所有吸头为再次可用

6. 液体跟踪

定义液体以更好协议文档：

# 定义试剂
water = protocol.define_liquid(
    name="水",
    description="分子生物学级H2O",
    display_color="#0000FF"
)

buffer = protocol.define_liquid(
    name="裂解缓冲液",
    description="10mM Tris-HCl pH 8.0",
    display_color="#00FF00"
)

# 分配液体到孔带体积
reservoir["A1"].load_liquid(liquid=water, volume=50000)  # 50mL
plate["A1"].load_liquid(liquid=buffer, volume=200)

7. 运行时参数

用户可配置变量：

def add_parameters(parameters):
    parameters.add_int(
        variable_name="sample_count",
        display_name="样品数量",
        description="要处理的样品数",
        default=24,
        minimum=1,
        maximum=96,
        unit="样品"
    )

    parameters.add_float(
        variable_name="transfer_volume",
        display_name="转移体积",
        default=50.0,
        minimum=10.0,
        maximum=200.0,
        unit="µL"
    )

def run(protocol: protocol_api.ProtocolContext):
    # 访问参数
    num_samples = protocol.params.sample_count
    vol = protocol.params.transfer_volume

硬件模块

Opentrons支持多个硬件模块用于专门工作流。每个模块有专用API方法：

温度模块

精确加热/冷却（4-95°C）：

temp_mod = protocol.load_module("temperature module gen2", "D1")
plate = temp_mod.load_labware("opentrons_96_aluminumblock_generic_pcr_strip_200ul")

temp_mod.set_temperature(celsius=4)  # 阻塞直到达到
temp_mod.deactivate()

使用 temperature-module 子技能 获取详细指导。

加热摇床模块

带轨道混合的温度控制：

hs_mod = protocol.load_module("heaterShakerModuleV1", "D1")
adapter = hs_mod.load_adapter("opentrons_96_flat_bottom_adapter")
plate = adapter.load_labware("nest_96_wellplate_200ul_flat")

hs_mod.close_labware_latch()
hs_mod.set_and_wait_for_temperature(37)
hs_mod.set_and_wait_for_shake_speed(500)  # rpm
protocol.delay(minutes=5)
hs_mod.deactivate_shaker()
hs_mod.deactivate_heater()
hs_mod.open_labware_latch()

使用 heater-shaker 子技能 获取详细指导，包括非阻塞温度控制、速度范围和OT-2甲板限制。

热循环模块

PCR热循环：

tc_mod = protocol.load_module("thermocyclerModuleV2")
plate = tc_mod.load_labware("opentrons_96_wellplate_200ul_pcr_full_skirt")

tc_mod.close_lid()
tc_mod.set_lid_temperature(105)
tc_mod.set_block_temperature(95, hold_time_seconds=180, block_max_volume=50)

# PCR配置文件
profile = [
    {"temperature": 95, "hold_time_seconds": 30},
    {"temperature": 57, "hold_time_seconds": 30},
    {"temperature": 72, "hold_time_seconds": 60}
]
tc_mod.execute_profile(steps=profile, repetitions=30, block_max_volume=50)
tc_mod.set_block_temperature(72, hold_time_minutes=5)

tc_mod.deactivate_lid()
tc_mod.deactivate_block()
tc_mod.open_lid()

使用 thermocycler 子技能 获取详细指导，包括自动密封盖和高级配置文件。

吸光度板读取器（仅Flex）

微板分光光度法：

reader = protocol.load_module("absorbanceReaderV1", "D3")

reader.close_lid()
reader.initialize("single", [450])  # 单波长
reader.open_lid()

# 使用抓取器移动板到读取器
protocol.move_labware(plate, reader, use_gripper=True)

reader.close_lid()
data = reader.read(export_filename="my_plate_data")
reader.open_lid()

# 访问结果
absorbance_a1 = data[450]["A1"]  # 孔A1在450nm处的OD

使用 absorbance-reader 子技能 获取详细指导，包括多波长读取和数据格式。

磁块（仅Flex）

磁珠分离：

mag_block = protocol.load_module("magneticBlockV1", "D1")
mag_plate = mag_block.load_labware("biorad_96_wellplate_200ul_pcr")

# 使用抓取器移动板到磁块
protocol.move_labware(mag_plate, mag_block, use_gripper=True)

# 等待磁珠分离
protocol.delay(minutes=3)

# 移液上清液（磁珠由磁铁固定）
pipette.transfer(100, mag_plate["A1"], waste["A1"])

# 移动板远离磁铁
protocol.move_labware(mag_plate, "C1", use_gripper=True)

使用 magnetic-block 子技能 获取详细指导。

Flex特定功能

抓取器

自动化实验室移动：

# 在位置间移动实验室
protocol.move_labware(
    labware=plate,
    new_location="C2",
    use_gripper=True
)

# 移动到模块
protocol.move_labware(plate, temp_mod, use_gripper=True)

# 丢弃在废物槽
protocol.move_labware(plate, protocol.load_waste_chute(), use_gripper=True)

# 带偏移调整移动
protocol.move_labware(
    plate,
    "D2",
    use_gripper=True,
    pick_up_offset={"x": 0, "y": 0, "z": 2},
    drop_offset={"x": 0, "y": 0, "z": 1}
)

重要： 在抓取器移动前打开模块盖/闩锁（例如 tc_mod.open_lid(), hs_mod.open_labware_latch()）。

使用 gripper 子技能 获取详细指导。

96通道移液

单操作中全板转移：

pipette_96 = protocol.load_instrument("flex_96channel_1000", "left")

# 拾取整个吸头架
pipette_96.pick_up_tip()

# 转移整个板
pipette_96.transfer(100, source_plate.wells(), dest_plate.wells())

pipette_96.drop_tip()

暂存区域插槽

第4列插槽（A4, B4, C4, D4）用作暂存区域用于：

  • 吸光度读取器盖存储
  • 临时实验室放置
  • 抓取器操作

注意： 当吸光度读取器存在时，不能在列4加载实验室。

适配OT-2协议为Flex

需要的关键更改：

  1. 更新要求：
requirements = {"robotType": "Flex", "apiLevel": "2.19"}
  1. 更新吸头模型：
# OT-2
p300 = protocol.load_instrument("p300_single_gen2", "left")

# Flex
p1000 = protocol.load_instrument("flex_1channel_1000", "left")
  1. 更新吸头架：
# OT-2
tips = protocol.load_labware("opentrons_96_tiprack_300ul", "1")

# Flex
tips = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "A1")
  1. 加载垃圾桶（API 2.16+）：
trash = protocol.load_trash_bin("A3")
  1. 更新甲板插槽（可选 - 两种格式都工作）：
# 数字（OT-2样式，两者工作）
plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "1")

# 坐标（Flex样式，两者工作）
plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "D1")

常见模式

系列稀释

def serial_dilution(pipette, source, destinations, dilution_factor, volume):
    """在孔间执行系列稀释。"""
    # 从源到第一个目标转移
    pipette.transfer(volume, source, destinations[0])

    # 带混合的系列转移
    for i in range(len(destinations) - 1):
        pipette.transfer(
            volume / dilution_factor,
            destinations[i],
            destinations[i + 1],
            mix_after=(3, volume / 2)
        )

# 使用模式
serial_dilution(
    pipette=p1000,
    source=reservoir["A1"],
    destinations=plate.rows()[0],  # 行A
    dilution_factor=2,
    volume=100
)

板复制

# 复制整个板
pipette.transfer(
    volume=50,
    source=source_plate.wells(),
    dest=dest_plate.wells(),
    new_tip="always"
)

选点

# 转移特定孔
source_wells = [source_plate["A1"], source_plate["C3"], source_plate["E5"]]
dest_wells = [dest_plate["B2"], dest_plate["D4"], dest_plate["F6"]]

pipette.transfer(100, source_wells, dest_wells, new_tip="always")

试剂分配

# 从储液器分配到板
pipette.distribute(
    volume=50,
    source=reservoir["A1"],
    dest=plate.wells(),
    disposal_volume=10,  # 吹出的额外体积
    new_tip="once"
)

最佳实践

  1. 使用液体跟踪 - 定义和加载液体以更好协议文档
  2. 添加运行时参数 - 无需编辑代码使协议可配置
  3. 优化吸头使用 - 使用 distribute/consolidate 以最小化吸头消耗
  4. 设置适当流速 - 调整粘稠或挥发性液体
  5. 包括延迟 - 允许混合、沉降或温度平衡时间
  6. 停用模块 - 在协议结束时关闭加热器/摇床/冷却器
  7. 用模拟测试 - 在硬件上运行前验证协议
  8. 彻底文档化 - 使用注释、元数据和液体定义
  9. 优雅处理错误 - 添加暂停以用户干预
  10. 校准实验室偏移 - 确保您的特定实验室的准确定位

高级功能

条件逻辑

# 基于参数的动态协议行为
if protocol.params.include_control:
    pipette.transfer(100, control_buffer, plate["A1"])

# 仅处理占用孔
for well in plate.wells():
    if well.has_liquid():
        pipette.mix(3, 100, well)

空气间隙

防止孔间滴漏：

pipette.aspirate(100, source_well)
pipette.air_gap(10)  # 10µL空气间隙
pipette.dispense(110, dest_well)

触吸

移除吸头外部液滴：

pipette.aspirate(100, source_well)
pipette.touch_tip(location=source_well, radius=0.8, v_offset=-2)
pipette.dispense(100, dest_well)

吹出

确保完全分配：

pipette.aspirate(100, source_well)
pipette.dispense(100, dest_well)
pipette.blow_out(dest_well.top())

常见错误

❌ 忘记拾取吸头：

pipette.aspirate(100, plate["A1"])  # 错误：无吸头附着

✅ 正确：

pipette.pick_up_tip()
pipette.aspirate(100, plate["A1"])

❌ 不停用模块：

temp_mod.set_temperature(4)
# 协议结束 - 模块保持在4°C！

✅ 正确：

temp_mod.set_temperature(4)
# ... 操作 ...
temp_mod.deactivate()

❌ 抓取器移动时闩锁关闭：

protocol.move_labware(plate, hs_mod, use_gripper=True)  # 错误：闩锁关闭

✅ 正确：

hs_mod.open_labware_latch()
protocol.move_labware(plate, hs_mod, use_gripper=True)
hs_mod.close_labware_latch()

❌ Flex的甲板插槽格式错误： 使用无引号的数字插槽可能引起混淆；两种都工作，但坐标格式更清晰：

plate = protocol.load_labware("corning_96_wellplate_360ul_flat", 1)  # 工作但不清晰

✅ 正确：

plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "D1")  # 清晰

故障排除

协议无法加载：

  • 检查要求中的API版本是否匹配您的机器人固件
  • 验证实验室名称正确（检查Opentrons实验室库）
  • 确保模块加载指定了机器人有效甲板插槽

移液错误：

  • 验证吸头架正确加载且有可用吸头
  • 检查体积在吸头范围内
  • 确保源/目标孔有足够体积/空间

模块错误：

  • 抓取器移动前打开盖/闩锁
  • 允许模块达到目标温度前继续
  • 验证模块加载在兼容甲板插槽

抓取器错误：

  • 确保实验室可抓取（有兼容几何）
  • 检查目标可访问且未占用
  • 验证 use_gripper=True 设置

安装

协议通过Opentrons App在Opentrons机器人上运行。对于协议开发和模拟：

pip install opentrons

模拟：

opentrons_simulate protocol.py

附加资源

相关子技能

对于详细模块特定指导：

  • heater-shaker - 加热摇床模块
  • absorbance-reader - 吸光度板读取器
  • gripper - Flex抓取器
  • thermocycler - 热循环模块
  • temperature-module - 温度模块
  • magnetic-block - 磁块