Opentrons API Version 2

For the OT 1 API, please go to this link

For Version 1 of the OT 2 API, please go to this link

The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.

We’ve designed it in a way we hope is accessible to anyone with basic computer and wetlab skills. As a bench scientist, you should be able to code your automated protocols in a way that reads like a lab notebook.

View source code on GitHub


How it Looks

The design goal of the Opentrons API is to make code readable and easy to understand. For example, below is a short set of instruction to transfer from well 'A1' to well 'B1' that even a computer could understand:

This protocol is by me; it’s called Opentrons Protocol Tutorial and is used for demonstrating the Opentrons API

Begin the protocol

Add a 96 well plate, and place it in slot '2' of the robot deck
Add a 200uL tip rack, and place it in slot '1' of the robot deck

Add a single-channel 300uL pipette to the left mount, and tell it to use that tip rack

Transfer 100uL from the plate's 'A1' well to it's 'B2' well

If we were to rewrite this with the Opentrons API, it would look like the following:

# metadata
metadata = {
    'protocolName': 'My Protocol',
    'author': 'Name <email@address.com>',
    'description': 'Simple protocol to get started using OT2',
    'source': 'Opentrons Protocol Tutorial'
}

# protocol run function
def run(protocol_context):

    # labware
    plate = protocol_context.load_labware_by_name('generic_96_wellplate_380_ul', '2')
    tiprack = protocol_context.load_labware_by_name('opentrons_96_tiprack_300_ul', '1')

    # pipettes
    pipette = protocol_context.load_instrument('p300_single', 'left', tip_racks=[tiprack])

    # commands
    pipette.aspirate(100, plate.wells_by_index()['A1'])
    pipette.dispense(100, plate.wells_by_index()['B2'])

How it’s Organized

When writing protocols using the Opentrons API, there are generally five sections:

  1. Metadata
  2. Run function
  3. Labware
  4. Pipettes
  5. Commands

Metadata

Metadata is a dictionary of data that is read by the server and returned to client applications (such as the Opentrons Run App). It is not needed to run a protocol (and is entirely optional), but if present can help the client application display additional data about the protocol currently being executed.

The fields above (“protocolName”, “author”, “description”, and “source”) are the recommended fields, but the metadata dictionary can contain fewer fields, or additional fields as desired (though non-standard fields may not be rendered by the client, depending on how it is designed).

Run Function

Opentrons API version 2 protocols are structured around a function called run(ctx). This function must be named exactly run and must take exactly one mandatory argument (its name doesn’t matter). When the robot runs a protocol, it will call this function, and pass it an object that does two things:

  1. Remember, track, and check the robot’s state
  2. Expose the functions that make the robot act

This object is called the protocol context, and is always an instance of the ProtocolContext class. The protocol context plays the same role as the robot, labware, instruments, and modules objects in past versions of the API, with one important difference: it is only one object; and because it is passed in to your protocol rather than imported, it is possible for the API to be much more rigorous about separating simulation from reality.

The key point is that there is no longer any need to import opentrons at the top of every protocol, since the robot now runs the protocol, rather than the protocol running the robot.

Labware

The labware section informs the protocol context what labware is present on the robot’s deck. In this section, you define the tip racks, well plates, troughs, tubes, or anything else you’ve put on the deck.

Each labware is given a name (ex: 'generic_96_wellplate_380_ul'), and the slot on the robot it will be placed (ex: '2'). A list of valid labware can be found in protocol-api-valid-labware. In this example, we’ll use 'generic_96_wellplate_380_ul' (an ANSI standard 96-well plate) and 'opentrons_96_tiprack_300_ul', the Opentrons standard 300 uL tiprack.

From the example above, the “labware” section looked like:

plate = protocol_context.load_labware_by_name('generic_96_wellplate_380_ul', '2')
tiprack = protocol_context.load_labware_by_name('opentrons_96_tiprack_300_ul', '1')

and informed the protocol context that the deck contains a 300 uL tiprack in slot 1 and a 96 well plate in slot 2.

More complete documentation on labware methods (such as the .wells() method) is available in Labware and Wells.

This table lists the names of valid labwares that can be loaded with ProtocolContext.load_labware_by_name(), along with the name of the legacy labware definition each is equivalent to (if any).

API 2 Labware Name API 1 Labware Name
biorad_96_wellplate_pcr_200_ul 96-pcr-flat
corning_12_wellplate_6.9_ml 12-well-plate
corning_24_wellplate_3.4_ml 24-well-plate
corning_384_wellplate_112_ul 384-plate
corning_48_wellplate_1.6_ml 48-well-plate
corning_6_wellplate_16.8_ml 6-well-plate
eppendorf_96_tiprack_1000_ul
eppendorf_96_tiprack_10_ul
generic_96_wellplate_380_ul 96-flat
opentrons_15_tuberack_15_ml_falcon opentrons-tuberack-15ml
opentrons_24_aluminum_tuberack_2_ml opentrons-aluminum-block-2ml-eppendorf
opentrons_24_tuberack_1.5_ml_eppendorf opentrons-tuberack-1.5ml-eppendorf
opentrons_24_tuberack_2_ml_eppendorf opentrons-tuberack-2ml-eppendorf
opentrons_24_tuberack_2_ml_screwcap opentrons-tuberack-2ml-screwcap
opentrons_6_tuberack_falcon_50_ml opentrons-tuberack-50ml
opentrons_6x15_ml_4x50_ml_tuberack opentrons-tuberack-15_50ml
opentrons_96_aluminum_biorad_plate_200_ul opentrons-aluminum-block-96-PCR-plate
opentrons_96_aluminum_tuberack_200_ul
opentrons_96_tiprack_1000_ul tiprack-1000ul
opentrons_96_tiprack_10_ul tiprack-10ul
opentrons_96_tiprack_300_ul opentrons-tiprack-300ul
usa_scientific_12_trough_22_ml trough-12row

