UniteLabs

Move labware with the Tecan Freedom EVO RoMa gripper

Moving labware around the deck with the Tecan Freedom EVO's Robotic Manipulator Arm.
The Freedom EVO is supported in Liquid Handling SDK versions >=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, or LEFT — defaults to the arm's current direction.
  • pick_up_offset: a Vector(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 (default 6).
  • grip_search_distance: how far inside the labware dimension the fingers close to find the labware, in mm (default 3.8).
  • rotation_offset: the angle in degrees that the arm turns past approach_direction, for a site that is not square to the deck (default 0). The gripper offset turns with the arm.
Offset alignment: if you use 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().

Rotated placement: dropping from a different 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.
Calling 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