Move labware with the Tecan Freedom EVO RoMa gripper
>=0.35.0. This page applies to Liquid Handling SDK version 0.43.0 and later, and to Tecan Freedom EVO connector version 0.6.0 and later.The Freedom EVO's Robotic Manipulator (RoMa) is a plate gripper that moves labware between deck sites. It is mounted on a separate arm that is independent from the pipetting head and approaches labware from one of four cardinal directions.
Prerequisites
- A switched on Tecan Freedom EVO device with a Robotic Manipulator Arm
- A plate carrier with a plate
- A running Tecan Freedom EVO connector
- Basic understanding of the liquid handler class (See Deck & carriers)
Connect and Initialize
from unitelabs.sdk import AsyncApiClient
from unitelabs.liquid_handling.tecan import TecanFreedomEvo
client = AsyncApiClient()
evo = TecanFreedomEvo(name="Tecan Freedom EVO", client=client)
await evo.configure()
await evo.initialize()
await evo.activate()
gripper is a vendor-neutral alias for roma — both refer to the same RoboticManipulatorArm instance.Arrange the Deck
from unitelabs.labware.plates import Standard96Plate
from unitelabs.labware.tecan import MP_3Pos_flat
plate_carrier = MP_3Pos_flat()
plate = Standard96Plate(identifier="Plate_96Well")
plate_carrier[0] = plate
evo.deck.add(plate_carrier, track=1)
Pick Up Labware
Pass the labware object directly to pick_up(). The RoMa approaches from its current facing direction unless approach_direction is given explicitly.
from unitelabs.liquid_handling.tecan import ApproachDirection
await evo.roma.pick_up(plate, approach_direction=ApproachDirection.FRONT)
assert evo.roma.get() == plate
assert await evo.roma.has_labware() is True
pick_up() accepts optional parameters to fine-tune the grip:
approach_direction:FRONT,RIGHT,BACK, orLEFT— defaults to the arm's current direction.pick_up_offset: aVector(dx, dy)in mm to adjust the pick-up location.width_offset: an offset in mm to adjust the assumed size of the labware.grip_gap: the initial gap between the gripper and the labware before closing, in mm (default6).grip_search_distance: how far inside the labware dimension the fingers close to find the labware, in mm (default3.8).rotation_offset: the angle in degrees that the arm turns pastapproach_direction, for a site that is not square to the deck (default0). The gripper offset turns with the arm.
pick_up_offset when picking up, pass the same value as drop_offset to put_down. A mismatch can misalign the gripper on the drop.Put Down Labware
Pass the target carrier site to put_down() — indexing a carrier returns its CarrierSite objects, not the deck. plate_carrier[1] is the second (empty) site of the 3-position carrier used above.
await evo.roma.put_down(plate_carrier[1], approach_direction=ApproachDirection.FRONT)
assert evo.roma.get() is None
assert plate_carrier[1].get() == plate
put_down() also accepts rotation_offset, with the same meaning as for pick_up().
approach_direction than the labware was picked up with lands it physically rotated on the deck. The labware's own rotation attribute is updated to match, so downstream resource-graph state stays accurate.Pick Up From / Transfer
pick_up_from references a carrier site directly instead of the labware object:
await evo.roma.pick_up_from(plate_carrier[1])
await evo.roma.put_down(plate_carrier[1])
transfer() combines pick up and put down into a single call:
await evo.roma.transfer(plate, target=plate_carrier[2])
transfer_from() moves labware between two sites without needing a reference to the labware object:
await evo.roma.transfer_from(
source=plate_carrier[2],
target=plate_carrier[0],
)
transfer() and transfer_from() accept grip_search_distance, and they accept a different rotation offset for each end of the move: pick_up_rotation_offset and drop_rotation_offset.
Gripper Fingers
Open or close the fingers directly, independent of a pick up/put down operation.
# Open to a specific width (mm, finger to finger)
await evo.roma.open_to(width=100)
# Close onto a plate; searches for it under the configured current limit
await evo.roma.close_to(width=80)
# Current opening width
width = await evo.roma.current_grip_width()
# Reachable travel limits (finger to finger), in mm
lower, upper = await evo.roma.get_gripper_machine_range()
close_to()/close_by() raise a RuntimeError if the gripper is already holding labware — release it with open_to() first.open_to() while the gripper is holding labware unassigns the labware from the gripper — it's no longer attached to any carrier site either, so you must manually reassign it by calling assign() on the target site (e.g. plate_carrier[1].assign(plate)). Prefer put_down() over open_to() for placing labware, since it does this internally; using open_to() to release labware is mainly for error recovery.Configure the grip search parameters:
await evo.roma.set_gripper_parameters(
speed=50, # search speed while closing, in mm/s (0.1-150)
pwm_limit=100, # gripper PWM limit (0-249)
current_limit=2, # grip strength as current limit (0-3)
)
Arm Movement
evo.roma.move_to() and evo.roma.move_by() raise a NotImplementedError. To move the RoMa body directly by absolute location or relative offset, use the protocol layer evo.roma.api. Rotations are in degrees:
from unitelabs.labware import Vector
await evo.roma.api.move_to(location=Vector(x=200, y=150, z=100), rotation=0)
await evo.roma.api.move_by(offset=Vector(z=-10), rotation_offset=90)
api.move_to() and api.move_by() move the arm in a straight line. They do not raise the arm to the traverse height first, and they do not do a reach check. Make sure that the path is clear before you move the arm.location = await evo.roma.current_location()
rotation = await evo.roma.current_rotation()
direction = await evo.roma.current_direction() # nearest ApproachDirection within 90°
Initialization State
evo.initialize() initializes the RoMa together with the other installed arms. evo.activate() reads the initialization state of the RoMa axes from the instrument, and raises a ModuleError if an axis is not initialized.
To read the error code of each RoMa axis, use the protocol layer:
from unitelabs.liquid_handling.tecan.tecan_freedom_evo_protocol import EvoModule
errors = await evo.api.read_extended_error(EvoModule.ROBOTIC_MANIPULATOR_ARM) # one code per axis
An error code of 7 shows that the axis is not initialized.
Troubleshooting
Last updated