Pipettes

Next, pipettes are created and attached to a specific mount on the OT-2 ('left' or 'right').

There are other parameters for pipettes, but the most important are the tip rack(s) it will use during the protocol.

From the example above, the “pipettes” section looked like:

pipette = protocol_context.load_instrument('p300_single', 'left', tip_racks=[tiprack])

And finally, the actual protocol commands! The most common commands are transfer(), aspirate(), dispense(), pick_up_tip(), drop_tip(), and much more.

This section can tend to get long, relative to the complexity of your protocol. However, with a better understanding of Python you can learn to compress and simplify even the most complex-seeming protocols.

From the example above, the “commands” section looked like:

pipette.aspirate(100, plate.wells_by_index()['A1'])
pipette.dispense(100, plate.wells_by_index()['B2'])

which does exactly what it says - aspirate 100 uL from A1 and dispense it all in B2.

Complete documentation of pipettes and pipette commands can be found in Protocols and Instruments.

Modules

Modules are peripherals that attach to the OT-2 to extend its capabilities. Modules currently supported are the Temperature Module and the Magnetic Module. The Thermocycler is under development.

A Temperature Module, for example, can be loaded and used in a protocol like this:

def run(protocol_context):
    temp_mod = protocol_context.load_module('Temperature Module', '10')
    temp_plate = temp_mod.load_labware('biorad_96_wellplate_pcr_200_ul')

    master_mix = labware.load('opentrons_6_tuberack_falcon_50_ml')

    for target_well in temp_plate.wells():
        pipette.transfer(50, master_mix.wells_by_index()['A1'], target_well)

    target_temp = 80.0  # degrees Celcius
    temp_mod.set_temp(target_temp)
    temp_mod.wait_for_temp()

    # perform other operations

    temp_mod.deactivate()

Complete documentation on all module classes is available in Modules.

Protocols and Instruments

class opentrons.protocol_api.contexts.ProtocolContext(loop: asyncio.events.AbstractEventLoop = None, hardware: opentrons.hardware_control.API = None, broker=None) → None

The Context class is a container for the state of a protocol.

It encapsulates many of the methods formerly found in the Robot class, including labware, instrument, and module loading, as well as core functions like pause and resume.

Unlike the old robot class, it is designed to be ephemeral. The lifetime of a particular instance should be about the same as the lifetime of a protocol. The only exception is the one stored in back_compat.robot, which is provided only for back compatibility and should be used less and less as time goes by.

comment(msg)

Add a user-readable comment string that will be echoed to the Opentrons app.

config

Get the robot’s configuration object.

Returns .robot_config:
 The loaded configuration.
connect(hardware: opentrons.hardware_control.API)

Connect to a running hardware API.

This can be either a simulator or a full hardware controller.

Note that there is no true disconnected state for a ProtocolContext; disconnect() simply creates a new simulator and replaces the current hardware with it.

deck

The object holding the deck layout of the robot.

delay(seconds=0, minutes=0, msg=None)

Delay protocol execution for a specific amount of time.

Parameters:
  • seconds (float) – A time to delay in seconds
  • minutes (float) – A time to delay in minutes

If both seconds and minutes are specified, they will be added.

disconnect()

Disconnect from currently-connected hardware and simulate instead

fixed_trash

The trash fixed to slot 12 of the robot deck.

home()

Homes the robot.

load_instrument(instrument_name: str, mount: typing.Union[opentrons.types.Mount, str], tip_racks: typing.List[opentrons.protocol_api.labware.Labware] = None, replace: bool = False) → opentrons.protocol_api.contexts.InstrumentContext

Load a specific instrument required by the protocol.

This value will actually be checked when the protocol runs, to ensure that the correct instrument is attached in the specified location.

Parameters:
  • instrument_name (str) – The name of the instrument model, or a prefix. For instance, ‘p10_single’ may be used to request a P10 single regardless of the version.
  • mount (types.Mount or str) – The mount in which this instrument should be attached. This can either be an instance of the enum type types.Mount or one of the strings ‘left’ and ‘right’.
  • tip_racks (List[Labware]) – A list of tip racks from which to pick tips if InstrumentContext.pick_up_tip() is called without arguments.
  • replace (bool) – Indicate that the currently-loaded instrument in mount (if such an instrument exists) should be replaced by instrument_name.
load_labware(labware_obj: opentrons.protocol_api.labware.Labware, location: typing.Union[int, str]) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the OT2 deck.

This function loads the labware specified by labware (previously loaded from a configuration file) to the location specified by location.

Parameters:
  • labware (Labware) – The labware object to load
  • location (int or str) – The slot into which to load the labware such as 1 or ‘1’
load_labware_by_name(labware_name: str, location: typing.Union[int, str], label: str = None) → opentrons.protocol_api.labware.Labware

A convenience function to specify a piece of labware by name.

For labware already defined by Opentrons, this is a convient way to collapse the two stages of labware initialization (creating the labware and adding it to the protocol) into one.

This function returns the created and initialized labware for use later in the protocol.

Parameters:
  • labware_name (str) – The name of the labware to load
  • location (int or str) – The slot into which to load the labware such as 1 or ‘1’
  • label (str) – An optional special name to give the labware. If specified, this is the name the labware will appear as in the run log and the calibration view in the Opentrons app.
loaded_instruments

Get the instruments that have been loaded into the protocol.

