API Version 2 Reference

Protocols

class opentrons.protocol_api.ProtocolContext(api_version: APIVersion, core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], broker: Optional[LegacyBroker] = None, core_map: Optional[LoadedCoreMap] = None, deck: Optional[Deck] = None, bundled_data: Optional[Dict[str, bytes]] = None)

A context for the state of a protocol.

The ProtocolContext class provides the objects, attributes, and methods that allow you to configure and control the protocol.

Methods generally fall into one of two categories.

• They can change the state of the ProtocolContext object, such as adding pipettes, hardware modules, or labware to your protocol.

• They can control the flow of a running protocol, such as pausing, displaying messages, or controlling built-in robot hardware like the ambient lighting.

Do not instantiate a ProtocolContext directly. The run() function of your protocol does that for you. See the Tutorial for more information.

Use opentrons.execute.get_protocol_api() to instantiate a ProtocolContext when using Jupyter Notebook. See Advanced Control.

New in version 2.0.

property api_version: APIVersion

Return the API version specified for this protocol context.

This value is set when the protocol context is initialized.

• When the context is the argument of run(), the "apiLevel" key of the metadata or requirements dictionary determines api_version.

• When the context is instantiated with opentrons.execute.get_protocol_api() or opentrons.simulate.get_protocol_api(), the value of its version argument determines api_version.

It may be lower than the maximum version supported by the robot software, which is accessible via the protocol_api.MAX_SUPPORTED_VERSION constant.

New in version 2.0.

property bundled_data: Dict[str, bytes]

Accessor for data files bundled with this protocol, if any.

This is a dictionary mapping the filenames of bundled datafiles to their contents. The filename keys are formatted with extensions but without paths. For example, a file stored in the bundle as data/mydata/aspirations.csv will have the key "aspirations.csv". The values are bytes objects representing the contents of the files.

New in version 2.0.

capture_image(self, home_before: 'Optional[bool]' = False, filename: 'Optional[str]' = None, resolution: 'Optional[Tuple[int, int]]' = None, zoom: 'Optional[float]' = None, contrast: 'Optional[float]' = None, brightness: 'Optional[float]' = None, saturation: 'Optional[float]' = None) → 'None'

Capture an image using the camera. Captured images are saved as during the protocol run.

Parameters:

• home_before – If True, homes the pipette before capturing an image.

• filename – Custom name to use when saving the captured image as a file. The custom name is added as the beginning of the filename, followed by the robot and protocol name, a timestamp for the protocol run, the step number, and a timestamp for the command running when the image was captured.

• resolution – Accepts a width and height (as a tuple) to determine the camera’s resolution when capturing the image.

• zoom – Zoom level the camera will use. Defaults to the minimum of 1x zoom (1.0) and has a maximum of 2x zoom (2.0).

• contrast – The contrast level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (0.0 to 100.0).

• brightness – The brightness level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (0.0 to 100.0).

• saturation – The saturation level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (0.0 to 100.0).

New in version 2.27.

commands(self) → 'List[str]'

Return the run log.

This is a list of human-readable strings representing what’s been done in the protocol so far. For example, “Aspirating 123 µL from well A1 of 96 well plate in slot 1.”

The exact format of these entries is not guaranteed. The format here may differ from other places that show the run log, such as the Opentrons App or touchscreen.

New in version 2.0.

comment(self, msg: 'str') → 'None'

Add a user-readable message to the run log.

The message is visible anywhere you can view the run log, including the Opentrons App and the touchscreen on Flex.

Note

The value of the message is computed during protocol analysis, so comment() can’t communicate real-time information during the actual protocol run.

New in version 2.0.

create_timer(self, seconds: 'float') → 'Task'

Create a timer Task that runs in the background.

Parameters:

seconds (float) – The time to delay in seconds.

This timer will continue to run until it is complete and will not block subsequent commands.

New in version 2.27.

property deck: Deck

An interface to provide information about what’s currently loaded on the deck. This object is useful for determining if a slot on the deck is free.

This object behaves like a dictionary whose keys are the deck slot names. For instance, deck[1], deck["1"], and deck["D1"] will all return the object loaded in the front-left slot.

The value for each key depends on what is loaded in the slot:

• A Labware if the slot contains a labware.

• A module context if the slot contains a hardware module.

• None if the slot doesn’t contain anything.

A module that occupies multiple slots is set as the value for all of the relevant slots. Currently, the only multiple-slot module is the Thermocycler. When loaded, the ThermocyclerContext object is the value for deck keys "A1" and "B1" on Flex, and 7, 8, 10, and 11 on OT-2. In API version 2.13 and earlier, only slot 7 keyed to the Thermocycler object, and slots 8, 10, and 11 keyed to None.

Rather than filtering the objects in the deck map yourself, you can also use loaded_labwares to get a dict of labwares and loaded_modules to get a dict of modules.

For Advanced Control only, you can delete an element of the deck dict. This only works for deck slots that contain labware objects. For example, if slot 1 contains a labware, del protocol.deck["1"] will free the slot so you can load another labware there.

Warning

Deleting labware from a deck slot does not pause the protocol. Subsequent commands continue immediately. If you need to physically move the labware to reflect the new deck state, add a pause() or use move_labware() instead.

Changed in version 2.14: Includes the Thermocycler in all of the slots it occupies.

Changed in version 2.15: del sets the corresponding labware’s location to OFF_DECK.

New in version 2.0.

define_liquid(self, name: str, description: Optional[str] = None, display_color: Optional[str] = None)

Define a liquid within a protocol.

Parameters:

• name (str) – A human-readable name for the liquid.

• description (Optional[str]) – An optional description of the liquid.

• display_color (Optional[str]) – An optional hex color code, with hash included, to represent the specified liquid. For example, "#48B1FA". Standard three-value, four-value, six-value, and eight-value syntax are all acceptable.

Returns:

A Liquid object representing the specified liquid.

Changed in version 2.20: You can now omit the description and display_color arguments. Formerly, when you didn’t want to provide values, you had to supply description=None and display_color=None explicitly.

New in version 2.14.

define_liquid_class(self, name: 'str', properties: 'Dict[str, Dict[str, TransferPropertiesDict]]', base_liquid_class: 'Optional[LiquidClass]' = None, display_name: 'Optional[str]' = None) → 'LiquidClass'

Define a custom liquid class, either based on an existing liquid class, or create a completely new one.

Parameters:

• name – The name to give to the new liquid class. Cannot use the name of an Opentrons-verified liquid class.

• properties – A dict of transfer properties for pipette and tip combinations to use for liquid class transfers. The nested dictionary must have top-level keys corresponding to pipette load names and second-level keys corresponding to compatible tip rack load names. Further nested key–value pairs should be as specified in TransferPropertiesDict. See the liquid class type definitions.

• base_liquid_class – An existing liquid class object to base the newly defined liquid class on. The specified transfer_properties will override any existing properties for the specified pipette and tip combinations. All other properties will remain the same as those in the base class.

• display_name – An optional name for the liquid class. Defaults to the title-case name if a display name isn’t provided.

Returns:

A new LiquidClass object.

New in version 2.24.

delay(self, seconds: 'float' = 0, minutes: 'float' = 0, msg: 'Optional[str]' = None) → 'None'

Delay protocol execution for a specific amount of time.

Parameters:

• seconds (float) – The time to delay in seconds.

• minutes (float) – The time to delay in minutes.

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

New in version 2.0.

property door_closed: bool

Returns True if the front door of the robot is closed.

New in version 2.5.

property fixed_trash: Union[Labware, TrashBin]

The trash fixed to slot 12 of an OT-2’s deck.

In API version 2.15 and earlier, the fixed trash is a Labware object with one well. Access it like labware in your protocol. For example, protocol.fixed_trash["A1"].

In API version 2.15 only, Flex protocols have a fixed trash in slot A3.

In API version 2.16 and later, the fixed trash only exists in OT-2 protocols. It is a TrashBin object, which doesn’t have any wells. Trying to access fixed_trash in a Flex protocol will raise an error. See Trash Bin for details on using the movable trash in Flex protocols.

Changed in version 2.16: Returns a TrashBin object.

New in version 2.0.

get_liquid_class(self, name: 'str', version: 'Optional[int]' = None) → 'LiquidClass'

Get an instance of an Opentrons-verified liquid class for use in a Flex protocol.

Parameters:

• name –

  Name of an Opentrons-verified liquid class. Must be one of:

  • "water": an Opentrons-verified liquid class based on deionized water.

  • "glycerol_50": an Opentrons-verified liquid class for viscous liquid. Based on 50% glycerol.

  • "ethanol_80": an Opentrons-verified liquid class for volatile liquid. Based on 80% ethanol.

• version – Version of the liquid class to retrieve. If left unspecified, defaults to the latest version for the protocol’s API level.

Raises:

LiquidClassDefinitionDoesNotExist: if the specified liquid class does not exist.

Returns:

A new LiquidClass object.

New in version 2.24.

home(self) → 'None'

Home the movement system of the robot.

New in version 2.0.

is_simulating(self) → 'bool'

Returns True if the protocol is running in simulation.

Returns False if the protocol is running on actual hardware.

You can evaluate the result of this method in an if statement to make your protocol behave differently in different environments. For example, you could refer to a data file on your computer when simulating and refer to a data file stored on the robot when not simulating.

You can also use it to skip time-consuming aspects of your protocol. Most Python Protocol API methods, like delay(), are designed to evaluate instantaneously in simulation. But external methods, like those from the time module, will run at normal speed if not skipped.

New in version 2.0.

