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

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 command queue.
  • Write your instructions which will get converted into an execution plan.
  • Review the list of commands in the robot’s queue by running commands().
  • Call simulate() to run the protocol it against a virtual robot.
  • connect() to the robot and call run() it on a real robot.

See Pipette for the list of supported instructions.

Examples

>>> from opentrons import Robot
>>> from opentrons import instruments, containers
>>> robot = Robot()
>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> plate = containers.load('96-flat', 'A1', 'plate')
>>> p200 = instruments.Pipette(axis='b', max_volume=200)
>>> p200.aspirate(200, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> robot.commands()
['Aspirating 200 at <Deck><Slot A1><Container plate><Well A1>']
>>> robot.simulate()
[]
actions

Return a copy of a raw list of commands in the Robot’s queue.

add_instrument(axis, instrument)

Adds instrument to a robot.

Parameters:
  • axis (str) – Specifies which axis the instruments is attached to.
  • 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.instruments.pipette import Pipette
p200 = Pipette(axis='a')

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

commands()

Access the human-readable list of commands in the robot’s queue.

Returns:
  • A list of string values for each command in the queue, for example
  • 'Aspirating 200uL at <Deck>/<Slot A1>/<Container plate>/<Well A1>'
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.

containers()

Returns the dict with all of the containers on the deck.

diagnostics()

Access diagnostics information for the robot.

Returns:
  • axis_homed — axis that are currently in home position.
  • switches — end stop switches currently hit.
  • steps_per_mm — steps per millimeter calibration

values for x and y axis.

Return type:Dictionary with the following keys
disconnect()

Disconnects from the robot.

get_mosfet(mosfet_index)

Get MOSFET for a MagBead (URL).

Parameters:mosfet_index (int) – Number of a MOSFET on MagBead.
Returns:
Return type:Instance of InstrumentMosfet.
get_motor(axis)

Get robot’s head motor.

Parameters:axis ({'a', 'b'}) – Axis name. Please check stickers on robot’s gantry for the name.
get_warnings()

Get current runtime warnings.

Returns:
head_speed(*args, **kwargs)

Set the XY axis speeds of the robot, set in millimeters per minute

Parameters:rate (int) – An integer setting the mm/minute rate of the X and Y axis. Speeds too fast (around 6000 and higher) will cause the robot to skip step, be careful when using this method

Examples

>>> from opentrons import robot
>>> robot.connect('Virtual Smoothie')
>>> robot.home()
>>> robot.head_speed(4500)
>>> robot.move_head(x=200, y=200)
home(*args, **kwargs)

Home robot’s head and plunger motors.

Parameters:
  • *args

    A string with axes to home. For example 'xyz' or 'ab'.

    If no arguments provided home Z-axis then X, Y, B, A

  • enqueue ({True, False} Default: False) – If True put into command queue, if False execute immediately.

Notes

Sometimes while executing a long protocol, a robot might accumulate precision error and it is recommended to home it. In this scenario, add robot.home('xyzab', enqueue=True) into your script.

Examples

>>> from opentrons import Robot
>>> robot.connect('Virtual Smoothie')
>>> robot.home()
move_to(location, instrument=None, 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.

Examples

>>> from opentrons import Robot
>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> robot.connect('Virtual Smoothie')
>>> robot.home()
>>> plate = robot.add_container('96-flat', 'A1', 'plate')
>>> robot.move_to(plate[0])
>>> robot.move_to(plate[0].top())
pause()

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

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

Resume execution of the protocol after pause()

run(**kwargs)

Run the command queue on a device provided in connect().

Notes

If connect() was called with port='Virtual Smoothie' it will execute similar to simulate().

Examples

>>> from opentrons import Robot
>>> from opentrons.instruments.pipette import Pipette
>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> robot.connect('Virtual Smoothie')
>>> robot.home()
>>> plate = robot.add_container('96-flat', 'A1', 'plate')
>>> p200 = Pipette(axis='a')
>>> robot.move_to(plate[0])
>>> robot.move_to(plate[0].top())
simulate(switches=False)

Simulate a protocol run on a virtual robot.

It is recommended to call this method before running the protocol on a real robot.

Parameters:switches (bool) – If True tells the robot to stop execution and throw an error if limit switch was hit.
stop()

Stops execution of the protocol.

Pipette

class opentrons.instruments.Pipette(axis, name=None, channels=1, min_volume=0, max_volume=None, trash_container=None, tip_racks=[], aspirate_speed=300, dispense_speed=500)
Through this class you can can:
Here are the typical steps of using the Pipette:
  • Instantiate a pipette with a maximum volume (uL)

and an axis (a or b) * Design your protocol through the pipette’s liquid-handling commands * Run on the Robot using run or simulate

Parameters:
  • axis (str) – The axis of the pipette’s actuator on the Opentrons robot (‘a’ or ‘b’)
  • name (str) – Assigns the pipette a unique name for saving it’s calibrations
  • channels (int) – The number of channels on this pipette (Default: 1)
  • min_volume (int) – The smallest recommended uL volume for this pipette (Default: 0)
  • max_volume (int) – The largest uL volume for this pipette (Default: min_volume + 1)
  • trash_container (Container) – Sets the default location drop_tip() will put tips (Default: None)
  • tip_racks (list) – A list of Containers for this Pipette to track tips when calling pick_up_tip() (Default: [])
  • aspirate_speed (int) – The speed (in mm/minute) the plunger will move while aspirating (Default: 300)
  • dispense_speed (int) – The speed (in mm/minute) the plunger will move while dispensing (Default: 500)
Returns:

Return type:

A new instance of Pipette.

Examples

>>> from opentrons import instruments, containers
>>> p1000 = instruments.Pipette(axis='a', max_volume=1000)
>>> tip_rack_200ul = containers.load('tiprack-200ul', 'A1')
>>> p200 = instruments.Pipette(
...     axis='b',
...     max_volume=200,
...     tip_racks=[tip_rack_200ul])
aspirate(volume=None, location=None, rate=1.0, enqueue=True)

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

Notes

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

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())
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a', max_volume=200)
>>> # aspirate 50uL from a Well
>>> p200.aspirate(50, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # aspirate 50uL from the center of a well
>>> relative_vector = plate[1].center()
>>> p200.aspirate(50, (plate[1], relative_vector)) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # aspirate 20uL in place, twice as fast
>>> p200.aspirate(20, rate=2.0) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # aspirate the pipette's remaining volume (80uL) from a Well
>>> p200.aspirate(plate[2]) 
<opentrons.instruments.pipette.Pipette object at ...>
blow_out(location=None, enqueue=True)

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
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a', max_volume=200)
>>> p200.aspirate(50).dispense().blow_out() 
<opentrons.instruments.pipette.Pipette object at ...>
calibrate(position)

Calibrate a saved plunger position to the robot’s current position

Notes

This will only work if the API is connected to a robot

Parameters:position (str) – Either “top”, “bottom”, “blow_out”, or “drop_tip”
Returns:
Return type:This instance of Pipette.

Examples

>>> robot = Robot()
>>> p200 = instruments.Pipette(axis='a')
>>> robot.move_plunger(**{'a': 10})
>>> # save plunger 'top' to coordinate 10
>>> p200.calibrate('top') 
<opentrons.instruments.pipette.Pipette object at ...>
calibrate_position(location, current=None)

Save the position of a Placeable (usually a Container) relative to this pipette.

Notes

The saved position will be persisted under this pipette’s name and axis (see Pipette)

Parameters:
  • location (tuple(Placeable, Vector)) – A tuple with first item Placeable, second item relative Vector
  • current (Vector) – The coordinate to save this container to (Default: robot current position)
Returns:

Return type:

This instance of Pipette.

Examples

>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> tiprack = containers.load('tiprack-200ul', 'A1')
>>> p200 = instruments.Pipette(axis='a')
>>> robot.move_head(x=100, y=100, z=100)
>>> rel_pos = tiprack[0].from_center(x=0, y=0, z=-1, reference=tiprack)
>>> p200.calibrate_position((tiprack, rel_pos)) 
<opentrons.instruments.pipette.Pipette object at ...>
delay(seconds=0, minutes=0, enqueue=True)
Parameters:
  • seconds (float) – The number of seconds to freeeze in place.
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
dispense(volume=None, location=None, rate=1.0, enqueue=True)

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

Notes

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

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())
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a', max_volume=200)
>>> # fill the pipette with liquid (200uL)
>>> p200.aspirate(plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # dispense 50uL to a Well
>>> p200.dispense(50, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # dispense 50uL to the center of a well
>>> relative_vector = plate[1].center()
>>> p200.dispense(50, (plate[1], relative_vector)) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # dispense 20uL in place, at half the speed
>>> p200.dispense(20, rate=0.5) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # dispense the pipette's remaining volume (80uL) to a Well
>>> p200.dispense(plate[2]) 
<opentrons.instruments.pipette.Pipette object at ...>
drop_tip(location=None, home_after=True, enqueue=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
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> tiprack = containers.load('tiprack-200ul', 'A1')
>>> trash = containers.load('point', 'A1')
>>> p200 = instruments.Pipette(axis='a', trash_container=trash)
>>> p200.pick_up_tip(tiprack[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # drops the tip in the trash
>>> p200.drop_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.pick_up_tip(tiprack[1]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # drops the tip back at its tip rack
>>> p200.drop_tip(tiprack[1]) 
<opentrons.instruments.pipette.Pipette object at ...>
home(enqueue=True)

Home the pipette’s plunger axis during a protocol run

Notes

Pipette.home() enqueues to Robot commands (see run and simulate)

Parameters:enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:
Return type:This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a')
>>> p200.home() 
<opentrons.instruments.pipette.Pipette object at ...>
mix(repetitions=1, volume=None, location=None, rate=1.0, enqueue=True)

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())
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a', max_volume=200)
>>> # mix 50uL in a Well, three times
>>> p200.mix(3, 50, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # mix 3x with the pipette's max volume, from current position
>>> p200.mix(3) 
<opentrons.instruments.pipette.Pipette object at ...>
move_to(location, strategy='arc', enqueue=True)

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
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

pick_up_tip(location=None, presses=3, enqueue=True)

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
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> tiprack = containers.load('tiprack-200ul', 'A1')
>>> p200 = instruments.Pipette(axis='a', tip_racks=[tiprack])
>>> p200.pick_up_tip(tiprack[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.return_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
>>> # `pick_up_tip` will automatically go to tiprack[1]
>>> p200.pick_up_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.return_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
return_tip(home_after=True, enqueue=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)

Parameters:enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:
Return type:This instance of Pipette.

Examples

>>> robot.reset() 
<opentrons.robot.robot.Robot object at ...>
>>> tiprack = containers.load('tiprack-200ul', 'A1')
>>> p200 = instruments.Pipette(axis='a', tip_racks=[tiprack])
>>> p200.pick_up_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.aspirate(50, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.dispense(plate[1]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.return_tip() 
<opentrons.instruments.pipette.Pipette object at ...>
set_speed(**kwargs)

Set the speed (mm/minute) the Pipette plunger will move during aspirate() and dispense()

Parameters:kwargs (Dict) – A dictionary who’s keys are either “aspirate” or “dispense”, and who’s values are int or float (Example: {“aspirate”: 300})
touch_tip(location=None, radius=1.0, enqueue=True)

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 number between 0.0 and 1.0, 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.
  • enqueue (bool) – If set to True (default), the method will be appended to the robots list of commands for executing during run or simulate. If set to False, the method will skip the command queue and execute immediately
Returns:

Return type:

This instance of Pipette.

Examples

>>> p200 = instruments.Pipette(axis='a', max_volume=200)
>>> p200.aspirate(50, plate[0]) 
<opentrons.instruments.pipette.Pipette object at ...>
>>> p200.dispense(plate[1]).touch_tip() 
<opentrons.instruments.pipette.Pipette object at ...>