API Reference

If you are reading this, you are probably looking for an in-depth explanation of API classes and methods to fully master your protocol development skills.

Robot

All protocols are set up, simulated and executed using a Robot class.

class opentrons.legacy_api.robot.Robot(config=None)

This class is the main interface to the robot.

It should never be instantiated directly; instead, the global instance may be accessed at opentrons.robot.

Through this class you can can:
  • define your opentrons.Deck
  • connect() to Opentrons physical robot
  • home() axis, move head (move_to())
  • pause() and resume() the protocol run
  • set the head_speed() of the robot

Each Opentrons protocol is a Python script. When evaluated the script creates an execution plan which is stored as a list of commands in Robot’s command queue.

Here are the typical steps of writing the protocol:
  • Using a Python script and the Opentrons API load your containers and define instruments (see Pipette).
  • Call reset() to reset the robot’s state and clear commands.
  • Write your instructions which will get converted into an execution plan.
  • Review the list of commands generated by a protocol commands().
  • connect() to the robot and call run() it on a real robot.

See Pipette for the list of supported instructions.

add_instrument(mount, instrument)

Adds instrument to a robot.

Parameters:
  • mount (str) – Specifies which axis the instruments is attached to. Valid options are “left” or “right”.
  • instrument (Instrument) – An instance of a Pipette to attached to the axis.

Notes

A canonical way to add to add a Pipette to a robot is:

from opentrons import instruments
m300 = instruments.P300_Multi(mount='left')

This will create a pipette and call add_instrument() to attach the instrument.

connect(port=None, options=None)

Connects the robot to a serial port.

Parameters:
  • port (str) – OS-specific port name or 'Virtual Smoothie'
  • options (dict) – if port is set to 'Virtual Smoothie', provide the list of options to be passed to get_virtual_device()
Returns:

Return type:

True for success, False for failure.

Note

If you wish to connect to the robot without using the OT App, you will need to use this function.

Examples

>>> from opentrons import robot 
>>> robot.connect() 
disconnect()

Disconnects from the robot.

get_warnings()

Get current runtime warnings.

Returns:
  • Runtime warnings accumulated since the last run()
  • or simulate().
head_speed(combined_speed=None, x=None, y=None, z=None, a=None, b=None, c=None)

Set the speeds (mm/sec) of the robot

Parameters:
  • combined_speed (number specifying a combined-axes speed) –
  • <axis> (key/value pair, specifying the maximum speed of that axis) –

Examples

>>> from opentrons import robot 
>>> robot.reset() 
>>> robot.head_speed(combined_speed=400) 
#  sets the head speed to 400 mm/sec or the axis max per axis
>>> robot.head_speed(x=400, y=200) 
# sets max speeds of X and Y
home(*args, **kwargs)

Home robot’s head and plunger motors.

move_to(location, instrument, strategy='arc', **kwargs)

Move an instrument to a coordinate, container or a coordinate within a container.

Parameters:
  • location (one of the following:) – 1. Placeable (i.e. Container, Deck, Slot, Well) — will move to the origin of a container. 2. Vector move to the given coordinate in Deck coordinate system. 3. (Placeable, Vector) move to a given coordinate within object’s coordinate system.
  • instrument – Instrument to move relative to. If None, move relative to the center of a gantry.
  • strategy ({'arc', 'direct'}) –

    arc : move to the point using arc trajectory avoiding obstacles.

    direct : move to the point in a straight line.

pause(msg=None)

Pauses execution of the protocol. Use resume() to resume

reset()
Resets the state of the robot and clears:
  • Deck
  • Instruments
  • Command queue
  • Runtime warnings

Examples

>>> from opentrons import robot 
>>> robot.reset() 
resume()

Resume execution of the protocol after pause()

stop()

Stops execution of the protocol. (alias for halt)

Pipette

