urkit 0.3.22__tar.gz → 0.3.23__tar.gz

{urkit-0.3.22 → urkit-0.3.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.22
+Version: 0.3.23
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -506,6 +506,16 @@ robot.move_until_contact(speed_z=-0.02, zero_first=False)
 # Full speed vector
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
 
+# Abort after 10s or 200mm of travel, whichever comes first
+robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2)
+
+# Returns True if contact detected, False if timeout/max_distance hit
+for _ in range(3):
+    if robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2):
+        break  # contact detected
+    # No contact — back off and retry
+    robot.move_by(z=0.01)
+
 # Manual zero (e.g. before custom force-based logic)
 robot.zero_ft_sensor()
 ```

{urkit-0.3.22 → urkit-0.3.23}/README.md

@@ -480,6 +480,16 @@ robot.move_until_contact(speed_z=-0.02, zero_first=False)
 # Full speed vector
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
 
+# Abort after 10s or 200mm of travel, whichever comes first
+robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2)
+
+# Returns True if contact detected, False if timeout/max_distance hit
+for _ in range(3):
+    if robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2):
+        break  # contact detected
+    # No contact — back off and retry
+    robot.move_by(z=0.01)
+
 # Manual zero (e.g. before custom force-based logic)
 robot.zero_ft_sensor()
 ```

{urkit-0.3.22 → urkit-0.3.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "urkit"
-version = "0.3.22"
+version = "0.3.23"
 description = "Universal Robots e-Series control toolkit built on ur_rtde"
 readme = "README.md"
 license = {text = "MIT"}

{urkit-0.3.22 → urkit-0.3.23}/src/urkit/__init__.py

@@ -24,7 +24,7 @@ Quick start::
 
 from __future__ import annotations
 
-__version__ = "0.3.22"
+__version__ = "0.3.23"
 
 from urkit.config import load_config, resolve_config
 from urkit.exceptions import (

{urkit-0.3.22 → urkit-0.3.23}/src/urkit/motion.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import io
 import logging
+import math
 import os
 import sys
 import time
@@ -278,7 +279,9 @@ class Motion:
         threshold: float = 5.0,
         acceleration: float = 0.1,
         zero_first: bool = True,
-    ) -> None:
+        timeout: float | None = None,
+        max_distance: float | None = None,
+    ) -> bool:
         """Move until contact is detected via TCP force sensing.
 
         Runs a 500 Hz control loop that sends ``speedL()`` commands and
@@ -300,15 +303,30 @@ class Motion:
             zero_first: If True (default), zero the FT sensor before reading
                 the baseline. Set to False if you need absolute force values
                 rather than delta from zero.
+            timeout: Maximum time in seconds before aborting. If exceeded,
+                returns ``False``. Set to ``None`` (default) for no time limit.
+            max_distance: Maximum TCP travel distance in meters before aborting.
+                If exceeded, returns ``False``. Set to ``None`` (default) for
+                no distance limit.
+
+        Returns:
+            ``True`` if contact was detected, ``False`` if timeout or
+            max_distance was reached without contact.
 
         Raises:
-            MotionError: If the command fails or the vector is invalid.
+            MotionError: If the command fails (connection lost, E-stop,
+                protective stop, invalid params).
 
         Example:
             >>> # Move straight down until contact (zeros FT sensor first)
             >>> motion.move_until_contact([0, 0, -0.02, 0, 0, 0])
             >>> # Move down while rotating, higher threshold
             >>> motion.move_until_contact([0, 0, -0.02, 0, 0.1, 0], threshold=10.0)
+            >>> # Retry loop with guards
+            >>> for _ in range(3):
+            ...     if motion.move_until_contact([0, 0, -0.02, 0, 0, 0], timeout=10.0, max_distance=0.2):
+            ...         break
+            ...     # No contact — reposition and retry
         """
         if len(speed_vector) != 6:
             raise MotionError(
@@ -316,11 +334,16 @@ class Motion:
             )
         if threshold <= 0:
             raise MotionError(f"Threshold must be > 0, got {threshold}.")
+        if timeout is not None and timeout <= 0:
+            raise MotionError(f"Timeout must be > 0, got {timeout}.")
+        if max_distance is not None and max_distance <= 0:
+            raise MotionError(f"max_distance must be > 0, got {max_distance}.")
 
+        contact_detected = False
         try:
             logger.debug(
-                "move_until_contact: speed_vector=%s, threshold=%.2f",
-                speed_vector, threshold,
+                "move_until_contact: speed_vector=%s, threshold=%.2f, timeout=%s, max_distance=%s",
+                speed_vector, threshold, timeout, max_distance,
             )
 
             # Zero FT sensor to clear gravity bias before reading baseline
@@ -331,7 +354,34 @@ class Motion:
             # Baseline force reading before the loop
             baseline = list(self._rtde_r.getActualTCPForce())
 
