1---2name: 051-api-reference-b41625023description: Opentrons Python Protocol API v2 Reference4---5# Opentrons Python Protocol API v2 Reference67## Protocol Context Methods89### Labware Management1011| Method | Description | Returns |12|--------|-------------|---------|13| `load_labware(name, location, label=None, namespace=None, version=None)` | Load labware onto deck | Labware object |14| `load_adapter(name, location, namespace=None, version=None)` | Load adapter onto deck | Labware object |15| `load_labware_from_definition(definition, location, label=None)` | Load custom labware from JSON | Labware object |16| `load_labware_on_adapter(name, adapter, label=None)` | Load labware on adapter | Labware object |17| `load_labware_by_name(name, location, label=None, namespace=None, version=None)` | Alternative load method | Labware object |18| `load_lid_stack(load_name, location, quantity=None)` | Load lid stack (Flex only) | Labware object |1920### Instrument Management2122| Method | Description | Returns |23|--------|-------------|---------|24| `load_instrument(instrument_name, mount, tip_racks=None, replace=False)` | Load pipette | InstrumentContext |2526### Module Management2728| Method | Description | Returns |29|--------|-------------|---------|30| `load_module(module_name, location=None, configuration=None)` | Load hardware module | ModuleContext |3132### Liquid Management3334| Method | Description | Returns |35|--------|-------------|---------|36| `define_liquid(name, description=None, display_color=None)` | Define liquid type | Liquid object |3738### Execution Control3940| Method | Description | Returns |41|--------|-------------|---------|42| `pause(msg=None)` | Pause protocol execution | None |43| `resume()` | Resume after pause | None |44| `delay(seconds=0, minutes=0, msg=None)` | Delay execution | None |45| `comment(msg)` | Add comment to protocol log | None |46| `home()` | Home all axes | None |47| `set_rail_lights(on)` | Control rail lights (Flex only) | None |4849### Protocol Properties5051| Property | Description | Type |52|----------|-------------|------|53| `deck` | Deck layout | Deck object |54| `fixed_trash` | Fixed trash location (OT-2) | TrashBin object |55| `loaded_labwares` | Dictionary of loaded labware | Dict |56| `loaded_instruments` | Dictionary of loaded instruments | Dict |57| `loaded_modules` | Dictionary of loaded modules | Dict |58| `is_simulating()` | Check if protocol is simulating | Bool |59| `bundled_data` | Access to bundled data files | Dict |60| `params` | Runtime parameters | ParametersContext |6162## Instrument Context (Pipette) Methods6364### Tip Management6566| Method | Description | Returns |67|--------|-------------|---------|68| `pick_up_tip(location=None, presses=None, increment=None)` | Pick up tip | InstrumentContext |69| `drop_tip(location=None, home_after=True)` | Drop tip in trash | InstrumentContext |70| `return_tip(home_after=True)` | Return tip to rack | InstrumentContext |71| `reset_tipracks()` | Reset tip tracking | None |7273### Liquid Handling - Basic7475| Method | Description | Returns |76|--------|-------------|---------|77| `aspirate(volume=None, location=None, rate=1.0)` | Aspirate liquid | InstrumentContext |78| `dispense(volume=None, location=None, rate=1.0, push_out=None)` | Dispense liquid | InstrumentContext |79| `blow_out(location=None)` | Expel remaining liquid | InstrumentContext |80| `touch_tip(location=None, radius=1.0, v_offset=-1.0, speed=60.0)` | Remove droplets from tip | InstrumentContext |81| `mix(repetitions=1, volume=None, location=None, rate=1.0)` | Mix liquid | InstrumentContext |82| `air_gap(volume=None, height=None)` | Create air gap | InstrumentContext |8384### Liquid Handling - Complex8586| Method | Description | Returns |87|--------|-------------|---------|88| `transfer(volume, source, dest, **kwargs)` | Transfer liquid | InstrumentContext |89| `distribute(volume, source, dest, **kwargs)` | Distribute from one to many | InstrumentContext |90| `consolidate(volume, source, dest, **kwargs)` | Consolidate from many to one | InstrumentContext |9192**transfer(), distribute(), consolidate() kwargs:**93- `new_tip`: 'always', 'once', or 'never'94- `trash`: True/False - trash tips after use95- `touch_tip`: True/False - touch tip after aspirate/dispense96- `blow_out`: True/False - blow out after dispense97- `mix_before`: (repetitions, volume) tuple98- `mix_after`: (repetitions, volume) tuple99- `disposal_volume`: Extra volume for contamination prevention100- `carryover`: True/False - enable multi-transfer for large volumes101- `gradient`: (start_concentration, end_concentration) for gradients102103### Movement and Positioning104105| Method | Description | Returns |106|--------|-------------|---------|107| `move_to(location, force_direct=False, minimum_z_height=None, speed=None)` | Move to location | InstrumentContext |108| `home()` | Home pipette axes | None |109110### Pipette Properties111112| Property | Description | Type |113|----------|-------------|------|114| `default_speed` | Default movement speed | Float |115| `min_volume` | Minimum pipette volume | Float |116| `max_volume` | Maximum pipette volume | Float |117| `current_volume` | Current volume in tip | Float |118| `has_tip` | Check if tip is attached | Bool |119| `name` | Pipette name | String |120| `model` | Pipette model | String |121| `mount` | Mount location | String |122| `channels` | Number of channels | Int |123| `tip_racks` | Associated tip racks | List |124| `trash_container` | Trash location | TrashBin object |125| `starting_tip` | Starting tip for protocol | Well object |126| `flow_rate` | Flow rate settings | FlowRates object |127128### Flow Rate Properties129130Access via `pipette.flow_rate`:131132| Property | Description | Units |133|----------|-------------|-------|134| `aspirate` | Aspirate flow rate | µL/s |135| `dispense` | Dispense flow rate | µL/s |136| `blow_out` | Blow out flow rate | µL/s |137138## Labware Methods139140### Well Access141142| Method | Description | Returns |143|--------|-------------|---------|144| `wells()` | Get all wells | List[Well] |145| `wells_by_name()` | Get wells dictionary | Dict[str, Well] |146| `rows()` | Get wells by row | List[List[Well]] |147| `columns()` | Get wells by column | List[List[Well]] |148| `rows_by_name()` | Get rows dictionary | Dict[str, List[Well]] |149| `columns_by_name()` | Get columns dictionary | Dict[str, List[Well]] |150151### Labware Properties152153| Property | Description | Type |154|----------|-------------|------|155| `name` | Labware name | String |156| `parent` | Parent location | Location object |157| `quirks` | Labware quirks list | List |158| `magdeck_engage_height` | Magnetic module height | Float |159| `uri` | Labware URI | String |160| `calibrated_offset` | Calibration offset | Point |161162## Well Methods and Properties163164### Liquid Operations165166| Method | Description | Returns |167|--------|-------------|---------|168| `load_liquid(liquid, volume)` | Load liquid into well | None |169| `load_empty()` | Mark well as empty | None |170| `from_center_cartesian(x, y, z)` | Get location from center | Location |171172### Location Methods173174| Method | Description | Returns |175|--------|-------------|---------|176| `top(z=0)` | Get location at top of well | Location |177| `bottom(z=0)` | Get location at bottom of well | Location |178| `center()` | Get location at center of well | Location |179180### Well Properties181182| Property | Description | Type |183|----------|-------------|------|184| `diameter` | Well diameter (circular) | Float |185| `length` | Well length (rectangular) | Float |186| `width` | Well width (rectangular) | Float |187| `depth` | Well depth | Float |188| `max_volume` | Maximum volume | Float |189| `display_name` | Display name | String |190| `has_tip` | Check if tip present | Bool |191192## Module Contexts193194### Temperature Module195196| Method | Description | Returns |197|--------|-------------|---------|198| `set_temperature(celsius)` | Set target temperature | None |199| `await_temperature(celsius)` | Wait for temperature | None |200| `deactivate()` | Turn off temperature control | None |201| `load_labware(name, label=None, namespace=None, version=None)` | Load labware on module | Labware |202203**Properties:**204- `temperature`: Current temperature (°C)205- `target`: Target temperature (°C)206- `status`: 'idle', 'holding', 'cooling', or 'heating'207- `labware`: Loaded labware208209### Magnetic Module210211| Method | Description | Returns |212|--------|-------------|---------|213| `engage(height_from_base=None, offset=None, height=None)` | Engage magnets | None |214| `disengage()` | Disengage magnets | None |215| `load_labware(name, label=None, namespace=None, version=None)` | Load labware on module | Labware |216217**Properties:**218- `status`: 'engaged' or 'disengaged'219- `labware`: Loaded labware220221### Heater-Shaker Module222223| Method | Description | Returns |224|--------|-------------|---------|225| `set_target_temperature(celsius)` | Set heater target | None |226| `wait_for_temperature()` | Wait for temperature | None |227| `set_and_wait_for_temperature(celsius)` | Set and wait | None |228| `deactivate_heater()` | Turn off heater | None |229| `set_and_wait_for_shake_speed(rpm)` | Set shake speed | None |230| `deactivate_shaker()` | Turn off shaker | None |231| `open_labware_latch()` | Open latch | None |232| `close_labware_latch()` | Close latch | None |233| `load_labware(name, label=None, namespace=None, version=None)` | Load labware on module | Labware |234235**Properties:**236- `temperature`: Current temperature (°C)237- `target_temperature`: Target temperature (°C)238- `current_speed`: Current shake speed (rpm)239- `target_speed`: Target shake speed (rpm)240- `labware_latch_status`: 'idle_open', 'idle_closed', 'opening', 'closing'241- `status`: Module status242- `labware`: Loaded labware243244### Thermocycler Module245246| Method | Description | Returns |247|--------|-------------|---------|248| `open_lid()` | Open lid | None |249| `close_lid()` | Close lid | None |250| `set_lid_temperature(celsius)` | Set lid temperature | None |251| `deactivate_lid()` | Turn off lid heater | None |252| `set_block_temperature(temperature, hold_time_seconds=0, hold_time_minutes=0, ramp_rate=None, block_max_volume=None)` | Set block temperature | None |253| `deactivate_block()` | Turn off block | None |254| `execute_profile(steps, repetitions, block_max_volume=None)` | Run temperature profile | None |255| `load_labware(name, label=None, namespace=None, version=None)` | Load labware on module | Labware |256257**Profile step format:**258```python259{'temperature': 95, 'hold_time_seconds': 30, 'hold_time_minutes': 0}260```261262**Properties:**263- `block_temperature`: Current block temperature (°C)264- `block_target_temperature`: Target block temperature (°C)265- `lid_temperature`: Current lid temperature (°C)266- `lid_target_temperature`: Target lid temperature (°C)267- `lid_position`: 'open', 'closed', 'in_between'268- `ramp_rate`: Block temperature ramp rate (°C/s)269- `status`: Module status270- `labware`: Loaded labware271272### Absorbance Plate Reader Module273274| Method | Description | Returns |275|--------|-------------|---------|276| `initialize(mode, wavelengths)` | Initialize reader | None |277| `read(export_filename=None)` | Read plate | Dict |278| `close_lid()` | Close lid | None |279| `open_lid()` | Open lid | None |280| `load_labware(name, label=None, namespace=None, version=None)` | Load labware on module | Labware |281282**Read modes:**283- `'single'`: Single wavelength284- `'multi'`: Multiple wavelengths285286**Properties:**287- `is_lid_on`: Lid status288- `labware`: Loaded labware289290## Common Labware API Names291292### Plates293294- `corning_96_wellplate_360ul_flat`295- `nest_96_wellplate_100ul_pcr_full_skirt`296- `nest_96_wellplate_200ul_flat`297- `biorad_96_wellplate_200ul_pcr`298- `appliedbiosystems_384_wellplate_40ul`299300### Reservoirs301302- `nest_12_reservoir_15ml`303- `nest_1_reservoir_195ml`304- `usascientific_12_reservoir_22ml`305306### Tip Racks307308**Flex:**309- `opentrons_flex_96_tiprack_50ul`310- `opentrons_flex_96_tiprack_200ul`311- `opentrons_flex_96_tiprack_1000ul`312313**OT-2:**314- `opentrons_96_tiprack_20ul`315- `opentrons_96_tiprack_300ul`316- `opentrons_96_tiprack_1000ul`317318### Tube Racks319320- `opentrons_10_tuberack_falcon_4x50ml_6x15ml_conical`321- `opentrons_24_tuberack_nest_1.5ml_snapcap`322- `opentrons_24_tuberack_nest_1.5ml_screwcap`323- `opentrons_15_tuberack_falcon_15ml_conical`324325### Adapters326327- `opentrons_flex_96_tiprack_adapter`328- `opentrons_96_deep_well_adapter`329- `opentrons_aluminum_flat_bottom_plate`330331## Error Handling332333Common exceptions:334335- `OutOfTipsError`: No tips available336- `LabwareNotLoadedError`: Labware not loaded on deck337- `InvalidContainerError`: Invalid labware specification338- `InstrumentNotLoadedError`: Pipette not loaded339- `InvalidVolumeError`: Volume out of range340341## Simulation and Debugging342343Check simulation status:344```python345if protocol.is_simulating():346 protocol.comment('Running in simulation')347```348349Access bundled data files:350```python351data_file = protocol.bundled_data['data.csv']352with open(data_file) as f:353 data = f.read()354```355356## Version Compatibility357358API Level compatibility:359360| API Level | Features |361|-----------|----------|362| 2.19 | Latest features, Flex support |363| 2.18 | Absorbance plate reader |364| 2.17 | Liquid tracking improvements |365| 2.16 | Flex 8-channel partial tip pickup |366| 2.15 | Heater-Shaker Gen1 |367| 2.13 | Temperature Module Gen2 |368| 2.0-2.12 | Core OT-2 functionality |369370Always use the latest stable API version for new protocols.
tools-only