class opentrons.legacy_api.instruments.Pipette(robot, model_offset=(0, 0, 0), mount=None, axis=None, mount_obj=None, name=None, ul_per_mm=None, channels=1, min_volume=0, max_volume=None, trash_container='', tip_racks=[], aspirate_speed=5, dispense_speed=10, aspirate_flow_rate=None, dispense_flow_rate=None, plunger_current=0.5, drop_tip_current=0.5, plunger_positions={'top': 18.5, 'bottom': 2, 'blow_out': 0, 'drop_tip': -3.5}, pick_up_current=0.1, pick_up_distance=10, quirks=[], fallback_tip_length=51.7)

DIRECT USE OF THIS CLASS IS DEPRECATED – this class should not be used directly. Its parameters, defaults, methods, and behaviors are subject to change without a major version release. Use the model-specific constructors available through from opentrons import instruments.

All model-specific instrument constructors are inheritors of this class. With any of those instances you can can:

Here are the typical steps of using the Pipette:
  • Instantiate a pipette with a maximum volume (uL)

and a mount (left or right) * Design your protocol through the pipette’s liquid-handling commands

Methods in this class include assertions where needed to ensure that any action that requires a tip must be preceeded by pick_up_tip. For example: mix, transfer, aspirate, blow_out, and drop_tip.

Parameters:
  • mount (str) – The mount of the pipette’s actuator on the Opentrons robot (‘left’ or ‘right’)
  • trash_container (Container) – Sets the default location drop_tip() will put tips (Default: fixed-trash)
  • tip_racks (list) – A list of Containers for this Pipette to track tips when calling pick_up_tip() (Default: [])
  • aspirate_flow_rate (int) – The speed (in ul/sec) the plunger will move while aspirating (Default: See Model Type)
  • dispense_flow_rate (int) – The speed (in ul/sec) the plunger will move while dispensing (Default: See Model Type)
Returns:

Return type:

A new instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tip_rack_300ul = labware.load(
...     'GEB-tiprack-300ul', '1') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tip_rack_300ul]) 
aspirate(volume=None, location=None, rate=1.0)

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

Notes

If only a volume is passed, the pipette will aspirate from it’s current position. If only a location is passed, aspirate will default to it’s max_volume.

The location may be a Well, or a specific position in relation to a Well, such as Well.top(). If a Well is specified without calling a a position method (such as .top or .bottom), this method will default to the bottom of the well.

Parameters:
  • volume (int or float) – The number of microliters to aspirate (Default: self.max_volume)
  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the aspirate. Can also be a tuple with first item Placeable, second item relative Vector
  • rate (float) – Set plunger speed for this aspirate, where speed = rate * aspirate_speed (see set_speed())
Returns:

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '2') 
>>> p300 = instruments.P300_Single(mount='right') 
>>> p300.pick_up_tip() 
# aspirate 50uL from a Well
>>> p300.aspirate(50, plate[0]) 
# aspirate 50uL from the center of a well
>>> p300.aspirate(50, plate[1].bottom()) 
>>> # aspirate 20uL in place, twice as fast
>>> p300.aspirate(20, rate=2.0) 
>>> # aspirate the pipette's remaining volume (80uL) from a Well
>>> p300.aspirate(plate[2]) 
blow_out(location=None)

Force any remaining liquid to dispense, by moving this pipette’s plunger to the calibrated blow_out position

Notes

If no location is passed, the pipette will blow_out from it’s current position.

Parameters:location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the blow_out. Can also be a tuple with first item Placeable, second item relative Vector
Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, robot 
>>> robot.reset() 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.aspirate(50).dispense().blow_out() 
consolidate(volume, source, dest, *args, **kwargs)

Consolidate will move a volume of liquid from a list of sources to a single target location. See Transfer for details and a full list of optional arguments.

Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', 'A3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.consolidate(50, plate.cols[0], plate[1]) 
delay(seconds=0, minutes=0)
Parameters:seconds (float) – The number of seconds to freeze in place.
dispense(volume=None, location=None, rate=1.0)

Dispense a volume of liquid (in microliters/uL) using this pipette

Notes

If only a volume is passed, the pipette will dispense from it’s current position. If only a location is passed, dispense will default to it’s current_volume

The location may be a Well, or a specific position in relation to a Well, such as Well.top(). If a Well is specified without calling a a position method (such as .top or .bottom), this method will default to the bottom of the well.

