Opentrons Integration

Opentrons集成

Overview

概述

Opentrons is a Python-based lab automation platform for Flex and OT-2 robots. Write Protocol API v2 protocols for liquid handling, control hardware modules (heater-shaker, thermocycler), manage labware, for automated pipetting workflows.

Opentrons是基于Python的Flex和OT-2机器人实验室自动化平台。编写Protocol API v2协议以实现液体操作、控制硬件模块（摇床加热器、热循环仪）、管理实验器皿，构建自动化移液工作流。

When to Use This Skill

何时使用该技能

This skill should be used when:

Writing Opentrons Protocol API v2 protocols in Python
Automating liquid handling workflows on Flex or OT-2 robots
Controlling hardware modules (temperature, magnetic, heater-shaker, thermocycler)
Setting up labware configurations and deck layouts
Implementing complex pipetting operations (serial dilutions, plate replication, PCR setup)
Managing tip usage and optimizing protocol efficiency
Working with multi-channel pipettes for 96-well plate operations
Simulating and testing protocols before robot execution

当您需要以下操作时，应使用本技能：

使用Python编写Opentrons Protocol API v2协议
在Flex或OT-2机器人上自动化液体处理工作流
控制硬件模块（温度、磁力、摇床加热器、热循环仪）
设置实验器皿配置和工作台布局
实现复杂移液操作（系列稀释、平板复制、PCR配置）
管理吸头使用并优化协议效率
使用多通道移液器进行96孔板操作
在机器人执行前模拟和测试协议

Core Capabilities

核心功能

1. Protocol Structure and Metadata

1. 协议结构与元数据

Every Opentrons protocol follows a standard structure:

python

from opentrons import protocol_api

每个Opentrons协议都遵循标准结构：

python

from opentrons import protocol_api

Metadata

