gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/opentrons-integration/references/api_reference.md

Opentrons Python Protocol API v2 Reference

Protocol Context Methods

Labware Management

Method	Description	Returns
load_labware(name, location, label=None, namespace=None, version=None)	Load labware onto deck	Labware object
load_adapter(name, location, namespace=None, version=None)	Load adapter onto deck	Labware object
load_labware_from_definition(definition, location, label=None)	Load custom labware from JSON	Labware object
load_labware_on_adapter(name, adapter, label=None)	Load labware on adapter	Labware object
load_labware_by_name(name, location, label=None, namespace=None, version=None)	Alternative load method	Labware object
load_lid_stack(load_name, location, quantity=None)	Load lid stack (Flex only)	Labware object

Instrument Management

Method	Description	Returns
load_instrument(instrument_name, mount, tip_racks=None, replace=False)	Load pipette	InstrumentContext

Module Management

Method	Description	Returns
load_module(module_name, location=None, configuration=None)	Load hardware module	ModuleContext

Liquid Management

Method	Description	Returns
define_liquid(name, description=None, display_color=None)	Define liquid type	Liquid object

Execution Control

Method	Description	Returns
pause(msg=None)	Pause protocol execution	None
resume()	Resume after pause	None
delay(seconds=0, minutes=0, msg=None)	Delay execution	None
comment(msg)	Add comment to protocol log	None
home()	Home all axes	None
set_rail_lights(on)	Control rail lights (Flex only)	None

Protocol Properties

Property	Description	Type
deck	Deck layout	Deck object
fixed_trash	Fixed trash location (OT-2)	TrashBin object
loaded_labwares	Dictionary of loaded labware	Dict
loaded_instruments	Dictionary of loaded instruments	Dict
loaded_modules	Dictionary of loaded modules	Dict
is_simulating()	Check if protocol is simulating	Bool
bundled_data	Access to bundled data files	Dict
params	Runtime parameters	ParametersContext

Instrument Context (Pipette) Methods

Tip Management

Method	Description	Returns
pick_up_tip(location=None, presses=None, increment=None)	Pick up tip	InstrumentContext
drop_tip(location=None, home_after=True)	Drop tip in trash	InstrumentContext
return_tip(home_after=True)	Return tip to rack	InstrumentContext
reset_tipracks()	Reset tip tracking	None

Liquid Handling - Basic

Method	Description	Returns
aspirate(volume=None, location=None, rate=1.0)	Aspirate liquid	InstrumentContext
dispense(volume=None, location=None, rate=1.0, push_out=None)	Dispense liquid	InstrumentContext
blow_out(location=None)	Expel remaining liquid	InstrumentContext
touch_tip(location=None, radius=1.0, v_offset=-1.0, speed=60.0)	Remove droplets from tip	InstrumentContext
mix(repetitions=1, volume=None, location=None, rate=1.0)	Mix liquid	InstrumentContext
air_gap(volume=None, height=None)	Create air gap	InstrumentContext

Liquid Handling - Complex

Method	Description	Returns
transfer(volume, source, dest, **kwargs)	Transfer liquid	InstrumentContext
distribute(volume, source, dest, **kwargs)	Distribute from one to many	InstrumentContext
consolidate(volume, source, dest, **kwargs)	Consolidate from many to one	InstrumentContext

transfer(), distribute(), consolidate() kwargs:

• new_tip: 'always', 'once', or 'never'
• trash: True/False - trash tips after use
• touch_tip: True/False - touch tip after aspirate/dispense
• blow_out: True/False - blow out after dispense
• mix_before: (repetitions, volume) tuple
• mix_after: (repetitions, volume) tuple
• disposal_volume: Extra volume for contamination prevention
• carryover: True/False - enable multi-transfer for large volumes
• gradient: (start_concentration, end_concentration) for gradients

Movement and Positioning

Method	Description	Returns
move_to(location, force_direct=False, minimum_z_height=None, speed=None)	Move to location	InstrumentContext
home()	Home pipette axes	None

Pipette Properties

Property	Description	Type
default_speed	Default movement speed	Float
min_volume	Minimum pipette volume	Float
max_volume	Maximum pipette volume	Float
current_volume	Current volume in tip	Float
has_tip	Check if tip is attached	Bool
name	Pipette name	String
model	Pipette model	String
mount	Mount location	String
channels	Number of channels	Int
tip_racks	Associated tip racks	List
trash_container	Trash location	TrashBin object
starting_tip	Starting tip for protocol	Well object
flow_rate	Flow rate settings	FlowRates object

Flow Rate Properties

Access via pipette.flow_rate:

Property	Description	Units
aspirate	Aspirate flow rate	µL/s
dispense	Dispense flow rate	µL/s
blow_out	Blow out flow rate	µL/s

Labware Methods

Well Access

Method	Description	Returns
wells()	Get all wells	List[Well]
wells_by_name()	Get wells dictionary	Dict[str, Well]
rows()	Get wells by row	List[List[Well]]
columns()	Get wells by column	List[List[Well]]
rows_by_name()	Get rows dictionary	Dict[str, List[Well]]
columns_by_name()	Get columns dictionary	Dict[str, List[Well]]

Labware Properties

Property	Description	Type
name	Labware name	String
parent	Parent location	Location object
quirks	Labware quirks list	List
magdeck_engage_height	Magnetic module height	Float
uri	Labware URI	String
calibrated_offset	Calibration offset	Point

Well Methods and Properties

Liquid Operations

Method	Description	Returns
load_liquid(liquid, volume)	Load liquid into well	None
load_empty()	Mark well as empty	None
from_center_cartesian(x, y, z)	Get location from center	Location

Location Methods

