urkit 0.3.6__tar.gz → 0.3.8__tar.gz

{urkit-0.3.6 → urkit-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.6
+Version: 0.3.8
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -88,7 +88,7 @@ robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E)
 robot.gripper.activate()
 
 robot.move_to("home")
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])
+robot.move_to("pick", offset_z=0.05)  # 5cm above
 robot.gripper.close()
 robot.move_to("place")
 robot.gripper.open()
@@ -394,10 +394,12 @@ A pose is `[x, y, z, rx, ry, rz]`: position in meters and orientation as a **rot
 
 #### Offsets
 
-Offsets are 6-element lists `[dx, dy, dz, drx, dry, drz]`:
+Offsets can use individual parameters or a full 6-element list:
 
 ```python
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])  # 5cm above pick
+robot.move_to("pick", offset_z=0.05)  # 5cm above
+robot.move_to("pick", offset_x=0.01, offset_z=-0.02)  # combined
+robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full with rotation
 ```
 
 #### Resolve a Pose
@@ -416,7 +418,7 @@ robot.move_to(pose)  # move to the resolved pose later
 from urkit import MoveFrame
 
 robot.move_frame = MoveFrame.TOOL   # default is BASE
-robot.move_relative([0, 0, 0.05, 0, 0, 0])  # 5cm along tool Z
+robot.move_relative(delta_z=0.05)  # 5cm along tool Z
 ```
 
 - **BASE** (default): delta relative to robot base
@@ -440,8 +442,9 @@ robot.import_points("backup.json")
 #### Relative Moves
 
 ```python
-robot.move_relative([0, 0.01, 0, 0, 0, 0])  # 1cm along Y
-robot.move_relative([0, 0, 0.05, 0, 0, 0], frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative(delta_y=0.01)  # 1cm along Y
+robot.move_relative(delta_z=0.05, frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative([0, 0.01, 0, 0, 0, 0])
 ```
 
 #### Sequences with Blending
@@ -454,7 +457,17 @@ robot.move_sequence(["a", "b", "c"], blend_radius=0.02)
 #### Contact Detection
 
 ```python
+# Zeros FT sensor automatically, then moves until force exceeds threshold
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
+
+# Custom threshold (default: 5.0 N/Nm)
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], threshold=10.0)
+
+# Skip zeroing if you need absolute force values
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], zero_first=False)
+
+# Manual zero (e.g. before custom force-based logic)
+robot.zero_ft_sensor()
 ```
 
 #### Velocity Control

{urkit-0.3.6 → urkit-0.3.8}/README.md

@@ -62,7 +62,7 @@ robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E)
 robot.gripper.activate()
 
 robot.move_to("home")
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])
+robot.move_to("pick", offset_z=0.05)  # 5cm above
 robot.gripper.close()
 robot.move_to("place")
 robot.gripper.open()
@@ -368,10 +368,12 @@ A pose is `[x, y, z, rx, ry, rz]`: position in meters and orientation as a **rot
 
 #### Offsets
 
-Offsets are 6-element lists `[dx, dy, dz, drx, dry, drz]`:
+Offsets can use individual parameters or a full 6-element list:
 
 ```python
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])  # 5cm above pick
+robot.move_to("pick", offset_z=0.05)  # 5cm above
+robot.move_to("pick", offset_x=0.01, offset_z=-0.02)  # combined
+robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full with rotation
 ```
 
 #### Resolve a Pose
@@ -390,7 +392,7 @@ robot.move_to(pose)  # move to the resolved pose later
 from urkit import MoveFrame
 
 robot.move_frame = MoveFrame.TOOL   # default is BASE
-robot.move_relative([0, 0, 0.05, 0, 0, 0])  # 5cm along tool Z
+robot.move_relative(delta_z=0.05)  # 5cm along tool Z
 ```
 
 - **BASE** (default): delta relative to robot base