metadata = { 'protocolName': 'My Protocol', 'author': 'Name email@example.com', 'description': 'Protocol description', 'apiLevel': '2.19' # Use latest available API version }

Requirements (optional)

requirements = { 'robotType': 'Flex', # or 'OT-2' 'apiLevel': '2.19' }

Run function

def run(protocol: protocol_api.ProtocolContext): # Protocol commands go here pass


**Key elements:**
- Import `protocol_api` from `opentrons`
- Define `metadata` dict with protocolName, author, description, apiLevel
- Optional `requirements` dict for robot type and API version
- Implement `run()` function receiving `ProtocolContext` as parameter
- All protocol logic goes inside the `run()` function

def run(protocol: protocol_api.ProtocolContext): # Protocol commands go here pass


**关键元素：**
- 从`opentrons`导入`protocol_api`
- 定义包含protocolName、author、description、apiLevel的`metadata`字典
- 可选的`requirements`字典，用于指定机器人类型和API版本
- 实现接收`ProtocolContext`作为参数的`run()`函数
- 所有协议逻辑都在`run()`函数内实现

2. Loading Hardware

2. 加载硬件

Loading Instruments (Pipettes):

python

def run(protocol: protocol_api.ProtocolContext):
    # Load pipette on specific mount
    left_pipette = protocol.load_instrument(
        'p1000_single_flex',  # Instrument name
        'left',               # Mount: 'left' or 'right'
        tip_racks=[tip_rack]  # List of tip rack labware objects
    )

Common pipette names:

Flex:

p50_single_flex

,

p1000_single_flex

,

p50_multi_flex

,

p1000_multi_flex

OT-2:

p20_single_gen2

,

p300_single_gen2

,

p1000_single_gen2

,

p20_multi_gen2

,

p300_multi_gen2

Loading Labware:

python

undefined

加载移液器：

python

def run(protocol: protocol_api.ProtocolContext):
    # Load pipette on specific mount
    left_pipette = protocol.load_instrument(
        'p1000_single_flex',  # Instrument name
        'left',               # Mount: 'left' or 'right'
        tip_racks=[tip_rack]  # List of tip rack labware objects
    )

常见移液器名称：

Flex:

p50_single_flex

,

p1000_single_flex

,

p50_multi_flex

,

p1000_multi_flex

OT-2:

p20_single_gen2

,

p300_single_gen2

,

p1000_single_gen2

,

p20_multi_gen2

,

p300_multi_gen2

加载实验器皿：

python

undefined

Load labware directly on deck

plate = protocol.load_labware( 'corning_96_wellplate_360ul_flat', # Labware API name 'D1', # Deck slot (Flex: A1-D3, OT-2: 1-11) label='Sample Plate' # Optional display label )

Load tip rack

tip_rack = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')

Load labware on adapter

adapter = protocol.load_adapter('opentrons_flex_96_tiprack_adapter', 'B1') tips = adapter.load_labware('opentrons_flex_96_tiprack_200ul')


**Loading Modules:**

```python

adapter = protocol.load_adapter('opentrons_flex_96_tiprack_adapter', 'B1') tips = adapter.load_labware('opentrons_flex_96_tiprack_200ul')


**加载模块：**

```python

Temperature module

temp_module = protocol.load_module('temperature module gen2', 'D3') temp_plate = temp_module.load_labware('corning_96_wellplate_360ul_flat')

Magnetic module

mag_module = protocol.load_module('magnetic module gen2', 'C2') mag_plate = mag_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

Heater-Shaker module

hs_module = protocol.load_module('heaterShakerModuleV1', 'D1') hs_plate = hs_module.load_labware('corning_96_wellplate_360ul_flat')

Thermocycler module (takes up specific slots automatically)

tc_module = protocol.load_module('thermocyclerModuleV2') tc_plate = tc_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

undefined

tc_module = protocol.load_module('thermocyclerModuleV2') tc_plate = tc_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

undefined

3. Liquid Handling Operations

3. 液体操作

Basic Operations:

python

undefined

基础操作：

python

undefined

Pick up tip

pipette.pick_up_tip()

Aspirate (draw liquid in)

pipette.aspirate( volume=100, # Volume in µL location=source['A1'] # Well or location object )

Dispense (expel liquid)

pipette.dispense( volume=100, location=dest['B1'] )

Drop tip

pipette.drop_tip()

Return tip to rack

pipette.return_tip()


**Complex Operations:**

```python

pipette.return_tip()


**复杂操作：**

```python

Transfer (combines pick_up, aspirate, dispense, drop_tip)

pipette.transfer( volume=100, source=source_plate['A1'], dest=dest_plate['B1'], new_tip='always' # 'always', 'once', or 'never' )

Distribute (one source to multiple destinations)

pipette.distribute( volume=50, source=reservoir['A1'], dest=[plate['A1'], plate['A2'], plate['A3']], new_tip='once' )

Consolidate (multiple sources to one destination)

pipette.consolidate( volume=50, source=[plate['A1'], plate['A2'], plate['A3']], dest=reservoir['A1'], new_tip='once' )


**Advanced Techniques:**

```python

pipette.consolidate( volume=50, source=[plate['A1'], plate['A2'], plate['A3']], dest=reservoir['A1'], new_tip='once' )


**高级技巧：**

```python

Mix (aspirate and dispense in same location)

pipette.mix( repetitions=3, volume=50, location=plate['A1'] )

Air gap (prevent dripping)

pipette.aspirate(100, source['A1']) pipette.air_gap(20) # 20µL air gap pipette.dispense(120, dest['A1'])

Blow out (expel remaining liquid)

pipette.blow_out(location=dest['A1'].top())

Touch tip (remove droplets on tip exterior)

pipette.touch_tip(location=plate['A1'])


**Flow Rate Control:**

```python

pipette.touch_tip(location=plate['A1'])


**流速控制：**

```python

Set flow rates (µL/s)

pipette.flow_rate.aspirate = 150 pipette.flow_rate.dispense = 300 pipette.flow_rate.blow_out = 400

undefined

pipette.flow_rate.aspirate = 150 pipette.flow_rate.dispense = 300 pipette.flow_rate.blow_out = 400

undefined

4. Accessing Wells and Locations

4. 访问孔位与位置

Well Access Methods:

python

undefined

孔位访问方法：

python

undefined

By name

well_a1 = plate['A1']

By index

first_well = plate.wells()[0]

All wells

all_wells = plate.wells() # Returns list

By rows

rows = plate.rows() # Returns list of lists row_a = plate.rows()[0] # All wells in row A

By columns

columns = plate.columns() # Returns list of lists column_1 = plate.columns()[0] # All wells in column 1

Wells by name (dictionary)

wells_dict = plate.wells_by_name() # {'A1': Well, 'A2': Well, ...}


**Location Methods:**

```python

wells_dict = plate.wells_by_name() # {'A1': Well, 'A2': Well, ...}


**位置方法：**

```python

Top of well (default: 1mm below top)

pipette.aspirate(100, well.top()) pipette.aspirate(100, well.top(z=5)) # 5mm above top

Bottom of well (default: 1mm above bottom)

pipette.aspirate(100, well.bottom()) pipette.aspirate(100, well.bottom(z=2)) # 2mm above bottom

Center of well

pipette.aspirate(100, well.center())

undefined

pipette.aspirate(100, well.center())

undefined

5. Hardware Module Control

5. 硬件模块控制

Temperature Module:

python

undefined

温度模块：

python

undefined

Set temperature

temp_module.set_temperature(celsius=4)

Wait for temperature

temp_module.await_temperature(celsius=4)

Deactivate

temp_module.deactivate()

Check status

current_temp = temp_module.temperature # Current temperature target_temp = temp_module.target # Target temperature


**Magnetic Module:**

```python

current_temp = temp_module.temperature # Current temperature target_temp = temp_module.target # Target temperature


**磁力模块：**

```python

Engage (raise magnets)

mag_module.engage(height_from_base=10) # mm from labware base

Disengage (lower magnets)

mag_module.disengage()

Check status

is_engaged = mag_module.status # 'engaged' or 'disengaged'


**Heater-Shaker Module:**

```python

is_engaged = mag_module.status # 'engaged' or 'disengaged'


**摇床加热器模块：**

```python

Set temperature

hs_module.set_target_temperature(celsius=37)

Wait for temperature

hs_module.wait_for_temperature()

Set shake speed

hs_module.set_and_wait_for_shake_speed(rpm=500)

Close labware latch

hs_module.close_labware_latch()

Open labware latch

hs_module.open_labware_latch()

Deactivate heater

hs_module.deactivate_heater()

Deactivate shaker

hs_module.deactivate_shaker()


**Thermocycler Module:**

```python

hs_module.deactivate_shaker()


**热循环仪模块：**

```python

Open lid

tc_module.open_lid()

Close lid

tc_module.close_lid()

Set lid temperature

tc_module.set_lid_temperature(celsius=105)

Set block temperature

tc_module.set_block_temperature( temperature=95, hold_time_seconds=30, hold_time_minutes=0.5, block_max_volume=50 # µL per well )

Execute profile (PCR cycling)

profile = [ {'temperature': 95, 'hold_time_seconds': 30}, {'temperature': 57, 'hold_time_seconds': 30}, {'temperature': 72, 'hold_time_seconds': 60} ] tc_module.execute_profile( steps=profile, repetitions=30, block_max_volume=50 )

Deactivate

tc_module.deactivate_lid() tc_module.deactivate_block()


**Absorbance Plate Reader:**

```python

tc_module.deactivate_lid() tc_module.deactivate_block()


**吸光度酶标仪：**

```python

Initialize and read

result = plate_reader.read(wavelengths=[450, 650])

Access readings

absorbance_data = result # Dict with wavelength keys

undefined

absorbance_data = result # Dict with wavelength keys

undefined

6. Liquid Tracking and Labeling

6. 液体追踪与标记

Define Liquids:

python

undefined

定义液体：

python

undefined

Define liquid types

water = protocol.define_liquid( name='Water', description='Ultrapure water', display_color='#0000FF' # Hex color code )

sample = protocol.define_liquid( name='Sample', description='Cell lysate sample', display_color='#FF0000' )


**Load Liquids into Wells:**

```python

water = protocol.define_liquid( name='Water', description='Ultrapure water', display_color='#0000FF' # Hex color code )

sample = protocol.define_liquid( name='Sample', description='Cell lysate sample', display_color='#FF0000' )


**向孔位加载液体：**

```python

Load liquid into specific wells

reservoir['A1'].load_liquid(liquid=water, volume=50000) # µL plate['A1'].load_liquid(liquid=sample, volume=100)

Mark wells as empty

plate['B1'].load_empty()

undefined

plate['B1'].load_empty()

undefined

7. Protocol Control and Utilities

7. 协议控制与工具

Execution Control:

python

undefined

执行控制：

python

undefined

Pause protocol

protocol.pause(msg='Replace tip box and resume')

Delay

protocol.delay(seconds=60) protocol.delay(minutes=5)

Comment (appears in logs)

protocol.comment('Starting serial dilution')

Home robot

protocol.home()


**Conditional Logic:**

```python

protocol.home()


**条件逻辑：**

```python

Check if simulating

if protocol.is_simulating(): protocol.comment('Running in simulation mode') else: protocol.comment('Running on actual robot')


**Rail Lights (Flex only):**

```python

if protocol.is_simulating(): protocol.comment('Running in simulation mode') else: protocol.comment('Running on actual robot')


**导轨灯光（仅Flex支持）：**

```python

Turn lights on

protocol.set_rail_lights(on=True)

Turn lights off

protocol.set_rail_lights(on=False)

undefined

protocol.set_rail_lights(on=False)

undefined

8. Multi-Channel and 8-Channel Pipetting

8. 多通道与8通道移液

When using multi-channel pipettes:

python

undefined

使用多通道移液器时：

python

undefined

Load 8-channel pipette

multi_pipette = protocol.load_instrument( 'p300_multi_gen2', 'left', tip_racks=[tips] )

Access entire column with single well reference

multi_pipette.transfer( volume=100, source=source_plate['A1'], # Accesses entire column 1 dest=dest_plate['A1'] # Dispenses to entire column 1 )

Use rows() for row-wise operations

for row in plate.rows(): multi_pipette.transfer(100, reservoir['A1'], row[0])

undefined

for row in plate.rows(): multi_pipette.transfer(100, reservoir['A1'], row[0])

undefined

9. Common Protocol Patterns

9. 常见协议模式

Serial Dilution:

python

def run(protocol: protocol_api.ProtocolContext):
    # Load labware
    tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'D1')
    reservoir = protocol.load_labware('nest_12_reservoir_15ml', 'D2')
    plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D3')

    # Load pipette
    p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])

    # Add diluent to all wells except first
    p300.transfer(100, reservoir['A1'], plate.rows()[0][1:])

    # Serial dilution across row
    p300.transfer(
        100,
        plate.rows()[0][:11],  # Source: wells 0-10
        plate.rows()[0][1:],   # Dest: wells 1-11
        mix_after=(3, 50),     # Mix 3x with 50µL after dispense
        new_tip='always'
    )

Plate Replication:

python

def run(protocol: protocol_api.ProtocolContext):
    # Load labware
    tips = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')
    source = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D1')
    dest = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D2')

    # Load pipette
    p1000 = protocol.load_instrument('p1000_single_flex', 'left', tip_racks=[tips])

    # Transfer from all wells in source to dest
    p1000.transfer(
        100,
        source.wells(),
        dest.wells(),
        new_tip='always'
    )

PCR Setup:

python

def run(protocol: protocol_api.ProtocolContext):
    # Load thermocycler
    tc_mod = protocol.load_module('thermocyclerModuleV2')
    tc_plate = tc_mod.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

    # Load tips and reagents
    tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'C1')
    reagents = protocol.load_labware('opentrons_24_tuberack_nest_1.5ml_snapcap', 'D1')

    # Load pipette
    p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])

    # Open thermocycler lid
    tc_mod.open_lid()

    # Distribute master mix
    p300.distribute(
        20,
        reagents['A1'],
        tc_plate.wells(),
        new_tip='once'
    )

    # Add samples (example for first 8 wells)
    for i, well in enumerate(tc_plate.wells()[:8]):
        p300.transfer(5, reagents.wells()[i+1], well, new_tip='always')

    # Run PCR
    tc_mod.close_lid()
    tc_mod.set_lid_temperature(105)

    # PCR profile
    tc_mod.set_block_temperature(95, hold_time_seconds=180)

    profile = [
        {'temperature': 95, 'hold_time_seconds': 15},
        {'temperature': 60, 'hold_time_seconds': 30},
        {'temperature': 72, 'hold_time_seconds': 30}
    ]
    tc_mod.execute_profile(steps=profile, repetitions=35, block_max_volume=25)

    tc_mod.set_block_temperature(72, hold_time_minutes=5)
    tc_mod.set_block_temperature(4)

    tc_mod.deactivate_lid()
    tc_mod.open_lid()

系列稀释：

python

def run(protocol: protocol_api.ProtocolContext):
    # Load labware
    tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'D1')
    reservoir = protocol.load_labware('nest_12_reservoir_15ml', 'D2')
    plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D3')

    # Load pipette
    p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])

    # Add diluent to all wells except first
    p300.transfer(100, reservoir['A1'], plate.rows()[0][1:])

    # Serial dilution across row
    p300.transfer(
        100,
        plate.rows()[0][:11],  # Source: wells 0-10
        plate.rows()[0][1:],   # Dest: wells 1-11
        mix_after=(3, 50),     # Mix 3x with 50µL after dispense
        new_tip='always'
    )

