pylabrobot.brooks.precise_flex.PreciseFlexArm.probe_z_using_ztouch#

async PreciseFlexArm.probe_z_using_ztouch(*, search_start_position: float | None = None, search_end_position: float | None = None, approach_speed_percent: float | None = None, search_speed_percent: int | None = None, detection_force: float = 15.0, perform_second_measurement_on_lift_off: bool = False, post_detection_distance: float = 2.0, move_to_parking_position_after: bool = False, read_timeout: float = 120.0) → float | None#

Lower the arm until the gripper presses on something, and read the height.

Stand the wrist joint over the target, not the fingers: the gripper’s back flat presses on it. Heights are the back flat’s, above the surface the base plate stands on. The controller does not know what touched, so a target under another part reads wrong by the difference.

Parameters:

  • search_start_position (float | None) – back flat height the search starts from, in mm; reached by a checked move. Where the arm stands when None.

  • search_end_position (float | None) – lowest back flat height, in mm. The Z joint’s soft limit when None.

  • approach_speed_percent (float | None) – profile speed down to the start and to the rest after. default_ztouch_approach_speed_percent when None.

  • search_speed_percent (int | None) – system speed during the search, put back after. default_ztouch_search_speed_percent when None. The search has no speed of its own.

  • detection_force (float) – the force at which the search stops, in N.

  • perform_second_measurement_on_lift_off (bool) – whether to measure again while lifting off.

  • post_detection_distance (float) – where to rest above what it met, in mm. Not moved when 0, or when the search met nothing.

  • move_to_parking_position_after (bool) – whether to park afterwards, instead of resting.

  • read_timeout (float) – how long to wait for the search to end, in seconds. A second measurement on lift-off doubles the time: a 90 mm search at 20 percent takes 13 s, 27 s with it.

Returns:

The back flat height where it pressed, in mm, or None if it reached the end. A halt from elsewhere also returns a height, with nothing met: the reply looks the same.

Raises:

  • RuntimeError – If the controller has no licence for Z height detection.

  • ValueError – If an argument is out of range, or the way down would hit the column or the base plate.

  • OperationInterrupted – On a user interrupt; the arm is halted and rises by itself.

  • TimeoutError – If the search outlasts read_timeout. It is then stopped.

Return type:

float | None