load_adapter(self, load_name: 'str', location: 'Union[DeckLocation, OffDeckType]', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto a location.

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

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

Parameters:

• load_name (str) – A string to use for looking up a labware definition for the adapter. You can find the load_name for any standard adapter on the Opentrons Labware Library.

• location (int or str or OFF_DECK) – Either a deck slot, like 1, "1", or "D1", or the special value OFF_DECK.

• namespace (str) –

  The namespace that the labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.

  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons standard definition, and you want to explicitly choose one or the other.

• version – The version of the labware definition. You should normally leave this unspecified to let load_adapter() choose a version automatically.

New in version 2.15.

load_adapter_from_definition(self, adapter_def: "'LabwareDefinition'", location: 'Union[DeckLocation, OffDeckType]') → 'Labware'

Specify the presence of an adapter on the deck.

This function loads the adapter definition specified by adapter_def to the location specified by location.

Parameters:

• adapter_def – The adapter’s labware definition.

• location (int or str or OFF_DECK) – The slot into which to load the labware, such as 1, "1", or "D1". See Deck Slots.

New in version 2.15.

load_instrument(self, instrument_name: 'str', mount: 'Union[Mount, str, None]' = None, tip_racks: 'Optional[List[Labware]]' = None, replace: 'bool' = False, liquid_presence_detection: 'Optional[bool]' = None) → 'InstrumentContext'

Load a specific instrument for use in the protocol.

When analyzing the protocol on the robot, instruments loaded with this method are compared against the instruments attached to the robot. You won’t be able to start the protocol until the correct instruments are attached and calibrated.

Currently, this method only loads pipettes. You do not need to load the Flex Gripper to use it in protocols. See Automatic vs Manual Moves.

Parameters:

• instrument_name (str) – The instrument to load. See API Load Names for the valid values.

• mount (types.Mount or str or None) – The mount where the instrument should be attached. This can either be an instance of types.Mount or one of the strings "left" or "right". When loading a Flex 96-Channel Pipette (instrument_name="flex_96channel_1000"), you can leave this unspecified, since it always occupies both mounts; if you do specify a value, it will be ignored.

• tip_racks (List[Labware]) – A list of tip racks from which to pick tips when calling InstrumentContext.pick_up_tip() without arguments.

• replace (bool) – If True, replace the currently loaded instrument in mount, if any. This is intended for advanced control applications. You cannot replace an instrument in the middle of a protocol being run from the Opentrons App or touchscreen.

• liquid_presence_detection (bool) –

  If True, enable automatic liquid presence detection for Flex 1-, 8-, or 96-channel pipettes.

  New in version 2.20.

New in version 2.0.

load_labware(self, load_name: 'str', location: 'Union[DeckLocation, OffDeckType]', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto a location.

For Opentrons-verified labware, this is a convenient 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:

• load_name (str) – A string to use for looking up a labware definition. You can find the load_name for any Opentrons-verified labware on the Labware Library.

• location (int or str or OFF_DECK) –

  Either a deck slot, like 1, "1", or "D1", or the special value OFF_DECK.

  Changed in version 2.15: You can now specify a deck slot as a coordinate, like "D1".

• label (str) – An optional special name to give the labware. If specified, this is how the labware will appear in the run log, Labware Position Check, and elsewhere in the Opentrons App and on the touchscreen.

• namespace (str) –

  The namespace that the labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.

  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version – The version of the labware definition. You should normally leave this unspecified to let load_labware() choose a version automatically.

• adapter –

  The load name of an adapter to load the labware on top of. Accepts the same values as the load_name parameter of load_adapter().

  New in version 2.15.

• adapter_namespace –

  The namespace of the adapter being loaded. Applies to adapter the same way that namespace applies to load_name.

  Changed in version 2.26: adapter_namespace may now be specified explicitly. When you’ve specified namespace for load_name but not adapter_namespace, adapter_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• adapter_version –

  The version of the adapter being loaded. Applies to adapter the same way that version applies to load_name.

  Changed in version 2.26: adapter_version may now be specified explicitly. When unspecified, the API uses the newest version available for your protocol’s API level.

• lid –

  A lid to load on the top of the main labware. Accepts the same values as the load_name parameter of load_lid_stack(). The lid will use the same namespace as the labware, and the API will choose the lid’s version automatically.

  New in version 2.23.

• lid_namespace –

  The namespace of the lid being loaded. Applies to lid the same way that namespace applies to load_name.

  Changed in version 2.26: lid_namespace may now be specified explicitly. When you’ve specified namespace for load_name but not lid_namespace, lid_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• lid_version –

  The version of the adapter being loaded. Applies to lid the same way that version applies to load_name.

  Changed in version 2.26: lid_version may now be specified explicitly. When unspecified, the API uses the newest version available for your protocol’s API level.

New in version 2.0.

load_labware_by_name(self, load_name: 'str', location: 'DeckLocation', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'int' = 1) → 'Labware'

Deprecated since version 2.0: Use load_labware() instead.

New in version 2.0.

load_labware_from_definition(self, labware_def: "'LabwareDefinition'", location: 'Union[DeckLocation, OffDeckType]', label: 'Optional[str]' = None) → 'Labware'

Specify the presence of a labware on the deck.

This function loads the labware definition specified by labware_def to the location specified by location.

Parameters:

• labware_def – The labware’s definition.

• location (int or str or OFF_DECK) – The slot into which to load the labware, such as 1, "1", or "D1". See Deck Slots.

• label (str) – An optional special name to give the labware. If specified, this is how the labware will appear in the run log, Labware Position Check, and elsewhere in the Opentrons App and on the touchscreen.

New in version 2.0.

load_lid_stack(self, load_name: 'str', location: 'Union[DeckLocation, Labware]', quantity: 'int', adapter: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None) → 'Labware'

Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.

Parameters:

• load_name (str) –

  A string to use for looking up a lid definition. You can find the load_name for any compatible lid on the Opentrons Labware Library.

• location – Either a deck slot, like 1, "1", or "D1", or a valid Opentrons Adapter.

• quantity (int) – The quantity of lids to be loaded in the stack.

• adapter – An adapter to load the lid stack on top of. Accepts the same values as the load_name parameter of load_adapter(). The adapter will use the same namespace as the lid labware, and the API will choose the adapter’s version automatically.

• namespace (str) –

  The namespace that the lid labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.

  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version – The version of the labware definition. You should normally leave this unspecified to let load_lid_stack() choose a version automatically.

• adapter_namespace –

  The namespace of the adapter being loaded. Applies to adapter the same way that namespace applies to load_name.

  Changed in version 2.26: adapter_namespace may now be specified explicitly. When you’ve specified namespace for load_name but not adapter_namespace, adapter_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• adapter_version –

  The version of the adapter being loaded. Applies to adapter the same way that version applies to load_name.

  New in version 2.26: adapter_version may now be specified explicitly.

Returns:

The initialized and loaded labware object representing the lid stack.

New in version 2.23.

New in version 2.23.

load_module(self, module_name: 'str', location: 'Optional[DeckLocation]' = None, configuration: 'Optional[str]' = None) → 'ModuleTypes'

Load a module onto the deck, given its name or model.

This is the function to call to use a module in your protocol, like load_instrument() is the method to call to use an instrument in your protocol. It returns the created and initialized module context, which will be a different class depending on the kind of module loaded.

After loading modules, you can access a map of deck positions to loaded modules with loaded_modules.

Parameters:

• module_name (str) – The name or model of the module. See Available Modules for possible values.

• location (str or int or None) –

  The location of the module.

  This is usually the name or number of the slot on the deck where you will be placing the module, like 1, "1", or "D1". See Deck Slots.

  The Thermocycler is only valid in one deck location. You don’t have to specify a location when loading it, but if you do, it must be 7, "7", or "B1". See Thermocycler Module.

  Changed in version 2.15: You can now specify a deck slot as a coordinate, like "D1".

• configuration –

  Configure a Thermocycler to be in the semi position. This parameter does not work. Do not use it.

  Changed in version 2.14: This parameter dangerously modified the protocol’s geometry system, and it didn’t function properly, so it was removed.

Returns:

The loaded and initialized module—a HeaterShakerContext, MagneticBlockContext, MagneticModuleContext, TemperatureModuleContext, or ThermocyclerContext, depending on what you requested with module_name.

Changed in version 2.13: Added HeaterShakerContext return value.

Changed in version 2.15: Added MagneticBlockContext return value.

New in version 2.0.

load_trash_bin(self, location: 'DeckLocation') → 'TrashBin'

Load a trash bin on the deck of a Flex.

See Trash Bin for details.

If you try to load a trash bin on an OT-2, the API will raise an error.

Parameters:

location –

The deck slot where the trash bin is. The location can be any unoccupied slot in column 1 or 3.

If you try to load a trash bin in column 2 or 4, the API will raise an error.

New in version 2.16.

load_waste_chute(self) → 'WasteChute'

Load the waste chute on the deck of a Flex.

See Waste Chute for details, including the deck configuration variants of the waste chute.

The deck plate adapter for the waste chute can only go in slot D3. If you try to load another item in slot D3 after loading the waste chute, or vice versa, the API will raise an error.

New in version 2.16.

property loaded_instruments: Dict[str, InstrumentContext]

Get the instruments that have been loaded into the protocol.

This is a map of mount name to instruments previously loaded with load_instrument(). It does not reflect what instruments are actually installed on the robot. For example, if the robot has instruments installed on both mounts but your protocol has only loaded one of them with load_instrument(), the unused one will not be included in loaded_instruments.

Returns:

A dict mapping mount name ("left" or "right") to the instrument in that mount. If a mount has no loaded instrument, that key will be missing from the dict.

New in version 2.0.

property loaded_labwares: Dict[int, Labware]

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

Slots with nothing in them will not be present in the return value.

Note

If a module is present on the deck but no labware has been loaded into it with module.load_labware(), there will be no entry for that slot in this value. That means you should not use loaded_labwares to determine if a slot is available or not, only to get a list of labwares. If you want a data structure of all objects on the deck regardless of type, use deck.

Returns:

Dict mapping deck slot number to labware, sorted in order of the locations.

New in version 2.0.

property loaded_modules: Dict[int, Union[TemperatureModuleContext, MagneticModuleContext, ThermocyclerContext, HeaterShakerContext, MagneticBlockContext, AbsorbanceReaderContext, FlexStackerContext]]

Get the modules loaded into the protocol context.

This is a map of deck positions to modules loaded by previous calls to load_module(). It does not reflect what modules are actually attached to the robot. For example, if the robot has a Magnetic Module and a Temperature Module attached, but the protocol has only loaded the Temperature Module with load_module(), only the Temperature Module will be included in loaded_modules.

Returns:

Dict mapping slot name to module contexts. The elements may not be ordered by slot number.

New in version 2.0.

property max_speeds: AxisMaxSpeeds

Per-axis speed limits for moving instruments.

Changing values within this property sets the speed limit for each non-plunger axis of the robot. Note that this property only sets upper limits and can’t exceed the physical speed limits of the movement system.

This property is a dict mapping string names of axes to float values of maximum speeds in mm/s. To change a speed, set that axis’s value. To reset an axis’s speed to default, delete the entry for that axis or assign it to None.

See Axis Speed Limits for examples.

Note

This property is not yet supported in API version 2.14 or higher.

New in version 2.0.

move_labware(self, labware: 'Labware', new_location: 'Union[DeckLocation, Labware, ModuleTypes, OffDeckType, WasteChute, TrashBin]', use_gripper: 'bool' = False, pick_up_offset: 'Optional[Mapping[str, float]]' = None, drop_offset: 'Optional[Mapping[str, float]]' = None) → 'None'

Move a loaded labware to a new location.

See Moving Labware for more details.

Parameters:

• labware – The labware to move. It should be a labware already loaded using load_labware().

• new_location –

  Where to move the labware to. This is either:

  • A deck slot like 1, "1", or "D1". See Deck Slots.

  • A hardware module that’s already been loaded on the deck with load_module().

  • A labware or adapter that’s already been loaded on the deck with load_labware() or load_adapter().

  • The special constant OFF_DECK.

• use_gripper –

  Whether to use the Flex Gripper for this movement.

  • If True, use the gripper to perform an automatic movement. This will raise an error in an OT-2 protocol.

  • If False, pause protocol execution until the user performs the movement. Protocol execution remains paused until the user presses Confirm and resume.

Gripper-only parameters:

Parameters:

• pick_up_offset – Optional x, y, z vector offset to use when picking up labware.

• drop_offset – Optional x, y, z vector offset to use when dropping off labware.

Before moving a labware to or from a hardware module, make sure that the labware’s current and new locations are accessible, i.e., open the Thermocycler lid or open the Heater-Shaker’s labware latch.

New in version 2.15.

move_lid(self, source_location: 'Union[DeckLocation, Labware]', new_location: 'Union[DeckLocation, Labware, OffDeckType, WasteChute, TrashBin]', use_gripper: 'bool' = False, pick_up_offset: 'Optional[Mapping[str, float]]' = None, drop_offset: 'Optional[Mapping[str, float]]' = None) → 'Labware | None'

Move a compatible lid from a valid source to a new location. Can return a lid stack if one is created.

Parameters:

• source_location –

  The lid’s starting location. This is either:

  • A deck slot like 1, "1", or "D1". See Deck Slots.

  • A labware or adapter that’s already been loaded on the deck with load_labware() or load_adapter().

  • A lid stack that’s already been loaded on the deck with with load_lid_stack().

• new_location –

  Where to move the lid to. This is either:

  • A deck slot like 1, "1", or "D1". See Deck Slots.

  • A hardware module that’s already been loaded on the deck with load_module().

  • A labware or adapter that’s already been loaded on the deck with load_labware() or load_adapter().

  • The special constant OFF_DECK.

• use_gripper –

  Whether to use the Flex Gripper to move the lid.

  • If True, use the gripper to perform an automatic movement. This will raise an error in an OT-2 protocol.

  • If False, pause protocol execution until the user performs the movement. Protocol execution remains paused until the user presses Confirm and resume.

Gripper-only parameters:

Parameters:

• pick_up_offset – Optional x, y, z vector offset to use when picking up a lid.

• drop_offset – Optional x, y, z vector offset to use when dropping off a lid.

Before moving a lid to or from a labware in a hardware module, make sure that the labware’s current and new locations are accessible, i.e., open the Thermocycler lid or open the Heater-Shaker’s labware latch.

New in version 2.23.

New in version 2.23.

property params: Parameters

The values of runtime parameters, as set during run setup.

Each attribute of this object corresponds to the variable_name of a parameter. See Using Parameters for details.

Parameter values can only be set during run setup. If you try to alter the value of any attribute of params, the API will raise an error.

New in version 2.18.

pause(self, msg: 'Optional[str]' = None) → 'None'

Pause execution of the protocol until it’s resumed.

A human can resume the protocol in the Opentrons App or on the touchscreen.

Note

In Python Protocol API version 2.13 and earlier, the pause will only take effect on the next function call that involves moving the robot.

Parameters:

msg (str) – An optional message to show in the run log entry for the pause step.

New in version 2.0.

property rail_lights_on: bool

Returns True if the robot’s ambient lighting is on.

New in version 2.5.

resume(self) → 'None'

Resume the protocol after pause().

Deprecated since version 2.12: The Python Protocol API supports no safe way for a protocol to resume itself. If you’re looking for a way for your protocol to resume automatically after a period of time, use delay().

New in version 2.0.

property robot: RobotContext

The RobotContext for the protocol.

New in version 2.22.

set_rail_lights(self, on: 'bool') → 'None'

Controls the robot’s ambient lighting (rail lights).

Parameters:

on (bool) – If True, turn on the lights; otherwise, turn them off.

New in version 2.5.

wait_for_tasks(self, tasks: 'list[Task]') → 'None'

Wait for a list of tasks to complete before executing subsequent commands.

Parameters:

Task (list) – tasks: A list of Task objects to wait for.

Task objects can be commands that are allowed to run concurrently.

New in version 2.27.

class opentrons.protocol_api.Task(core: TaskCore, api_version: APIVersion)

A concurrent protocol task created by a protocol API function.

New in version 2.27.

property created_at: datetime

The timestamp of when the task was created.

New in version 2.27.

property done: bool

Returns True if the task is done.

New in version 2.27.

property finished_at: datetime.datetime | None

The timestamp of the when the task finished.

Returns None if the task hasn’t finished yet.

New in version 2.27.

property started: bool

Returns True if the task has started.

New in version 2.27.

Instruments

class opentrons.protocol_api.InstrumentContext(core: AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], broker: LegacyBroker, api_version: APIVersion, tip_racks: List[Labware], trash: Optional[Union[Labware, TrashBin, WasteChute]], requested_as: str, core_map: LoadedCoreMap)

A context for a specific pipette or instrument.

The InstrumentContext class provides the objects, attributes, and methods that allow you to use pipettes in your protocols.

Methods generally fall into one of two categories.

• They can change the state of the InstrumentContext object, like how fast it moves liquid or where it disposes of used tips.

• They can command the instrument to perform an action, like picking up tips, moving to certain locations, and aspirating or dispensing liquid.

Objects in this class should not be instantiated directly. Instead, instances are returned by ProtocolContext.load_instrument().

New in version 2.0.

property active_channels: int

The number of channels the pipette will use to pick up tips.

By default, all channels on the pipette. Use configure_nozzle_layout() to set the pipette to use fewer channels.

New in version 2.16.

air_gap(self, volume: 'Optional[float]' = None, height: 'Optional[float]' = None, in_place: 'Optional[bool]' = None, rate: 'Optional[float]' = None, flow_rate: 'Optional[float]' = None) → 'InstrumentContext'

Draw air into the pipette’s tip at the current well.

See Air Gap.

Parameters:

• volume (float) – The amount of air, measured in µL. Calling air_gap() with no arguments uses the entire remaining volume in the pipette.

• height (float) – The height, in mm, to move above the current well before creating the air gap. The default is 5 mm above the current well.

• in_place (bool) – Air gap at the pipette’s current position, without moving to some height above the well. If in_place is specified, height must be unset.

• rate (float) – A multiplier for the default flow rate of the pipette. Calculated as rate multiplied by flow_rate.aspirate. If neither rate nor flow_rate is specified, the pipette will aspirate at a rate of 1.0 * InstrumentContext.flow_rate.aspirate. See Pipette Flow Rates.

• flow_rate (float) – The rate, in µL/s, at which the pipette will draw in air.

Raises:

UnexpectedTipRemovalError – If no tip is attached to the pipette.

Raises:

RuntimeError – If location cache is None and the air gap is not in_place. This would happen if air_gap() is called without first calling a method that takes a location (e.g., aspirate(), dispense())

Returns:

This instance.

Both volume and height are optional, but if you want to specify only height you must do it as a keyword argument: pipette.air_gap(height=2). If you call air_gap with a single, unnamed argument, it will always be interpreted as a volume.

Note

In API version 2.21 and earlier, this function was implemented as an aspirate, and dispensing into a well would add the air gap volume to the liquid tracked in the well. In API version 2.22 and later, air gap volume is not tracked as liquid when dispensing into a well.

Changed in version 2.22: No longer implemented as an aspirate.

Changed in version 2.24: Added the in_place option.

Changed in version 2.24: Adds the rate and flow_rate parameter. You can only define one or the other. If both are unspecified then rate is by default set to 1.0. Can air gap over a trash bin or waste chute.

New in version 2.0.

property api_version: APIVersion

New in version 2.0.

aspirate(self, volume: 'Optional[float]' = None, location: 'Optional[Union[types.Location, labware.Well]]' = None, rate: 'float' = 1.0, flow_rate: 'Optional[float]' = None, end_location: 'Optional[types.Location]' = None, movement_delay: 'Optional[float]' = None) → 'InstrumentContext'

Draw liquid into a pipette tip.

See Aspirate for more details and examples.

Parameters:

• volume (int or float) –

  The volume to aspirate, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its currently attached tip.

  If aspirate is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: aspirate until the pipette is full. On API levels at or above 2.16, no liquid will be aspirated.

• location –

  Tells the robot where to aspirate from. The location can be a Well or a Location.

  • If the location is a Well, the robot will aspirate at or above the bottom center of the well. The distance (in mm) from the well bottom is specified by well_bottom_clearance.aspirate.

  • If the location is a Location (e.g., the result of Well.top() or Well.bottom()), the robot will aspirate from that specified position.

  • If the location is unspecified, the robot will aspirate from its current position.

• rate (float) – A multiplier for the default flow rate of the pipette. Calculated as rate multiplied by flow_rate.aspirate. If not specified, defaults to 1.0. See Pipette Flow Rates.

• flow_rate (float) – The absolute flow rate in µL/s. If flow_rate is specified, rate must not be set.

• end_location (Location) – Tells the robot to move from the specified location to the specified end_location while aspirating liquid. When this argument is used, the location and end_location must both be a Location.

• movement_delay (float) – Time in seconds to delay after the pipette starts aspirating and before it begins moving from location to end_location. This option is only valid when using end_location. When this argument is used, the pipette will wait the specified time after the pipette starts to aspirate before moving. This may help when aspirating very viscous liquids that need to build up some pressure before liquid starts to flow.

Returns:

This instance.

Note

If aspirate is called with a single, unnamed argument, it will treat that argument as volume. If you want to call aspirate with only location, specify it as a keyword argument: pipette.aspirate(location=plate['A1'])

Changed in version 2.24: Added the flow_rate parameter.

Changed in version 2.27: Added the end_location and movement_delay parameters.

New in version 2.0.

blow_out(self, location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None) → 'InstrumentContext'

Blow an extra amount of air through a pipette’s tip to clear it.

If dispense() is used to empty a pipette, usually a small amount of liquid remains in the tip. During a blowout, the pipette moves the plunger beyond its normal limits to help remove all liquid from the pipette tip. See Blow Out.

Parameters:

location (Well or Location or None) –

The blowout location. If no location is specified, the pipette will blow out from its current position.

Changed in version 2.16: Accepts TrashBin and WasteChute values.

Raises:

RuntimeError – If no location is specified and the location cache is None. This should happen if blow_out() is called without first calling a method that takes a location, like aspirate() or dispense().

Returns:

This instance.

Changed in version 2.24: location is no longer required if the pipette just moved to, dispensed, or blew out into a trash bin or waste chute.

New in version 2.0.

property channels: int

The number of channels on the pipette.

Possible values are 1, 8, or 96.

See also type.

New in version 2.0.

configure_for_volume(self, volume: 'float') → 'None'

Configure a pipette to handle a specific volume of liquid, measured in µL. The pipette enters a volume mode depending on the volume provided. Changing pipette modes alters properties of the instance of InstrumentContext, such as default flow rate, minimum volume, and maximum volume. The pipette remains in the mode set by this function until it is called again.

The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a low-volume mode to accurately dispense very small volumes of liquid. Low-volume mode can only be set by calling configure_for_volume(). See Volume Modes.

Note

Changing a pipette’s mode will reset its flow rates.

This function will raise an error if called when the pipette’s tip contains liquid. It won’t raise an error if a tip is not attached, but changing modes may affect which tips the pipette can subsequently pick up without raising an error.

This function will also raise an error if volume is outside of the minimum and maximum capacities of the pipette (e.g., setting volume=1 for a Flex 1000 µL pipette).

Parameters:

volume (float) – The volume, in µL, that the pipette will prepare to handle.

New in version 2.15.

configure_nozzle_layout(self, style: 'NozzleLayout', start: 'Optional[str]' = None, end: 'Optional[str]' = None, front_right: 'Optional[str]' = None, back_left: 'Optional[str]' = None, tip_racks: 'Optional[List[labware.Labware]]' = None) → 'None'

Configure how many tips the 8-channel or 96-channel pipette will pick up.

Changing the nozzle layout will affect gantry movement for all subsequent pipetting actions that the pipette performs. It also alters the pipette’s behavior for picking up tips. The pipette will continue to use the specified layout until this function is called again.

Note

When picking up fewer than 96 tips at once, the tip rack must not be placed in a tip rack adapter in the deck. If you try to pick up fewer than 96 tips from a tip rack that is in an adapter, the API will raise an error.

Parameters:

• style (NozzleLayout or None) –

  The shape of the nozzle layout. You must import the layout constant in order to use it.

  • ALL resets the pipette to use all of its nozzles. Calling configure_nozzle_layout with no arguments also resets the pipette.

  • COLUMN sets a 96-channel pipette to use 8 nozzles, aligned from front to back with respect to the deck. This corresponds to a column of wells on labware. For 8-channel pipettes, use ALL instead.

  • PARTIAL_COLUMN sets an 8-channel pipette to use 2–7 nozzles, aligned from front to back with respect to the deck. Not compatible with the 96-channel pipette.

  • ROW sets a 96-channel pipette to use 12 nozzles, aligned from left to right with respect to the deck. This corresponds to a row of wells on labware. Not compatible with 8-channel pipettes.

  • SINGLE sets the pipette to use 1 nozzle. This corresponds to a single well on labware.

• start (str or None) –

  The primary nozzle of the layout, which the robot uses to determine how it will move to different locations on the deck. The string should be of the same format used when identifying wells by name. Required unless setting style=ALL.

  Note

  If possible, don’t use both start="A1" and start="A12" to pick up tips from the same rack. Doing so can affect positional accuracy.

• end (str or None) – The nozzle at the end of a linear layout, which is used to determine how many tips will be picked up by a pipette. The string should be of the same format used when identifying wells by name. Required when setting style=PARTIAL_COLUMN.

• tip_racks (List[Labware]) – Behaves the same as setting the tip_racks parameter of load_instrument(). If not specified, the new configuration resets InstrumentContext.tip_racks and you must specify the location every time you call pick_up_tip().

Changed in version 2.20: Added partial column, row, and single layouts.

New in version 2.16.

consolidate(self, volume: 'Union[float, Sequence[float]]', source: 'List[labware.Well]', dest: 'labware.Well', \*args: 'Any', \*\*kwargs: 'Any') → 'InstrumentContext'

Move liquid from multiple source wells to a single destination well.

Parameters:

• volume – The amount, in µL, to aspirate from each source well.

• source – A list of wells to aspirate liquid from.

• dest – A single well to dispense liquid into.

• kwargs – See transfer() and the Complex Liquid Handling Parameters page. Some parameters behave differently than when transferring. disposal_volume and mix_before are ignored.

Returns:

This instance.

New in version 2.0.

consolidate_with_liquid_class(self, liquid_class: 'LiquidClass', volume: 'float', source: 'Union[labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]]]', dest: 'Union[labware.Well, Sequence[labware.Well], TrashBin, WasteChute]', new_tip: 'TransferTipPolicyV2Type' = 'once', trash_location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None, return_tip: 'bool' = False, group_wells: 'bool' = True, keep_last_tip: 'Optional[bool]' = None, tip_racks: 'Optional[List[labware.Labware]]' = None, tips: 'Optional[Union[Sequence[labware.Well], Sequence[Sequence[labware.Well]]]]' = None) → 'InstrumentContext'

Consolidate a particular type of liquid from a group of wells to one well.

Parameters:

• liquid_class (LiquidClass) – The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

• volume – The amount, in µL, to aspirate from each source well.

• source – A list of wells to aspirate liquid from.

• dest – A single well, list of wells, trash bin, or waste chute to dispense liquid into. Multiple wells can only be given for multi-channel pipette configurations, and must be able to be dispensed to in a single dispense.

• new_tip –

  When to pick up and drop tips during the command. Defaults to "once".

  • "once": Use one tip for the entire command.

  • "always": Use a new tip after each aspirate and dispense, even when visiting the same source again.

  • "never": Do not pick up or drop tips at all.

  See Tip Handling for details.

• trash_location – A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

• return_tip – Whether to drop used tips in their original locations in the tip rack, instead of the trash.

• group_wells – For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

• keep_last_tip – When True, the pipette keeps the last tip used in the consolidate attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

• tip_racks – A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated InstrumentContext.tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

• tips –

  An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if InstrumentContext.tip_racks or the tip_racks parameter of this method is set.

  Changed in version 2.25: Added the tip_racks parameter.

  Changed in version 2.27: Added the tips parameter.

New in version 2.24.

current_tip_source_well(self) → 'Optional[labware.Well]'

Returns the tip rack well the current tip has been picked up from.

If there is no tip currently on the pipette, this will return None.

New in version 2.25.

property current_volume: float

The current amount of liquid held in the pipette, measured in µL.

New in version 2.0.

property default_speed: float

The speed at which the robot’s gantry moves in mm/s.

The default speed for Flex varies between 300 and 350 mm/s. The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the speed argument of the InstrumentContext.move_to() method. See Gantry Speed.

New in version 2.0.

detect_liquid_presence(self, well: 'labware.Well') → 'bool'

Checks for liquid in a well.

Returns True if liquid is present and False if liquid is not present. Will not raise an error if it does not detect liquid. When simulating a protocol, the check always succeeds (returns True). Works with Flex 1-, 8-, and 96-channel pipettes. See Detect Liquids.

Note

The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.

New in version 2.20.

dispense(self, volume: 'Optional[float]' = None, location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None, rate: 'float' = 1.0, push_out: 'Optional[float]' = None, flow_rate: 'Optional[float]' = None, end_location: 'Optional[types.Location]' = None, movement_delay: 'Optional[float]' = None) → 'InstrumentContext'

Dispense liquid from a pipette tip.

See Dispense for more details and examples.

Parameters:

• volume (int or float) –

  The volume to dispense, measured in µL.

  • If unspecified or None, dispense the current_volume.

  • If 0, the behavior of dispense() depends on the API level of the protocol. In API version 2.16 and earlier, dispense all liquid in the pipette (same as unspecified or None). In API version 2.17 and later, dispense no liquid.

  • If greater than current_volume, the behavior of dispense() depends on the API level of the protocol. In API version 2.16 and earlier, dispense all liquid in the pipette. In API version 2.17 and later, raise an error.

• location –

  Tells the robot where to dispense liquid held in the pipette. The location can be a Well, Location, TrashBin, or WasteChute.

  • If a Well, the pipette will dispense at or above the bottom center of the well. The distance (in mm) from the well bottom is specified by well_bottom_clearance.dispense.

  • If a Location (e.g., the result of Well.top() or Well.bottom()), the pipette will dispense at that specified position.

  • If a trash container, the pipette will dispense at a location relative to its center and the trash container’s top center. See Position Relative to Trash Containers for details.

  • If unspecified, the pipette will dispense at its current position.

  If only a location is passed (e.g., pipette.dispense(location=plate['A1'])), all of the liquid aspirated into the pipette will be dispensed (the amount is accessible through current_volume).

  Changed in version 2.16: Accepts TrashBin and WasteChute values.

• rate (float) – How quickly a pipette dispenses liquid. The speed in µL/s is calculated as rate multiplied by flow_rate.dispense. If not specified, defaults to 1.0. See Pipette Flow Rates.

• push_out (float) –

  Continue past the plunger bottom to help ensure all liquid leaves the tip. Measured in µL. The default value is None.

  When not specified or set to None, the plunger moves by a non-zero default amount.

  For a table of default values, see Push Out After Dispense.

• flow_rate (float) – The absolute flow rate in µL/s. If flow_rate is specified, rate must not be set.

• end_location (Location) – Tells the robot to move from the specified location to the specified end_location while dispensing liquid held in the pipette. When this argument is used, the location and end_location must both be a Location.

• movement_delay (float) – Time in seconds to delay after the pipette starts dispensing and before it begins moving from location to end_location. This option is only valid when using end_location. When this argument is used, the pipette will wait the specified time after the pipette starts to dispense before moving. This may help when dispensing very viscous liquids that need to build up some pressure before liquid starts to flow.

Returns:

This instance.

Note

If dispense is called with a single, unnamed argument, it will treat that argument as volume. If you want to call dispense with only location, specify it as a keyword argument: pipette.dispense(location=plate['A1']).

Changed in version 2.15: Added the push_out parameter.

Changed in version 2.17: Behavior of the volume parameter.

Changed in version 2.24: Added the flow_rate parameter.

Changed in version 2.24: location is no longer required if the pipette just moved to, dispensed, or blew out into a trash bin or waste chute.

Changed in version 2.27: Added the end_location and movement_delay parameters.

New in version 2.0.

distribute(self, volume: 'Union[float, Sequence[float]]', source: 'labware.Well', dest: 'List[labware.Well]', \*args: 'Any', \*\*kwargs: 'Any') → 'InstrumentContext'

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

Parameters:

• volume – The amount, in µL, to dispense into each destination well.

• source – A single well to aspirate liquid from.

• dest – A list of wells to dispense liquid into.

• kwargs –

  See transfer() and the Complex Liquid Handling Parameters page. Some parameters behave differently than when transferring.

  • disposal_volume aspirates additional liquid to improve the accuracy of each dispense. Defaults to the minimum volume of the pipette. See Disposal Volume for details.

  • mix_after is ignored.

Returns:

This instance.

New in version 2.0.

distribute_with_liquid_class(self, liquid_class: 'LiquidClass', volume: 'float', source: 'Union[labware.Well, Sequence[labware.Well]]', dest: 'Union[labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]]]', new_tip: 'TransferTipPolicyV2Type' = 'once', trash_location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None, return_tip: 'bool' = False, group_wells: 'bool' = True, keep_last_tip: 'Optional[bool]' = None, tip_racks: 'Optional[List[labware.Labware]]' = None, tips: 'Optional[Union[Sequence[labware.Well], Sequence[Sequence[labware.Well]]]]' = None) → 'InstrumentContext'

Distribute a particular type of liquid from one well to a group of wells.

Parameters:

• liquid_class (LiquidClass) – The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

• volume – The amount, in µL, to dispense to each destination.

• source – A single well for the pipette to target, or a group of wells to target in a single aspirate for a multi-channel pipette.

• dest – A list of wells to dispense liquid into.

• new_tip –

  When to pick up and drop tips during the command. Defaults to "once".

  • "once": Use one tip for the entire command.

  • "always": Use a new tip before each aspirate.

  • "never": Do not pick up or drop tips at all.

  See Tip Handling for details.

• trash_location – A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

• return_tip – Whether to drop used tips in their original locations in the tip rack, instead of the trash.

• group_wells – For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

• keep_last_tip – When True, the pipette keeps the last tip used in the distribute attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

• tip_racks – A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated InstrumentContext.tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

• tips –

  An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if InstrumentContext.tip_racks or the tip_racks parameter of this method is set.

  Changed in version 2.25: Added the tip_racks parameter.

  Changed in version 2.27: Added the tips parameter.

New in version 2.24.

drop_tip(self, location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None, home_after: 'Optional[bool]' = None) → 'InstrumentContext'

Drop the current tip.

See Dropping a Tip for examples.

If no location is passed (e.g. pipette.drop_tip()), the pipette will drop the attached tip into its trash_container.

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:

• As a Well. This uses a default location relative to the well. This style of call can be used to make the robot drop a tip into labware like a well plate or a reservoir. For example, pipette.drop_tip(location=reservoir["A1"]).

• As a Location. For example, to drop a tip from an unusually large height above the tip rack, you could call pipette.drop_tip(tip_rack["A1"].top(z=10)).

• As a TrashBin. This uses a default location relative to the TrashBin object. For example, pipette.drop_tip(location=trash_bin).

• As a WasteChute. This uses a default location relative to the WasteChute object. For example, pipette.drop_tip(location=waste_chute).

In API versions 2.15 to 2.17, if location is a TrashBin or not specified, the API will instruct the pipette to drop tips in different locations within the bin. Varying the tip drop location helps prevent tips from piling up in a single location.

Starting with API version 2.18, the API will only vary the tip drop location if location is not specified. Specifying a TrashBin as the location behaves the same as specifying TrashBin.top(), which is a fixed position.

Parameters:

• location (Location or Well or None) –

  Where to drop the tip.

  Changed in version 2.16: Accepts TrashBin and WasteChute values.

• home_after –

  Whether to home the pipette’s plunger after dropping the tip. If not specified, defaults to True on an OT-2.

  When False, the pipette does not home its plunger. This can save a few seconds, but is not recommended. Homing helps the robot track the pipette’s position.

Returns:

This instance.

New in version 2.0.

dynamic_mix(self, aspirate_start_location: 'types.Location', dispense_start_location: 'types.Location', repetitions: 'int' = 1, volume: 'Optional[float]' = None, aspirate_end_location: 'Optional[types.Location]' = None, dispense_end_location: 'Optional[types.Location]' = None, rate: 'float' = 1.0, aspirate_flow_rate: 'Optional[float]' = None, dispense_flow_rate: 'Optional[float]' = None, aspirate_delay: 'Optional[float]' = None, dispense_delay: 'Optional[float]' = None, final_push_out: 'Optional[float]' = None, movement_delay: 'Optional[float]' = None) → 'InstrumentContext'

Mix a volume of liquid by repeatedly aspirating and dispensing it in a multiple locations.

See Dynamic Mix for examples.

Parameters:

• repetitions – Number of times to mix (default is 1).

• volume –

  The volume to mix, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its attached tip.

  If mix is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: mix the full working volume of the pipette. On API levels at or above 2.16, no liquid will be mixed.

• aspirate_start_location – The Location where the pipette will start aspirating from.

• aspirate_end_location – A Location. If specified, the pipette will move between the aspirate_start_location and the aspirate_end_location while performing the aspirate.

• dispense_start_location – The Location where the pipette will start dispensing to.

• dispense_end_location – A Location. If specified, the pipette will move between the dispense_start_location and the dispense_end_location while performing the dispense.

• rate – How quickly the pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as rate multiplied by flow_rate.aspirate. The dispensing flow rate is calculated as rate multiplied by flow_rate.dispense. See Pipette Flow Rates.

• aspirate_flow_rate – The absolute flow rate for each aspirate in the mix, in µL/s. If this is specified, rate must not be set.

• dispense_flow_rate – The absolute flow rate for each dispense in the mix, in µL/s. If this is specified, rate must not be set.

• aspirate_delay – How long to wait after each aspirate in the mix, in seconds.

• dispense_delay – How long to wait after each dispense in the mix, in seconds.

• final_push_out – How much volume to push out after the final mix repetition. The pipette will not push out after earlier repetitions. If not specified or None, the pipette will push out the default non-zero amount. See Push Out After Dispense.

• movement_delay (float) – Time in seconds to delay after the pipette starts aspirating or dispensing and before it begins moving from the aspirate_start_location or dispense_start_location to the aspirate_end_location or dispense_end_location. This option is only valid when using aspirate_end_location or dispense_end_location. When this argument is used, the pipette will wait the specified time after the pipette starts to aspirate or dispense before moving. This may help when mixing very viscous liquids that need to build up some pressure before liquid starts to flow.

Raises:

UnexpectedTipRemovalError – If no tip is attached to the pipette.

Returns:

This instance.

Note

The aspirate_start_location and dispense_start_location arguments of dynamic_mix are required.

New in version 2.27.

property flow_rate: FlowRates

The speeds, in µL/s, configured for the pipette.

See Pipette Flow Rates.

This is an object with attributes aspirate, dispense, and blow_out holding the flow rate for the corresponding operation.

Note

Setting values of speed, which is deprecated, will override the values in flow_rate.

New in version 2.0.

get_minimum_liquid_sense_height(self) → 'float'

Get the minimum allowed height for liquid-level detection.

New in version 2.21.

property has_tip: bool

Whether this instrument has a tip attached or not.

The value of this property is determined logically by the API, not by detecting the physical presence of a tip. This is the case even on Flex, which has sensors to detect tip attachment.

New in version 2.7.

home(self) → 'InstrumentContext'

Home the robot.

See Homing.

Returns:

This instance.

New in version 2.0.

home_plunger(self) → 'InstrumentContext'

Home the plunger associated with this mount.

Returns:

This instance.

New in version 2.0.

property hw_pipette: PipetteDict

View the information returned by the hardware API directly.

Raises:

types.PipetteNotAttachedError if the pipette is no longer attached (should not happen).

New in version 2.0.

property liquid_presence_detection: bool

Whether the pipette will perform automatic liquid presence detection.

When True, the pipette will check for liquid on every aspiration. Defaults to False. See Liquid Presence Detection.

New in version 2.20.

property max_volume: float

The maximum volume, in µL, that the pipette can hold.

The maximum volume that you can actually aspirate might be lower than this, depending on what kind of tip is attached to this pipette. For example, a P300 Single-Channel pipette always has a max_volume of 300 µL, but if it’s using a 200 µL filter tip, its usable volume would be limited to 200 µL.

New in version 2.0.

measure_liquid_height(self, well: 'labware.Well') → 'LiquidTrackingType'

Check the height of the liquid within a well.

Returns:

The height, in mm, of the liquid from the bottom of the well.

New in version 2.20.

property min_volume: float

The minimum volume, in µL, that the pipette can hold. This value may change based on the volume mode that the pipette is currently configured for.

New in version 2.0.

mix(self, repetitions: 'int' = 1, volume: 'Optional[float]' = None, location: 'Optional[Union[types.Location, labware.Well]]' = None, rate: 'float' = 1.0, aspirate_flow_rate: 'Optional[float]' = None, dispense_flow_rate: 'Optional[float]' = None, aspirate_delay: 'Optional[float]' = None, dispense_delay: 'Optional[float]' = None, final_push_out: 'Optional[float]' = None) → 'InstrumentContext'

Mix a volume of liquid by repeatedly aspirating and dispensing it in a single location.

See Mix for examples.

Parameters:

• repetitions – Number of times to mix (default is 1).

• volume –

  The volume to mix, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its attached tip.

  If mix is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: mix the full working volume of the pipette. On API levels at or above 2.16, no liquid will be mixed.

• location – The Well or Location where the pipette will mix. If unspecified, the pipette will mix at its current position.

• rate – How quickly the pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as rate multiplied by flow_rate.aspirate. The dispensing flow rate is calculated as rate multiplied by flow_rate.dispense. See Pipette Flow Rates.

• aspirate_flow_rate – The absolute flow rate for each aspirate in the mix, in µL/s. If this is specified, rate must not be set.

• dispense_flow_rate – The absolute flow rate for each dispense in the mix, in µL/s. If this is specified, rate must not be set.

• aspirate_delay – How long to wait after each aspirate in the mix, in seconds.

• dispense_delay – How long to wait after each dispense in the mix, in seconds.

• final_push_out – How much volume to push out after the final mix repetition. The pipette will not push out after earlier repetitions. If not specified or None, the pipette will push out the default non-zero amount. See Push Out After Dispense.

Raises:

UnexpectedTipRemovalError – If no tip is attached to the pipette.

Returns:

This instance.

Note

All the arguments of mix are optional. However, if you omit one of them, all subsequent arguments must be passed as keyword arguments. For instance, pipette.mix(1, location=wellplate['A1']) is a valid call, but pipette.mix(1, wellplate['A1']) is not.

Changed in version 2.21: Does not repeatedly check for liquid presence.

Changed in version 2.24: Adds the aspirate_flow_rate, dispense_flow_rate, aspirate_delay, dispense_delay, and final_push_out parameters.

New in version 2.0.

property model: str

The model string for the pipette (e.g., 'p300_single_v1.3')

New in version 2.0.

property mount: str

Return the name of the mount the pipette is attached to.

The possible names are "left" and "right".

New in version 2.0.

move_to(self, location: 'Union[types.Location, TrashBin, WasteChute]', force_direct: 'bool' = False, minimum_z_height: 'Optional[float]' = None, speed: 'Optional[float]' = None, publish: 'bool' = True) → 'InstrumentContext'

Move the instrument.

See Move To for examples.

Parameters:

• location (Location) –

  Where to move to.

  Changed in version 2.16: Accepts TrashBin and WasteChute values.

• force_direct –

  If True, move directly to the destination without arc motion.

  Warning

  Forcing direct motion can cause the pipette to crash into labware, modules, or other objects on the deck.

• minimum_z_height – An amount, measured in mm, to raise the mid-arc height. The mid-arc height can’t be lowered.

• speed – The speed at which to move. By default, InstrumentContext.default_speed. This controls the straight linear speed of the motion. To limit individual axis speeds, use ProtocolContext.max_speeds.

• publish – Whether to list this function call in the run preview. Default is True.

New in version 2.0.

property name: str

The name string for the pipette.

From API version 2.15 to 2.22, this property returned an internal name for Flex pipettes. (e.g., "p1000_single_flex").

In API version 2.23 and later, this property returns the Python Protocol API load name of Flex pipettes (e.g., "flex_1channel_1000").

New in version 2.0.

pick_up_tip(self, location: 'Union[types.Location, labware.Well, labware.Labware, None]' = None, presses: 'Optional[int]' = None, increment: 'Optional[float]' = None, prep_after: 'Optional[bool]' = None) → 'InstrumentContext'

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

See Picking Up a Tip.

If no location is passed, the pipette will pick up the next available tip in its tip_racks list. Within each tip rack, tips will be picked up in the order specified by the labware definition and Labware.wells(). To adjust where the sequence starts, use starting_tip.

The exact position for tip pickup accounts for the length of the tip and how much the tip overlaps with the pipette nozzle. These measurements are fixed values on Flex, and are based on the results of tip length calibration on OT-2.

Note

API version 2.19 updates the tip overlap values for Flex. When updating a protocol from 2.18 (or lower) to 2.19 (or higher), pipette performance should improve without additional changes to your protocol. Nevertheless, it is good practice after updating to do the following:

• Run Labware Position Check.

• Perform a dry run of your protocol.

• If tip position is slightly higher than expected, adjust the location parameter of pipetting actions to achieve the desired result.

Parameters:

• location (Well or Labware or types.Location) –

  The location from which to pick up a tip. The location argument can be specified in several ways:

  • As a Well. For example, pipette.pick_up_tip(tiprack.wells()[0]) will always pick up the first tip in tiprack, even if the rack is not a member of InstrumentContext.tip_racks.

  • As a labware. pipette.pick_up_tip(tiprack) will pick up the next available tip in tiprack, even if the rack is not a member of InstrumentContext.tip_racks.

  • As a Location. Use this to make fine adjustments to the pickup location. For example, to tell the robot to start its pick up tip routine 1 mm closer to the top of the well in the tip rack, call pipette.pick_up_tip(tiprack["A1"].top(z=-1)).

• presses (int) –

  The number of times to lower and then raise the pipette when picking up a tip, to ensure a good seal. Zero (0) will result in the pipette hovering over the tip but not picking it up (generally not desirable, but could be used for a dry run).

  Deprecated since version 2.14: Use the Opentrons App to change pipette pick-up settings.

• increment (float) –

  The additional distance to travel on each successive press. For example, if presses=3 and increment=1.0, then the first press will travel down into the tip by 3.5 mm, the second by 4.5 mm, and the third by 5.5 mm).

  Deprecated since version 2.14: Use the Opentrons App to change pipette pick-up settings.