平板复制：

python

def run(protocol: protocol_api.ProtocolContext):
    # Load labware
    tips = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')
    source = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D1')
    dest = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D2')

    # Load pipette
    p1000 = protocol.load_instrument('p1000_single_flex', 'left', tip_racks=[tips])

    # Transfer from all wells in source to dest
    p1000.transfer(
        100,
        source.wells(),
        dest.wells(),
        new_tip='always'
    )

PCR配置：

python

def run(protocol: protocol_api.ProtocolContext):
    # Load thermocycler
    tc_mod = protocol.load_module('thermocyclerModuleV2')
    tc_plate = tc_mod.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

    # Load tips and reagents
    tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'C1')
    reagents = protocol.load_labware('opentrons_24_tuberack_nest_1.5ml_snapcap', 'D1')

    # Load pipette
    p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])

    # Open thermocycler lid
    tc_mod.open_lid()

    # Distribute master mix
    p300.distribute(
        20,
        reagents['A1'],
        tc_plate.wells(),
        new_tip='once'
    )

    # Add samples (example for first 8 wells)
    for i, well in enumerate(tc_plate.wells()[:8]):
        p300.transfer(5, reagents.wells()[i+1], well, new_tip='always')

    # Run PCR
    tc_mod.close_lid()
    tc_mod.set_lid_temperature(105)

    # PCR profile
    tc_mod.set_block_temperature(95, hold_time_seconds=180)

    profile = [
        {'temperature': 95, 'hold_time_seconds': 15},
        {'temperature': 60, 'hold_time_seconds': 30},
        {'temperature': 72, 'hold_time_seconds': 30}
    ]
    tc_mod.execute_profile(steps=profile, repetitions=35, block_max_volume=25)

    tc_mod.set_block_temperature(72, hold_time_minutes=5)
    tc_mod.set_block_temperature(4)

    tc_mod.deactivate_lid()
    tc_mod.open_lid()

