Hardware Control Reference

Top Level

The definitions here can be reached by importing opentrons.hardware_control and nothing else.

Main API Class

This is the main class used by the API.

class opentrons.hardware_control.api.API(backend: Union[Controller, Simulator], loop: AbstractEventLoop, config: RobotConfig, feature_flags: Optional[HardwareFeatureFlags] = None)

This API is the primary interface to the hardware controller.

Because the hardware manager controls access to the system’s hardware as a whole, it is designed as a class of which only one should be instantiated at a time. This class’s methods should be the only method of external access to the hardware. Each method may be minimal - it may only delegate the call to another submodule of the hardware manager - but its purpose is to be gathered here to provide a single interface.

This implements the protocols in opentrons.hardware_control.protocols, and longer method docstrings may be found there. Docstrings for the methods in this class only note where their behavior is different or extended from that described in the protocol.

async aspirate(self, mount: opentrons.types.Mount, volume: Optional[float] = None, rate: float = 1.0, correction_volume: float = 0.0) → None

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

property attached_modules: List[AbstractModule]

Return a list of currently-attached modules.

property attached_subsystems: Dict[SubSystem, SubSystemState]

Get a view of the hardware subsystems currently attached to the machine.

These subsystems are the programmable parts that underly and provide things like motion control and instruments. Depending on the machine, different subsystems may be available. In general, callers should not use the presence or absence of a specific subsystem to decide whether or not the hardware is operating properly.

axis_is_present(self, axis: opentrons.hardware_control.types.Axis) → bool

Get whether a motor axis is present on the machine.

async blow_out(self, mount: opentrons.types.Mount, volume: Optional[float] = None) → None

Force any remaining liquid to dispense. The liquid will be dispensed at the current location of pipette

property board_revision: str

Return the revision of the central hardware.

async classmethod build_hardware_controller(config: Union[opentrons.config.types.RobotConfig, opentrons.config.types.OT3Config, NoneType] = None, port: Optional[str] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, firmware: Optional[Tuple[pathlib.Path, str]] = None, feature_flags: Optional[opentrons.hardware_control.types.HardwareFeatureFlags] = None) → 'API'

Build a hardware controller that will actually talk to hardware.

This method should not be used outside of a real robot, and on a real robot only one true hardware controller may be active at one time.

Parameters:

  • config – A config to preload. If not specified, load the default.

  • port – A port to connect to. If not specified, the default port (found by scanning for connected FT232Rs).

  • loop – An event loop to use. If not specified, use the result of asyncio.get_event_loop().

async classmethod build_hardware_simulator(attached_instruments: Optional[Dict[opentrons.types.Mount, Dict[str, Optional[str]]]] = None, attached_modules: Optional[Dict[str, List[opentrons.hardware_control.modules.types.SimulatingModule]]] = None, config: Union[opentrons.config.types.RobotConfig, opentrons.config.types.OT3Config, NoneType] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, strict_attached_instruments: bool = True, feature_flags: Optional[opentrons.hardware_control.types.HardwareFeatureFlags] = None) → 'API'

Build a simulating hardware controller.

This method may be used both on a real robot and on dev machines. Multiple simulating hardware controllers may be active at one time.

async cache_instruments(self, require: Optional[Dict[opentrons.types.Mount, Literal['p10_single', 'p10_multi', 'p20_single_gen2', 'p20_multi_gen2', 'p50_single', 'p50_multi', 'p50_single_flex', 'p50_multi_flex', 'p300_single', 'p300_multi', 'p300_single_gen2', 'p300_multi_gen2', 'p1000_single', 'p1000_single_gen2', 'p1000_single_flex', 'p1000_multi_flex', 'p1000_multi_em_flex', 'p1000_96', 'p200_96']]] = None, skip_if_would_block: bool = False) → None

Scan the attached instruments, take necessary configuration actions, and set up hardware controller internal state if necessary.

