Expose STARBackend.move_channel_probe_z()

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

@@ -4530,11 +4530,82 @@ async def move_channel_y(self, channel: int, y: float):
     )
 
   async def move_channel_z(self, channel: int, z: float):
-    """Move a channel in the z direction."""
+    """Move a channel in the Z direction.
+
+    The Hamilton firmware interprets this Z position based on its internal
+    "tip mounted" state for the specified channel. When the firmware state
+    indicates that no tip is mounted, the absolute Z position refers to the
+    bottom of the stop disc. In that case, this command is effectively
+    equivalent to :meth:`move_channel_probe_z` for the same numeric Z value.
+
+    When the firmware state indicates that a tip is mounted on the channel,
+    the same Z position instead refers to the physical end of the tip. In
+    this case, the numeric Z value used with this method may differ from the
+    probe Z position used with :meth:`move_channel_probe_z` for the same
+    physical height above the deck.
+    """
     await self.position_single_pipetting_channel_in_z_direction(
       pipetting_channel_index=channel + 1, z_position=round(z * 10)
     )
 
+  async def move_channel_probe_z(
+    self,
+    channel: int,
+    z: float,
+    speed: float = 125.0,
+    acceleration: float = 800.0,
+    current_limit: int = 3,
+  ):
+    """Move a channel's probe Z-drive to an absolute position, communicating directly
+    with the individual channel rather than through the master module.
+
+    "Probe" refers to the lowest point of the stop disc / entire channel assembly
+    without a tip attached.
+
+    Use this instead of `move_channel_z` when the firmware's internal "tip picked up"
+    flag has been incorrectly set (e.g. after sleeve-sensing displacement during
+    tip-presence probing), which causes master-routed Z moves to misbehave.
+
+    Args:
+      channel: Channel index (0-based, backmost = 0).
+      z: Target Z position in mm.
+      speed: Max Z-drive speed in mm/sec. Default 125.0 mm/s.
+      acceleration: Acceleration in mm/sec². Default 800.0. Valid range: ~53.6 to 1609.
+      current_limit: Current limit (0-7). Default 3.
+    """
+
+    z_increment = STARBackend.mm_to_z_drive_increment(z)
+    speed_increment = STARBackend.mm_to_z_drive_increment(speed)
+    acceleration_increment = STARBackend.mm_to_z_drive_increment(acceleration / 1000)
+
+    if not isinstance(channel, int):
+      raise ValueError(f"channel must be an int, got {type(channel).__name__}")
+    if not (0 <= channel < self.num_channels):
+      raise ValueError(
+        f"channel index {channel} out of range for instrument with {self.num_channels} channels"
+      )
+    assert 9320 <= z_increment <= 31200, (
+      f"z must be between {STARBackend.z_drive_increment_to_mm(9320)} and "
+      f"{STARBackend.z_drive_increment_to_mm(31200)} mm, got {z} mm"
+    )
+    assert 20 <= speed_increment <= 15000, (
+      f"speed must be between {STARBackend.z_drive_increment_to_mm(20)} and "
+      f"{STARBackend.z_drive_increment_to_mm(15000)} mm/s, got {speed} mm/s"
+    )
+    assert 5 <= acceleration_increment <= 150, (
+      f"acceleration must be between ~53.6 and ~1609 mm/s², got {acceleration} mm/s²"
+    )
+    assert 0 <= current_limit <= 7, f"current_limit must be between 0 and 7, got {current_limit}"
+
+    return await self.send_command(
+      module=STARBackend.channel_id(channel),
+      command="ZA",
+      za=f"{z_increment:05}",
+      zv=f"{speed_increment:05}",
+      zr=f"{acceleration_increment:03}",
+      zw=f"{current_limit:01}",
+    )
+
   async def move_channel_x_relative(self, channel: int, distance: float):
     """Move a channel in the x direction by a relative amount."""
     current_x = await self.request_x_pos_channel_n(channel)