Best Practices

最佳实践

Always specify API level: Use the latest stable API version in metadata
Use meaningful labels: Label labware for easier identification in logs
Check tip availability: Ensure sufficient tips for protocol completion
Add comments: Use
```
protocol.comment()
```
for debugging and logging
Simulate first: Always test protocols in simulation before running on robot
Handle errors gracefully: Add pauses for manual intervention when needed
Consider timing: Use delays when protocols require incubation periods
Track liquids: Use liquid tracking for better setup validation
Optimize tip usage: Use
```
new_tip='once'
```
when appropriate to save tips
Control flow rates: Adjust flow rates for viscous or volatile liquids

始终指定API版本：在元数据中使用最新稳定的API版本
使用有意义的标签：为实验器皿添加标签，便于在日志中识别
检查吸头可用性：确保有足够的吸头完成协议
添加注释：使用
```
protocol.comment()
```
进行调试和日志记录
先模拟：在机器人上运行前，始终先在模拟环境中测试协议
优雅处理错误：必要时添加暂停以进行人工干预
考虑时序：当协议需要孵育时间时，使用延迟
追踪液体：使用液体追踪功能优化设置验证
优化吸头使用：适当使用
```
new_tip='once'
```
以节省吸头
控制流速：针对粘性或挥发性液体调整流速