• prep_after (bool) –

  Whether the pipette plunger should prepare itself to aspirate immediately after picking up a tip.

  If True, the pipette will move its plunger position to bottom in preparation for any following calls to aspirate().

  If False, the pipette will prepare its plunger later, during the next call to aspirate(). This is accomplished by moving the tip to the top of the well, and positioning the plunger outside any potential liquids.

  Warning

  This is provided for compatibility with older Python Protocol API behavior. You should normally leave this unset.

  Setting prep_after=False may create an unintended pipette movement, when the pipette automatically moves the tip to the top of the well to prepare the plunger.

Changed in version 2.13: Adds the prep_after argument. In version 2.12 and earlier, the plunger can’t prepare itself for aspiration during pick_up_tip(), and will instead always prepare during aspirate(). Version 2.12 and earlier will raise an APIVersionError if a value is set for prep_after.

Changed in version 2.19: Uses new values for how much a tip overlaps with the pipette nozzle.

Returns:

This instance.

New in version 2.0.

prepare_to_aspirate(self) → 'None'

Prepare a pipette for aspiration.

Before a pipette can aspirate into an empty tip, the plunger must be in its bottom position. After dropping a tip or blowing out, the plunger will be in a different position. This function moves the plunger to the bottom position, regardless of its current position, to make sure that the pipette is ready to aspirate.