+            # Track timeout and distance guards
+            start_time = time.monotonic() if timeout is not None else None
+            start_pose = list(self._rtde_r.getActualTCPPose())[:3] if max_distance is not None else None
+
             while True:
+                # Check time timeout
+                if start_time is not None and timeout is not None:
+                    elapsed = time.monotonic() - start_time
+                    if elapsed >= timeout:
+                        logger.info(
+                            "move_until_contact timed out after %.1fs (limit: %.1fs)",
+                            elapsed, timeout,
+                        )
+                        break
+
+                # Check distance timeout
+                if start_pose is not None and max_distance is not None:
+                    current_pose = list(self._rtde_r.getActualTCPPose())[:3]
+                    distance = math.sqrt(
+                        sum((current_pose[i] - start_pose[i]) ** 2 for i in range(3))
+                    )
+                    if distance >= max_distance:
+                        logger.info(
+                            "move_until_contact exceeded max_distance: %.3fm travelled (limit: %.3fm)",
+                            distance, max_distance,
+                        )
+                        break
+
                 if not self._rtde_c.isConnected():
                     raise MotionError(
                         "RTDE connection lost during move_until_contact. "
@@ -363,6 +413,7 @@ class Motion:
                 if any(
                     abs(current[i] - baseline[i]) > threshold for i in range(6)
                 ):
+                    contact_detected = True
                     break
 
                 with _suppress_rtde_stderr():
@@ -378,6 +429,8 @@ class Motion:
             except Exception:
                 pass
 
+        return contact_detected
+
     def move_velocity(
         self,
         speed_vector: list[float],

{urkit-0.3.22 → urkit-0.3.23}/src/urkit/robot.py

@@ -1614,13 +1614,15 @@ class URRobot:
         threshold: float = 5.0,
         acceleration: float = 0.1,
         zero_first: bool = True,
+        timeout: float | None = None,
+        max_distance: float | None = None,
         speed_x: float = 0.0,
         speed_y: float = 0.0,
         speed_z: float = 0.0,
         speed_rx: float = 0.0,
         speed_ry: float = 0.0,
         speed_rz: float = 0.0,
-    ) -> None:
+    ) -> bool:
         """Move until contact is detected via TCP force sensing.
 
         Runs an interruptible control loop — press Ctrl+C to stop at any time.
@@ -1636,9 +1638,17 @@ class URRobot:
             acceleration: Acceleration limit passed to ``speedL()`` in m/s².
             zero_first: If True (default), zero the FT sensor before reading
                 the baseline. Set to False if you need absolute force values.
+            timeout: Maximum time in seconds before aborting. Set to ``None``
+                (default) for no time limit.
+            max_distance: Maximum TCP travel distance in meters before aborting.
+                Set to ``None`` (default) for no distance limit.
             speed_x, speed_y, speed_z: Linear speed components in m/s.
             speed_rx, speed_ry, speed_rz: Angular speed components in rad/s.
 
+        Returns:
+            ``True`` if contact was detected, ``False`` if timeout or
+            max_distance was reached without contact.
+
         Example:
             >>> # Move straight down until contact
             >>> robot.move_until_contact(speed_z=-0.02)
@@ -1646,6 +1656,8 @@ class URRobot:
             >>> robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
             >>> # Higher threshold for heavier contact
             >>> robot.move_until_contact(speed_z=-0.02, threshold=10.0)
+            >>> # Abort after 10s or 200mm, whichever comes first
+            >>> robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2)
         """
         self._check_connection()
         self._disable_freedrive_guard()
@@ -1655,11 +1667,13 @@ class URRobot:
         else:
             final_vector = [speed_x, speed_y, speed_z, speed_rx, speed_ry, speed_rz]
 
-        self._motion.move_until_contact(
+        return self._motion.move_until_contact(
             final_vector,
             threshold=threshold,
             acceleration=acceleration,
             zero_first=zero_first,
+            timeout=timeout,
+            max_distance=max_distance,
         )
 
     def move_velocity(

{urkit-0.3.22 → urkit-0.3.23}/src/urkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.22
+Version: 0.3.23
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -506,6 +506,16 @@ robot.move_until_contact(speed_z=-0.02, zero_first=False)
 # Full speed vector
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
 
+# Abort after 10s or 200mm of travel, whichever comes first
+robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2)
+
+# Returns True if contact detected, False if timeout/max_distance hit
+for _ in range(3):
+    if robot.move_until_contact(speed_z=-0.02, timeout=10.0, max_distance=0.2):
+        break  # contact detected
+    # No contact — back off and retry
+    robot.move_by(z=0.01)
+
 # Manual zero (e.g. before custom force-based logic)
 robot.zero_ft_sensor()
 ```