Troubleshooting

故障排除

Common Issues:

Out of tips: Verify tip rack capacity matches protocol requirements
Labware collisions: Check deck layout for spatial conflicts
Volume errors: Ensure volumes don't exceed well or pipette capacities
Module not responding: Verify module is properly connected and firmware is updated
Inaccurate volumes: Calibrate pipettes and check for air bubbles
Protocol fails in simulation: Check API version compatibility and labware definitions

常见问题：

吸头耗尽：验证吸头架容量是否符合协议要求
实验器皿碰撞：检查工作台布局是否存在空间冲突
体积错误：确保体积不超过孔位或移液器的容量
模块无响应：验证模块是否正确连接且固件已更新
体积不准确：校准移液器并检查是否有气泡
协议在模拟中失败：检查API版本兼容性和实验器皿定义

Resources

资源

For detailed API documentation, see

references/api_reference.md

in this skill directory.

For example protocol templates, see

scripts/

directory.

如需详细的API文档，请查看本技能目录中的

references/api_reference.md

。

如需示例协议模板，请查看

scripts/

目录。

opentrons-integration

Original

Translation

Opentrons Integration

Opentrons集成

Overview

概述

When to Use This Skill

何时使用该技能

Core Capabilities

核心功能

1. Protocol Structure and Metadata

