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

async STAR.clld_probe_z_height_using_channel(channel_idx: int, lowest_immers_pos: float = 99.98, start_pos_search: float | None = None, channel_speed: float = 10.0, channel_acceleration: float = 800.0, detection_edge: int = 10, detection_drop: int = 2, post_detection_trajectory: Literal[0, 1] = 1, post_detection_dist: float = 2.0, move_channels_to_safe_pos_after: bool = False) → float#

Probe the liquid surface Z-height using a channel’s capacitive LLD (cLLD).

Uses the specified channel to perform a downward cLLD search and returns the last liquid level detected by the instrument for that channel.

This helper is responsible for:

  • Ensuring a tip is mounted on the chosen channel.

  • Reading the mounted tip length and applying the fixed fitting depth (8 mm) to convert tip-referenced Z positions (C0-style coordinates) into the channel Z-drive coordinates required by the firmware ZL cLLD command.

  • Optionally moving channels to a Z-safe position after probing.

Note

cLLD requires a conductive target (e.g., conductive liquid / surface).

Parameters:

  • channel_idx (int) – Channel index to probe with (0-based; backmost channel = 0).

  • lowest_immers_pos (float) – Lowest allowed search position in mm, expressed in the tip-referenced coordinate system (i.e., the position you would use for commands that include tip length). Internally converted to channel Z-drive coordinates before issuing ZL.

  • start_pos_search (float | None) – Start position for the cLLD search in mm, expressed in the tip-referenced coordinate system. Internally converted to channel Z-drive coordinates before issuing ZL. If None, the highest safe position is used based on tip length.

  • channel_speed (float) – Search speed in mm/s. Defaults to 10.0.

  • channel_acceleration (float) – Search acceleration in mm/s^2. Defaults to 800.0.

  • detection_edge (int) – Edge steepness threshold for cLLD detection (0-1023). Defaults to 10.

  • detection_drop (int) – Offset applied after cLLD edge detection (0-1023). Defaults to 2.

  • post_detection_trajectory (Literal[0, 1]) – Firmware post-detection move mode (0 or 1). Defaults to 1.

  • post_detection_dist (float) – Distance in mm to move after detection (interpreted per trajectory). Defaults to 2.0.

  • move_channels_to_safe_pos_after (bool) – If True, moves all channels to a Z-safe position after the probing sequence completes.

Raises:

  • RuntimeError – If no tip is mounted on channel_idx.

  • ValueError – If the computed start position is outside the allowed safe range.

  • STARFirmwareError – If the firmware reports an error during cLLD (channels are moved to Z-safe before re-raising).

Returns:

The detected liquid surface Z-height in mm as reported by request_pip_height_last_lld() for channel_idx.

Return type:

float