@@ -414,8 +416,9 @@ robot.import_points("backup.json")
 #### Relative Moves
 
 ```python
-robot.move_relative([0, 0.01, 0, 0, 0, 0])  # 1cm along Y
-robot.move_relative([0, 0, 0.05, 0, 0, 0], frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative(delta_y=0.01)  # 1cm along Y
+robot.move_relative(delta_z=0.05, frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative([0, 0.01, 0, 0, 0, 0])
 ```
 
 #### Sequences with Blending
@@ -428,7 +431,17 @@ robot.move_sequence(["a", "b", "c"], blend_radius=0.02)
 #### Contact Detection
 
 ```python
+# Zeros FT sensor automatically, then moves until force exceeds threshold
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
+
+# Custom threshold (default: 5.0 N/Nm)
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], threshold=10.0)
+
+# Skip zeroing if you need absolute force values
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], zero_first=False)
+
+# Manual zero (e.g. before custom force-based logic)
+robot.zero_ft_sensor()
 ```
 
 #### Velocity Control

{urkit-0.3.6 → urkit-0.3.8}/pyproject.toml

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

{urkit-0.3.6 → urkit-0.3.8}/src/urkit/__init__.py

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

{urkit-0.3.6 → urkit-0.3.8}/src/urkit/cli/teach.py

@@ -1441,7 +1441,7 @@ def teach_command(args) -> None:
             **gripper_kwargs,
         )
         print("  Connected.", flush=True)
-        if robot.activate_gripper():
+        if robot._activate_gripper():
             print("  Gripper activated.", flush=True)
     except ConnectionError as e:
         print(f"Connection error: {e}")

{urkit-0.3.6 → urkit-0.3.8}/src/urkit/motion.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import logging
 import os
 import sys
-import time as _time
+import time
 from contextlib import contextmanager
 from enum import IntEnum
 from typing import Iterator
@@ -255,12 +255,28 @@ class Motion:
                 f"Relative move failed: {e}"
             )
 
+    def zero_ft_sensor(self) -> None:
+        """Zero the robot's force/torque sensor.
+
+        Clears the baseline so that subsequent ``getActualTCPForce()``
+        readings reflect only forces applied after this call. Call before
+        ``move_until_contact()`` or any force-based operation.
+
+        Raises:
+            MotionError: If the command fails.
+        """
+        try:
+            self._rtde_c.zeroFtSensor()
+        except Exception as e:
+            raise MotionError(f"Failed to zero FT sensor: {e}")
+
     def move_until_contact(
         self,
         speed_vector: list[float],
         *,
         threshold: float = 5.0,
         acceleration: float = 0.1,
+        zero_first: bool = True,
     ) -> None:
         """Move until contact is detected via TCP force sensing.
 
@@ -280,12 +296,15 @@ class Motion:
                 Contact fires when any of the 6 wrench components changes
                 by more than this value from the baseline reading.
             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
+                rather than delta from zero.
 
         Raises:
             MotionError: If the command fails or the vector is invalid.
 
         Example:
-            >>> # Move straight down until contact
+            >>> # 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)
@@ -303,6 +322,11 @@ class Motion:
                 speed_vector, threshold,
             )
 
+            # Zero FT sensor to clear gravity bias before reading baseline
+            if zero_first:
+                self.zero_ft_sensor()
+                time.sleep(0.05)  # let sensor settle after zero
+
             # Baseline force reading before the loop
             baseline = list(self._rtde_r.getActualTCPForce())
 
@@ -387,9 +411,9 @@ class Motion:
             raise MotionError(f"Duration must be > 0, got {duration}.")
 
         try:
-            start = _time.monotonic()
+            start = time.monotonic()
             while True:
-                elapsed = _time.monotonic() - start
+                elapsed = time.monotonic() - start
                 if elapsed >= duration:
                     break
                 if not self._rtde_c.isConnected():

{urkit-0.3.6 → urkit-0.3.8}/src/urkit/robot.py

@@ -254,19 +254,19 @@ class URRobot:
 
         logger.info("URRobot initialized at %s", ip)
 
-    def activate_gripper(self, *, timeout: float = 10.0) -> bool:
-        """Activate the gripper with a timeout.
+    def _activate_gripper(self, *, timeout: float = 10.0) -> bool:
+        """Activate the gripper with error handling (internal use).
 
         Tries to activate the configured gripper. If activation fails
         or times out (e.g., gripper not physically connected), disconnects
         the gripper, nulls out ``self._gripper``, and returns ``False``.
 
-        This is the single place that handles gripper activation — the
-        CLI and library code should call this rather than touching
-        ``gripper.activate()`` directly.
+        Users should call ``robot.gripper.activate()`` directly instead.
+        This method exists for the CLI which needs graceful fallback
+        when the gripper isn't connected.
 
         Args:
-            timeout: Maximum seconds to wait for activation (default 5.0).
+            timeout: Maximum seconds to wait for activation (default 10.0).
 
         Returns:
             ``True`` if the gripper was activated successfully,
@@ -438,7 +438,7 @@ class URRobot:
         Example:
             >>> robot.move_frame = MoveFrame.TOOL
             >>> robot.move_relative([0.01, 0, 0, 0, 0, 0])  # +X in tool frame
-            >>> robot.move_to("pick", offset=[0, 0, 0.05])   # offset in tool frame
+            >>> robot.move_to("pick", offset_z=0.05)   # offset in tool frame
         """
         return self._move_frame
 