You rarely need to call this function. The API automatically prepares the pipette for aspiration as part of other commands:

• After picking up a tip with pick_up_tip().

• When calling aspirate(), if the pipette isn’t already prepared. If the pipette is in a well, it will move out of the well, move the plunger, and then move back.

Use prepare_to_aspirate() when you need to control exactly when the plunger motion will happen. A common use case is a pre-wetting routine, which requires preparing for aspiration, moving into a well, and then aspirating without leaving the well:

pipette.move_to(well.bottom(z=2))
protocol.delay(5)
pipette.mix(10, 10)
pipette.move_to(well.top(z=5))
pipette.blow_out()
pipette.prepare_to_aspirate()
pipette.move_to(well.bottom(z=2))
protocol.delay(5)
pipette.aspirate(10, well.bottom(z=2))

The call to prepare_to_aspirate() means that the plunger will be in the bottom position before the call to aspirate(). Since it doesn’t need to prepare again, it will not move up out of the well to move the plunger. It will aspirate in place.

New in version 2.16.

require_liquid_presence(self, well: 'labware.Well') → 'None'

Check for liquid in a well and raises an error if none is detected.

When this method raises an error, Flex will offer the opportunity to enter recovery mode. In recovery mode, you can manually add liquid to resolve the error. When simulating a protocol, the check always succeeds (does not raise an error). Works with Flex 1-, 8-, and 96-channel pipettes. See Liquid Presence Detection and Require Liquids.

Note

The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.

New in version 2.20.

reset_tipracks(self) → 'None'

Reload all tips in each tip rack and reset the starting tip.

New in version 2.0.

resin_tip_dispense(self, location: 'types.Location', volume: 'Optional[float]' = None, rate: 'Optional[float]' = None) → 'InstrumentContext'

Push liquid out of resin tips that are currently sealed to a pipette.

The volume and rate parameters for this function control the motion of the plunger to create a desired pressure profile inside the pipette chamber. Unlike a regular dispense action, the volume and rate do not correspond to liquid volume or flow rate dispensed from the resin tips. Select your values for volume and flow rate based on experimentation with the resin tips to create a pressure profile.

The common way to use this function is as follows:

1. Seal resin tips to the pipette using InstrumentContext.resin_tip_seal().

2. Use InstrumentContext.resin_tip_dispense() to displace an experimentally derived volume at an experimentally derived rate to create an experimentally derived target pressure inside the pipette.

3. Use ProtocolContext.delay() to wait an experimentally derived amount of time for the pressure inside the pipette to push liquid into and through the resin tip and out the other side.

4. As liquid passes through the resin tip, the pressure inside the pipette will fall. If not all liquid has been dispensed from the resin tip, repeat steps 2 and 3.

5. Unseal resin tips from the pipette using InstrumentContext.resin_tip_unseal().

Flex pipette pressure sensors will raise an overpressure when a differential pressure inside the pipette chamber above sensor limits is detected. You may need to disable the pressure sensor to create the required pressure profile.

Warning

Building excessive pressure inside the pipette chamber (significantly above the sensor limit) with the pressure sensors disabled can damage the pipette.

Parameters:

• location (Location) – Tells the robot where to dispense.

• volume (float) – The volume that the plunger should displace, in µL. Does not directly relate to the volume of liquid that will be dispensed.

• rate (float) –

  How quickly the plunger moves to displace the commanded volume, in µL/s. This rate does not directly relate to the flow rate of liquid out of the resin tip.

  Defaults to 10.0 µL/s.

New in version 2.23.

resin_tip_seal(self, location: 'Union[labware.Well, labware.Labware]') → 'InstrumentContext'

Seal resin tips onto the pipette.

The location provided should contain resin tips. The pipette will attach itself to the resin tips but does not check any tip presence sensors. Before the pipette seals to the tips, the plunger will rise to the top of its working range so that it can perform a resin_tip_dispense() immediately.

Parameters:

location (Location) – A location containing resin tips, must be a Labware or a Well.

New in version 2.23.

resin_tip_unseal(self, location: 'Union[labware.Well, labware.Labware]') → 'InstrumentContext'

Release resin tips from the pipette.

The location provided should be a valid location to drop resin tips.

Parameters:

• location (Location) – A location containing that can accept tips.

• home_after –

  Whether to home the pipette after dropping the tip. If not specified defaults to True on a Flex. The plunger will not home on an unseal.

  When False, the pipette does not home its plunger. This can save a few seconds, but is not recommended. Homing helps the robot track the pipette’s position.

New in version 2.23.

property return_height: float

The height to return a tip to its tip rack.

Returns:

A scaling factor to apply to the tip length. During drop_tip(), this factor is multiplied by the tip length to get the distance from the top of the well to drop the tip.

New in version 2.2.

return_tip(self, home_after: 'Optional[bool]' = None) → 'InstrumentContext'

Drop the currently attached tip in its original location in the tip rack.

Returning a tip does not reset tip tracking, so Well.has_tip will remain False for the destination.

Returns:

This instance.

Parameters:

home_after – See the home_after parameter of drop_tip().

New in version 2.0.

property speed: PlungerSpeeds

The speeds (in mm/s) configured for the pipette plunger.

This is an object with attributes aspirate, dispense, and blow_out holding the plunger speeds for the corresponding operation.

Note

Setting values of flow_rate will override the values in speed.

Changed in version 2.14: This property has been removed because it’s fundamentally misaligned with the step-wise nature of a pipette’s plunger speed configuration. Use flow_rate instead.

New in version 2.0.

property starting_tip: Optional[Well]

Which well of a tip rack the pipette should start at when automatically choosing tips to pick up.

See pick_up_tip().

Note

In robot software versions 6.3.0 and 6.3.1, protocols specifying API level 2.14 ignored starting_tip on the second and subsequent calls to InstrumentContext.pick_up_tip() with no argument. This is fixed for all API levels as of robot software version 7.0.0.

New in version 2.0.

property tip_racks: List[Labware]

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. See Picking Up a Tip.

New in version 2.0.

touch_tip(self, location: 'Optional[labware.Well]' = None, radius: 'float' = 1.0, v_offset: 'float' = - 1.0, speed: 'float' = 60.0, mm_from_edge: 'Union[float, _Unset]' = _Unset) → 'InstrumentContext'

Touch the pipette tip to the sides of a well, with the intent of removing leftover droplets.

See Touch Tip for more details and examples.

Parameters:

• location (Well or None) – If no location is passed, the pipette will touch its tip at the edges of the current well.

• radius (float) – How far to move, as a proportion of the target well’s radius. When radius=1.0, the pipette tip will move all the way to the edge of the target well. When radius=0.5, it will move to 50% of the well’s radius. Default is 1.0 (100%)

• v_offset (float) – How far above or below the well to touch the tip, measured in mm. A positive offset moves the tip higher above the well. A negative offset moves the tip lower into the well. Default is -1.0 mm.

• speed (float) –

  The speed for touch tip motion, in mm/s.

  • Default: 60.0 mm/s

  • Maximum: 80.0 mm/s

  • Minimum: 1.0 mm/s

• mm_from_edge (float) – How far to move inside the well, as a distance from the well’s edge. When mm_from_edge=0, the pipette will move to the target well’s edge to touch the tip. When mm_from_edge=1, the pipette will move to 1 mm from the target well’s edge to touch the tip. Values lower than 0 will press the tip harder into the target well’s walls; higher values will touch the well more lightly, or not at all. mm_from_edge and radius are mutually exclusive: to use mm_from_edge, radius must be unspecified (left to its default value of 1.0).

Raises:

UnexpectedTipRemovalError – If no tip is attached to the pipette.

Raises:

RuntimeError – If no location is specified and the location cache is None. This should happen if touch_tip is called without first calling a method that takes a location, like aspirate() or dispense().

Raises:

ValueError: If both mm_from_edge and radius are specified.

Returns:

This instance.

Changed in version 2.24: Added the mm_from_edge parameter.

New in version 2.0.

transfer(self, volume: 'Union[float, Sequence[float]]', source: 'AdvancedLiquidHandling', dest: 'AdvancedLiquidHandling', trash: 'bool' = True, \*\*kwargs: 'Any') → 'InstrumentContext'

Move liquid from one well or group of wells to another.

Transfer is a higher-level command, incorporating other InstrumentContext commands, like aspirate() and dispense(). It makes writing a protocol easier at the cost of specificity. See Complex Commands for details on how transfer and other complex commands perform their component steps.

Parameters:

• volume – The amount, in µL, to aspirate from each source and dispense to each destination. If volume is a list, each amount will be used for the source and destination at the matching index. A list item of 0 will skip the corresponding wells entirely. See List of Volumes for details and examples.

• source – A single well or a list of wells to aspirate liquid from.

• dest – A single well or a list of wells to dispense liquid into.

Keyword Arguments:

Transfer accepts a number of optional parameters that give you greater control over the exact steps it performs. See Complex Liquid Handling Parameters or the links under each argument’s entry below for additional details and examples.

• new_tip (string) – When to pick up and drop tips during the command. Defaults to "once".

  • "once": Use one tip for the entire command.

  • "always": Use a new tip for each set of aspirate and dispense steps.

  • "never": Do not pick up or drop tips at all.

  See Tip Handling for details.

• trash (boolean) – If True (default), the pipette will drop tips in its trash_container(). If False, the pipette will return tips to their tip rack.

  See Trash Tips for details.

• touch_tip (boolean) – If True, perform a touch_tip() following each aspirate() and dispense(). Defaults to False.

  See Touch Tip for details.

• 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 False (default), the pipette will not blow out liquid.

  See Blow Out for details.

• blowout_location (string) – Accepts one of three string values: "trash", "source well", or "destination well".

  If blow_out is False (its default), this parameter is ignored.

  If blow_out is True and this parameter is not set:

  • Blow out into the trash, if the pipette is empty or only contains the disposal volume.

  • Blow out into the source well, if the pipette otherwise contains liquid.

• mix_before (tuple) – Perform a mix() before each aspirate() during the transfer. The first value of the tuple is the number of repetitions, and the second value is the amount of liquid to mix in µL.

  See Mix Before for details.

• mix_after (tuple) – Perform a mix() after each dispense() during the transfer. The first value of the tuple is the number of repetitions, and the second value is the amount of liquid to mix in µL.

  See Mix After for details.

• disposal_volume (float) – Transfer ignores the numeric value of this parameter. If set, the pipette will not aspirate additional liquid, but it will perform a very small blow out after each dispense.

  See Disposal Volume for details.

Returns:

This instance.

New in version 2.0.

transfer_with_liquid_class(self, liquid_class: 'LiquidClass', volume: 'float', source: 'Union[labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]]]', dest: 'Union[labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]], TrashBin, WasteChute]', new_tip: 'TransferTipPolicyV2Type' = 'once', trash_location: 'Optional[Union[types.Location, labware.Well, TrashBin, WasteChute]]' = None, return_tip: 'bool' = False, group_wells: 'bool' = True, keep_last_tip: 'Optional[bool]' = None, tip_racks: 'Optional[List[labware.Labware]]' = None, tips: 'Optional[Union[Sequence[labware.Well], Sequence[Sequence[labware.Well]]]]' = None) → 'InstrumentContext'

Move a particular type of liquid from one well or group of wells to another.

Parameters:

• liquid_class (LiquidClass) – The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

• volume – The amount, in µL, to aspirate from each source and dispense to each destination.

• source – A single well or a list of wells to aspirate liquid from.

• dest – A single well, list of wells, trash bin, or waste chute to dispense liquid into.

• new_tip –

  When to pick up and drop tips during the command. Defaults to "once".

  • "once": Use one tip for the entire command.

  • "always": Use a new tip for each set of aspirate and dispense steps.

  • "per source": Use one tip for each source well, even if tip refilling is required.

  • "per destination": Use one tip for each destination well, even if tip refilling is required.

  • "never": Do not pick up or drop tips at all.

  See Tip Handling for details.

• trash_location – A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

• return_tip – Whether to drop used tips in their original locations in the tip rack, instead of the trash.

• group_wells – For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

• keep_last_tip – When True, the pipette keeps the last tip used in the transfer attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

• tip_racks – A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated InstrumentContext.tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

• tips –

  An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if InstrumentContext.tip_racks or the tip_racks parameter of this method is set.

  Changed in version 2.25: Added the tip_racks parameter.

  Changed in version 2.27: Added the tips parameter.

New in version 2.24.

property trash_container: Union[Labware, TrashBin, WasteChute]

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.

You can set this to a Labware, TrashBin, or WasteChute.

The default value depends on the robot type and API version:

• ProtocolContext.fixed_trash, if it exists.

• Otherwise, the first item previously loaded with ProtocolContext.load_trash_bin() or ProtocolContext.load_waste_chute().

Changed in version 2.16: Added support for TrashBin and WasteChute objects.

New in version 2.0.

property type: str

'single' if this is a 1-channel pipette, or 'multi' otherwise.

See also channels, which can distinguish between 8-channel and 96-channel pipettes.

New in version 2.0.

property well_bottom_clearance: Clearances

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

This is an object with attributes aspirate and dispense, describing the default height of the corresponding operation. The default is 1.0 mm for both aspirate and 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.

To change, set the corresponding attribute:

pipette.well_bottom_clearance.aspirate = 2

New in version 2.0.

Robot Motors

class opentrons.protocol_api.RobotContext(core: AbstractRobot, protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], api_version: APIVersion, broker: Optional[LegacyBroker] = None)

A context for the movement system of the robot.

The RobotContext class provides the objects, attributes, and methods that allow you to control robot motor axes individually.

Its methods can command the robot to perform an action, like moving to an absolute position, controlling the gripper jaw, or moving individual pipette motors.

Objects in this class should not be instantiated directly. Instead, instances are returned by ProtocolContext.robot().

New in version 2.22.

property api_version: APIVersion

New in version 2.22.

axis_coordinates_for(self, mount: Union[opentrons.types.Mount, str], location: Union[opentrons.types.Location, opentrons.protocol_api.module_contexts.ModuleContext, int, str]) → Dict[opentrons.types.AxisType, float]