async cancel_execution_and_running_tasks(self) → None

Cancel all tasks and set execution manager state to Cancelled.

async clean_up(self) → None

Get the API ready to stop cleanly.

property config: RobotConfig

Get the robot’s configuration object.

Returns .RobotConfig:

The object.

async create_simulating_module(self, model: Union[opentrons.hardware_control.modules.types.MagneticModuleModel, opentrons.hardware_control.modules.types.TemperatureModuleModel, opentrons.hardware_control.modules.types.ThermocyclerModuleModel, opentrons.hardware_control.modules.types.HeaterShakerModuleModel, opentrons.hardware_control.modules.types.MagneticBlockModel, opentrons.hardware_control.modules.types.AbsorbanceReaderModel, opentrons.hardware_control.modules.types.FlexStackerModuleModel]) → opentrons.hardware_control.modules.mod_abc.AbstractModule

Get a simulating module hardware API interface for the given model.

async current_position(self, mount: opentrons.types.Mount, critical_point: Optional[opentrons.hardware_control.types.CriticalPoint] = None, refresh: bool = False, fail_on_not_homed: bool = False) → Dict[opentrons.hardware_control.types.Axis, float]

Return the postion (in deck coords) of the critical point of the specified mount.

async delay(self, duration_s: float) → None

Delay execution by pausing and sleeping.

async disengage_axes(self, which: List[opentrons.hardware_control.types.Axis]) → None

Disengage some axes.

async dispense(self, mount: opentrons.types.Mount, volume: Optional[float] = None, rate: float = 1.0, push_out: Optional[float] = None, correction_volume: float = 0.0, is_full_dispense: bool = False) → None

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

property door_state: DoorState

The current state of the machine’s door.

async drop_tip(self, mount: opentrons.types.Mount, home_after: bool = True) → None

Drop tip at the current location.

property engaged_axes: Dict[Axis, bool]

Which axes are engaged and holding

property fw_version: str

Return the firmware version of the connected hardware.

The version is a string retrieved directly from the attached hardware (or possibly simulator).

async gantry_position(self, mount: opentrons.types.Mount, critical_point: Optional[opentrons.hardware_control.types.CriticalPoint] = None, refresh: bool = False, fail_on_not_homed: bool = False) → opentrons.types.Point

Return the position of the critical point for only gantry axes.

get_config(self) → opentrons.config.types.RobotConfig

Get the robot’s configuration object.

Returns .RobotConfig:

The object.

get_deck_from_machine(self, machine_pos: Dict[opentrons.hardware_control.types.Axis, float]) → Dict[opentrons.hardware_control.types.Axis, float]

Convert machine coordinates to deck coordinates.

get_engaged_axes(self) → Dict[opentrons.hardware_control.types.Axis, bool]

Which axes are engaged and holding.

get_estop_state(self) → opentrons.hardware_control.types.EstopState

Get the current Estop state.

If the Estop is not supported on this robot, this will always return Disengaged.

Returns:

The current Estop state.

get_fw_version(self) → str

Return the firmware version of the connected motor control board.

The version is a string retrieved directly from the attached hardware (or possibly simulator).

get_instrument_max_height(self, mount: opentrons.types.Mount, critical_point: Optional[opentrons.hardware_control.types.CriticalPoint] = None) → float

Return max achievable height of the attached instrument based on the current critical point

async get_lights(self) → Dict[str, bool]

Return the current status of the robot lights.

Returns:

A dict of the lights: {‘button’: bool, ‘rails’: bool}

async get_serial_number(self) → Optional[str]

Get the robot serial number, if provisioned. If not provisioned, will be None.

get_status_bar_state(self) → opentrons.hardware_control.types.StatusBarState

There is no status bar on OT-2, return IDLE at all times.

async halt(self, disengage_before_stopping: bool = False) → None

Immediately stop motion, cancel execution manager and cancel running tasks.