@@ -821,6 +821,12 @@ class URRobot:
         *,
         offset: list[float] | None = None,
         frame: MoveFrame | None = None,
+        offset_x: float = 0.0,
+        offset_y: float = 0.0,
+        offset_z: float = 0.0,
+        offset_rx: float = 0.0,
+        offset_ry: float = 0.0,
+        offset_rz: float = 0.0,
     ) -> list[float]:
         """Resolve a saved point or raw pose to a TCP pose.
 
@@ -831,9 +837,16 @@ class URRobot:
             target: A saved point name (str) or a raw TCP pose
                 [x, y, z, rx, ry, rz].
             offset: Optional offset [dx, dy, dz, drx, dry, drz]
-                applied to the target pose.
+                applied to the target pose. Mutually exclusive with
+                individual offset_* parameters.
             frame: Coordinate frame for the offset. Falls back to the
                 current ``move_frame`` property (BASE or TOOL).
+            offset_x: X offset in meters (default 0.0).
+            offset_y: Y offset in meters (default 0.0).
+            offset_z: Z offset in meters (default 0.0).
+            offset_rx: Roll offset in radians (default 0.0).
+            offset_ry: Pitch offset in radians (default 0.0).
+            offset_rz: Yaw offset in radians (default 0.0).
 
         Returns:
             TCP pose as [x, y, z, rx, ry, rz].
@@ -843,18 +856,32 @@ class URRobot:
 
         Example:
             >>> pose = robot.get_pose("pick")
-            >>> pose = robot.get_pose("pick", offset=[0, 0, 0.05, 0, 0, 0])
+            >>> pose = robot.get_pose("pick", offset_z=0.05)
             >>> robot.move_to(pose)
         """
         point = self._lookup_point(target)
 
-        if offset is not None:
-            if len(offset) != 6:
+        # Build offset from individual params or use provided list
+        individual_offset = [offset_x, offset_y, offset_z, offset_rx, offset_ry, offset_rz]
+        has_individual = any(v != 0.0 for v in individual_offset)
+
+        if offset is not None and has_individual:
+            raise PointError(
+                "Cannot use both 'offset' list and individual offset_* parameters. "
+                "Use one or the other."
+            )
+
+        final_offset = offset if offset is not None and not has_individual else (
+            individual_offset if has_individual else None
+        )
+
+        if final_offset is not None:
+            if len(final_offset) != 6:
                 raise PointError(
                     f"Offset must have 6 values [dx, dy, dz, drx, dry, drz], "
-                    f"got {len(offset)}."
+                    f"got {len(final_offset)}."
                 )
