UniteLabs
How-to

Deck & carriers

Setting up the Tecan Freedom EVO worktable with tracks, model presets, and carriers.
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 worktable is a series of 25 mm rail tracks (Tecan calls this surface the worktable; we call it the deck). Carriers are placed by track number, not by absolute coordinate, and each carrier occupies a contiguous span of tracks derived from its width. Labware such as plates and tip boxes are never added to the deck directly — they sit on sites belonging to a carrier.

Prerequisites

  • A switched on Tecan Freedom EVO device
  • A running Tecan Freedom EVO connector
  • Basic understanding of how labware is used (See the using standard labware tutorial)

Coordinate System

The Freedom EVO uses the default UniteLabs deck coordinate system. All measurements are in millimeters.

The y-axis runs the other way than in EVOware. In UniteLabs, y increases toward the back of the worktable and a positive y offset moves toward the back, while in EVOware y increases toward the front. Flip the sign of any y offset you directly carry over from an EVOware method.

Connect and Configure

from unitelabs.sdk import AsyncApiClient
from unitelabs.liquid_handling.tecan import TecanFreedomEvo, TecanFreedomEvoConfiguration
from unitelabs.labware import Vector

client = AsyncApiClient()

evo = TecanFreedomEvo(
    name="Tecan Freedom EVO",
    client=client,
    configuration=TecanFreedomEvoConfiguration(
        model="EVO150",
        mca_discard_location=Vector(x=1000, y=100, z=100),
    ),
)

await evo.configure()
await evo.initialize()
await evo.activate()
configure() reads the instrument's installed-module map from the firmware (whether a Robotic Manipulator Arm and/or Multi-Channel Arm are fitted) and only configures/initializes the modules that are actually present. initialize() calls configure() implicitly if it hasn't run yet. It initializes each installed arm in the sequence that the instrument reports.
Required for the MCA: if the instrument reports a Multi-Channel Arm, mca_discard_location must be set on the configuration before configure() is called — it's the deck-frame position (mm) of channel A1 when the head discards tips into the waste. Omitting it raises a ValueError.

Deck Models

Pass model on the configuration (as done in the example above) to set the track count from an EVO model preset. The track count is applied when configure() runs.

ModelTracks
EVO10030
EVO15045
EVO20069

For a non-standard deck, call deck.configure() directly with an explicit track count instead of a model preset:

await evo.deck.configure(tracks=40, min_track=1, max_track=38)

min_track/max_track bound where carriers may be placed (both default to the full track range); set either to None to remove that boundary.

Arrange Carriers

Carriers hold labware on fixed sites and are placed on the deck by track number. This example uses a 3-position flat microplate carrier.

from unitelabs.labware.plates import Standard96Plate
from unitelabs.labware.tecan import MP_3Pos_flat

plate_carrier = MP_3Pos_flat()
plate = Standard96Plate(identifier="DestinationPlate_96Well")

plate_carrier[0] = plate
evo.deck.add(plate_carrier, track=1)

deck.add() only accepts Carrier instances — passing a plate or tip box directly raises a RuntimeError. Tip boxes (EvoTipBox and its variants) also sit on an ordinary plate carrier site, not a dedicated tip carrier:

from unitelabs.labware.tecan import EvoTipBox_MCA_DiTi_200, EvoTip_MCA_DiTi_200, MP_4Pos_flat

tip_carrier = MP_4Pos_flat()
tip_box = EvoTipBox_MCA_DiTi_200(identifier="TipBox_200uL")
tip_box.fill(EvoTip_MCA_DiTi_200)

tip_carrier[0] = tip_box
evo.deck.add(tip_carrier, track=7)

Alternatively, add a carrier at an explicit location instead of a track. The location is relative to the deck origin, thus Vector(x=25, y=0) is the position of track 2:

evo.deck.add(plate_carrier, location=Vector(x=25, y=0))

Track Boundaries and Overlaps

Placing a carrier outside min_track/max_track raises an IndexError. Placing a carrier so it overlaps tracks already occupied by another carrier raises an OccupiedError.

try:
    evo.deck.add(plate_carrier, track=1)  # already occupied
except Exception as error:
    print(error)
    # Invalid track: 1. Carrier occupies 6 tracks and track 1 is occupied by MP_3Pos_flat

Deck Summary

Print a track-oriented overview of the current deck layout — useful for debugging deck arrangements interactively.

print(evo.deck.summary())
   Track  Name                          ID            Position (x, y, z mm)
================================================================================
     1-6  MP_3Pos_flat                  24a65f1f      (-11.3, -35.5, 0.0)
          └── Standard96Plate          DestinationP (-1.3, 168.3, 6.0)
          └── <empty>
          └── <empty>
    7-12  MP_4Pos_flat                  34c2ae53      (138.7, -35.5, 0.0)
          └── EvoTipBox_MCA_DiTi_200   TipBox_200uL (151.9, 256.9, 6.9)
          └── <empty>
          └── <empty>
          └── <empty>

The summary shows absolute positions. The deck origin is at x = -11.3 mm and y = -35.5 mm, thus a carrier on track 1 starts at (-11.3, -35.5, 0.0).

Remove a Carrier

evo.deck.remove(plate_carrier)

Or clear the whole deck:

evo.deck.clear()

System Controls

The Freedom EVO connector exposes door lock control, but has no stop, resume, or home commands implemented — calling them logs a warning instead of raising, so scripts written against the generic LiquidHandler interface don't break.

# Lock and unlock the front cover
await evo.lock_cover()
await evo.unlock_cover()

lock_cover() and unlock_cover() switch the two locks of the front cover, Lock.LOCK_1 and Lock.LOCK_2. If a lock does not close, the command fails.

The outputs of door locks 3 and 4 can control add-on devices. Use set_lock() to switch these outputs on or off:

from unitelabs.liquid_handling.tecan import Lock

await evo.set_lock(Lock.LOCK_3, on=True)
await evo.set_lock(Lock.LOCK_3, on=False)
set_lock() raises a ValueError for Lock.LOCK_1 and Lock.LOCK_2. Use set_lock() only if you know which device each output controls.
evo.stop(), evo.resume(), and evo.home() are no-ops that log a warning. There is currently no way to halt or home the instrument through the SDK; use the physical stop button or EVOware for emergency stops.

Last updated