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.Robot(config=None)

This class is the main interface to the robot.

Through this class you can can:

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.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}, 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() 
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]) 
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()