Returns:A dict mapping mount names in lowercase to the instrument in that mount, or None if no instrument is present.
loaded_labwares

Get the labwares that have been loaded into the protocol context.

The return value is a dict mapping locations to labware, sorted in order of the locations.

location_cache

The cache used by the robot to determine where it last was.

pause(msg=None)

Pause execution of the protocol until resume is called.

This function returns immediately, but the next function call that is blocked by a paused robot (anything that involves moving) will not return until resume() is called.

Parameters:msg (str) – A message to echo back to connected clients.
reset()

Reset the state of the context and the hardware.

For instance, this call will - reset all cached knowledge about attached tips - unload all labware - unload all instruments - clear all location and instrument caches

The only state that will be kept is the position of the robot.

resume()

Resume a previously-paused protocol

temp_connect(hardware: opentrons.hardware_control.API)

Connect temporarily to the specified hardware controller.

This should be used as a context manager:

with ctx.temp_connect(hw):
    # do some tasks
    ctx.home()
# after the with block, the context is connected to the same
# hardware control API it was connected to before, even if
# an error occured in the code inside the with block
update_config(**kwargs)

Update values of the robot’s configuration.

kwargs should contain keys of the robot’s configuration. For instace, update_config(name=’Grace Hopper’) would change the name of the robot

Documentation on keys can be found in the documentation for robot_config.

class opentrons.protocol_api.contexts.InstrumentContext(ctx: opentrons.protocol_api.contexts.ProtocolContext, hardware_mgr: opentrons.protocol_api.contexts.ProtocolContext.HardwareManager, mount: opentrons.types.Mount, log_parent: logging.Logger, tip_racks: typing.List[opentrons.protocol_api.labware.Labware] = None, trash: opentrons.protocol_api.labware.Labware = None, **config_kwargs) → None

A context for a specific pipette or instrument.

This can be used to call methods related to pipettes - moves or aspirates or dispenses, or higher-level methods.

Instances of this class bundle up state and config changes to a pipette - for instance, changes to flow rates or trash containers. Action methods (like aspirate() or distribute()) are defined here for convenience.

In general, this class should not be instantiated directly; rather, instances are returned from ProtcolContext.load_instrument().

air_gap(volume: float = None, height: float = None) → opentrons.protocol_api.contexts.InstrumentContext

Pull air into the pipette current tip at the current location

Parameters:
  • volume (float) – The amount in uL to aspirate air into the tube. (Default will use all remaining volume in tip)
  • height (float) – The number of millimiters to move above the current Well to air-gap aspirate. (Default: 5mm above current Well)
Raises:
  • NoTipAttachedError – If no tip is attached to the pipette
  • RuntimeError – If location cache is None. This should happen if touch_tip is called without first calling a method that takes a location (eg, aspirate(), dispense())
Returns:

This instance

aspirate(volume: float = None, location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None, rate: float = 1.0) → opentrons.protocol_api.contexts.InstrumentContext

Aspirate a volume of liquid (in microliters/uL) using this pipette from the specified location

If only a volume is passed, the pipette will aspirate from its current position. If only a location is passed, aspirate() will default to its max_volume.

Parameters:
  • volume (int or float) – The volume to aspirate, in microliters. If not specified, max_volume.
  • location – Where to aspirate from. If location is a Well, the robot will aspirate from well_bottom_clearance mm above the bottom of the well. If location is a Location (i.e. the result of Well.top() or Well.bottom()), the robot will aspirate from the exact specified location. If unspecified, the robot will aspirate from the current position.
  • rate (float) – The relative plunger speed for this aspirate. During this aspirate, the speed of the plunger will be rate * aspirate_speed. If not specified, defaults to 1.0 (speed will not be modified).
Returns:

This instance.

blow_out(location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None) → opentrons.protocol_api.contexts.InstrumentContext

Blow liquid out of the tip.

If dispense is used to completely empty a pipette, usually a small amount of liquid will remain in the tip. This method moves the plunger past its usual stops to fully remove any remaining liquid from the tip. Regardless of how much liquid was in the tip when this function is called, after it is done the tip will be empty.

Parameters:location (Well or Location or None) – The location to blow out into. If not specified, defaults to the current location of the pipette
Raises:RuntimeError – If no location is specified and location cache is None. This should happen if blow_out is called without first calling a method that takes a location (eg, aspirate(), dispense())
Returns:This instance
channels

The number of channels on the pipette.

consolidate(volume: float, source: typing.List[opentrons.protocol_api.labware.Well], dest: opentrons.protocol_api.labware.Well, *args, **kwargs) → opentrons.protocol_api.contexts.InstrumentContext

Move liquid from multiple wells (sources) to a single well(destination)

Parameters:
  • volume – The amount of volume to consolidate from each source well.
  • source – List of wells from where liquid will be aspirated.
  • dest – The single well into which liquid will be dispensed.
  • kwargs – See transfer().
Returns:

This instance

current_volume

The current amount of liquid, in microliters, held in the pipette.

dispense(volume: float = None, location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None, rate: float = 1.0) → opentrons.protocol_api.contexts.InstrumentContext

Dispense a volume of liquid (in microliters/uL) using this pipette into the specified location.

If only a volume is passed, the pipette will dispense from its current position. If only a location is passed, all of the liquid aspirated into the pipette will be dispensed (this volume is accessible through current_volume).

