pylabrobot.liquid_handling.backends.hamilton.STAR_backend.STAR.probe_liquid_heights#

async STAR.probe_liquid_heights(containers: List[Container], use_channels: List[int] | None = None, resource_offsets: List[Coordinate] | None = None, lld_mode: LLDMode = LLDMode.GAMMA, search_speed: float = 10.0, n_replicates: int = 1, min_traverse_height_at_beginning_of_command: float | None = None, min_traverse_height_during_command: float | None = None, z_position_at_end_of_command: float | None = None, move_to_z_safety_after: bool | None = None) → List[float]#

Probe liquid surface heights in containers using liquid level detection.

Performs capacitive or pressure-based liquid level detection (LLD) by moving channels to container positions and sensing the liquid surface. Heights are measured from the bottom of each container’s cavity.

Parameters:

  • containers (List[Container]) – List of Container objects to probe, one per channel.

  • use_channels (List[int] | None) – Channel indices to use for probing (0-indexed).

  • resource_offsets (List[Coordinate] | None) – Optional XYZ offsets from container centers. Auto-calculated for single containers with odd channel counts to avoid center dividers. Defaults to container centers.

  • lld_mode (LLDMode) – Detection mode - LLDMode(1) for capacitive, LLDMode(2) for pressure-based. Defaults to capacitive.

  • search_speed (float) – Z-axis search speed in mm/s. Default 10.0 mm/s.

  • n_replicates (int) – Number of measurements per channel. Default 1.

  • min_traverse_height_at_beginning_of_command (float | None) – Absolute Z height (mm) to move involved channels to before the first batch. None (default) uses full Z safety.

  • min_traverse_height_during_command (float | None) – Absolute Z height (mm) to move involved channels to between batches (X groups and Y sub-batches). None (default) uses full Z safety.

  • z_position_at_end_of_command (float | None) – Absolute Z height (mm) to move involved channels to after probing. None (default) uses full Z safety.

  • move_to_z_safety_after (bool | None)

Returns:

Mean of measured liquid heights for each container (mm from cavity bottom).

Raises:

RuntimeError – If channels lack tips.

Return type:

List[float]

Notes

  • All specified channels must have tips attached

  • Containers at different X positions are probed in sequential groups (single X carriage)

  • For single containers with odd channel counts, Y-offsets are applied to avoid center dividers (Hamilton 1000 uL spacing: 9mm, offset: 5.5mm)