-            point = point.with_offset(offset, frame=frame or self._move_frame)
+            point = point.with_offset(final_offset, frame=frame or self._move_frame)
 
         return list(point.pose)
 
@@ -868,6 +895,12 @@ class URRobot:
         vel: float | None = None,
         acc: float | None = None,
         asynchronous: bool = False,
+        offset_x: float = 0.0,
+        offset_y: float = 0.0,
+        offset_z: float = 0.0,
+        offset_rx: float = 0.0,
+        offset_ry: float = 0.0,
+        offset_rz: float = 0.0,
     ) -> None:
         """Move to a saved point or raw pose.
 
@@ -877,11 +910,18 @@ class URRobot:
             linear: If True (default), use Cartesian linear move (moveL).
                 If False, use joint-space move (moveJ).
             offset: Optional offset [dx, dy, dz, drx, dry, drz]
-                applied to the target pose before moving.
+                applied to the target pose before moving. Mutually
+                exclusive with individual offset_* parameters.
             frame: Coordinate frame for the offset. Falls back to the
                 current ``move_frame`` property (BASE or TOOL).
             vel: Velocity override. Falls back to default_vel.
             acc: Acceleration override. Falls back to default_acc.
+            offset_x: X offset in meters (default 0.0).
+            offset_y: Y offset in meters (default 0.0).
+            offset_z: Z offset in meters (default 0.0).
+            offset_rx: Roll offset in radians (default 0.0).
+            offset_ry: Pitch offset in radians (default 0.0).
+            offset_rz: Yaw offset in radians (default 0.0).
 
         Raises:
             MotionError: If the move fails or IK has no solution.
@@ -890,8 +930,9 @@ class URRobot:
         Example:
             >>> robot.move_to("home")
             >>> robot.move_to("pick", linear=False)
-            >>> robot.move_to("place", offset=[0, 0, 0.05, 0, 0, 0])
-            >>> robot.move_to("place", offset=[0, 0, 0.05], frame=MoveFrame.TOOL)
+            >>> robot.move_to("pick", offset_z=0.05)  # 5cm above
+            >>> robot.move_to("pick", offset_x=0.01, offset_z=-0.02)
+            >>> robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full
             >>> robot.move_to([0.5, 0, 0.3, 0, 0, 0])  # raw pose
         """
         self._check_connection()
@@ -899,14 +940,28 @@ class URRobot:
 
         point = self._lookup_point(target)
 
+        # Build offset from individual params or use provided list
+        individual_offset = [offset_x, offset_y, offset_z, offset_rx, offset_ry, offset_rz]
+        has_individual = any(v != 0.0 for v in individual_offset)
+
+        if offset is not None and has_individual:
+            raise PointError(
+                "Cannot use both 'offset' list and individual offset_* parameters. "
+                "Use one or the other."
+            )
+
+        final_offset = offset if offset is not None and not has_individual else (
+            individual_offset if has_individual else None
+        )
+
         # Apply offset if provided
-        if offset is not None:
-            if len(offset) != 6:
+        if final_offset is not None:
+            if len(final_offset) != 6:
                 raise PointError(
                     f"Offset must have 6 values [dx, dy, dz, drx, dry, drz], "
-                    f"got {len(offset)}."
+                    f"got {len(final_offset)}."
                 )
-            point = point.with_offset(offset, frame=frame or self._move_frame)
+            point = point.with_offset(final_offset, frame=frame or self._move_frame)
 
         pose = list(point.pose)
 