1. 协议结构与元数据

Metadata

Metadata

Requirements (optional)

Requirements (optional)

Run function

Run function

2. Loading Hardware

2. 加载硬件

Load labware directly on deck

Load labware directly on deck

Load tip rack

Load tip rack

Load labware on adapter

Load labware on adapter

Temperature module

Temperature module

Magnetic module

Magnetic module

Heater-Shaker module

Heater-Shaker module

Thermocycler module (takes up specific slots automatically)

Thermocycler module (takes up specific slots automatically)

3. Liquid Handling Operations

3. 液体操作

Pick up tip

Pick up tip

Aspirate (draw liquid in)

Aspirate (draw liquid in)

Dispense (expel liquid)

Dispense (expel liquid)

Drop tip

Drop tip

Return tip to rack

Return tip to rack

Transfer (combines pick_up, aspirate, dispense, drop_tip)

Transfer (combines pick_up, aspirate, dispense, drop_tip)

Distribute (one source to multiple destinations)

Distribute (one source to multiple destinations)

Consolidate (multiple sources to one destination)

Consolidate (multiple sources to one destination)

Mix (aspirate and dispense in same location)

Mix (aspirate and dispense in same location)

Air gap (prevent dripping)

Air gap (prevent dripping)

Blow out (expel remaining liquid)

Blow out (expel remaining liquid)

Touch tip (remove droplets on tip exterior)

Touch tip (remove droplets on tip exterior)

Set flow rates (µL/s)

Set flow rates (µL/s)

4. Accessing Wells and Locations

4. 访问孔位与位置

By name

By name

By index

By index

All wells

All wells

By rows

By rows

By columns

By columns

Wells by name (dictionary)

Wells by name (dictionary)

Top of well (default: 1mm below top)

Top of well (default: 1mm below top)

Bottom of well (default: 1mm above bottom)