Parameters:
  • volume (int or float) – The volume of liquid to dispense, in microliters. If not specified, defaults to current_volume.
  • location – Where to dispense into. If location is a Well, the robot will dispense into well_bottom_clearance mm above the bottom of the well. If location is a Location (i.e. the result of Well.top() or Well.bottom()), the robot will dispense into the exact specified location. If unspecified, the robot will dispense into the current position.
  • rate (float) – The relative plunger speed for this dispense. During this dispense, the speed of the plunger will be rate * dispense_speed. If not specified, defaults to 1.0 (speed will not be modified).
Returns:

This instance.

distribute(volume: float, source: opentrons.protocol_api.labware.Well, dest: typing.List[opentrons.protocol_api.labware.Well], *args, **kwargs) → opentrons.protocol_api.contexts.InstrumentContext

Move a volume of liquid from one source to multiple destinations.

Parameters:
  • volume – The amount of volume to distribute to each destination well.
  • source – A single well from where liquid will be aspirated.
  • dest – List of Wells where liquid will be dispensed to.
  • kwargs – See transfer().
Returns:

This instance

drop_tip(location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None) → opentrons.protocol_api.contexts.InstrumentContext

Drop the current tip.

If no location is passed, the Pipette will drop the tip into its trash_container, which if not specified defaults to the fixed trash in slot 12.

The location in which to drop the tip can be manually specified with the location argument. The location argument can be specified in several ways:

  • If the only thing to specify is which well into which to drop a tip, location can be a Well. For instance, if you have a tip rack in a variable called tiprack, you can drop a tip into a specific well on that tiprack with the call instr.pick_up_tip(tiprack.wells()[0]). This style of call can be used to make the robot drop a tip into arbitrary labware.
  • If the position to drop the tip from as well as the Well to drop the tip into needs to be specified, for instance to tell the robot to drop a tip from an unusually large height above the tiprack, location can be a types.Location; for instance, you can call instr.pick_up_tip(tiprack.wells()[0].top()).

Note

OT1 required homing the plunger after dropping tips, so the prior version of drop_tip automatically homed the plunger. This is no longer needed in OT2. If you need to home the plunger, use home_plunger().

Parameters:location (types.Location or Well or None) – The location to drop the tip
Returns:This instance
flow_rate

The speeds (in uL/s) configured for the pipette, as a dict.

Returns a dict with the keys ‘aspirate’ and ‘dispense’ and correspoding values are the flow rates for each operation.

Note:This property is equivalent to speeds; the only

difference is the units in which this property is specified.

home() → opentrons.protocol_api.contexts.InstrumentContext

Home the robot.

Returns:This instance.
home_plunger() → opentrons.protocol_api.contexts.InstrumentContext

Home the plunger associated with this mount

Returns:This instance.
hw_pipette

View the information returned by the hardware API directly.

Raises:a types.PipetteNotAttachedError if the pipette is no longer attached (should not happen).
max_volume

The maximum volume, in microliters, this pipette can hold.

mix(repetitions: int = 1, volume: float = None, location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None, rate: float = 1.0) → opentrons.protocol_api.contexts.InstrumentContext

Mix a volume of liquid (uL) using this pipette. If no location is specified, the pipette will mix from its current position. If no Volume is passed, ‘mix’ will default to its max_volume.

Parameters:
  • repetitions – how many times the pipette should mix (default: 1)
  • volume – number of microlitres to mix (default: self.max_volume)
  • location – a Well or a position relative to well. e.g, plate.rows()[0][0].bottom() (types.Location type).
  • rate – Set plunger speed for this mix, where, speed = rate * (aspirate_speed or dispense_speed)
Raises:

NoTipAttachedError – If no tip is attached to the pipette.

Returns:

This instance

mount

Return the name of the mount this pipette is attached to

move_to(location: opentrons.types.Location, force_direct: bool = False, minimum_z_height: float = None) → opentrons.protocol_api.contexts.InstrumentContext

Move the instrument.

Parameters:
  • location (types.Location) – The location to move to.
  • force_direct – If set to true, move directly to destination without arc motion.
  • minimum_z_height – When specified, this Z margin is able to raise (but never lower) the mid-arc height.
name

The model string for the pipette.

pick_up_current

The current (amperes) the pipette mount’s motor will use while picking up a tip. Specified in amps.

pick_up_tip(location: typing.Union[opentrons.types.Location, opentrons.protocol_api.labware.Well] = None, presses: int = 3, increment: float = 1.0) → opentrons.protocol_api.contexts.InstrumentContext

Pick up a tip for the pipette to run liquid-handling commands with

If no location is passed, the Pipette will pick up the next available tip in its InstrumentContext.tip_racks list.

The tip to pick up can be manually specified with the location argument. The location argument can be specified in several ways:

  • If the only thing to specify is which well from which to pick up a tip, location can be a Well. For instance, if you have a tip rack in a variable called tiprack, you can pick up a specific tip from it with instr.pick_up_tip(tiprack.wells()[0]). This style of call can be used to make the robot pick up a tip from a tip rack that was not specified when creating the InstrumentContext.
  • If the position to move to in the well needs to be specified, for instance to tell the robot to run its pick up tip routine starting closer to or farther from the top of the tip, location can be a types.Location; for instance, you can call instr.pick_up_tip(tiprack.wells()[0].top()).
Parameters:
  • location (types.Location or Well to pick up a tip from.) – The location from which to pick up a tip.
  • presses (int) – The number of times to lower and then raise the pipette when picking up a tip, to ensure a good seal (0 [zero] will result in the pipette hovering over the tip but not picking it up–generally not desireable, but could be used for dry-run).
  • increment (float) – The additional distance to travel on each successive press (e.g.: if presses=3 and increment=1.0, then the first press will travel down into the tip by 3.5mm, the second by 4.5mm, and the third by 5.5mm).
Returns:

This instance

return_tip() → opentrons.protocol_api.contexts.InstrumentContext

If a tip is currently attached to the pipette, then it will return the tip to it’s location in the tiprack.

It will not reset tip tracking so the well flag will remain False.

Returns:This instance
speeds

The speeds (in mm/s) configured for the pipette, as a dict.

The keys will be ‘aspirate’ and ‘dispense’ (e.g. the keys of MODE)

Note:This property is equivalent to speeds; the only

difference is the units in which this property is specified.

tip_racks

The tip racks that have been linked to this pipette.

This is the property used to determine which tips to pick up next when calling pick_up_tip() without arguments.

touch_tip(location: opentrons.protocol_api.labware.Well = None, radius: float = 1.0, v_offset: float = -1.0, speed: float = 60.0) → opentrons.protocol_api.contexts.InstrumentContext

Touch the pipette tip to the sides of a well, with the intent of removing left-over droplets

Parameters:
  • location (Well or None) – If no location is passed, pipette will touch tip at current well’s edges
  • radius (float) – Describes the proportion of the target well’s radius. When radius=1.0, the pipette tip will move to the edge of the target well; when radius=0.5, it will move to 50% of the well’s radius. Default: 1.0 (100%)
  • v_offset (float) – The offset in mm from the top of the well to touch tip A positive offset moves the tip higher above the well, while a negative offset moves it lower into the well Default: -1.0 mm
  • speed (float) – The speed for touch tip motion, in mm/s. Default: 60.0 mm/s, Max: 80.0 mm/s, Min: 20.0 mm/s
Raises:
  • NoTipAttachedError – if no tip is attached to the pipette
  • RuntimeError – If no location is specified and location cache is None. This should happen if touch_tip is called without first calling a method that takes a location (eg, aspirate(), dispense())
Returns:

This instance

Note

This is behavior change from legacy API (which accepts any Placeable as the location parameter)

transfer(volume: typing.Union[float, typing.Sequence[float]], source, dest, **kwargs) → opentrons.protocol_api.contexts.InstrumentContext

Transfer will move a volume of liquid from a source location(s) to a dest location(s). It is a higher-level command, incorporating other InstrumentContext commands, like aspirate() and dispense(), designed to make protocol writing easier at the cost of specificity.

Parameters:
  • volume – The amount of volume to aspirate from each source and dispense to each destination. If volume is a list, each volume will be used for the sources/targets at the matching index. If volumes is a tuple with two elements, like (20, 100), then a list of volumes will be generated with a linear gradient between the two volumes in the tuple.
  • source – A single well or a list of wells from where liquid will be aspirated.
  • dest – A single well or a list of wells where liquid will be dispensed to.
  • **kwargs – See below
Keyword Arguments:
 
  • new_tip (string) –

    • ‘never’: no tips will be picked up or dropped during transfer
    • ‘once’: (default) a single tip will be used for all commands.
    • ‘always’: use a new tip for each transfer.
  • trash (boolean) – If False (default behavior), tips will be returned to their tip rack. If True and a trash container has been attached to this Pipette, then the tip will be sent to the trash container.

  • touch_tip (boolean) – If True, a touch_tip() will occur following each aspirate() and dispense(). If set to False (default behavior), no touch_tip() will occur.

  • blow_out (boolean) – If True, a blow_out() will occur following each dispense(), but only if the pipette has no liquid left in it. If set to False (default), no blow_out() will occur.

  • mix_before (tuple) – The tuple, if specified, gives the amount of volume to mix() preceding each aspirate() during the transfer. The tuple is interpreted as (repetitions, volume).

  • mix_after (tuple) – The tuple, if specified, gives the amount of volume to mix() after each dispense() during the transfer. The tuple is interpreted as (repetitions, volume).

  • disposal_vol (float) – (distribute() only) Volume of liquid to be disposed off after distributing. When dispensing multiple times from the same tip, it is recommended to aspirate an extra amount of liquid to be disposed off after distributing.

  • carryover (boolean) – If True (default), any volume that exceeds the maximum volume of this Pipette will be split into multiple smaller volumes.

  • gradient (lambda) – Function for calculating the curve used for gradient volumes. When volume is a tuple of length 2, its values are used to create a list of gradient volumes. The default curve for this gradient is linear (lambda x: x), however a method can be passed with the gradient keyword argument to create a custom curve.

Returns:

This instance

trash_container

The trash container associated with this pipette.

This is the property used to determine where to drop tips and blow out liquids when calling drop_tip() or blow_out() without arguments.

type

One of ‘single’ or ‘multi’.

well_bottom_clearance

The distance above the bottom of a well to aspirate or dispense.

When aspirate() or dispense() is given a Well rather than a full Location, the robot will move this distance above the bottom of the well to aspirate or dispense.

Labware and Wells

This module will replace Placeable

class opentrons.protocol_api.labware.Labware(definition: dict, parent: opentrons.types.Location, label: str = None) → None

This class represents a labware, such as a PCR plate, a tube rack, trough, tip rack, etc. It defines the physical geometry of the labware, and provides methods for accessing wells within the labware.

columns(*args) → typing.List[typing.List[opentrons.protocol_api.labware.Well]]

Accessor function used to navigate through a labware by column.

With indexing one can treat it as a typical python nested list. To access row A for example, simply write: labware.columns()[0] This will output [‘A1’, ‘B1’, ‘C1’, ‘D1’...].