Method	Description	Returns
top(z=0)	Get location at top of well	Location
bottom(z=0)	Get location at bottom of well	Location
center()	Get location at center of well	Location

Well Properties

Property	Description	Type
diameter	Well diameter (circular)	Float
length	Well length (rectangular)	Float
width	Well width (rectangular)	Float
depth	Well depth	Float
max_volume	Maximum volume	Float
display_name	Display name	String
has_tip	Check if tip present	Bool

Module Contexts

Temperature Module

Method	Description	Returns
set_temperature(celsius)	Set target temperature	None
await_temperature(celsius)	Wait for temperature	None
deactivate()	Turn off temperature control	None
load_labware(name, label=None, namespace=None, version=None)	Load labware on module	Labware

Properties:

• temperature: Current temperature (°C)
• target: Target temperature (°C)
• status: 'idle', 'holding', 'cooling', or 'heating'
• labware: Loaded labware

Magnetic Module

Method	Description	Returns
engage(height_from_base=None, offset=None, height=None)	Engage magnets	None
disengage()	Disengage magnets	None
load_labware(name, label=None, namespace=None, version=None)	Load labware on module	Labware

Properties:

• status: 'engaged' or 'disengaged'
• labware: Loaded labware

Heater-Shaker Module

Method	Description	Returns
set_target_temperature(celsius)	Set heater target	None
wait_for_temperature()	Wait for temperature	None
set_and_wait_for_temperature(celsius)	Set and wait	None
deactivate_heater()	Turn off heater	None
set_and_wait_for_shake_speed(rpm)	Set shake speed	None
deactivate_shaker()	Turn off shaker	None
open_labware_latch()	Open latch	None
close_labware_latch()	Close latch	None
load_labware(name, label=None, namespace=None, version=None)	Load labware on module	Labware

Properties:

• temperature: Current temperature (°C)
• target_temperature: Target temperature (°C)
• current_speed: Current shake speed (rpm)
• target_speed: Target shake speed (rpm)
• labware_latch_status: 'idle_open', 'idle_closed', 'opening', 'closing'
• status: Module status
• labware: Loaded labware

Thermocycler Module

Method	Description	Returns
open_lid()	Open lid	None
close_lid()	Close lid	None
set_lid_temperature(celsius)	Set lid temperature	None
deactivate_lid()	Turn off lid heater	None
set_block_temperature(temperature, hold_time_seconds=0, hold_time_minutes=0, ramp_rate=None, block_max_volume=None)	Set block temperature	None
deactivate_block()	Turn off block	None
execute_profile(steps, repetitions, block_max_volume=None)	Run temperature profile	None
load_labware(name, label=None, namespace=None, version=None)	Load labware on module	Labware

Profile step format:

{'temperature': 95, 'hold_time_seconds': 30, 'hold_time_minutes': 0}

Properties:

• block_temperature: Current block temperature (°C)
• block_target_temperature: Target block temperature (°C)
• lid_temperature: Current lid temperature (°C)
• lid_target_temperature: Target lid temperature (°C)
• lid_position: 'open', 'closed', 'in_between'
• ramp_rate: Block temperature ramp rate (°C/s)
• status: Module status
• labware: Loaded labware

Absorbance Plate Reader Module

Method	Description	Returns
initialize(mode, wavelengths)	Initialize reader	None
read(export_filename=None)	Read plate	Dict
close_lid()	Close lid	None
open_lid()	Open lid	None
load_labware(name, label=None, namespace=None, version=None)	Load labware on module	Labware

Read modes:

• 'single': Single wavelength
• 'multi': Multiple wavelengths

Properties:

• is_lid_on: Lid status
• labware: Loaded labware

Common Labware API Names

Plates

• corning_96_wellplate_360ul_flat
• nest_96_wellplate_100ul_pcr_full_skirt
• nest_96_wellplate_200ul_flat
• biorad_96_wellplate_200ul_pcr
• appliedbiosystems_384_wellplate_40ul

Reservoirs

• nest_12_reservoir_15ml
• nest_1_reservoir_195ml
• usascientific_12_reservoir_22ml

Tip Racks

Flex:

• opentrons_flex_96_tiprack_50ul
• opentrons_flex_96_tiprack_200ul
• opentrons_flex_96_tiprack_1000ul

OT-2:

• opentrons_96_tiprack_20ul
• opentrons_96_tiprack_300ul
• opentrons_96_tiprack_1000ul

Tube Racks

• opentrons_10_tuberack_falcon_4x50ml_6x15ml_conical
• opentrons_24_tuberack_nest_1.5ml_snapcap
• opentrons_24_tuberack_nest_1.5ml_screwcap
• opentrons_15_tuberack_falcon_15ml_conical

Adapters

• opentrons_flex_96_tiprack_adapter
• opentrons_96_deep_well_adapter
• opentrons_aluminum_flat_bottom_plate

Error Handling

Common exceptions:

• OutOfTipsError: No tips available
• LabwareNotLoadedError: Labware not loaded on deck
• InvalidContainerError: Invalid labware specification
• InstrumentNotLoadedError: Pipette not loaded
• InvalidVolumeError: Volume out of range

Simulation and Debugging

Check simulation status:

if protocol.is_simulating():
    protocol.comment('Running in simulation')

Access bundled data files:

data_file = protocol.bundled_data['data.csv']
with open(data_file) as f:
    data = f.read()

Version Compatibility

API Level compatibility:

API Level	Features
2.19	Latest features, Flex support
2.18	Absorbance plate reader
2.17	Liquid tracking improvements
2.16	Flex 8-channel partial tip pickup
2.15	Heater-Shaker Gen1
2.13	Temperature Module Gen2
2.0-2.12	Core OT-2 functionality

Always use the latest stable API version for new protocols.