Parameters:
  • volume (int or float) – The number of microliters to dispense (Default: self.current_volume)
  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the dispense. Can also be a tuple with first item Placeable, second item relative Vector
  • rate (float) – Set plunger speed for this dispense, where speed = rate * dispense_speed (see set_speed())
Returns:

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '3') 
>>> p300 = instruments.P300_Single(mount='left') 
# fill the pipette with liquid (200uL)
>>> p300.aspirate(plate[0]) 
# dispense 50uL to a Well
>>> p300.dispense(50, plate[0]) 
# dispense 50uL to the center of a well
>>> relative_vector = plate[1].center() 
>>> p300.dispense(50, (plate[1], relative_vector)) 
# dispense 20uL in place, at half the speed
>>> p300.dispense(20, rate=0.5) 
# dispense the pipette's remaining volume (80uL) to a Well
>>> p300.dispense(plate[2]) 
distribute(volume, source, dest, *args, **kwargs)

Distribute will move a volume of liquid from a single of source to a list of target locations. See Transfer for details and a full list of optional arguments.

Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.distribute(50, plate[1], plate.cols[0]) 
drop_tip(location=None, home_after=True)

Drop the pipette’s current tip

Notes

If no location is passed, the pipette defaults to its trash_container (see Pipette)

Parameters:location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the drop_tip. Can also be a tuple with first item Placeable, second item relative Vector
Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('tiprack-200ul', 'C2') 
>>> trash = labware.load('point', 'A3') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.pick_up_tip(tiprack[0]) 
# drops the tip in the fixed trash
>>> p300.drop_tip() 
>>> p300.pick_up_tip(tiprack[1]) 
# drops the tip back at its tip rack
>>> p300.drop_tip(tiprack[1]) 
home()

Home the pipette’s plunger axis during a protocol run

Notes

Pipette.home() homes the Robot

Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, robot 
>>> robot.reset() 
>>> p300 = instruments.P300_Single(mount='right') 
>>> p300.home() 
mix(repetitions=1, volume=None, location=None, rate=1.0)

Mix a volume of liquid (in microliters/uL) using this pipette

Notes

If no location is passed, the pipette will mix from it’s current position. If no volume is passed, mix will default to it’s max_volume

Parameters:
  • repetitions (int) – How many times the pipette should mix (Default: 1)
  • volume (int or float) – The number of microliters to mix (Default: self.max_volume)
  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the mix. Can also be a tuple with first item Placeable, second item relative Vector
  • rate (float) – Set plunger speed for this mix, where speed = rate * (aspirate_speed or dispense_speed) (see set_speed())
Returns:

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '4') 
>>> p300 = instruments.P300_Single(mount='left') 
# mix 50uL in a Well, three times
>>> p300.mix(3, 50, plate[0]) 
# mix 3x with the pipette's max volume, from current position
>>> p300.mix(3) 
move_to(location, strategy=None)

Move this Pipette to a Placeable on the Deck

Notes

Until obstacle-avoidance algorithms are in place, Robot and Pipette move_to() use either an “arc” or “direct”

Parameters:
  • location (Placeable or tuple(Placeable, Vector)) – The destination to arrive at
  • strategy ("arc" or "direct") – “arc” strategies (default) will pick the head up on Z axis, then over to the XY destination, then finally down to the Z destination. “direct” strategies will simply move in a straight line from the current position
Returns:

Return type:

This instance of Pipette.

pick_up_tip(location=None, presses=3, increment=1)

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

Notes

A tip can be manually set by passing a location. If no location is passed, the Pipette will pick up the next available tip in it’s tip_racks list (see Pipette)

Parameters:
  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the pick_up_tip. Can also be a tuple with first item Placeable, second item relative Vector
  • presses (:any: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 (:int) – The additional distance to travel on each successive press (e.g.: if presses=3 and increment=1, 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:

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('GEB-tiprack-300', '2') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tiprack]) 
>>> p300.pick_up_tip(tiprack[0]) 
>>> p300.return_tip() 
# `pick_up_tip` will automatically go to tiprack[1]
>>> p300.pick_up_tip() 
>>> p300.return_tip() 
return_tip(home_after=True)

