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

async STAR.clld_probe_y_position_using_channel(channel_idx: int, probing_direction: Literal['forward', 'backward'], start_pos_search: float | None = None, end_pos_search: float | None = None, channel_speed: float = 10.0, channel_acceleration_int: Literal[1, 2, 3, 4] = 4, detection_edge: int = 10, current_limit_int: Literal[1, 2, 3, 4, 5, 6, 7] = 7, post_detection_dist: float = 2.0, tip_bottom_diameter: float = 1.2) → float#

Probe the y-position of a conductive material using the channel’s capacitive Liquid Level Detection (cLLD).

This method carefully moves a specified STAR channel along the y-axis to detect the presence of a conductive surface. It uses STAR’s built-in capacitive sensing to measure where the needle tip first encounters the material, applying safety checks to prevent channel collisions with adjacent channels. After detection, the channel is retracted by a configurable safe distance (post_detection_dist) to avoid mechanical interference.

By default, the parameter tip_bottom_diameter assumes STAR’s integrated teaching needles, which feature an extended, straight bottom section. The correction accounts for the needle’s geometry by adjusting the final reported material y-position to represent the material center rather than the conductive detection edge. If you are using different tips or needle designs (e.g., conical tips or third-party teaching needles), you should adapt the tip_bottom_diameter value to reflect their actual geometry.

Parameters:

  • channel_idx (int) – Index of the channel to probe (0-based). The backmost channel is 0.

  • probing_direction (Literal['forward', 'backward']) – Direction of probing: - “forward” decreases y-position, - “backward” increases y-position.

  • start_pos_search (float | None) – Initial y-position for the search (in mm). If not set, defaults to the current channel y-position.

  • end_pos_search (float | None) – Final y-position for the search (in mm). If not set, defaults to the maximum safe travel range.

  • channel_speed (float) – Channel movement speed during probing (mm/sec). Defaults to 10.0 mm/sec.

  • channel_acceleration_int (Literal[1, 2, 3, 4]) – Acceleration ramp setting [1-4], where the physical acceleration is value * 5,000 steps/sec². Defaults to 4.

  • detection_edge (int) – Edge steepness for capacitive detection [0-1024]. Defaults to 10.

  • current_limit_int (Literal[1, 2, 3, 4, 5, 6, 7]) – Current limit setting [1-7]. Defaults to 7.

  • post_detection_dist (float) – Retraction distance after detection (in mm). Defaults to 2.0 mm.

  • tip_bottom_diameter (float) – Effective diameter of the needle/tip bottom (in mm). Defaults to 1.2 mm, corresponding to STAR’s integrated teaching needles.

Returns:

The corrected y-position (in mm) of the detected conductive material, adjusted for the specified tip_bottom_diameter.

Raises:

ValueError –

  • If probing_direction is invalid. - If start_pos_search or end_pos_search is outside the safe range. - If the configured end position conflicts with the probing direction. - If no conductive material is detected.

Return type:

float