After this call, the smoothie will be in a bad state until a call to stop().

has_gripper(self) → bool

Return whether there is a gripper attached to this instance.

  • On robots that do not support a gripper, this will always return False.

  • On robots that support a gripper, this will return based on the current

presence of a gripper.

async home(self, axes: Optional[List[opentrons.hardware_control.types.Axis]] = None) → None

Home the entire robot and initialize current position.

async home_plunger(self, mount: opentrons.types.Mount) → None

Home the plunger motor for a mount, and then return it to the ‘bottom’ position.

async home_z(self, mount: Optional[opentrons.types.Mount] = None, allow_home_other: bool = True) → None

Home the Z-stage(s) of the instrument mounts.

If given a mount, will try to only home that mount. However, if the other mount is currently extended, both mounts will be homed, unless allow_home_other is explicitly set to False.

Setting allow_home_other to False is a bad idea, but the option exists for strict backwards compatibility.

async identify(self, duration_s: int = 5) → None

Blink the button light to identify the robot.

is_movement_execution_taskified(self) → bool

Get whether move functions are being executed inside cancellable tasks.

property is_simulator: bool

True if this is a simulator; False otherwise.

property loop: AbstractEventLoop

The event loop used by this instance.

async move_axes(self, position: Mapping[opentrons.hardware_control.types.Axis, float], speed: Optional[float] = None, max_speeds: Optional[Dict[opentrons.hardware_control.types.Axis, float]] = None, expect_stalls: bool = False) → None

Moves the effectors of the specified axis to the specified position. The effector of the x,y axis is the center of the carriage. The effector of the pipette mount axis are the mount critical points but only in z.

async move_rel(self, mount: opentrons.types.Mount, delta: opentrons.types.Point, speed: Optional[float] = None, max_speeds: Optional[Dict[opentrons.hardware_control.types.Axis, float]] = None, check_bounds: opentrons.hardware_control.types.MotionChecks = <MotionChecks.NONE: 0>, fail_on_not_homed: bool = False) → None

Move the critical point of the specified mount by a specified displacement in a specified direction, at the specified speed.

async move_to(self, mount: opentrons.types.Mount, abs_position: opentrons.types.Point, speed: Optional[float] = None, critical_point: Optional[opentrons.hardware_control.types.CriticalPoint] = None, max_speeds: Optional[Dict[opentrons.hardware_control.types.Axis, float]] = None) → None

Move the critical point of the specified mount to a location relative to the deck, at the specified speed.

pause(self, pause_type: opentrons.hardware_control.types.PauseType) → None

Pause motion of the robot after a current motion concludes.

pause_with_message(self, message: str) → None

As pause, but providing a message to registered callbacks.

async pick_up_tip(self, mount: opentrons.types.Mount, tip_length: float, presses: Optional[int] = None, increment: Optional[float] = None, prep_after: bool = True) → None

Pick up tip from current location.

async prepare_for_aspirate(self, mount: opentrons.types.Mount, rate: float = 1.0) → None

Prepare the pipette for aspiration.

async prepare_for_mount_movement(self, mount: opentrons.types.Mount) → None

Retract the other mount if necessary.

register_callback(self, cb: Callable[[Union[opentrons.hardware_control.types.DoorStateNotification, opentrons.hardware_control.types.ErrorMessageNotification, opentrons.hardware_control.types.EstopStateNotification]], NoneType]) → Callable[[], NoneType]

Allows the caller to register a callback, and returns a closure that can be used to unregister the provided callback

async reset(self) → None

Reset the stored state of the system.

resume(self, pause_type: opentrons.hardware_control.types.PauseType) → None

Resume motion after a call to pause.

async retract(self, mount: opentrons.types.Mount, margin: float = 10) → None

Pull the specified mount up to its home position.

Works regardless of critical point or home status.

async retract_axis(self, axis: opentrons.hardware_control.types.Axis, margin: float = 10) → None