Drop the pipette’s current tip to it’s originating tip rack

Notes

This method requires one or more tip-rack Container to be in this Pipette’s tip_racks list (see Pipette)

Returns:
Return type:This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> tiprack = labware.load('GEB-tiprack-300', '2') 
>>> p300 = instruments.P300_Single(mount='left',
...     tip_racks=[tiprack, tiprack2]) 
>>> p300.pick_up_tip() 
>>> p300.aspirate(50, plate[0]) 
>>> p300.dispense(plate[1]) 
>>> p300.return_tip() 
set_flow_rate(aspirate=None, dispense=None)

Set the speed (uL/second) the Pipette plunger will move during aspirate() and dispense(). The speed is set using nominal max volumes for any given pipette model. :param aspirate: The speed in microliters-per-second, at which the plunger will

move while performing an aspirate
Parameters:dispense (int) – The speed in microliters-per-second, at which the plunger will move while performing an dispense
touch_tip(location=None, radius=1.0, v_offset=-1.0, speed=60.0)

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

Notes

If no location is passed, the pipette will touch_tip from it’s current position.

Parameters:
  • location (Placeable or tuple(Placeable, Vector)) – The Placeable (Well) to perform the touch_tip. Can also be a tuple with first item Placeable, second item relative Vector
  • radius (float) – Radius is a floating point describing the percentage of a well’s radius. When radius=1.0, touch_tip() will move to 100% of the wells radius. When radius=0.5, touch_tip() will move to 50% of the wells radius. Default: 1.0 (100%)
  • 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
  • v_offset (float) – The offset in mm from the top of the well to touch tip. Default: -1.0 mm
Returns:

Return type:

This instance of Pipette.

Examples

>>> from opentrons import instruments, labware, robot 
>>> robot.reset() 
>>> plate = labware.load('96-flat', '8') 
>>> p300 = instruments.P300_Single(mount='left') 
>>> p300.aspirate(50, plate[0]) 
>>> p300.dispense(plate[1]).touch_tip() 
transfer(volume, source, dest, **kwargs)

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 Pipette commands, like aspirate and dispense, designed to make protocol writing easier at the cost of specificity.

Parameters:
  • volumes (number, list, or tuple) – The amount of volume to remove from each sources Placeable and add to each targets Placeable. If volumes 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 (Placeable or list) – Single Placeable or list of :any:`Placeable`s, from where liquid will be :any:`aspirate`ed from.
  • dest (Placeable or list) – Single Placeable or list of :any:`Placeable`s, where liquid will be :any:`dispense`ed to.
  • new_tip (number) – The number of clean tips this transfer command will use. If 0, no tips will be picked up nor dropped. If 1, a single tip will be used for all commands.
  • 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), 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) – Specify the number of repetitions volume to mix, and a mix will proceed each aspirate during the transfer and dispense. The tuple’s values is interpreted as (repetitions, volume).
  • mix_after (tuple) – Specify the number of repetitions volume to mix, and a mix will following each dispense during the transfer or consolidate. The tuple’s values is interpreted as (repetitions, volume).
  • carryover (boolean) – If True (default), any volumes that exceed the maximum volume of this Pipette will be split into multiple smaller volumes.
  • repeat (boolean) – (Only applicable to distribute and consolidate)If True (default), sequential aspirate volumes will be combined into one tip for the purpose of saving time. If False, all volumes will be transferred seperately.
  • gradient (lambda) – Function for calculated the curve used for gradient volumes. When volumes is a tuple of length 2, it’s 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:

Return type:

This instance of Pipette.

Examples

... >>> from opentrons import instruments, labware, robot # doctest: +SKIP >>> robot.reset() # doctest: +SKIP >>> plate = labware.load(‘96-flat’, ‘5’) # doctest: +SKIP >>> p300 = instruments.P300_Single(mount=’right’) # doctest: +SKIP >>> p300.transfer(50, plate[0], plate[1]) # doctest: +SKIP