Build an axis map from a location to provide to either RobotContext.move_axes_to() or RobotContext.move_axes_relative(). You must provide only one of either a location, slot, or module to build the axis map.

Parameters:

• mount (types.Mount or str) – The mount of the instrument you wish create an axis map for. This can either be an instance of types.Mount or one of the strings "left", "right", "extension", "gripper". Note that the gripper mount can be referred to either as "extension" or "gripper".

• location (Well, ModuleContext, DeckLocation or OffDeckType) –

  Any location on the deck, specified as:

  • a deck location, like slot "A1".

  • a defined location, like a module on the deck.

build_axis_map(self, axis_map: Dict[str, float]) → Dict[opentrons.types.AxisType, float]

Take in a types.StringAxisMap and output an axis map.

The types.StringAxisMap is allowed to contain any of the following strings: "x", "y", “z_l", “z_r", “z_g", "q".

An example of a valid axis map could be:

{“x”: 1, “y”: 2} or {“Z_L”: 100}

Note that capitalization does not matter.

close_gripper_jaw(self, force: Optional[float] = None) → None

Closes the Flex Gripper jaws with a specified force.

Parameters:

force – Force with which to close the gripper jaws in newtons.

move_axes_relative(self, axis_map: Union[Dict[opentrons.types.AxisType, float], Dict[str, float]], speed: Optional[float] = None) → None

Move a set of axes to a relative position on the deck.

Parameters:

• axis_map – A dictionary mapping axes to relative movements from the current position in mm.

• speed (float) – The maximum speed with which to move all axes in mm/s.

New in version 2.22.

move_axes_to(self, axis_map: Union[Dict[opentrons.types.AxisType, float], Dict[str, float]], critical_point: Union[Dict[opentrons.types.AxisType, float], Dict[str, float], NoneType] = None, speed: Optional[float] = None) → None

Move a set of axes to an absolute position on the deck.

Parameters:

• axis_map – A dictionary mapping axes to an absolute position on the deck in mm.

• critical_point – The critical point, or specific point on the object being moved, to move the axes with. It should only specify the gantry axes (i.e. x, y, z). When you specify a critical point, you’re specifying the object on the gantry to be moved. If not specified, the critical point defaults to the center of the carriage attached to the gantry.

• speed (float) – The maximum speed with which to move all axes in mm/s.

New in version 2.22.

move_to(self, mount: Union[opentrons.types.Mount, str], destination: opentrons.types.Location, speed: Optional[float] = None) → None

Move a specified mount to a location on the deck.

Parameters:

• mount (types.Mount or str) – The mount of the instrument you wish to move. This can either be an instance of types.Mount or one of the strings "left", "right", "extension", "gripper". Note that the gripper mount can be referred to either as "extension" or "gripper".

• destination –

  Any location on the deck, specified as:

  • a slot, like "A1"

  • a defined location, like labware in a deck slot

  • an absolute location, like a point {x=10 , y=10, z=10} or a deck location and point (“A1” + point {x=10 , y=10, z=10})

• speed – The absolute speed in mm/s.

New in version 2.22.

open_gripper_jaw(self) → None

Opens the Flex Gripper jaws with a specified force.

Parameters:

force – Force with which to open the gripper jaws in newtons.

plunger_coordinates_for_named_position(self, mount: Union[opentrons.types.Mount, str], position_name: opentrons.protocol_api._types.PlungerPositionTypes) → Dict[opentrons.types.AxisType, float]

Build an axis map to move a pipette plunger motor to a named position.

Parameters:

position_name – A named position to move the pipette plunger to. Choose from top, bottom, blowout, or drop plunger positions.

plunger_coordinates_for_volume(self, mount: Union[opentrons.types.Mount, str], volume: float, action: opentrons.protocol_api._types.PipetteActionTypes) → Dict[opentrons.types.AxisType, float]

Build an axis map to move a pipette plunger motor to complete liquid handling actions.

Mount:

The left or right instrument mount the pipette is attached to.

Parameters:

• volume – A volume to convert to an axis map for linear plunger displacement.

• action – Choose to aspirate or dispense.

Labware

class opentrons.protocol_api.Labware(core: AbstractLabware[Any], api_version: APIVersion, protocol_core: ProtocolCore, core_map: LoadedCoreMap)

This class represents a piece of labware.

Labware available in the API generally fall under two categories.

• Consumable labware: well plates, tubes in racks, reservoirs, tip racks, etc.

• Adapters: durable items that hold other labware, either on modules or directly on the deck.

The Labware class defines the physical geometry of the labware and provides methods for accessing wells within the labware.

Create Labware objects by calling the appropriate load_labware() method, depending on where you are loading the labware. For example, to load labware on a Thermocycler Module, use ThermocyclerContext.load_labware(). To load labware directly on the deck, use ProtocolContext.load_labware(). See Loading Labware.

property api_version: APIVersion

See ProtocolContext.api_version.

New in version 2.0.

property calibrated_offset: Point

The front-left-bottom corner of the labware, including its labware offset.

The offset is an x, y, z vector in deck coordinates (see Position Relative to the Deck).

When running a protocol in the Opentrons App or on the touchscreen, Labware Position Check sets the labware offset.

New in version 2.0.

property child: Optional[Labware]

The labware (if any) present on this labware.

New in version 2.15.

columns(self, \*args: 'Union[int, str]') → 'List[List[Well]]'

Accessor function to navigate through a labware by column.

Use indexing to access individual columns or wells contained in the nested list. For example, access column 1 with labware.columns()[0]. On a standard 96-well plate, this will output a list of Well objects containing A1 through H1.

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .columns(1, 4) or .columns("1", "4") is valid, but .columns("1", 4) is not.

Returns:

A list of column lists.

New in version 2.0.

columns_by_index(self) → 'Dict[str, List[Well]]'

Deprecated since version 2.0: Use columns_by_name() instead.

New in version 2.0.

columns_by_name(self) → 'Dict[str, List[Well]]'

Accessor function to navigate through a labware by column name.

Use indexing to access individual columns or wells contained in the dictionary. For example, access column 1 with labware.columns_by_name()["1"]. On a standard 96-well plate, this will output a list of Well objects containing A1 through H1.

Returns:

Dictionary of Well lists keyed by column name.

New in version 2.0.

property highest_z: float

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

This is taken from the zDimension property of the dimensions object in the labware definition and takes into account the labware offset.

New in version 2.0.

property is_adapter: bool

Whether the labware behaves as an adapter.

Returns True if the labware definition specifies adapter as one of the labware’s allowedRoles.

New in version 2.15.

property is_tiprack: bool

Whether the labware behaves as a tip rack.

Returns True if the labware definition specifies isTiprack as True.

New in version 2.0.

load_empty(self, wells: 'Sequence[Union[Well, str]]') → 'None'

Mark several wells as empty.

This method should be called at the beginning of a protocol, after loading the labware and before liquid handling begins. Loading liquids is required for liquid tracking functionality. If a well in a labware hasn’t been assigned a starting volume with Labware.load_empty(), Labware.load_liquid(), or Labware.load_liquid_by_well(), the volume it contains is unknown and the well’s liquid will not be tracked throughout the protocol.

Parameters:

wells (Union[List[Well], List[str]]) – The list of wells to mark empty. To mark all wells as empty, pass labware.wells(). You can also specify wells by their names (for instance, labware.load_empty(['A1', 'A2'])).

New in version 2.22.