@@ -978,12 +1033,18 @@ class URRobot:
 
     def move_relative(
         self,
-        delta: list[float],
+        delta: list[float] | None = None,
         *,
         linear: bool = True,
         frame: MoveFrame | None = None,
         vel: float | None = None,
         acc: float | None = None,
+        delta_x: float = 0.0,
+        delta_y: float = 0.0,
+        delta_z: float = 0.0,
+        delta_rx: float = 0.0,
+        delta_ry: float = 0.0,
+        delta_rz: float = 0.0,
     ) -> None:
         """Relative Cartesian move from the current position.
 
@@ -992,27 +1053,55 @@ class URRobot:
 
         Args:
             delta: [dx, dy, dz, drx, dry, drz] in meters/radians.
+                Mutually exclusive with individual delta_* parameters.
             linear: If True (default), use Cartesian linear move.
                 If False, solve IK and use joint-space move.
             frame: Coordinate frame for the delta. Falls back to the
                 current ``move_frame`` property (BASE or TOOL).
             vel: Velocity override. Falls back to default_vel.
             acc: Acceleration override. Falls back to default_acc.
+            delta_x: X delta in meters (default 0.0).
+            delta_y: Y delta in meters (default 0.0).
+            delta_z: Z delta in meters (default 0.0).
+            delta_rx: Roll delta in radians (default 0.0).
+            delta_ry: Pitch delta in radians (default 0.0).
+            delta_rz: Yaw delta in radians (default 0.0).
 
         Raises:
             MotionError: If the move fails.
 
         Example:
-            >>> robot.move_relative([0, 0.01, 0, 0, 0, 0])  # 1cm along Y
-            >>> robot.move_relative([0, 0, 0.05], frame=MoveFrame.TOOL)
+            >>> robot.move_relative(delta_y=0.01)  # 1cm along Y
+            >>> robot.move_relative(delta_z=0.05, frame=MoveFrame.TOOL)
+            >>> robot.move_relative([0, 0.01, 0, 0, 0, 0])  # full list
         """
         self._check_connection()
         self._disable_freedrive_guard()
 
-        if len(delta) != 6:
+        # Build delta from individual params or use provided list
+        individual_delta = [delta_x, delta_y, delta_z, delta_rx, delta_ry, delta_rz]
+        has_individual = any(v != 0.0 for v in individual_delta)
+
+        if delta is not None and has_individual:
+            raise MotionError(
+                "Cannot use both 'delta' list and individual delta_* parameters. "
+                "Use one or the other."
+            )
+
+        final_delta = delta if delta is not None and not has_individual else (
+            individual_delta if has_individual else None
+        )
+
+        if final_delta is None:
+            raise MotionError(
+                "Relative move requires either 'delta' list or at least one "
+                "delta_* parameter."
+            )
+
+        if len(final_delta) != 6:
             raise MotionError(
                 f"Relative move requires 6 values [dx,dy,dz,drx,dry,drz], "
-                f"got {len(delta)}."
+                f"got {len(final_delta)}."
             )
 
         vel = vel if vel is not None else self._default_vel
@@ -1021,7 +1110,7 @@ class URRobot:
 
         try:
             current = list(self._rtde_r.getActualTCPPose())
-            target = transform_pose_delta(current, delta, effective_frame)
+            target = transform_pose_delta(current, final_delta, effective_frame)
 
             if linear:
                 self._motion.movel(target, vel=vel, acc=acc)
@@ -1113,16 +1202,31 @@ class URRobot:
         except Exception as e:
             raise MotionError(f"move_sequence failed: {e}")
 
