# 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:**
```python
{'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:
```python
if protocol.is_simulating():
    protocol.comment('Running in simulation')
```

Access bundled data files:
```python
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.