Pull the specified axis up to its home position.

Works regardless of critical point or home status.

set_config(self, config: Union[opentrons.config.types.OT3Config, opentrons.config.types.RobotConfig]) → None

Replace the currently-loaded config

async set_lights(self, button: Optional[bool] = None, rails: Optional[bool] = None) → None

Control the robot lights.

async set_status_bar_enabled(self, enabled: bool) → None

The status bar does not exist on OT-2!

async set_status_bar_state(self, state: opentrons.hardware_control.types.StatusBarState) → None

The status bar does not exist on OT-2!

should_taskify_movement_execution(self, taskify: bool) → None

Specify whether move functions should be executed inside cancellable tasks.

async stop(self, home_after: bool = True) → None

Stop motion as soon as possible, reset, and optionally home.

This will cancel motion (after the current call to move(); see pause() for more detail), then home and reset the robot. After this call, no further recovery is necessary.

async update_config(self, \*\*kwargs: Any) → None

Update values of the robot’s configuration.

kwargs should contain keys of the robot’s configuration. For instance, update_config(log_level=’debug) would change the API server log level to logging.DEBUG.

Documentation on keys can be found in the documentation for RobotConfig.

async update_firmware(self, firmware_file: str, loop: Optional[asyncio.events.AbstractEventLoop] = None, explicit_modeset: bool = True) → str

Update the firmware on the motor controller board.

Parameters:

  • firmware_file – The path to the firmware file.

  • explicit_modeset – True to force the smoothie into programming mode; False to assume it is already in programming mode.

  • loop – An asyncio event loop to use; if not specified, the one associated with this instance will be used.

Returns:

The stdout of the tool used to update the smoothie

async update_nozzle_configuration_for_mount(self, mount: opentrons.types.Mount, back_left_nozzle: Optional[str], front_right_nozzle: Optional[str], starting_nozzle: Optional[str] = None) → None

Update a nozzle configuration for a given pipette.

The expectation of this function is that the back_left_nozzle/front_right_nozzle are the two corners of a rectangle of nozzles. A call to this function that does not follow that schema will result in an error.

Parameters:

  • mount – A robot mount that the instrument is on.

  • back_left_nozzle – A string representing a nozzle name of the form <LETTER><NUMBER> such as ‘A1’.

  • front_right_nozzle – A string representing a nozzle name of the form <LETTER><NUMBER> such as ‘A1’.

  • starting_nozzle – A string representing the starting nozzle which will be used as the critical point

of the pipette nozzle configuration. By default, the back left nozzle will be the starting nozzle if none is provided. :return: None.

If none of the nozzle parameters are provided, the nozzle configuration will be reset to default.

ThreadManager

The ThreadManager wraps the hardware controller and runs it in another thread, which lets some things run in the background and allows you to run your own asyncio loop in the main thread without being blocked by Smoothie communication.

class opentrons.hardware_control.thread_manager.ThreadManager(builder: ~typing.Callable[[~Builder], ~typing.Awaitable[~opentrons.hardware_control.thread_manager.WrappedObj]], *args: ~typing.~Builder, **kwargs: ~typing.~Builder)

A wrapper to make every call into hardware_control.API execute within the same thread.

This class spawns a worker thread and starts an event loop within. It then calls the async builder parameter within that worker thread’s event loop passing thru all args and kwargs and injecting the worker thread’s loop as a kwarg to the builder. The resulting built object is stored as a member of the class, and a synchronous interface to the managed object’s members is also exposed for convenience.

If you want to wait for the managed object’s creation separately (with managed_thread_ready_blocking or managed_thread_ready_async)

use the nonblocking_builder static method to add an attribute to the builder

function, i.e.

thread_manager = ThreadManager(ThreadManager.nonblocking_builder(builder), …)

Example



