Deck & carriers
>=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.
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.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.
| Model | Tracks |
|---|---|
EVO100 | 30 |
EVO150 | 45 |
EVO200 | 69 |
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