+    def zero_ft_sensor(self) -> None:
+        """Zero the robot's force/torque sensor.
+
+        Clears the baseline so that subsequent force/torque readings
+        reflect only forces applied after this call. Call before
+        ``move_until_contact()`` or any force-based operation.
+
+        Raises:
+            MotionError: If the command fails.
+        """
+        self._check_connection()
+        self._motion.zero_ft_sensor()
+
     def move_until_contact(
         self,
         speed_vector: list[float],
         *,
         threshold: float = 5.0,
         acceleration: float = 0.1,
+        zero_first: bool = True,
     ) -> None:
         """Move until contact is detected via TCP force sensing.
 
         Runs an interruptible control loop — press Ctrl+C to stop at any time.
+        Zeros the FT sensor by default before reading the baseline.
 
         Args:
             speed_vector: 6-element speed vector
@@ -1131,9 +1235,11 @@ class URRobot:
                 Contact fires when any wrench component changes by more
                 than this value from the baseline reading.
             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.
 
         Example:
-            >>> # Move straight down until contact
+            >>> # Move straight down until contact (zeros FT sensor first)
             >>> robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
             >>> # Higher threshold for heavier contact
             >>> robot.move_until_contact([0, 0, -0.02, 0, 0, 0], threshold=10.0)
@@ -1141,7 +1247,10 @@ class URRobot:
         self._check_connection()
         self._disable_freedrive_guard()
         self._motion.move_until_contact(
-            speed_vector, threshold=threshold, acceleration=acceleration
+            speed_vector,
+            threshold=threshold,
+            acceleration=acceleration,
+            zero_first=zero_first,
         )
 
     def move_velocity(

{urkit-0.3.6 → urkit-0.3.8}/src/urkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urkit
-Version: 0.3.6
+Version: 0.3.8
 Summary: Universal Robots e-Series control toolkit built on ur_rtde
 Author: URKit Contributors
 License: MIT
@@ -88,7 +88,7 @@ robot = URRobot(ip="192.168.1.50", points="points.db", gripper=ROBOTIQ_HAND_E)
 robot.gripper.activate()
 
 robot.move_to("home")
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])
+robot.move_to("pick", offset_z=0.05)  # 5cm above
 robot.gripper.close()
 robot.move_to("place")
 robot.gripper.open()
@@ -394,10 +394,12 @@ A pose is `[x, y, z, rx, ry, rz]`: position in meters and orientation as a **rot
 
 #### Offsets
 
-Offsets are 6-element lists `[dx, dy, dz, drx, dry, drz]`:
+Offsets can use individual parameters or a full 6-element list:
 
 ```python
-robot.move_to("pick", offset=[0, 0, 0.05, 0, 0, 0])  # 5cm above pick
+robot.move_to("pick", offset_z=0.05)  # 5cm above
+robot.move_to("pick", offset_x=0.01, offset_z=-0.02)  # combined
+robot.move_to("pick", offset=[0, 0, 0.05, 0, 0.1, 0])  # full with rotation
 ```
 
 #### Resolve a Pose
@@ -416,7 +418,7 @@ robot.move_to(pose)  # move to the resolved pose later
 from urkit import MoveFrame
 
 robot.move_frame = MoveFrame.TOOL   # default is BASE
-robot.move_relative([0, 0, 0.05, 0, 0, 0])  # 5cm along tool Z
+robot.move_relative(delta_z=0.05)  # 5cm along tool Z
 ```
 
 - **BASE** (default): delta relative to robot base
@@ -440,8 +442,9 @@ robot.import_points("backup.json")
 #### Relative Moves
 
 ```python
-robot.move_relative([0, 0.01, 0, 0, 0, 0])  # 1cm along Y
-robot.move_relative([0, 0, 0.05, 0, 0, 0], frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative(delta_y=0.01)  # 1cm along Y
+robot.move_relative(delta_z=0.05, frame=MoveFrame.TOOL)  # 5cm along tool Z
+robot.move_relative([0, 0.01, 0, 0, 0, 0])
 ```
 
 #### Sequences with Blending
@@ -454,7 +457,17 @@ robot.move_sequence(["a", "b", "c"], blend_radius=0.02)
 #### Contact Detection
 
 ```python
+# Zeros FT sensor automatically, then moves until force exceeds threshold
 robot.move_until_contact([0, 0, -0.02, 0, 0, 0])
+
+# Custom threshold (default: 5.0 N/Nm)
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], threshold=10.0)
+
+# Skip zeroing if you need absolute force values
+robot.move_until_contact([0, 0, -0.02, 0, 0, 0], zero_first=False)
+
+# Manual zero (e.g. before custom force-based logic)
+robot.zero_ft_sensor()
 ```
 
 #### Velocity Control