>>> from opentrons.hardware_control import API, ThreadManager
>>> api_single_thread = ThreadManager(API.build_hardware_simulator)
>>> await api_single_thread.home() # call as awaitable async
>>> api_single_thread.sync.home() # call as blocking sync
static nonblocking_builder(builder: Callable[Builder, Awaitable[Built]]) → Callable[Builder, Awaitable[Built]]

Wrap an instance of a builder function to make initializes that use it nonblocking.

For instance, you can build a ThreadManager like this:

thread_manager = ThreadManager(ThreadManager.nonblocking_builder(API.build_hardware_controller), …)

to make the initialize call return immediately so you can later wait on it via managed_thread_ready_blocking or managed_thread_ready_async

wrap_module(self, module: opentrons.hardware_control.modules.mod_abc.AbstractModule) → opentrons.hardware_control.thread_manager.CallBridger[opentrons.hardware_control.modules.mod_abc.AbstractModule]

Return the module object wrapped in a CallBridger and cache it.

The wrapped module objects are cached in self._cached_modules so they can be re-used throughout the module object’s life, as creating a wrapper is expensive. We use a WeakKeyDictionary for caching so that module objects can be garbage collected when modules are detached (since entries in WeakKeyDictionary get discarded when there is no longer a strong reference to the key).

wrapped(self) → +WrappedObj

Expose the type of the underlying wrapped object.

This isn’t a method that does anything (it just returns self again) but the cast means that the type of self will be what the threadmanager’s generic wrapped object is. You can therefore use this to get typechecking when using ThreadManagers.

While the generic type is what you say it is when you annotate the instance variable containing a ThreadManager, if you restrict yourself to annotating

those instances using a protocol from hardware_api.protocols, things will more

or less work out through the rest of the system. Not perfect, but ok.

wraps_instance(self, of_type: Type[Any]) → bool

Do isinstance() on the wrapped object.

Modules

The module classes obey a framework. There are individual controller classes for each kind of module.

Top Level

These things may be imported by importing opentrons.hardware_control.modules.

Abstract Base Class

All module components have interfaces that match the abstract base class defined here.

class opentrons.hardware_control.modules.mod_abc.AbstractModule(port: str, usb_port: USBPort, execution_manager: ExecutionManager, hw_control_loop: AbstractEventLoop, disconnected_callback: Optional[Callable[[str, str | None], None]] = None)

Defines the common methods of a module.

abstract bootloader(self) → Callable[[str, str, Dict[str, Any]], Awaitable[Tuple[bool, str]]]

Method used to upload file to this module’s bootloader.

abstract async classmethod build(port: str, usb_port: opentrons.drivers.rpi_drivers.types.USBPort, execution_manager: opentrons.hardware_control.execution_manager.ExecutionManager, hw_control_loop: asyncio.events.AbstractEventLoop, poll_interval_seconds: Optional[float] = None, simulating: bool = False, sim_model: Optional[str] = None, sim_serial_number: Optional[str] = None, disconnected_callback: Optional[Callable[[str, str | None], NoneType]] = None) → 'AbstractModule'

Modules should always be created using this factory.

This lets the (perhaps blocking) work of connecting to and initializing a module be in a place that can be async.

async cleanup(self) → None

Clean up the module instance.

Clean up, i.e. stop pollers, disconnect serial, etc in preparation for object destruction.

abstract async deactivate(self, must_be_running: bool = True) → None

Deactivate the module.

Contains an override to the wait_for_is_running step in cases where the module must be deactivated regardless of context.

abstract property device_info: Mapping[str, str]

Return a dict of the module’s static information (serial, etc)

disconnected_callback(self) → None

Called from within the module object to signify the object is no longer connected

abstract firmware_prefix(self) → str

The prefix used for looking up firmware

get_bundled_fw(self) → Optional[opentrons.hardware_control.modules.types.BundledFirmware]

Get absolute path to bundled version of module fw if available.

has_available_update(self) → bool

Return whether a newer firmware file is available