Note that this method takes args for backward-compatibility, but use of args is deprecated and will be removed in future versions. Args can be either strings or integers, but must all be the same type (e.g.: self.columns(1, 4, 8) or self.columns(‘1’, ‘2’), but self.columns(‘1’, 4) is invalid.

Returns:A list of column lists
columns_by_index() → typing.Dict[str, typing.List[opentrons.protocol_api.labware.Well]]

Accessor function used to navigate through a labware by column name.

With indexing one can treat it as a typical python dictionary. To access row A for example, simply write: labware.columns_by_index()[‘1’] This will output [‘A1’, ‘B1’, ‘C1’, ‘D1’...].

Returns:Dictionary of Well lists keyed by column name
highest_z

The z-coordinate of the tallest single point anywhere on the labware.

This is drawn from the ‘dimensions’/’overallHeight’ elements of the labware definition and takes into account the calibration offset.

name

The canonical name of the labware, which is used to load it

next_tip(num_tips: int = 1) → typing.Union[opentrons.protocol_api.labware.Well, NoneType]

Find the next valid well for pick-up.

Determines the next valid start tip from which to retrieve the specified number of tips. There must be at least num_tips sequential wells for which all wells have tips, in the same column.

Parameters:num_tips (int) – target number of sequential tips in the same column
Returns:the Well meeting the target criteria, or None
parameters

Internal properties of a labware including type and quirks

parent

The parent of this labware. Usually a slot name.

quirks

Quirks specific to this labware.

rows(*args) → typing.List[typing.List[opentrons.protocol_api.labware.Well]]

Accessor function used to navigate through a labware by row.

With indexing one can treat it as a typical python nested list. To access row A for example, simply write: labware.rows()[0]. This will output [‘A1’, ‘A2’, ‘A3’, ‘A4’...]

Note that this method takes args for backward-compatibility, but use of args is deprecated and will be removed in future versions. Args can be either strings or integers, but must all be the same type (e.g.: self.rows(1, 4, 8) or self.rows(‘A’, ‘B’), but self.rows(‘A’, 4) is invalid.

Returns:A list of row lists
rows_by_index() → typing.Dict[str, typing.List[opentrons.protocol_api.labware.Well]]

Accessor function used to navigate through a labware by row name.

With indexing one can treat it as a typical python dictionary. To access row A for example, simply write: labware.rows_by_index()[‘A’] This will output [‘A1’, ‘A2’, ‘A3’, ‘A4’...].

Returns:Dictionary of Well lists keyed by row name
set_calibration(delta: opentrons.types.Point)

Called by save calibration in order to update the offset on the object.

use_tips(start_well: opentrons.protocol_api.labware.Well, num_channels: int = 1)

Removes tips from the tip tracker.

This method should be called when a tip is picked up. Generally, it will be called with num_channels=1 or num_channels=8 for single- and multi-channel respectively. If picking up with more than one channel, this method will automatically determine which tips are used based on the start well, the number of channels, and the geometry of the tiprack.

Parameters:
  • start_well (Well) – The Well from which to pick up a tip. For a single-channel pipette, this is the well to send the pipette to. For a multi-channel pipette, this is the well to send the back-most nozzle of the pipette to.
  • num_channels (int) – The number of channels for the current pipette
well(idx) → opentrons.protocol_api.labware.Well

Deprecated—use result of wells or wells_by_index

wells(*args) → typing.List[opentrons.protocol_api.labware.Well]

Accessor function used to generate a list of wells in top -> down, left -> right order. This is representative of moving down rows and across columns (e.g. ‘A1’, ‘B1’, ‘C1’...’A2’, ‘B2’, ‘C2’)

With indexing one can treat it as a typical python list. To access well A1, for example, simply write: labware.wells()[0]

Note that this method takes args for backward-compatibility, but use of args is deprecated and will be removed in future versions. Args can be either strings or integers, but must all be the same type (e.g.: self.wells(1, 4, 8) or self.wells(‘A1’, ‘B2’), but self.wells(‘A1’, 4) is invalid.

Returns:Ordered list of all wells in a labware
wells_by_index() → typing.Dict[str, opentrons.protocol_api.labware.Well]

Accessor function used to create a look-up table of Wells by name.

With indexing one can treat it as a typical python dictionary whose keys are well names. To access well A1, for example, simply write: labware.wells_by_index()[‘A1’]

Returns:Dictionary of well objects keyed by well name
class opentrons.protocol_api.labware.ModuleGeometry(definition: dict, parent: opentrons.types.Location) → None

This class represents an active peripheral, such as an Opentrons MagBead Module or Temperature Module. It defines the physical geometry of the device (primarily the offset that modifies the position of the labware mounted on top of it).

location

return – a Location representing the top of the module

class opentrons.protocol_api.labware.Well(well_props: dict, parent: opentrons.types.Location, display_name: str, has_tip: bool) → None

The Well class represents a single well in a Labware

It provides functions to return positions used in operations on the well such as top(), bottom()

bottom(z: float = 0.0) → opentrons.types.Location
Parameters:z – the z distance in mm
Returns:a Point corresponding to the absolute position of the bottom-center of the well (with the front-left corner of slot 1 as (0,0,0)). If z is specified, returns a point offset by z mm from bottom-center
center() → opentrons.types.Location
Returns:a Point corresponding to the absolute position of the center

of the well relative to the deck (with the front-left corner of slot 1 as (0,0,0))

top(z: float = 0.0) → opentrons.types.Location
Parameters:z – the z distance in mm
Returns:a Point corresponding to the absolute position of the top-center of the well relative to the deck (with the front-left corner of slot 1 as (0,0,0)). If z is specified, returns a point offset by z mm from top-center
class opentrons.protocol_api.labware.WellShape

An enumeration.

opentrons.protocol_api.labware.clear_calibrations()

Delete all calibration files for labware. This includes deleting tip-length data for tipracks.

opentrons.protocol_api.labware.load(name: str, parent: opentrons.types.Location, label: str = None) → opentrons.protocol_api.labware.Labware

Return a labware object constructed from a labware definition dict looked up by name (definition must have been previously stored locally on the robot)

Parameters:
  • name – A string to use for looking up a labware definition previously saved to disc. The definition file must have been saved in a known location with the filename ‘${name}.json’
  • parent – A Location representing the location where the front and left most point of the outside of labware is (often the front-left corner of a slot on the deck).
  • label (str) – An optional label that will override the labware’s display name from its definition
opentrons.protocol_api.labware.load_calibration(labware: opentrons.protocol_api.labware.Labware)

Look up a calibration if it exists and apply it to the given labware.

opentrons.protocol_api.labware.load_definition_by_name(name: str) → dict

Look up and return a definition by name (name is expected to correspond to the filename of the definition, with the .json extension) and return it or raise an exception

Parameters:name – A string to use for looking up a labware defintion previously saved to disc. The definition file must have been saved in a known location with the filename ‘${name}.json’
opentrons.protocol_api.labware.load_from_definition(definition: dict, parent: opentrons.types.Location, label: str = None) → opentrons.protocol_api.labware.Labware

Return a labware object constructed from a provided labware definition dict

Parameters:
  • definition – A dict representing all required data for a labware, including metadata such as the display name of the labware, a definition of the order to iterate over wells, the shape of wells (shape, physical dimensions, etc), and so on. The correct shape of this definition is governed by the “labware-designer” project in the Opentrons/opentrons repo.
  • parent – A Location representing the location where the front and left most point of the outside of labware is (often the front-left corner of a slot on the deck).
  • label (str) – An optional label that will override the labware’s display name from its definition
opentrons.protocol_api.labware.load_module(name: str, parent: opentrons.types.Location) → opentrons.protocol_api.labware.ModuleGeometry

Return a ModuleGeometry object from a definition looked up by name.

Parameters:
  • name – A string to use for looking up the definition. The string must be present as a top-level key in moduleSpecs.json.
  • parent – A Location representing the location where the front and left most point of the outside of the module is (often the front-left corner of a slot on the deck).
opentrons.protocol_api.labware.load_module_from_definition(definition: dict, parent: opentrons.types.Location) → opentrons.protocol_api.labware.ModuleGeometry

Return a ModuleGeometry object from a specified definition

Parameters:
  • definition – A dict representing all required data for a module’s geometry.
  • parent – A Location representing the location where the front and left most point of the outside of the module is (often the front-left corner of a slot on the deck).
opentrons.protocol_api.labware.quirks_from_any_parent(loc: typing.Union[opentrons.protocol_api.labware.Labware, opentrons.protocol_api.labware.Well, str, opentrons.protocol_api.labware.ModuleGeometry, NoneType]) → typing.List[str]

Walk the tree of wells and labwares and extract quirks

opentrons.protocol_api.labware.save_calibration(labware: opentrons.protocol_api.labware.Labware, delta: opentrons.types.Point)

Function to be used whenever an updated delta is found for the first well of a given labware. If an offset file does not exist, create the file using labware id as the filename. If the file does exist, load it and modify the delta and the lastModified fields under the “default” key.

opentrons.protocol_api.labware.save_tip_length(labware: opentrons.protocol_api.labware.Labware, length: float)

Function to be used whenever an updated tip length is found for of a given tip rack. If an offset file does not exist, create the file using labware id as the filename. If the file does exist, load it and modify the length and the lastModified fields under the “tipLength” key.

Modules

class opentrons.protocol_api.contexts.TemperatureModuleContext(ctx: opentrons.protocol_api.contexts.ProtocolContext, hw_module: opentrons.hardware_control.modules.tempdeck.TempDeck, geometry: opentrons.protocol_api.labware.ModuleGeometry, loop: asyncio.events.AbstractEventLoop) → None

An object representing a connected Temperature Module.

It should not be instantiated directly; instead, it should be created through ProtocolContext.load_module() using: ctx.load_module('Temperature Module', slot_number).

A minimal protocol with a Temperature module would look like this:

Note

In order to prevent physical obstruction of other slots, place the Temperature Module in a slot on the horizontal edges of the deck (such as 1, 4, 7, or 10 on the left or 3, 6, or 7 on the right), with the USB cable and power cord pointing away from the deck.

deactivate()

Stop heating (or cooling) and turn off the fan.

labware

The labware (if any) present on this module.

load_labware(labware: opentrons.protocol_api.labware.Labware) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the module.

Parameters:labware – The labware object. This object should be already initialized and its parent should be set to this module’s geometry. To initialize and load a labware onto the module in one step, see load_labware_by_name().
Returns:The properly-linked labware object
load_labware_by_name(name: str) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the module.

Parameters:name – The name of the labware object.
Returns:The initialized and loaded labware object.
set_temperature(celsius: float)

Set the target temperature, in C.

Must be between 4 and 95C based on Opentrons QA.

Parameters:celsius – The target temperature, in C
target

Current target temperature in C

temperature

Current temperature in C

wait_for_temp()

Block until the module reaches its setpoint.

class opentrons.protocol_api.contexts.MagneticModuleContext(ctx: opentrons.protocol_api.contexts.ProtocolContext, hw_module: opentrons.hardware_control.modules.magdeck.MagDeck, geometry: opentrons.protocol_api.labware.ModuleGeometry, loop: asyncio.events.AbstractEventLoop) → None

An object representing a connected Temperature Module.

It should not be instantiated directly; instead, it should be created through ProtocolContext.load_module().

calibrate()

Calibrate the Magnetic Module.

The calibration is used to establish the position of the lawbare on top of the magnetic module.

disengage()

Lower the magnets back into the Magnetic Module.

engage(height: float = None, offset: float = None)

Raise the Magnetic Module’s magnets.

The destination of the magnets can be specified in several different ways, based on internally stored default heights for labware:

  • If neither height nor offset is specified, the magnets will raise to a reasonable default height based on the specified labware.
  • If height is specified, it should be a distance in mm from the home position of the magnets.
  • If offset is specified, it should be an offset in mm from the default position. A positive number moves the magnets higher and a negative number moves the magnets lower.

Only certain labwares have defined engage heights for the Magnetic Module. If a labware that does not have a defined engage height is loaded on the Magnetic Module (or if no labware is loaded), then height must be specified.

Parameters:
  • height – The height to raise the magnets to, in mm from home.
  • offset – An offset relative to the default height for the labware in mm
labware

The labware (if any) present on this module.

load_labware(labware: opentrons.protocol_api.labware.Labware) → opentrons.protocol_api.labware.Labware

Load labware onto a Magnetic Module, checking if it is compatible

load_labware_by_name(name: str) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the module.

Parameters:name – The name of the labware object.
Returns:The initialized and loaded labware object.
status

The status of the module. either ‘engaged’ or ‘disengaged’

class opentrons.protocol_api.contexts.ThermocyclerContext(ctx: opentrons.protocol_api.contexts.ProtocolContext, hw_module: opentrons.hardware_control.modules.thermocycler.Thermocycler, geometry: opentrons.protocol_api.labware.ThermocyclerGeometry, loop: asyncio.events.AbstractEventLoop) → None

An object representing a connected Temperature Module.

It should not be instantiated directly; instead, it should be created through ProtocolContext.load_module().

close()

Closes the lid

hold_time

Remaining hold time in sec

labware

The labware (if any) present on this module.

lid_status

Lid open/close status string

load_labware(labware: opentrons.protocol_api.labware.Labware) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the module.

Parameters:labware – The labware object. This object should be already initialized and its parent should be set to this module’s geometry. To initialize and load a labware onto the module in one step, see load_labware_by_name().
Returns:The properly-linked labware object
load_labware_by_name(name: str) → opentrons.protocol_api.labware.Labware

Specify the presence of a piece of labware on the module.

Parameters:name – The name of the labware object.
Returns:The initialized and loaded labware object.
open()

Opens the lid

ramp_rate

Current ramp rate in degrees C/sec

set_temperature(temp: float, hold_time: float = None, ramp_rate: float = None)

Set the target temperature, in C.

Valid operational range yet to be determined. :param temp: The target temperature, in degrees C. :param hold_time: The time to hold after reaching temperature. If

hold_time is not specified, the Thermocycler will hold this temperature indefinitely (requiring manual intervention to end the cycle).
Parameters:ramp_rate – The target rate of temperature change, in degC/sec. If ramp_rate is not specified, it will default to the maximum ramp rate as defined in the device configuration.
target

Target temperature in degrees C

temperature

Current temperature in degrees C

wait_for_temp()

Block until the module reaches its setpoint

Useful Types and Definitions

class opentrons.types.Location

A location to target as a motion in the Opentrons API Version 2.

The location contains a Point (in protocol-api-deck-coordinates) and possibly an associated Labware or Well instance.

It should rarely be constructed directly by the user; rather, it is the return type of most Well accessors like Well.top() and is passed directly into a method like InstrumentContext.aspirate().

Warning

The labware attribute of this class is used by the protocol API internals to, among other things, determine safe heights to retract the instruments to when moving between locations. If constructing an instance of this class manually, be sure to either specify None as the labware (so the robot does its worst case retraction) or specify the correct labware for the point attribute.

Warning

The == operation compares both the position and associated labware. If you only need to compare locations, compare the point of each item.

labware

Alias for field number 1

move(point: opentrons.types.Point) → opentrons.types.Location

Alter the point stored in the location while preserving the labware.

This returns a new Location and does not alter the current one. It should be used like

>>> loc = Location(Point(1, 1, 1), 'Hi')
>>> new_loc = loc.move(Point(1, 1, 1))
>>> assert loc_2.point == Point(2, 2, 2)  # True
>>> assert loc.point == Point(1, 1, 1)  # True
point

Alias for field number 0

class opentrons.types.Mount

An enumeration.

exception opentrons.types.PipetteNotAttachedError

An error raised if a pipette is accessed that is not attached

class opentrons.types.Point(x, y, z)
x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

class opentrons.types.TransferTipPolicy

An enumeration.

Deck Coordinates

The OT2’s base coordinate system is known as deck coordinates. This coordinate system is referenced frequently through the API. It is a right-handed coordinate system always specified in mm, with (0, 0, 0) at the front left of the robot. +x is to the right, +y is to the back, and +z is up.

Note that there are technically two z axes, one for each pipette mount. In these terms, z is the axis of the left pipette mount and a is the axis of the right pipette mount. These are obscured by the API’s habit of defining motion commands on a per-pipette basis; the pipettes internally select the correct z axis to move. This is also true of the pipette plunger axes, b (left) and c (right).

When locations are specified to functions like opentrons.protocol_api.contexts.InstrumentContext.move_to(), in addition to being an instance of opentrons.protocol_api.labware.Well they may define coordinates in this deck coordinate space. These coordinates can be specified either as a standard python tuple of three floats, or as an instance of the collections.namedtuple opentrons.types.Point, which can be created in the same way.