Opentrons API Version 4

For the OT 1 API, please go to this link

For Version 3 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 4 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 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.

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])

Commands

And finally, the most fun section, 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.

Robot and Pipette

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)

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:

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.

The keys will be ‘aspirate’ and ‘dispense’.

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) → opentrons.protocol_api.contexts.InstrumentContext

Move the instrument.

Parameters:location (types.Location) – The location to move to.
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

    Note

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

  • 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

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.

class opentrons.protocol_api.transfers.TransferOptions

All available options for a transfer, distribute or consolidate function

aspirate

Option to customize aspirate rate. See AspirateOpts.

blow_out

Option to specify custom location for blow out. See BlowOutOpts.

dispense

Option to customize dispense rate. See DispenseOpts.

mix

Options to control mix behavior before aspirate and after dispense. See Mix.

pick_up_tip

Options used when picking up a tip during transfer. See PickUpTipOpts.

touch_tip

Options to customize touch tip. See TouchTipOpts.

transfer

Options pertaining to behavior of the transfer.

For instance you can control how frequently to get a new tip using Transfer.new_tip. For documentation of all transfer options see Transfer.

class opentrons.protocol_api.transfers.Transfer

Options pertaining to behavior of the transfer.

air_gap

Controls the volume (in uL) of air gap aspirated when moving to dispense.

Adding an air gap would slow down a transfer since less liquid will now fit in the pipette but it prevents the loss of liquid while moving between wells.

blow_out_strategy

Specifies the location to blow out the liquid in the pipette to.

BlowOutStrategy.TRASH
Blow out to trash container.
BlowOutStrategy.DEST_IF_EMPTY
If the volume in the current tip is 0 (expected), then blow out to the destination well in order to dispense any leftover liquid.
BlowOutStrategy.CUSTOM_LOCATION
If using any other location to blow out to. Specify the location in TransferOptions.blow_out.
carryover

Controls whether volumes larger than pipette’s max volume will be split into smaller volumes.

disposal_volume

The amount of liquid (in uL) to aspirate as a buffer.

The remaining buffer will be blown out into the location specified by blow_out_strategy.

This is useful to avoid under-pipetting but can waste reagent and slow down transfer.

drop_tip_strategy

Specifies the location to drop tip into.

DropTipStrategy.TRASH
Drop the tip into the trash container.
DropTipStrategy.RETURN
Return the tip to tiprack.
gradient_function

Specify a nonlinear gradient for volumes.

This should be a function that takes a single float between 0 and 1 and returns a single float between 0 and 1. This function is used to determine the path the transfer takes between the volume gradient minimum and maximum if the transfer volume is specified as a gradient. For instance, specifying the function as

def gradient(a):
    if a > 0.5:
        return 1.0
    else:
        return 0.0

would transfer the minimum volume of the gradient to the first half of the target wells, and the maximum to the other half.

mix_strategy

If and when to mix during a transfer.

MixStrategy.NEVER
Do not ever perform a mix during the transfer.
MixStrategy.BEFORE
Mix before each aspirate.
MixStrategy.AFTER
Mix after each dispense.
MixStrategy.BOTH
Mix before each aspirate and after each dispense.

To customize the mix behavior, see TransferOptions.mix

new_tip

Control when or if to pick up tip during a transfer

types.TransferTipPolicy.ALWAYS
Drop and pick up a new tip after each dispense.
types.TransferTipPolicy.ONCE
Pick up tip at the beginning of the transfer and use it throughout the transfer. This would speed up the transfer.
types.TransferTipPolicy.NEVER
Do not ever pick up or drop tip. The protocol should explicitly pick up a tip before transfer and drop it afterwards.

To customize where to drop tip, see drop_tip_strategy. To customize the behavior of pickup tip, see TransferOptions.pick_up_tip.

touch_tip_strategy

Controls whether to touch tip during the transfer

This helps in getting rid of any droplets clinging to the pipette tip at the cost of slowing down the transfer.

TouchTipStrategy.NEVER
Do not touch tip ever during the transfer.
TouchTipStrategy.ALWAYS
Touch tip after each aspirate.

To customize the behavior of touch tips, see TransferOptions.touch_tip.

class opentrons.protocol_api.transfers.PickUpTipOpts

Options to customize Transfer.new_tip.

These options will be passed to InstrumentContext.pick_up_tip() when it is called during the transfer.

increment

int

location

types.Location

presses

int

class opentrons.protocol_api.transfers.MixOpts

Options to customize behavior of mix.

These options will be passed to InstrumentContext.mix() when it is called during the transfer.

rate

float

repetitions

int

volume

float

class opentrons.protocol_api.transfers.Mix

Options to control mix behavior before aspirate and after dispense.

mix_after

Options applied to mix after dispense. See Mix.MixOpts.

mix_before

Options applied to mix before aspirate. See Mix.MixOpts.

class opentrons.protocol_api.transfers.BlowOutOpts

Location where to blow out instead of the trash.

This location will be passed to InstrumentContext.blow_out() when called during the transfer

location

types.Location

class opentrons.protocol_api.transfers.TouchTipOpts

Options to customize touch tip.

These options will be passed to InstrumentContext.touch_tip() when called during the transfer.

radius

float

speed

float

v_offset

float

class opentrons.protocol_api.transfers.AspirateOpts

Option to customize aspirate rate.

This option will be passed to InstrumentContext.aspirate() when called during the transfer.

rate

float

class opentrons.protocol_api.transfers.DispenseOpts

Option to customize dispense rate.

This option will be passed to InstrumentContext.dispense() when called during the transfer.

rate

float

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.

Valid Labware

This section 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 4.0 Labware Name API 3.x 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-tubrack-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_50_mL_falcon 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 usa_scientific_12_trough_22_mL

Useful Types and Definitions

class opentrons.types.Location

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

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

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.