abstract property is_simulated: bool

True if >this is a simulated module.

abstract property live_data: LiveData

Return a dict of the module’s dynamic information

abstract model(self) → str

A name for this specific module, matching module defs

abstract classmethod name() → str

A shortname used for matching usb ports, among other things

property port: str

The virtual port where the module is connected.

abstract async prep_for_update(self) → str

Prepare for an update.

By the time this coroutine completes, the hardware should be ready to take an update. This implicitly tears down the module instance; it does not need to be either working or recoverable after this coroutine completes.

Returns str:

The port we’re running on.

property serial_number: Optional[str]

The usb serial number of this device.

abstract property status: str

Return some string describing status.

property updating: bool

The device is updating is True.

property usb_port: USBPort

The physical port where the module is connected.

Temperature Module

class opentrons.hardware_control.modules.tempdeck.TempDeck(port: str, usb_port: USBPort, execution_manager: ExecutionManager, driver: AbstractTempDeckDriver, reader: TempDeckReader, poller: Poller, device_info: Dict[str, str], hw_control_loop: AbstractEventLoop, disconnected_callback: Optional[Callable[[str, str | None], None]] = None)

Hardware control interface for an attached Temperature Module.

async await_temperature(self, awaiting_temperature: 'Optional[float]') → 'None'

Await a target temperature in degrees Celsius.

Polls Temperature Module’s temperature until the specified temperature is reached.

Parameters:

temperature – The temperature to wait for. If None (recommended), the module’s target will be used. Specifying any value other than the current target may produce unpredictable behavior.

bootloader(self) → 'types.UploadFunction'

Method used to upload file to this module’s bootloader.

async classmethod build(port: 'str', usb_port: 'USBPort', execution_manager: 'ExecutionManager', hw_control_loop: 'asyncio.AbstractEventLoop', poll_interval_seconds: 'Optional[float]' = None, simulating: 'bool' = False, sim_model: 'Optional[str]' = None, sim_serial_number: 'Optional[str]' = None, disconnected_callback: 'ModuleDisconnectedCallback' = None) → "'TempDeck'"

Build a TempDeck

Parameters:

  • port – The port to connect to

  • usb_port – USB Port

  • execution_manager – Execution manager.

  • hw_control_loop – The event loop running in the hardware control thread.

  • poll_interval_seconds – Poll interval override.

  • simulating – whether to build a simulating driver

  • sim_model – The model name used by simulator

  • disconnected_callback – Callback to inform the module controller that the device was disconnected

Returns:

Tempdeck instance

async cleanup(self) → 'None'

Stop the poller task.

async deactivate(self, must_be_running: 'bool' = True) → 'None'

Stop heating/cooling and turn off the fan

property device_info: Dict[str, str]

Return a dict of the module’s static information (serial, etc)

firmware_prefix(self) → 'str'

The prefix used for looking up firmware

has_available_update(self) → 'bool'

Override of abc implementation to suppress update notifications for v1, v1.1, and v2 temperature modules which cannot be updated

property is_simulated: bool

True if >this is a simulated module.

property live_data: LiveData

Return a dict of the module’s dynamic information

model(self) → 'str'

A name for this specific module, matching module defs

classmethod name() → 'str'

A shortname used for matching usb ports, among other things

async prep_for_update(self) → 'str'

Prepare for an update.

By the time this coroutine completes, the hardware should be ready to take an update. This implicitly tears down the module instance; it does not need to be either working or recoverable after this coroutine completes.

Returns str:

The port we’re running on.

async start_set_temperature(self, celsius: 'float') → 'None'

Set the target temperature in degrees Celsius.

Range: 4 to 95 degrees Celsius (QA tested).

The internal temp range is -9 to 99 °C, which is limited by the two-digit temperature display. Any input outside of this range will be clipped to the nearest limit.

property status: TemperatureStatus

Return some string describing status.

Magnetic Module