load_labware(self, name: 'str', label: 'Optional[str]' = None, lid: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, \*, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a compatible labware onto the labware using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a compatible labware onto the labware using an inline definition.

Parameters:

• definition – The labware definition.

• label (str) – An optional special name to give the labware. If specified, this is how the labware will appear in the run log, Labware Position Check, and elsewhere in the Opentrons App and on the touchscreen.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_lid_stack(self, load_name: 'str', quantity: 'int', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.

Parameters:

• load_name (str) –

  A string to use for looking up a lid definition. You can find the load_name for any standard lid on the Opentrons Labware Library.

• quantity (int) – The quantity of lids to be loaded in the stack.

• namespace (str) –

  The namespace that the lid labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.

  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version – The version of the labware definition. You should normally leave this unspecified to let load_lid_stack() choose a version automatically.

Returns:

The initialized and loaded labware object representing the lid stack.

New in version 2.23.

load_liquid(self, wells: 'Sequence[Union[str, Well]]', volume: 'float', liquid: 'Liquid') → 'None'

Mark several wells as containing the same amount of liquid.

This method should be called at the beginning of a protocol, soon after loading labware and before liquid handling operations begin. Loading liquids is required for liquid tracking functionality. If a well hasn’t been assigned a starting volume with load_empty(), load_liquid(), or load_liquid_by_well(), the volume it contains is unknown and the well’s liquid will not be tracked throughout the protocol.

Parameters:

• wells (List of string well names or list of Well objects (e.g., from wells()).) – The wells to load the liquid into.

• volume (float) – The volume of liquid to load into each well.

• liquid (Liquid) – The liquid to load into each well, previously defined by define_liquid()

New in version 2.22.

load_liquid_by_well(self, volumes: 'Mapping[Union[str, Well], float]', liquid: 'Liquid') → 'None'

Mark several wells as containing unique volumes of liquid.

This method should be called at the beginning of a protocol, soon after loading labware and before liquid handling begins. Loading liquids is required for liquid tracking functionality. If a well hasn’t been assigned a starting volume with load_empty(), load_liquid(), or load_liquid_by_well(), the volume it contains is unknown and the well’s liquid will not be tracked throughout the protocol.

Parameters:

• volumes – A dictionary of well names (or Well objects, for instance from labware['A1'])

• liquid (Liquid) – The liquid to load into each well, previously defined by define_liquid()

New in version 2.22.

property load_name: str

The API load name of the labware definition.

New in version 2.0.

property magdeck_engage_height: Optional[float]

Return the default magnet engage height that MagneticModuleContext.engage() will use for this labware.

Warning

This currently returns confusing and unpredictable results that do not necessarily match what MagneticModuleContext.engage() will actually choose for its default height.

The confusion is related to how this height’s units and origin point are defined, and differences between Magnetic Module generations.

For now, we recommend you avoid accessing this property directly.

New in version 2.0.

property name: str

The display name of the labware.

If you specified a value for label when loading the labware, name is that value.

Otherwise, it is the load_name of the labware.

New in version 2.0.

property parameters: opentrons_shared_data.labware.types.LabwareParameters2 | opentrons_shared_data.labware.types.LabwareParameters3

Internal properties of a labware including type and quirks.

New in version 2.0.

property parent: Union[str, Labware, ModuleTypes, OffDeckType]

Where the labware is loaded.

This corresponds to the physical object that the labware directly rests upon.

Returns:

If the labware is directly on the robot’s deck, the str name of the deck slot, like "D1" (Flex) or "1" (OT-2). See Deck Slots.

If the labware is on a module, a module context.

If the labware is on a labware or adapter, a Labware.

If the labware is off-deck, OFF_DECK.

Changed in version 2.14: Return type for module parent changed. Formerly, the API returned an internal geometry interface.

Changed in version 2.15: Returns a Labware if the labware is loaded onto a labware/adapter. Returns OFF_DECK if the labware is off-deck. Formerly, if the labware was removed by using del on deck, this would return where it was before its removal.

New in version 2.0.

property quirks: List[str]

Quirks specific to this labware.

New in version 2.0.

reset(self) → 'None'

Reset tip tracking for a tip rack.

After resetting, the API treats all wells on the rack as if they contain unused tips. This is useful if you want to reuse tips after calling return_tip().

If you need to physically replace an empty tip rack in the middle of your protocol, use move_labware() instead. See The Off-Deck Location for an example.

Changed in version 2.14: This method will raise an exception if you call it on a labware that isn’t a tip rack. Formerly, it would do nothing.

New in version 2.0.

rows(self, \*args: 'Union[int, str]') → 'List[List[Well]]'

Accessor function to navigate through a labware by row.

Use indexing to access individual rows or wells contained in the nested list. On a standard 96-well plate, this will output a list of Well objects containing A1 through A12.

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .rows(1, 4) or .rows("1", "4") is valid, but .rows("1", 4) is not.

Returns:

A list of row lists.

New in version 2.0.

rows_by_index(self) → 'Dict[str, List[Well]]'

Deprecated since version 2.0: Use rows_by_name() instead.

New in version 2.0.

rows_by_name(self) → 'Dict[str, List[Well]]'

Accessor function to navigate through a labware by row name.

Use indexing to access individual rows or wells contained in the dictionary. For example, access row A with labware.rows_by_name()["A"]. On a standard 96-well plate, this will output a list of Well objects containing A1 through A12.

Returns:

Dictionary of Well lists keyed by row name.

New in version 2.0.

set_calibration(self, delta: 'Point') → 'None'

An internal, deprecated method used for updating the labware offset.

Deprecated since version 2.14.

set_offset(self, x: 'float', y: 'float', z: 'float') → 'None'

Set the labware’s position offset.

An offset of (x=0, y=0, z=0) means the labware’s uncalibrated position before any offset from Labware Position Check is applied.

How the motion system applies the offset depends on the API level of the protocol.

API level	Offset behavior
2.12–2.13	Offsets only apply to the exact Labware instance. If your protocol has multiple instances of the same type of labware, you must either use set_offset() on all of them or none of them.
2.14–2.17	set_offset() is not available, and the API raises an error.
2.18–2.22	Offsets apply to any labware of the same type, in the same on-deck location. Offsets can’t be set on labware that is currently off-deck. Offsets do not follow a labware instance when using move_labware().
2.23 and newer	On Flex, offsets can apply to all labware of the same type, regardless of their on-deck location.

Note

Setting offsets with this method will override any labware offsets set by running Labware Position Check in the Opentrons App.

This method is designed for use with mechanisms like opentrons.execute.get_protocol_api, which lack an interactive way to adjust labware offsets. (See Advanced Control.)

Changed in version 2.14: Temporarily removed.

Changed in version 2.18: Restored, and now applies to labware type–location pairs.

New in version 2.12.

property tip_length: float

For a tip rack labware, the length of the tips it holds, in mm.

This is taken from the tipLength property of the parameters object in the labware definition.

This method will raise an exception if you call it on a labware that isn’t a tip rack.

New in version 2.0.

property uri: str

A string fully identifying the labware.

The URI has three parts and follows the pattern "namespace/load_name/version". For example, opentrons/corning_96_wellplate_360ul_flat/2.

New in version 2.0.

well(self, idx: 'Union[int, str]') → 'Well'

Deprecated. Use result of wells() or wells_by_name().

New in version 2.0.

wells(self, \*args: 'Union[str, int]') → 'List[Well]'

Accessor function to navigate a labware top to bottom, left to right.

i.e., this method returns a list ordered A1, B1, C1…A2, B2, C2….

Use indexing to access individual wells contained in the list. For example, access well A1 with labware.wells()[0].

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .wells(1, 4) or .wells("1", "4") is valid, but .wells("1", 4) is not.

Returns:

Ordered list of all wells in a labware.

New in version 2.0.

wells_by_index(self) → 'Dict[str, Well]'

Deprecated since version 2.0: Use wells_by_name() or dict access instead.

New in version 2.0.

wells_by_name(self) → 'Dict[str, Well]'

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

Use indexing to access individual wells contained in the dictionary. For example, access well A1 with labware.wells_by_name()["A1"].

Returns:

Dictionary of Well objects keyed by well name.

New in version 2.0.

class opentrons.protocol_api.TrashBin

Represents a Flex or OT-2 trash bin.

See ProtocolContext.load_trash_bin().

top(self, x: 'float' = 0, y: 'float' = 0, z: 'float' = 0) → 'TrashBin'

Add a location offset to a trash bin.

The default location (x, y, and z all set to 0) is the center of the bin on the x- and y-axes, and slightly below its physical top on the z-axis.

Offsets can be positive or negative and are measured in mm. See Position Relative to the Deck.

New in version 2.18.

class opentrons.protocol_api.WasteChute

Represents a Flex waste chute.

See ProtocolContext.load_waste_chute().

top(self, x: 'float' = 0, y: 'float' = 0, z: 'float' = 0) → 'WasteChute'

Add a location offset to a waste chute.

The default location (x, y, and z all set to 0) is the center of the chute’s opening on the x- and y-axes, and slightly below its physical top on the z-axis. See Waste Chute for more information on possible configurations of the chute.

Offsets can be positive or negative and are measured in mm. See Position Relative to the Deck.

New in version 2.18.

Wells and Liquids

class opentrons.protocol_api.Well(parent: Labware, core: WellCore, api_version: APIVersion)

The Well class represents a single well in a Labware. It provides parameters and functions for three major uses:

• Calculating positions relative to the well. See Position Relative to Labware for details.

• Returning well measurements. See Well Dimensions for details.

• Specifying what liquid should be in the well at the beginning of a protocol. See Labeling Liquids in Labware for details.

property api_version: APIVersion

New in version 2.0.

bottom(self, z: 'float' = 0.0) → 'Location'

Parameters:

z – An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

Returns:

A Location corresponding to the absolute position of the bottom-center of the well, plus the z offset (if specified).

New in version 2.0.

center(self) → 'Location'

Returns:

A Location corresponding to the absolute position of the center of the well (in all three dimensions).

New in version 2.0.

current_liquid_height(self) → 'LiquidTrackingType'

Get the current liquid height in a well.

New in version 2.21.

current_liquid_volume(self) → 'LiquidTrackingType'

Get the current liquid volume in a well.

New in version 2.21.

property depth: float

The depth, in mm, of a well along the z-axis, from the very top of the well to the very bottom.

New in version 2.9.

property diameter: Optional[float]

The diameter, in mm, of a circular well. Returns None if the well is not circular.

New in version 2.0.

property display_name: str

A human-readable name for the well, including labware and deck location.

For example, “A1 of Corning 96 Well Plate 360 µL Flat on slot D1”. Run log entries use this format for identifying wells. See ProtocolContext.commands().

from_center_cartesian(self, x: 'float', y: 'float', z: 'float') → 'Point'

Specifies a Point based on fractions of the distance from the center of the well to the edge along each axis.

For example, from_center_cartesian(0, 0, 0.5) specifies a point at the well’s center on the x- and y-axis, and half of the distance from the center of the well to its top along the z-axis. To move the pipette to that location, construct a Location relative to the same well:

location = types.Location(
    plate["A1"].from_center_cartesian(0, 0, 0.5), plate["A1"]
)
pipette.move_to(location)

See Points and Locations for more information.

Parameters:

• x – The fraction of the distance from the well’s center to its edge along the x-axis. Negative values are to the left, and positive values are to the right.

• y – The fraction of the distance from the well’s center to its edge along the y-axis. Negative values are to the front, and positive values are to the back.

• z – The fraction of the distance from the well’s center to its edge along the x-axis. Negative values are down, and positive values are up.

Returns:

A Point representing the specified position in absolute deck coordinates.

Note

Even if the absolute values of x, y, and z are all less than 1, a location constructed from the well and the result of from_center_cartesian may be outside of the physical well. For example, from_center_cartesian(0.9, 0.9, 0) would be outside of a cylindrical well, but inside a square well.

New in version 2.8.

property has_tip: bool

Whether this well contains an unused tip.

From API v2.2 on:

• Returns False if:

  • the well has no tip present, or

  • the well has a tip that’s been used by the protocol previously

• Returns True if the well has an unused tip.

Before API v2.2:

• Returns True as long as the well has a tip, even if it is used.

Always False if the parent labware isn’t a tip rack.

New in version 2.0.

has_tracked_liquid(self) → 'bool'

Get the current liquid volume in a well.

New in version 2.27.

height_from_volume(self, volume: 'LiquidTrackingType') → 'LiquidTrackingType'

Return the height in a well corresponding to a given volume.

New in version 2.24.

property length: Optional[float]

The length, in mm, of a rectangular well along the x-axis (left to right). Returns None if the well is not rectangular.

New in version 2.9.

load_liquid(self, liquid: 'Liquid', volume: 'float') → 'None'

Load a liquid into a well.

Parameters:

• liquid (Liquid) – The liquid to load into the well.

• volume (float) – The volume of liquid to load, in µL.

Deprecated since version 2.22: Use Labware.load_liquid(), Labware.load_liquid_by_well(), or Labware.load_empty() instead.

New in version 2.14.

property max_volume: float

The maximum volume, in µL, that the well can hold.

This amount is set by the JSON labware definition, specifically the totalLiquidVolume property of the particular well.

meniscus(self, z: 'float' = 0.0, target: "Literal['start', 'end', 'dynamic']" = 'end') → 'Location'

Parameters:

• z – An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

• target – The relative position of the liquid meniscus inside the well to target when performing a liquid handling operation.

Returns:

A Location corresponding to the liquid meniscus, plus a target position and z offset as specified.

New in version 2.21.

property parent: Labware

The Labware object that the well is a part of.

New in version 2.0.

top(self, z: 'float' = 0.0) → 'Location'

Parameters:

z – An offset on the z-axis, in mm. Positive offsets are higher and negative offsets are lower.

Returns:

A Location corresponding to the absolute position of the top-center of the well, plus the z offset (if specified).

New in version 2.0.

volume_from_height(self, height: 'LiquidTrackingType') → 'LiquidTrackingType'

Return the volume contained in a well at any height.

New in version 2.24.

property well_name: str

A string representing the well’s coordinates.

For example, “A1” or “H12”.

The format of strings that this property returns is the same format as the key for accessing wells in a dictionary.

New in version 2.7.

property width: Optional[float]

The width, in mm, of a rectangular well along the y-axis (front to back). Returns None if the well is not rectangular.

New in version 2.9.

class opentrons.protocol_api.Liquid(_id: str, name: str, description: Optional[str], display_color: Optional[str])

A liquid to load into a well.

name

A human-readable name for the liquid.

Type:

str

description

An optional description.

Type:

Optional[str]

display_color

An optional display color for the liquid.

Type:

Optional[str]

New in version 2.14.

class opentrons.protocol_api.LiquidClass(_name: str, _display_name: str, _by_pipette_setting: Dict[str, Dict[str, TransferProperties]])

A data class that contains properties of a specific class of liquids.

get_for(self, pipette: 'Union[str, InstrumentContext]', tip_rack: 'Union[str, Labware]') → 'TransferProperties'

Get liquid class transfer properties for the specified pipette and tip.

Modules

Absorbance Plate Reader

class opentrons.protocol_api.AbsorbanceReaderContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Absorbance Plate Reader Module.

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

New in version 2.21.

property api_version: APIVersion

New in version 2.0.

close_lid(self) → 'None'

Use the Flex Gripper to close the lid of the Absorbance Plate Reader.

You must call this method before initializing the reader, even if the reader was in the closed position at the start of the protocol.

New in version 2.21.

initialize(self, mode: 'ABSMeasureMode', wavelengths: 'List[int]', reference_wavelength: 'Optional[int]' = None) → 'None'

Prepare the Absorbance Plate Reader to read a plate.

See Initialization for examples.

Parameters:

• mode –

  Either "single" or "multi".

  • In single measurement mode, AbsorbanceReaderContext.read() uses one sample wavelength and an optional reference wavelength.

  • In multiple measurement mode, AbsorbanceReaderContext.read() uses a list of up to six sample wavelengths.

• wavelengths –

  A list of wavelengths, in nm, to measure.

  • In the default hardware configuration, each wavelength must be one of 450 (blue), 562 (green), 600 (orange), or 650 (red). In custom hardware configurations, the module may accept other integers between 350 and 1000.

  • The list must contain only one item when initializing a single measurement.

  • The list can contain one to six items when initializing a multiple measurement.

• reference_wavelength – An optional reference wavelength, in nm. If provided, AbsorbanceReaderContext.read() will read at the reference wavelength and then subtract the reference wavelength values from the measurement wavelength values. Can only be used with single measurements.

New in version 2.21.

is_lid_on(self) → 'bool'

Return True if the Absorbance Plate Reader’s lid is currently closed.

New in version 2.21.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

open_lid(self) → 'None'

Use the Flex Gripper to open the lid of the Absorbance Plate Reader.

New in version 2.21.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

read(self, export_filename: 'Optional[str]' = None) → 'Dict[int, Dict[str, float]]'

Read a plate on the Absorbance Plate Reader.

This method always returns a dictionary of measurement data. It optionally will save a CSV file of the results to the Flex filesystem, which you can access from the Recent Protocol Runs screen in the Opentrons App. These files are only saved if you specify export_filename.

In simulation, the values for each well key in the dictionary are set to zero, and no files are written.

Note

Avoid divide-by-zero errors when simulating and using the results of this method later in the protocol. If you divide by any of the measurement values, use ProtocolContext.is_simulating() to use alternate dummy data or skip the division step.

Parameters:

export_filename –

An optional file basename. If provided, this method will write a CSV file for each measurement in the read operation. File names will use the value of this parameter, the measurement wavelength supplied in initialize(), and a .csv extension. For example, when reading at wavelengths 450 and 562 with export_filename="my_data", there will be two output files: my_data_450.csv and my_data_562.csv.

See CSV data for information on working with these CSV files.

Returns:

A dictionary of wavelengths to dictionary of values ordered by well name.

New in version 2.21.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.21.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Flex Stacker

class opentrons.protocol_api.FlexStackerContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Flex Stacker module.

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

New in version 2.25.

property api_version: APIVersion

New in version 2.0.

empty(self, message: 'str | None' = None) → 'None'

Pause the protocol to remove all labware stored in the Flex Stacker.

This method sets the location of all labware currently in the stacker to OFF_DECK.

Parameters:

message – A message to display to note what should be removed from the Flex Stacker.

New in version 2.25.

fill(self, count: 'int | None' = None, message: 'str | None' = None) → 'None'

Pause the protocol to add labware to the Flex Stacker.

The labware must be the same type the Stacker is configured to store using set_stored_labware(). If no labware type has been set, the API will raise an error.

Parameters:

• count – The amount of labware the Flex Stacker should hold after this command is executed. If not specified, the Flex Stacker should be full after this command is executed.

• message – A message to display noting what kind of labware to fill the Stacker with.

New in version 2.25.

fill_items(self, labware: 'list[Labware]', message: 'str | None' = None) → 'None'

Pause the protocol to add a specific list of labware to the Flex Stacker.

Parameters:

• labware –

  The list of labware to add. The list must:

  • Contain at least one labware.

  • Have labware of the same kind previously passed to set_stored_labware_items() or loaded by set_stored_labware().

  • All labware should be loaded OFF_DECK.

• message – A message to display noting the labware to fill the Stacker with.

New in version 2.25.

get_current_storable_labware(self) → 'int'

Get the number of labware that the Flex Stacker currently has space for.

Use this function to return the total number of labware that the Flex Stacker can store. A Stacker has a limited amount of internal space and calculates the number of labware that can be stored based on the z height of the labware and the amount they overlap when stacked.

The number is calculated based on the labware definition for the type of labware the Stacker is currently configured to store using set_stored_labware(). This function returns a number based on the current storage conditions of the Stacker, and will change as labware is added or removed. To get the overall maximum number of labware the Flex Stacker can store, use get_max_storable_labware().

New in version 2.25.

get_current_storable_labware_from_list(self, labware: 'list[Labware]') → 'list[Labware]'

Limit a list of labware instances to the number that the Flex Stacker currently has space for, based on the labware that is already stored in the Flex Stacker. Items will be taken from the head of the list.

A Flex Stacker has a limited amount of internal space and computes the number of labware that it can store based on the z height of the labware and the amount they overlap when stacked.

Note

The number of elements in the returned list will change as labware is added or removed from the Flex Stacker. To get a list limited to the overall maximum number of labware the Flex Stacker can store, use get_max_storable_labware_from_list().

Parameters:

labware – A list of labware to limit. The returned list takes from the front of the provided list, and it is guaranteed to be suitable for passing to fill_items().

New in version 2.25.

get_max_storable_labware(self) → 'int'

Get the maximum number of labware that the Flex Stacker can store.

Use this function to return the total number of labware that the Flex Stacker can store. A Stacker has a limited amount of internal space and calculates the total number of labware that can be stored based on the z height of the labware and the amount they overlap when stacked.

The total number is calculated based on the labware definition for the type of labware the Stacker is currently configured to store using set_stored_labware(). This number is the overall maximum and will not change as labware is added or removed. To get the number of labware that can be stored in the Flex Stacker based on its current conditions, use get_current_storable_labware().

New in version 2.25.

get_max_storable_labware_from_list(self, labware: 'list[Labware]', stacking_offset_z: 'float | None' = None) → 'list[Labware]'

Limit a list of labware instances to the number that can be stored in a Flex Stacker. Items will be taken from the head of the list.

A Flex Stacker has a limited amount of internal space and computes the number of labware (or labware with lids or adapters) that it can store based on the z heights of the labware and the amount they overlap when stacked. To calculate how many of a given labware the Stacker can store, the labware type must be specified.

Provide a list of labware to this function to return the maximum number of labware of the given type that the Stacker can store. The returned list is guaranteed to be suitable for passing to set_stored_labware_items().

This function limits the list of labware based on the overall maximum number the Stacker can hold and will not change as labware is added or removed. To limit a list of labware to the amount that will currently fit in the Flex Stacker, use get_current_storable_labware_from_list().

Note

If a z stacking offset is provided, be sure to specify the same value when configuring the Flex Stacker with set_stored_labware_items().

See set_stored_labware_items() for more details on stacking offset.

New in version 2.25.

get_stored_labware(self) → 'list[Labware]'

Get the list of labware currently stored inside the Stacker.

This function returns a list of all labware stored in the Stacker based on the labware intially stored using set_stored_labware() and any labware added or removed during the protocol.

The first element of the list occupies the bottom-most position in the labware stack and would be the labware retrieved by a call to retrieve().

New in version 2.25.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

load_adapter(self, name: 'str', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_adapter (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded adapter object.

New in version 2.15.

load_adapter_from_definition(self, definition: 'LabwareDefinition') → 'Labware'

Load an adapter onto the module using an inline definition.

Parameters:

definition – The labware definition.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

retrieve(self) → 'Labware'

Retrieve a labware from the Flex Stacker and move it onto the shuttle.

The Stacker will retrieve the bottom-most labware in the stack.

Returns:

The retrieved Labware object. This will always be the main labware, even if the Flex Stacker contains labware on an adapter. To get the adapter object, call Labware.parent on the returned labware.

New in version 2.25.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.25.

set_stored_labware(self, load_name: 'str', namespace: 'str | None' = None, version: 'int | None' = None, adapter: 'str | None' = None, lid: 'str | None' = None, count: 'int | None' = None, stacking_offset_z: 'float | None' = None, \*, adapter_namespace: 'str | None' = None, adapter_version: 'int | None' = None, lid_namespace: 'str | None' = None, lid_version: 'int | None' = None) → 'None'

Configure the type and starting quantity of labware the Flex Stacker will store during a protocol. This is the only type of labware you’ll be able to store in the Stacker until it’s reconfigured.

You must use this method to load a labware stack stored inside the Stacker before you’re able to retrieve() or store() additional labware.

Parameters:

• load_name (str) – A string to use for looking up a labware definition. You can find the load_name for any Opentrons-verified labware on the Labware Library.

• namespace (str) –

  The namespace that the labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.

  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version – The version of the labware definition. You should normally leave this unspecified to let the method choose a version automatically.

• adapter – An adapter to load the labware on top of. Accepts the same values as the load_name parameter of load_adapter().

• adapter_namespace –

  Applies to adapter the same way that namespace applies to load_name.

  Changed in version 2.26: adapter_namespace may now be specified explicitly. When you’ve specified namespace for load_name but not adapter_namespace, adapter_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• adapter_version –

  Applies to adapter the same way that version applies to load_name.

  Changed in version 2.26: adapter_version may now be specified explictly. When unspecified, improved search rules prevent selecting a version that does not exist.

• lid – A lid to load the on top of the main labware. Accepts the same values as the load_name parameter of load_lid_stack(). The lid will use the same namespace as the labware, and the API will choose the lid’s version automatically.

• lid_namespace –

  Applies to lid the same way that namespace applies to load_name.

  Changed in version 2.26: lid_namespace may now be specified explicitly. When you’ve specified namespace for load_name but not lid_namespace, lid_namespace now independently follows the same search rules described in namespace. Formerly, it took the exact namespace value.

• lid_version –

  Applies to lid the same way that version applies to load_name.

  Changed in version 2.26: lid_version may now be specified explicitly. When unspecified, improved search rules prevent selecting a version that does not exist.

• count – The number of labware that the Flex Stacker should store. If not specified, this will be the maximum amount of this kind of labware that the Flex Stacker is capable of storing.

• stacking_offset_z – Stacking z offset in mm of stored labware. If specified, this overrides the calculated value in the labware definition.

Note

The stacking offset is the amount of vertical overlap (in mm) between the bottom side of a labware unit and the top side of the unit below. This offset is used to determine how many units can fit in the Stacker and calculates the z position of the shuttle when retrieving or storing labware.

There are four possible stacking configurations, each with a different method of calculating the stacking offset:

• Bare labware: labware (bottom side) overlaps with the top side of the labware below.

• Labware on adapter: the adapter (bottom side) of the upper labware unit overlaps with the top side of the labware below.

• Labware with lid: the labware (bottom side) of the upper labware unit overlaps with the lid (top side) of the unit below.

• Labware with lid and adapter: the adapter (bottom side) of the upper labware unit overlaps with the lid (top side) of the unit below.

New in version 2.25.

set_stored_labware_items(self, labware: 'list[Labware]', stacking_offset_z: 'float | None' = None) → 'None'

Configure the labware the Flex Stacker will store during a protocol by providing an initial list of stored labware objects. The start of the list represents the bottom of the Stacker, and the end of the list represents the top of the Stacker.

The kind of labware stored by the Flex Stacker will be calculated from the list of labware specified here. You can use this to store labware objects that you have already created so that, for instance, you can set their liquid state or nicknames.

Parameters:

• labware –

  A list of labware to load into the Stacker.

  • The list must have at least one element.

  • All labware must be loaded OFF_DECK.

  • All labware must be of the same kind. If any of them have lids, they must all have lids, and the lids must be the same. If any of them are on adapters, they all must be on adapters, and the adapters must be the same. All lids and adapters must be compatible with the Stacker.

  • The number of labware objects must fit in the Stacker physically. To make sure the labware will fit, use the return value of get_max_storable_labware_from_list().

• stacking_offset_z – Stacking z offset in mm of stored labware. If specified, this overrides the calculated value from labware definitions.

Note

The stacking offset is the amount of vertical overlap (in mm) between the bottom side of a labware unit and the top side of the unit below. This offset is used to determine how many units can fit in the stacker and calculates the z position of the shuttle when retrieving or storing labware.

There are four possible stacking configurations, each with a different method of calculating the stacking offset:

• Bare labware: labware (bottom side) overlaps with the top side of the labware below.

• Labware on adapter: the adapter (bottom side) of the upper labware unit overlaps with the top side of the labware below.

• Labware with lid: the labware (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.

• Labware with lid and adapter: the adapter (bottom side) of the upper unit overlaps with the lid (top side) of the unit below.

New in version 2.25.

store(self) → 'None'

Move a labware currently on the Flex Stacker shuttle into the Flex Stacker.

The labware must be the same type the Stacker is configured to store using set_stored_labware(). If labware is currently stacked inside the module, this method moves the new labware to the bottom-most position of the stack.

New in version 2.25.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Heater-Shaker

class opentrons.protocol_api.HeaterShakerContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Heater-Shaker Module.

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

New in version 2.13.

property api_version: APIVersion

New in version 2.0.

close_labware_latch(self) → 'None'

Closes the labware latch.

The labware latch needs to be closed using this method before sending a shake command, even if the latch was manually closed before starting the protocol.

New in version 2.13.

property current_speed: int

The current speed of the Heater-Shaker’s plate in rpm.

New in version 2.13.

property current_temperature: float

The current temperature of the Heater-Shaker’s plate in °C.

Returns 23 in simulation if no target temperature has been set.

New in version 2.13.

deactivate_heater(self) → 'None'

Stops heating.

The module will passively cool to room temperature. The Heater-Shaker does not have active cooling.

New in version 2.13.

deactivate_shaker(self) → 'None'

Stops shaking.

Decelerating to 0 rpm typically only takes a few seconds.

New in version 2.13.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

property labware_latch_status: str

One of six possible latch statuses:

• opening – The latch is currently opening (in motion).

• idle_open – The latch is open and not moving.

• closing – The latch is currently closing (in motion).

• idle_closed – The latch is closed and not moving.

• idle_unknown – The default status upon reset, regardless of physical latch position. Use close_labware_latch() before other commands requiring confirmation that the latch is closed.

• unknown – The latch status can’t be determined.

New in version 2.13.

load_adapter(self, name: 'str', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_adapter (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded adapter object.

New in version 2.15.

load_adapter_from_definition(self, definition: 'LabwareDefinition') → 'Labware'

Load an adapter onto the module using an inline definition.

Parameters:

definition – The labware definition.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

open_labware_latch(self) → 'None'

Open the Heater-Shaker’s labware latch.

The labware latch needs to be closed before:

• Shaking

• Pipetting to or from the labware on the Heater-Shaker

• Pipetting to or from labware to the left or right of the Heater-Shaker

Attempting to open the latch while the Heater-Shaker is shaking will raise an error.

Note

Before opening the latch, this command will retract the pipettes upward if they are parked adjacent to the left or right of the Heater-Shaker.

New in version 2.13.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.14.

set_and_wait_for_shake_speed(self, rpm: 'int') → 'None'

Set a shake speed in rpm and block execution of further commands until the module reaches the target.

Reaching a target shake speed typically only takes a few seconds.

Note

Before shaking, this command will retract the pipettes upward if they are parked adjacent to the Heater-Shaker.

Parameters:

rpm – A value between 200 and 3000, representing the target shake speed in revolutions per minute.

New in version 2.13.

set_and_wait_for_temperature(self, celsius: 'float') → 'None'

Set a target temperature and wait until the module reaches the target.

No other protocol commands will execute while waiting for the temperature.

Changed in version 2.25: Removed the minimum temperature limit of 37 °C. Note that temperatures under ambient are not achievable.

Parameters:

celsius – A value under 95, representing the target temperature in °C. Values are automatically truncated to two decimal places, and the Heater-Shaker module has a temperature accuracy of ±0.5 °C.

New in version 2.13.

set_shake_speed(self, rpm: 'int') → 'Task'

Sets the Heater-Shaker’s shake speed in RPM and returns a Task that represents concurrent shaking.

Note

Before shaking, this command retracts pipettes upward if they are adjacent to the Heater-Shaker Module.

Parameters:

rpm – A value between 200 and 3000, representing the target shake speed in revolutions per minute.

New in version 2.27.

set_target_temperature(self, celsius: 'float') → 'Task'

Set target temperature and return immediately.

Sets the Heater-Shaker’s target temperature and returns immediately without waiting for the target to be reached. Allows the protocol to proceed while the module reaches the target temperature. Use wait_for_temperature() to delay protocol execution for API levels below 2.27.

Changed in version 2.25: Removed the minimum temperature limit of 37 °C. Note that temperatures under ambient are not achievable.

Changed in version 2.27: Returns a Task object that represents concurrent heating. Pass the task object to ProtocolContext.wait_for_tasks() to wait for the module to reach the target temperature.

Parameters:

celsius – A value under 95, representing the target temperature in °C. Values are automatically truncated to two decimal places, and the Heater-Shaker module has a temperature accuracy of ±0.5 °C.

New in version 2.13.

property speed_status: str

One of five possible shaking statuses:

• holding at target – The module has reached its target shake speed and is actively maintaining that speed.

• speeding up – The module is increasing its shake speed towards a target.

• slowing down – The module was previously shaking at a faster speed and is currently reducing its speed to a lower target or to deactivate.

• idle – The module is not shaking.

• error – The shaking status can’t be determined.

New in version 2.13.

property target_speed: Optional[int]

Target speed of the Heater-Shaker’s plate in rpm.

New in version 2.13.

property target_temperature: Optional[float]

The target temperature of the Heater-Shaker’s plate in °C.

Returns None if no target has been set.

New in version 2.13.

property temperature_status: str

One of five possible temperature statuses:

• holding at target – The module has reached its target temperature and is actively maintaining that temperature.

• cooling – The module has previously heated and is now passively cooling. The Heater-Shaker does not have active cooling.

• heating – The module is heating to a target temperature.

• idle – The module has not heated since the beginning of the protocol.

• error – The temperature status can’t be determined.

New in version 2.13.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

wait_for_temperature(self) → 'None'

Delays protocol execution until the Heater-Shaker has reached its target temperature.

Raises an error if no target temperature was previously set.

New in version 2.13.

Magnetic Block

class opentrons.protocol_api.MagneticBlockContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a Magnetic Block.

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

New in version 2.15.

property api_version: APIVersion

New in version 2.0.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

load_adapter(self, name: 'str', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_adapter (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded adapter object.

New in version 2.15.

load_adapter_from_definition(self, definition: 'LabwareDefinition') → 'Labware'

Load an adapter onto the module using an inline definition.

Parameters:

definition – The labware definition.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Magnetic Module

class opentrons.protocol_api.MagneticModuleContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Magnetic Module.

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

New in version 2.0.

property api_version: APIVersion

New in version 2.0.

disengage(self) → 'None'

Lower the magnets back into the Magnetic Module.

New in version 2.0.

engage(self, height: 'Optional[float]' = None, offset: 'Optional[float]' = None, height_from_base: 'Optional[float]' = None) → 'None'

Raise the Magnetic Module’s magnets. You can specify how high the magnets should move:

• No parameter: Move to the default height for the loaded labware. If the loaded labware has no default, or if no labware is loaded, this will raise an error.

• height_from_base – Move this many millimeters above the bottom of the labware. Acceptable values are between 0 and 25.

  This is the recommended way to adjust the magnets’ height.

  New in version 2.2.

• offset – Move this many millimeters above (positive value) or below (negative value) the default height for the loaded labware. The sum of the default height and offset must be between 0 and 25.

• height – Intended to move this many millimeters above the magnets’ home position. However, depending on the generation of module and the loaded labware, this may produce unpredictable results. You should normally use height_from_base instead.

  Changed in version 2.14: This parameter has been removed.

You shouldn’t specify more than one of these parameters. However, if you do, their order of precedence is height, then height_from_base, then offset.

New in version 2.0.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

load_adapter(self, name: 'str', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_adapter (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded adapter object.

New in version 2.15.

load_adapter_from_definition(self, definition: 'LabwareDefinition') → 'Labware'

Load an adapter onto the module using an inline definition.

Parameters:

definition – The labware definition.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.14.

property status: str

The status of the module, either engaged or disengaged.

New in version 2.0.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Temperature Module

class opentrons.protocol_api.TemperatureModuleContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Temperature Module.

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

New in version 2.0.

property api_version: APIVersion

New in version 2.0.

deactivate(self) → 'None'

Stop heating or cooling, and turn off the fan.

New in version 2.0.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

load_adapter(self, name: 'str', namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Load an adapter onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_adapter (which loads adapters directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded adapter object.

New in version 2.15.

load_adapter_from_definition(self, definition: 'LabwareDefinition') → 'Labware'

Load an adapter onto the module using an inline definition.

Parameters:

definition – The labware definition.

Returns:

The initialized and loaded labware object.

New in version 2.15.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.14.

set_temperature(self, celsius: 'float') → 'None'

Set a target temperature and wait until the module reaches the target.

No other protocol commands will execute while waiting for the temperature.

Parameters:

celsius – A value between 4 and 95, representing the target temperature in °C.

New in version 2.0.

start_set_temperature(self, celsius: 'float') → 'Task'

Sets the Temperature Module’s target temperature and returns immediately without waiting for the module to reach the target. Allows the protocol to proceed while the Temperature Module heats.

Changed in version 2.27: Returns a Task object that represents concurrent heating. Pass the task object to ProtocolContext.wait_for_tasks() to wait for the module to finish heating.

In API version 2.26 or below, this function returns None.

Parameters:

celsius – A value between 4 and 95, representing the target temperature in °C.

New in version 2.3.

property status: str

One of four possible temperature statuses:

• holding at target – The module has reached its target temperature and is actively maintaining that temperature.

• cooling – The module is cooling to a target temperature.

• heating – The module is heating to a target temperature.

• idle – The module has been deactivated.

New in version 2.3.

property target: Optional[float]

The target temperature of the Temperature Module’s deck in °C.

Returns None if no target has been set.

New in version 2.0.

property temperature: float

The current temperature of the Temperature Module’s deck in °C.

Returns 0 in simulation if no target temperature has been set.

New in version 2.0.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Thermocycler

class opentrons.protocol_api.ThermocyclerContext(core: AbstractModuleCore[AbstractLabware[AbstractWellCore]], protocol_core: AbstractProtocol[AbstractInstrument[AbstractWellCore, AbstractLabware[AbstractWellCore]], AbstractLabware[AbstractWellCore], AbstractModuleCore[AbstractLabware[AbstractWellCore]], AbstractTaskCore], core_map: LoadedCoreMap, api_version: APIVersion, broker: LegacyBroker)

An object representing a connected Thermocycler Module.

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

New in version 2.0.

property api_version: APIVersion

New in version 2.0.

property block_target_temperature: Optional[float]

The target temperature of the well block in °C.

New in version 2.0.

property block_temperature: Optional[float]

The current temperature of the well block in °C.

New in version 2.0.

property block_temperature_status: str

One of five possible temperature statuses:

• holding at target – The block has reached its target temperature and is actively maintaining that temperature.

• cooling – The block is cooling to a target temperature.

• heating – The block is heating to a target temperature.

• idle – The block is not currently heating or cooling.

• error – The temperature status can’t be determined.

New in version 2.0.

close_lid(self) → 'str'

Close the lid.

New in version 2.0.

deactivate(self) → 'None'

Turn off both the well block temperature controller and the lid heater.

New in version 2.0.

deactivate_block(self) → 'None'

Turn off the well block temperature controller.

New in version 2.0.

deactivate_lid(self) → 'None'

Turn off the lid heater.

New in version 2.0.

execute_profile(self, steps: 'List[ThermocyclerStep]', repetitions: 'int', block_max_volume: 'Optional[float]' = None) → 'None'

Execute a Thermocycler profile, defined as a cycle of steps, for a given number of repetitions.

Parameters:

• steps – List of steps that make up a single cycle. Each list item should be a dictionary that maps to the parameters of the set_block_temperature() method. The dictionary’s keys must be temperature and one or both of hold_time_seconds and hold_time_minutes.

• repetitions – The number of times to repeat the cycled steps.

• block_max_volume – The greatest volume of liquid contained in any individual well of the loaded labware, in µL. If not specified, the default is 25 µL.

Changed in version 2.21: Fixed run log listing number of steps instead of number of repetitions.

New in version 2.0.

property labware: Optional[Labware]

The labware (if any) present on this module.

New in version 2.0.

property lid_position: Optional[str]

One of these possible lid statuses:

• closed – The lid is closed.

• in_between – The lid is neither open nor closed.

• open – The lid is open.

• unknown – The lid position can’t be determined.

New in version 2.0.

property lid_target_temperature: Optional[float]

The target temperature of the lid in °C.

New in version 2.0.

property lid_temperature: Optional[float]

The current temperature of the lid in °C.

New in version 2.0.

property lid_temperature_status: Optional[str]

One of five possible temperature statuses:

• holding at target – The lid has reached its target temperature and is actively maintaining that temperature.

• cooling – The lid has previously heated and is now passively cooling.

  The Thermocycler lid does not have active cooling.

• heating – The lid is heating to a target temperature.

• idle – The lid has not heated since the beginning of the protocol.

• error – The temperature status can’t be determined.

New in version 2.0.

load_labware(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None, adapter: 'Optional[str]' = None, lid: 'Optional[str]' = None, \*, adapter_namespace: 'Optional[str]' = None, adapter_version: 'Optional[int]' = None, lid_namespace: 'Optional[str]' = None, lid_version: 'Optional[int]' = None) → 'Labware'

Load a labware onto the module using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

The initialized and loaded labware object.

New in version 2.1: The label, namespace, and version parameters.

New in version 2.26: The adapter_namespace, adapter_version, lid_namespace, and lid_version parameters.

load_labware_by_name(self, name: 'str', label: 'Optional[str]' = None, namespace: 'Optional[str]' = None, version: 'Optional[int]' = None) → 'Labware'

Deprecated since version 2.0: Use load_labware instead.

New in version 2.1.

load_labware_from_definition(self, definition: 'LabwareDefinition', label: 'Optional[str]' = None) → 'Labware'

Load a labware onto the module using an inline definition.

Parameters:

• definition – The labware definition.

• 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.

Returns:

The initialized and loaded labware object.

New in version 2.0.

property model: Union[Literal['magneticModuleV1', 'magneticModuleV2'], Literal['temperatureModuleV1', 'temperatureModuleV2'], Literal['thermocyclerModuleV1', 'thermocyclerModuleV2'], Literal['heaterShakerModuleV1'], Literal['magneticBlockV1'], Literal['absorbanceReaderV1'], Literal['flexStackerModuleV1']]

Get the module’s model identifier.

New in version 2.14.

open_lid(self) → 'str'

Open the lid.

New in version 2.0.

property parent: str

The name of the slot the module is on.

On a Flex, this will be like "D1". On an OT-2, this will be like "1". See Deck Slots.

New in version 2.14.

property serial_number: str

Get the module’s unique hardware serial number.

New in version 2.14.

set_block_temperature(self, temperature: 'float', hold_time_seconds: 'Optional[float]' = None, hold_time_minutes: 'Optional[float]' = None, ramp_rate: 'Optional[float]' = None, block_max_volume: 'Optional[float]' = None) → 'None'

Set the target temperature for the well block, in °C.

Parameters:

• temperature – A value between 4 and 99, representing the target temperature in °C.

• hold_time_minutes – The number of minutes to hold, after reaching temperature, before proceeding to the next command. If hold_time_seconds is also specified, the times are added together.

• hold_time_seconds – The number of seconds to hold, after reaching temperature, before proceeding to the next command. If hold_time_minutes is also specified, the times are added together.

• block_max_volume – The greatest volume of liquid contained in any individual well of the loaded labware, in µL. If not specified, the default is 25 µL. After API version 2.27 it will attempt to use the liquid tracking of the labware first and then fall back to the 25 if there is no probed or loaded liquid.

Note

If hold_time_minutes and hold_time_seconds are not specified, the Thermocycler will proceed to the next command immediately after temperature is reached.

New in version 2.0.

set_lid_temperature(self, temperature: 'float') → 'None'

Set the target temperature for the heated lid, in °C.

Parameters:

temperature – A value between 37 and 110, representing the target temperature in °C.

Note

The Thermocycler will proceed to the next command immediately after temperature is reached.

New in version 2.0.

start_execute_profile(self, steps: 'List[ThermocyclerStep]', repetitions: 'int', block_max_volume: 'Optional[float]' = None) → 'Task'

Starts a defined Thermocycler Module profile and return a Task representing its concurrent execution. Profile is defined as a cycle of steps, for a given number of repetitions.

Pass the task object to ProtocolContext.wait_for_tasks() to wait for the profile run to complete.

Parameters:

• steps – List of steps that make up a single cycle. Each list item should be a dictionary that maps to the parameters of the set_block_temperature() method. The dictionary’s keys must be temperature and one or both of hold_time_seconds and hold_time_minutes.

• repetitions – The number of times to repeat the cycled steps.

• block_max_volume – The greatest volume of liquid contained in any individual well of the loaded labware, in µL. If not specified, the default is 25 µL.

New in version 2.27.

start_set_block_temperature(self, temperature: 'float', ramp_rate: 'Optional[float]' = None, block_max_volume: 'Optional[float]' = None) → 'Task'

Sets the target temperature for the Thermocycler Module’s well block, in °C.

Returns a Task object that represents concurrent heating. Pass the task object to ProtocolContext.wait_for_tasks() to wait for the preheat to complete.

Parameters:

• temperature – A value between 4 and 99, representing the target temperature in °C.

• block_max_volume – The greatest volume of liquid contained in any individual well of the loaded labware, in µL. If not specified, the default is 25 µL. In API version 2.27 and newer, the API will first attempt to use the liquid tracking in labware, then default to 25 µL if the protocol lacks probed or loaded liquid information.

New in version 2.27.

start_set_lid_temperature(self, temperature: 'float') → 'Task'

Sets a target temperature to heat the Thermocycler Module’s lid, in °C. Returns a Task object that represents concurrent heating.

Pass the task object to ProtocolContext.wait_for_tasks() to wait for the lid to reach the target temperature.

Parameters:

temperature – A value between 37 and 110, representing the target temperature in °C.

New in version 2.27.

property type: Union[Literal['magneticModuleType'], Literal['temperatureModuleType'], Literal['thermocyclerModuleType'], Literal['heaterShakerModuleType'], Literal['magneticBlockType'], Literal['absorbanceReaderType'], Literal['flexStackerModuleType']]

Get the module’s general type identifier.

New in version 2.14.

Useful Types

class opentrons.types.Location(point: Point, labware: Union['Labware', 'Well', str, 'ModuleGeometry', LabwareLike, None, 'ModuleContext'])

A location to target as a motion.

The location contains a Point (in Position Relative to the Deck) 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.

move(self, point: 'Point') → "'Location'"

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

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

>>> loc = Location(Point(1, 1, 1), None)
>>> new_loc = loc.move(Point(1, 1, 1))
>>>
>>> # The new point is the old one plus the given offset.
>>> assert new_loc.point == Point(2, 2, 2)  # True
>>>
>>> # The old point hasn't changed.
>>> assert loc.point == Point(1, 1, 1)  # True

class opentrons.types.Mount(value)

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)

classmethod from_xyz_attrs(has_xyz: '_HasXYZ') → 'Point'

Construct a Point from another object that has .x/.y/.z attributes.

x: float

Alias for field number 0

y: float

Alias for field number 1

z: float

Alias for field number 2

class opentrons.protocol_api.CSVParameter(contents: Optional[bytes], api_version: APIVersion)

property contents: str

Returns the full contents of the CSV file as a single string.

property file: TextIO

Returns the file handler for the CSV file.

The file is treated as read-only, UTF-8-encoded text.

property file_opened: bool

Returns True if a file handler is open for the CSV parameter.

parse_as_csv(self, detect_dialect: bool = True, \*\*kwargs: Any) → List[List[str]]

Parses the CSV data and returns a list of lists.

Each item in the parent list corresponds to a row in the CSV file. If the CSV has a header, that will be the first row in the list: .parse_as_csv()[0].

Each item in the child lists corresponds to a single cell within its row. The data for each cell is represented as a string. You may need to trim whitespace or otherwise validate string contents before passing them as inputs to other API methods. For numeric data, cast these strings to integers or floating point numbers, as appropriate.

Parameters:

• detect_dialect – If True, examine the file and try to assign it a csv.Dialect to improve parsing behavior. Set this to False when using the file output of AbsorbanceReaderContext.read() as a runtime parameter.

• kwargs – For advanced CSV handling, you can pass any of the formatting parameters accepted by csv.reader() from the Python standard library.

opentrons.protocol_api.OFF_DECK

A special location value, indicating that a labware is not currently on the robot’s deck.

See The Off-Deck Location for details on using OFF_DECK with ProtocolContext.move_labware().

class opentrons.protocol_api.OffDeckType(value)

The type of the OFF_DECK constant.

Do not use directly, except in type annotations and isinstance calls.

Executing and Simulating Protocols

opentrons.execute: functions and entrypoint for running protocols

This module has functions that can be imported to provide protocol contexts for running protocols during interactive sessions like Jupyter or just regular python shells. It also provides a console entrypoint for running a protocol from the command line.

opentrons.execute.execute(protocol_file: Union[BinaryIO, TextIO], protocol_name: str, propagate_logs: bool = False, log_level: str = 'warning', emit_runlog: Optional[Callable[[Union[opentrons.legacy_commands.types.DropTipMessage, opentrons.legacy_commands.types.DropTipInDisposalLocationMessage, opentrons.legacy_commands.types.PickUpTipMessage, opentrons.legacy_commands.types.ReturnTipMessage, opentrons.legacy_commands.types.AirGapMessage, opentrons.legacy_commands.types.TouchTipMessage, opentrons.legacy_commands.types.BlowOutMessage, opentrons.legacy_commands.types.BlowOutInDisposalLocationMessage, opentrons.legacy_commands.types.MixMessage, opentrons.legacy_commands.types.TransferMessage, opentrons.legacy_commands.types.DistributeMessage, opentrons.legacy_commands.types.ConsolidateMessage, opentrons.legacy_commands.types.DispenseMessage, opentrons.legacy_commands.types.DispenseInDisposalLocationMessage, opentrons.legacy_commands.types.AspirateMessage, opentrons.legacy_commands.types.HomeMessage, opentrons.legacy_commands.types.HeaterShakerSetTargetTemperatureMessage, opentrons.legacy_commands.types.HeaterShakerWaitForTemperatureMessage, opentrons.legacy_commands.types.HeaterShakerSetAndWaitForShakeSpeedMessage, opentrons.legacy_commands.types.HeaterShakerSetShakeSpeedMessage, opentrons.legacy_commands.types.HeaterShakerOpenLabwareLatchMessage, opentrons.legacy_commands.types.HeaterShakerCloseLabwareLatchMessage, opentrons.legacy_commands.types.HeaterShakerDeactivateShakerMessage, opentrons.legacy_commands.types.HeaterShakerDeactivateHeaterMessage, opentrons.legacy_commands.types.ThermocyclerCloseMessage, opentrons.legacy_commands.types.ThermocyclerWaitForLidTempMessage, opentrons.legacy_commands.types.ThermocyclerDeactivateMessage, opentrons.legacy_commands.types.ThermocyclerDeactivateBlockMessage, opentrons.legacy_commands.types.ThermocyclerDeactivateLidMessage, opentrons.legacy_commands.types.ThermocyclerSetLidTempMessage, opentrons.legacy_commands.types.ThermocyclerWaitForTempMessage, opentrons.legacy_commands.types.ThermocyclerWaitForHoldMessage, opentrons.legacy_commands.types.ThermocyclerExecuteProfileMessage, opentrons.legacy_commands.types.ThermocyclerStartExecuteProfileMessage, opentrons.legacy_commands.types.ThermocyclerSetBlockTempMessage, opentrons.legacy_commands.types.ThermocyclerOpenMessage, opentrons.legacy_commands.types.TempdeckSetTempMessage, opentrons.legacy_commands.types.TempdeckDeactivateMessage, opentrons.legacy_commands.types.MagdeckEngageMessage, opentrons.legacy_commands.types.MagdeckDisengageMessage, opentrons.legacy_commands.types.MagdeckCalibrateMessage, opentrons.legacy_commands.types.CommentMessage, opentrons.legacy_commands.types.DelayMessage, opentrons.legacy_commands.types.PauseMessage, opentrons.legacy_commands.types.ResumeMessage, opentrons.legacy_commands.types.MoveToMessage, opentrons.legacy_commands.types.MoveToDisposalLocationMessage, opentrons.legacy_commands.types.MoveLabwareMessage, opentrons.legacy_commands.types.RobotMoveToMessage, opentrons.legacy_commands.types.RobotMoveAxisToMessage, opentrons.legacy_commands.types.RobotMoveAxisRelativeMessage, opentrons.legacy_commands.types.RobotOpenGripperJawMessage, opentrons.legacy_commands.types.RobotCloseGripperJawMessage, opentrons.legacy_commands.types.FlexStackerSetStoredLabwareMessage, opentrons.legacy_commands.types.FlexStackerRetrieveMessage, opentrons.legacy_commands.types.FlexStackerStoreMessage, opentrons.legacy_commands.types.FlexStackerEmptyMessage, opentrons.legacy_commands.types.FlexStackerFillMessage, opentrons.legacy_commands.types.WaitForTasksMessage, opentrons.legacy_commands.types.CreateTimerMessage]], NoneType]] = None, custom_labware_paths: Optional[List[str]] = None, custom_data_paths: Optional[List[str]] = None) → None

Run the protocol itself.

This is a one-stop function to run a protocol, whether python or json, no matter the api version, from external (i.e. not bound up in other internal server infrastructure) sources.

To run an opentrons protocol from other places, pass in a file like object as protocol_file; this function either returns (if the run has no problems) or raises an exception.

To call from the command line use either the autogenerated entrypoint opentrons_execute or python -m opentrons.execute.

Parameters:

• protocol_file – The protocol file to execute

• protocol_name – The name of the protocol file. This is required internally, but it may not be a thing we can get from the protocol_file argument.

• propagate_logs – Whether this function should allow logs from the Opentrons stack to propagate up to the root handler. This can be useful if you’re integrating this function in a larger application, but most logs that occur during protocol simulation are best associated with the actions in the protocol that cause them. Default: False

• log_level – The level of logs to emit on the command line: "debug", "info", "warning", or "error". Defaults to "warning".

• emit_runlog –

  A callback for printing the run log. If specified, this will be called whenever a command adds an entry to the run log, which can be used for display and progress estimation. If specified, the callback should take a single argument (the name doesn’t matter) which will be a dictionary:

  {
    'name': command_name,
    'payload': {
      'text': string_command_text,
      # The rest of this struct is
      # command-dependent; see
      # opentrons.legacy_commands.commands.
     }
  }
  

  Note

  In older software versions, payload["text"] was a format string. To get human-readable text, you had to do payload["text"].format(**payload). Don’t do that anymore. If payload["text"] happens to contain any { or } characters, it can confuse .format() and cause it to raise a KeyError.

• custom_labware_paths – A list of directories to search for custom labware. Loads valid labware from these paths and makes them available to the protocol context. If this is None (the default), and this function is called on a robot, it will look in the labware subdirectory of the Jupyter data directory.

• custom_data_paths – A list of directories or files to load custom data files from. Ignored if the apiv2 feature flag if not set. Entries may be either files or directories. Specified files and the non-recursive contents of specified directories are presented by the protocol context in ProtocolContext.bundled_data.

opentrons.execute.get_arguments(parser: argparse.ArgumentParser) → argparse.ArgumentParser

Get the argument parser for this module

Useful if you want to use this module as a component of another CLI program and want to add its arguments.

Parameters:

parser – A parser to add arguments to.

Returns argparse.ArgumentParser:

The parser with arguments added.

opentrons.execute.get_protocol_api(version: Union[str, opentrons.protocols.api_support.types.APIVersion], bundled_labware: Optional[Dict[str, ForwardRef('LabwareDefinitionDict')]] = None, bundled_data: Optional[Dict[str, bytes]] = None, extra_labware: Optional[Dict[str, ForwardRef('LabwareDefinitionDict')]] = None) → opentrons.protocol_api.protocol_context.ProtocolContext

Build and return a protocol_api.ProtocolContext connected to the robot.

This can be used to run protocols from interactive Python sessions such as Jupyter or an interpreter on the command line:

>>> from opentrons.execute import get_protocol_api
>>> protocol = get_protocol_api('2.0')
>>> instr = protocol.load_instrument('p300_single', 'right')
>>> instr.home()

When this function is called, modules and instruments will be recached.

Parameters:

• version – The API version to use. This must be lower than opentrons.protocol_api.MAX_SUPPORTED_VERSION. It may be specified either as a string ('2.0') or as a protocols.types.APIVersion (APIVersion(2, 0)).

• bundled_labware – If specified, a mapping from labware names to labware definitions for labware to consider in the protocol. Note that if you specify this, only labware in this argument will be allowed in the protocol. This is preparation for a beta feature and is best not used.

• bundled_data – If specified, a mapping from filenames to contents for data to be available in the protocol from opentrons.protocol_api.ProtocolContext.bundled_data.

• extra_labware – A mapping from labware load names to custom labware definitions. If this is None (the default), and this function is called on a robot, it will look for labware in the labware subdirectory of the Jupyter data directory.

Returns:

The protocol context.

opentrons.execute.main() → int

Handler for command line invocation to run a protocol.

Parameters:

argv – The arguments the program was invoked with; this is usually sys.argv but if you want to override that you can.

Returns int:

A success or failure value suitable for use as a shell return code passed to sys.exit (0 means success, anything else is a kind of failure).

opentrons.simulate: functions and entrypoints for simulating protocols

This module has functions that provide a console entrypoint for simulating a protocol from the command line.

opentrons.simulate.allow_bundle() → bool

Check if bundling is allowed with a special not-exposed-to-the-app flag.

Returns True if the environment variable OT_API_FF_allowBundleCreation is "1"

opentrons.simulate.bundle_from_sim(protocol: opentrons.protocols.types.PythonProtocol, context: opentrons.protocol_api.protocol_context.ProtocolContext) → opentrons.protocols.types.BundleContents

From a protocol, and the context that has finished simulating that protocol, determine what needs to go in a bundle for the protocol.

opentrons.simulate.format_runlog(runlog: List[Mapping[str, Any]]) → str

Format a run log (return value of simulate) into a human-readable string

Parameters:

runlog – The output of a call to simulate

opentrons.simulate.get_arguments(parser: argparse.ArgumentParser) → argparse.ArgumentParser

Get the argument parser for this module

Useful if you want to use this module as a component of another CLI program and want to add its arguments.

Parameters:

parser – A parser to add arguments to. If not specified, one will be created.

Returns argparse.ArgumentParser:

The parser with arguments added.

opentrons.simulate.get_protocol_api(version: Union[str, opentrons.protocols.api_support.types.APIVersion], bundled_labware: Optional[Dict[str, ForwardRef('LabwareDefinitionDict')]] = None, bundled_data: Optional[Dict[str, bytes]] = None, extra_labware: Optional[Dict[str, ForwardRef('LabwareDefinitionDict')]] = None, hardware_simulator: Optional[opentrons.hardware_control.thread_manager.ThreadManager[Union[opentrons.hardware_control.protocols.HardwareControlInterface[opentrons.hardware_control.robot_calibration.RobotCalibration, opentrons.types.Mount, opentrons.config.types.RobotConfig], opentrons.hardware_control.protocols.FlexHardwareControlInterface[opentrons.hardware_control.ot3_calibration.OT3Transforms, Union[opentrons.types.Mount, opentrons.hardware_control.types.OT3Mount], opentrons.config.types.OT3Config]]]] = None, \*, robot_type: Optional[Literal['OT-2', 'Flex']] = None, use_virtual_hardware: bool = True) → opentrons.protocol_api.protocol_context.ProtocolContext

Build and return a protocol_api.ProtocolContext that simulates robot control.

This can be used to simulate protocols from interactive Python sessions such as Jupyter or an interpreter on the command line:

>>> from opentrons.simulate import get_protocol_api
>>> protocol = get_protocol_api('2.0')
>>> instr = protocol.load_instrument('p300_single', 'right')
>>> instr.home()

Parameters:

• version – The API version to use. This must be lower than opentrons.protocol_api.MAX_SUPPORTED_VERSION. It may be specified either as a string ('2.0') or as a protocols.types.APIVersion (APIVersion(2, 0)).

• bundled_labware – If specified, a mapping from labware names to labware definitions for labware to consider in the protocol. Note that if you specify this, only labware in this argument will be allowed in the protocol. This is preparation for a beta feature and is best not used.

• bundled_data – If specified, a mapping from filenames to contents for data to be available in the protocol from opentrons.protocol_api.ProtocolContext.bundled_data.

• extra_labware – A mapping from labware load names to custom labware definitions. If this is None (the default), and this function is called on a robot, it will look for labware in the labware subdirectory of the Jupyter data directory.

• hardware_simulator – This is only for internal use by Opentrons. If specified, it’s a hardware simulator instance to reuse instead of creating a fresh one.

• robot_type – The type of robot to simulate: either "Flex" or "OT-2". If you’re running this function on a robot, the default is the type of that robot. Otherwise, the default is "OT-2", for backwards compatibility.

• use_virtual_hardware – This is only for internal use by Opentrons. If True, use the Protocol Engine’s virtual hardware. If False, use the lower level hardware simulator.

Returns:

The protocol context.

opentrons.simulate.main() → int

Run the simulation

opentrons.simulate.simulate(protocol_file: Union[BinaryIO, TextIO], file_name: Optional[str] = None, custom_labware_paths: Optional[List[str]] = None, custom_data_paths: Optional[List[str]] = None, propagate_logs: bool = False, hardware_simulator_file_path: Optional[str] = None, duration_estimator: Optional[opentrons.protocols.duration.estimator.DurationEstimator] = None, log_level: str = 'warning') → Tuple[List[Mapping[str, Any]], Optional[opentrons.protocols.types.BundleContents]]

Simulate the protocol itself.

This is a one-stop function to simulate a protocol, whether Python or JSON, no matter the API version, from external (i.e. not bound up in other internal server infrastructure) sources.

To simulate an opentrons protocol from other places, pass in a file-like object as protocol_file; this function either returns (if the simulation has no problems) or raises an exception.

To call from the command line, use either the autogenerated entrypoint opentrons_simulate (opentrons_simulate.exe, on windows) or python -m opentrons.simulate.

The return value is the run log, a list of dicts that represent the commands executed by the robot; and either the contents of the protocol that would be required to bundle, or None.

Each dict element in the run log has the following keys:

• level: The depth at which this command is nested. If this an aspirate inside a mix inside a transfer, for instance, it would be 3.

• payload: The command. The human-readable run log text is available at payload["text"]. The other keys of payload are command-dependent; see opentrons.legacy_commands.

  Note

  In older software versions, payload["text"] was a format string. To get human-readable text, you had to do payload["text"].format(**payload). Don’t do that anymore. If payload["text"] happens to contain any { or } characters, it can confuse .format() and cause it to raise a KeyError.

• logs: Any log messages that occurred during execution of this command, as a standard Python LogRecord.

Parameters:

• protocol_file – The protocol file to simulate.

• file_name – The name of the file

• custom_labware_paths – A list of directories to search for custom labware. Loads valid labware from these paths and makes them available to the protocol context. If this is None (the default), and this function is called on a robot, it will look in the labware subdirectory of the Jupyter data directory.

• custom_data_paths – A list of directories or files to load custom data files from. Ignored if the apiv2 feature flag if not set. Entries may be either files or directories. Specified files and the non-recursive contents of specified directories are presented by the protocol context in protocol_api.ProtocolContext.bundled_data.

• hardware_simulator_file_path – A path to a JSON file defining the simulated hardware. This is mainly for internal use by Opentrons, and is not necessary to simulate protocols.

• duration_estimator – For internal use only. Optional duration estimator object.

• propagate_logs – Whether this function should allow logs from the Opentrons stack to propagate up to the root handler. This can be useful if you’re integrating this function in a larger application, but most logs that occur during protocol simulation are best associated with the actions in the protocol that cause them. Default: False

• log_level – The level of logs to capture in the run log: "debug", "info", "warning", or "error". Defaults to "warning".

Returns:

A tuple of a run log for user output, and possibly the required data to write to a bundle to bundle this protocol. The bundle is only emitted if bundling is allowed and this is an unbundled Protocol API v2 python protocol. In other cases it is None.