setup() opens the connection and initialises head state. Nothing else works before it — PLR’s own @need_setup_finished decorator enforces this on aspirate, dispense, and the tip methods.
2
Carriers are labware that holds labware. PLT_CAR_L5AC_A00 is a five-position Hamilton plate carrier.
3
rails= is Hamilton-specific: deck positions are numbered rails, not slots. On an OTDeck you would pass a slot number instead.
Python you need here
carrier[0] = plate works because PlateCarrier implements __setitem__. It is the same assignment you would write for a list, and it does the assign_child_resource call for you.
11.1 Move a plate to a carrier position
Move a plate from one carrier position to another.
await lh.move_plate(plate, carrier[2])
The destination is deliberately permissive. Any of these work:
Gotcha: the grip is on the plate, not the plate and its lid.
move_plate grips the plate body. If the plate has a lid on it, the lid is not held — depending on the gripper and the plate, it can be left behind or dragged. Move the lid first (next recipe), or move the plate and lid as a unit only if your gripper supports it.
See also:lh.move_resource() for the general form, lh.pick_up_resource() / move_picked_up_resource() / drop_resource() when you need the three phases separately.
11.2 Take the lid off a plate and put it back
Move a plate’s lid off, then put it back.
lidded = cor_96_wellplate_360uL_Fb(name="lidded_plate", with_lid=True)carrier[3] = liddedlid = lidded.lidawait lh.move_lid(lid, carrier[4])assertnot lidded.has_lid()# ... pipette into the open plate ...await lh.move_lid(lid, lidded)
1
move_lid takes the Lid object, which you reach through plate.lid. Keep a reference to it — once the lid is off, lidded.lid is None, so this is your only handle for putting it back.
2
has_lid() is a method, not a property.not plate.has_lid is always False, because a bound method is truthy — the parentheses are load-bearing.
3
Moving a lid to a plate re-lids it — the plate is a valid destination, not just a location.
with_lid=True builds the plate with its lid already seated.
2
nesting_z_height is the vertical overlap between lid and parent. A Lid constructed with 0 prints a warning, because a lid that does not nest is almost always a mismeasurement.
3
The lid is centred on the parent’s top face and sunk by that overlap: 14.2 − 7.6 = 6.6 mm.
4
lid is a property derived from the children, with a setter: assigning None unassigns the lid, and assigning a Lid seats one.
plate size_z: 14.2
lid nesting_z: 7.6
lid seated at z: 6.6
has_lid(): True
after `lid = None`: False
A lid must cover what it sits on. Liddable.assign_child_resource compares footprints and allows a shortfall of at most LID_UNDERSIZE_TOLERANCE (1.0 mm), since real lids sit just inside the rim:
ValueError: Lid 'wrong_lid' (100.0 x 60.0 mm) is smaller than 'lidded_demo' (127.76 x 85.48 mm) and cannot cover it.
Liddable is mixed into Container as well as Plate, so troughs, tubes, petri dishes, and individual wells can carry a lid on the same API.
A seal is not a lid.
If your process heat-seals a plate rather than lidding it, there is no Lid object to move — the seal is applied by a machine and PLR has no representation of it. Model it however you like (a flag on your own protocol state), but do not expect has_lid to know about it.
11.3 Move a plate onto a magnetic bead stand
Move a plate onto an Alpaqua Magnum FLX magnetic rack for a bead cleanup, then take it off again.
magnet = alpaqua_96_plateadapter_magnum_flx(name="magnet")lh.deck.assign_child_resource(magnet, rails=20)await lh.move_plate(plate, magnet)# ... beads pellet against the magnet; aspirate the supernatant ...await lh.move_plate(plate, carrier[0])
1
The magnet is a PlateAdapter, not a machine. There is no turn_on() — see below.
2
Because it is a PlateAdapter, it computes where the plate sits rather than you supplying a location. compute_plate_location() does this from the plate’s own well geometry.
3
Coming off the magnet is the same call in reverse.
A magnet is not a machine.
Nothing turns this magnet on. Engagement is the plate’s position — the field is always there, and the plate being on the adapter is what puts the beads in it. This is the same idea as Incubator.take_in_plate(), whose entire implementation is two lines of tree bookkeeping:
plate.unassign()site.assign_child_resource(plate)
State expressed by position rather than by command. Once you see it, a lot of PLR reads differently.
WarningGotcha: plate_z_offset is not universal
The shipped definition carries this comment:
dz=27.5, # refers to magnet hole bottomplate_z_offset=0.0, # adjust at runtime based on plate's well geometry
plate_z_offset=0.0 is a default, not a measurement for your plate. A skirted PCR plate and a deep-well block do not sit at the same height on the same magnet. An unchecked value puts the tip above the liquid or into the plate bottom.
Gotcha: use the snake_case name.
Alpaqua_96_magnum_flx still exists but is a deprecation shim marked # TODO: Remove >2026-02. Use alpaqua_96_plateadapter_magnum_flx. This rename is part of a library-wide migration to <vendor>_<n>_<type>_<volume>uL_<bottom>; expect to meet it elsewhere.
11.4 Aspirating off the magnet
The reason bead protocols exist is to remove supernatant without disturbing the pellet, which lives on one side of the well. That is an offset, not a different well:
Pull 2.5 mm away from the magnet side and stay 1 mm off the bottom. Which sign of x is “away” depends on which side your magnet pellets to — check once, write it down.
See also:Chapter 4 for offsets and anchors in general; SergiLabSupplies_96_MagneticRack_250ul_Vb for a second magnet definition to compare against.
11.5 Gripper parameters
Every move takes the same set of gripper arguments. move_plate, move_lid, and move_resource differ only in their defaults.
Argument
Meaning
pickup_distance_from_top
how far below the resource’s top face the gripper closes, in mm
pickup_offset
offset applied at the source
destination_offset
offset applied at the destination
pickup_direction
which side the gripper approaches from
drop_direction
which side it faces when released
intermediate_locations
coordinates to traverse through on the way
import inspectfrom pylabrobot.liquid_handling import LiquidHandlerfor name in ("move_resource", "move_plate", "move_lid"): d = inspect.signature(getattr(LiquidHandler, name)).parameters["pickup_distance_from_top"].defaultprint(f"{name:15s} pickup_distance_from_top = {d}")
The defaults are per-method, not per-resource: a plate is gripped 9.87 mm below its top, a lid 2.37 mm below its own top, and move_resource grips at the top face unless told otherwise. A plate whose skirt is not 9.87 mm deep needs the argument.
Adjacent directions rotate 90°, opposite directions 180°, and the rotation accumulates on the resource’s existing rotation. A plate that comes back at 270° indexes along its own axes (chapter 3), so plate["A1"] is no longer where it was.
The backend receives this as three frozen dataclasses — ResourcePickup, ResourceMove, and ResourceDrop. ResourceDrop carries both directions plus the computed rotation, which is what a backend needs to command the arm (chapter 18).
See also: the three phases are separately callable as pick_up_resource, move_picked_up_resource, and drop_resource. Picking up twice without dropping raises RuntimeError: Resource ... already picked up, and a backend with no arm raises RuntimeError: No robotic arm is installed on this liquid handler.
11.6 Where a resource is gripped
pick_up_resource takes pickup_distance_from_top=None, and resolves it from the resource.
A point on the resource, measured in its own frame, where the gripper should close.
3
Resolution order when pickup_distance_from_top is None: use size_z - preferred_pickup_location.z if the resource has one, otherwise 5.0 mm. Both branches log at debug.
Machine definitions use this where the grip point is not a guess: the Byonoy plate readers ship preferred_pickup_location=Coordinate(x=size_x / 2, y=size_y / 2, z=29.5), so a plate is taken from the reader at the height the reader presents it.
Note the asymmetry: move_plate and move_lid pass a numeric default, so they never consult preferred_pickup_location. It applies to pick_up_resource and to move_resource when the argument is left as None.
11.7 Take the top plate off a stack
Take the top plate off a stack without tracking the index yourself.
Every protocol that involves a human step, an off-deck machine, or a manual intervention needs this. The alternative — leaving PLR’s model stale — produces the worst class of bug in lab automation: the robot is confidently, precisely wrong.
11.9 What to remember
move_plate / move_lid / move_resourcemove the object and update the model. Both halves.
A PlateAdapter computes where a plate sits. Do not hand-compute z onto a magnet or a block.
A magnet is not a machine; position is the state.
When something moves without PLR knowing, unassign() then assign_child_resource().