class opentrons.hardware_control.modules.magdeck.MagDeck(port: str, usb_port: USBPort, execution_manager: ExecutionManager, hw_control_loop: AbstractEventLoop, driver: AbstractMagDeckDriver, device_info: Dict[str, str], disconnected_callback: Optional[Callable[[str, str | None], None]] = None)

Hardware control interface for an attached Temperature Module.

bootloader(self) → Callable[[str, str, Dict[str, Any]], Awaitable[Tuple[bool, str]]]

Get the bootloating method.

async classmethod build(port: str, usb_port: opentrons.drivers.rpi_drivers.types.USBPort, execution_manager: opentrons.hardware_control.execution_manager.ExecutionManager, hw_control_loop: asyncio.events.AbstractEventLoop, poll_interval_seconds: Optional[float] = None, simulating: bool = False, sim_model: Optional[str] = None, sim_serial_number: Optional[str] = None, disconnected_callback: Optional[Callable[[str, str | None], NoneType]] = None) → 'MagDeck'

Factory function.

async calibrate(self) → None

Calibration involves probing for top plate to get the plate height.

async cleanup(self) → None

Clean up the module instance.

Clean up, i.e. stop pollers, disconnect serial, etc in preparation for object destruction.

property current_height: float

Get the current height.

async deactivate(self, must_be_running: bool = True) → None

Home the magnet.

property device_info: Dict[str, str]

a dict { ‘serial’: ‘abc123’, ‘model’: ‘8675309’, ‘version’: ‘9001’ }

Type:

Returns

async engage(self, height: Optional[float] = None, height_from_base: Optional[float] = None, must_be_running: bool = True) → None

Move the magnet to a specific height, measured from home position.

The units of position depend on the module model. For GEN1, it’s half millimeters (“short millimeters”). For GEN2, it’s millimeters.

firmware_prefix(self) → str

The prefix used for looking up firmware

property is_simulated: bool

True if >this is a simulated module.

property live_data: LiveData

Return a dict of the module’s dynamic information

model(self) → str

Get the model.

classmethod name() → str

Get the module name.

async prep_for_update(self) → str

Prepare for an update.

By the time this coroutine completes, the hardware should be ready to take an update. This implicitly tears down the module instance; it does not need to be either working or recoverable after this coroutine completes.

Returns str:

The port we’re running on.

property serial_number: Optional[str]

The usb serial number of this device

property status: MagneticStatus

Return some string describing status.

Thermocycler

class opentrons.hardware_control.modules.thermocycler.Thermocycler(port: str, usb_port: USBPort, execution_manager: ExecutionManager, driver: AbstractThermocyclerDriver, reader: ThermocyclerReader, poller: Poller, device_info: Dict[str, str], hw_control_loop: AbstractEventLoop, disconnected_callback: Optional[Callable[[str, str | None], None]] = None)

Hardware control interface for an attached Thermocycler.

bootloader(self) → 'types.UploadFunction'

Method used to upload file to this module’s bootloader.

async classmethod build(port: 'str', usb_port: 'USBPort', execution_manager: 'ExecutionManager', hw_control_loop: 'asyncio.AbstractEventLoop', poll_interval_seconds: 'Optional[float]' = None, simulating: 'bool' = False, sim_model: 'Optional[str]' = None, sim_serial_number: 'Optional[str]' = None, disconnected_callback: 'ModuleDisconnectedCallback' = None) → "'Thermocycler'"

Build and connect to a Thermocycler

Parameters:

  • port – The port to connect to

  • usb_port – USB Port

  • execution_manager – Execution manager.

  • hw_control_loop – The event loop running in the hardware control thread.

  • poll_interval_seconds – Poll interval override.

  • simulating – whether to build a simulating driver

  • loop – Loop

  • sim_model – The model name used by simulator

  • disconnected_callback – Callback to inform the module controller that the device was disconnected

Returns:

Thermocycler instance.

async cleanup(self) → 'None'

Stop the poller task.

async close(self) → 'str'

Close the lid if it is open

async cycle_temperatures(self, steps: 'List[types.ThermocyclerStep]', repetitions: 'int', volume: 'Optional[float]' = None) → 'None'

Begin a set temperature cycle.

Parameters:

  • steps – The set temperature steps.

  • repetitions – Number of repetitions.

  • volume – Optional volume.

Returns: None

async deactivate(self, must_be_running: 'bool' = True) → 'None'

Deactivate the block peltiers and lid heating pad

async deactivate_block(self, must_be_running: 'bool' = True) → 'None'

Deactivate the block peltiers

async deactivate_lid(self, must_be_running: 'bool' = True) → 'None'

Deactivate the lid heating pad

property device_info: Mapping[str, str]

Return a dict of the module’s static information (serial, etc)

async execute_profile(self, profile: 'List[Union[types.ThermocyclerCycle, types.ThermocyclerStep]]', volume: 'Optional[float]' = None) → 'None'

Begin a set temperature profile, with both repeating and non-repeating steps.

Parameters:

  • profile – The temperature profile to follow.

  • volume – Optional volume

Returns: None

firmware_prefix(self) → 'str'

The prefix used for looking up firmware

property is_simulated: bool

True if >this is a simulated module.

async lift_plate(self) → 'str'

If the lid is open, lift the plate.

Note that this should always be preceded by an open call. If the lid is not open, the Thermocycler will respond with an error message.

Returns: Thermocycler lid status after running the command.

property live_data: LiveData

Return a dict of the module’s dynamic information

model(self) → 'str'

A name for this specific module, matching module defs

classmethod name() → 'str'

A shortname used for matching usb ports, among other things

async open(self) → 'str'

Open the lid if it is closed

async prep_for_update(self) → 'str'

Prepare for an update.

By the time this coroutine completes, the hardware should be ready to take an update. This implicitly tears down the module instance; it does not need to be either working or recoverable after this coroutine completes.

Returns str:

The port we’re running on.

async raise_plate(self) → 'None'

Move lid an extra bit.

property ramp_rate: Optional[float]

Not supported.

async return_from_raise_plate(self) → 'None'

Return lid back to normal open position.

async set_lid_temperature(self, temperature: 'float') → 'None'

Set the lid temperature in degrees Celsius

async set_target_block_temperature(self, celsius: 'float', hold_time_seconds: 'Optional[float]' = None, volume: 'Optional[float]' = None) → 'None'

Set the Thermocycler’s target block temperature.

Does not wait for the target temperature to be reached.

Parameters:

celsius – The target block temperature, in degrees celsius.

async set_target_lid_temperature(self, celsius: 'float') → 'None'

Set the Thermocycler’s target lid temperature.

Does not wait for the target temperature to be reached.

Parameters:

celsius – The target lid temperature, in degrees celsius.

async set_temperature(self, temperature: 'float', hold_time_seconds: 'Optional[float]' = None, hold_time_minutes: 'Optional[float]' = None, ramp_rate: 'Optional[float]' = None, volume: 'Optional[float]' = None) → 'None'

Set the temperature and wait.

If hold time is set this function will return after the hold time expires.

Otherwise it will return when the target temperature is reached.

Parameters:

  • temperature – The target temperature.

  • hold_time_seconds – Optional number of seconds to wait.

  • hold_time_minutes – Optional number of minutes to wait.

  • ramp_rate – Optional ramp rate.

  • volume – Optional volume.

Returns: None

property status: TemperatureStatus

Return some string describing status.

async wait_for_block_target(self) → 'None'

Wait for thermocycler to reach given temperature.

Will return when the target temperature is reached.

Parameters:

temperature – The target temperature.

Returns: None

async wait_for_lid_target(self) → 'None'

Set the lid temperature in degrees Celsius