Move Until Contact

SUMMARY

Move Until Contact performs controlled motion along a direction until contact is detected.

This skill supports contact-sensitive tasks such as insertion, probing, alignment, and guarded approach operations.

UNITS

cartesian_velocity is [vx, vy, vz, ωx, ωy, ωz] in m/s and deg/s. acceleration in m/s².

The Skill

contacted = robot.move_until_contact(
    cartesian_velocity=[0, 0, -0.02, 0, 0, 0],
    direction=[0, 0, 0, 0, 0, 0],
    acceleration=0.1,
)

The Code

Safety first!

A real robot will faithfully do whatever you ask of it - so please take a moment to clear the workspace, keep an E-Stop within reach, and be ready to disconnect.

Operating real hardware is at your own risk.

Example

Move the TCP downward at 0.02 m/s and stop on contact detected from any direction.

"""
Drives the TCP down in -Z until contact is detected, then stops and reports the result.

Supports Universal Robots (UR).

Usage:
    python move_until_contact.py [--ip <ROBOT_IP>]
"""

import argparse

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(ip: str) -> None:
    """Move the TCP down in -Z until contact is detected, then report and disconnect."""

    #===================== Create Robot ==========================================
    robot = universal_robots.UniversalRobotsUR10E(name='UR10e')

    # ==================== Visualization (Optional) =============================
    # Live: subscribes to the robot's state topic and redraws as it moves.
    robot.visualize_rerun(live=True)

    try:
        #===================== Connect Robot ==========================================
        if ip:
            robot.connect(ip=ip)

        # ==================== Run Skill ============================================
        contacted = robot.move_until_contact(
            cartesian_velocity=[0, 0, -0.02, 0, 0, 0],
            direction=[0, 0, 0, 0, 0, 0],
            acceleration=0.1,
        )
        logger.info(f"Contact detected: {contacted}")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        robot.disconnect()
        robot.shutdown()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Move the TCP down until contact is detected")
    parser.add_argument("--ip", type=str, default=None,
                         help="UR robot IP address for real hardware, e.g. 192.168.1.100")
    args = parser.parse_args()

    main(ip=args.ip)

Running the Example

Real

python move_until_contact.py --ip 192.168.1.100

For all options:

python move_until_contact.py --help

Parameter Configuration

Parameter	Type	Default	Description
cartesian_velocity	list[float] or np.ndarray	-	Desired TCP velocity [xd, yd, zd, rxd, ryd, rzd]. Position in m/s; rotation in deg/s.
direction	list[float] or np.ndarray	-	Contact detection direction [x, y, z, rx, ry, rz] in the base frame. All zeros detects contact from any direction.
acceleration	float	1.4	TCP acceleration in m/s².

Returns

Type	Description
bool	True if a contact was detected during the move, False if the motion terminated without contact (e.g. joint limit reached or commanded move completed).

Raises

Exception	Condition
RuntimeError	The robot is not connected, or the underlying RTDE command fails.
TypeError	cartesian_velocity, direction, or acceleration is not of the expected type.
ValueError	cartesian_velocity or direction is not a 1D vector with exactly 6 elements.

How to Tune the Parameters

Use low approach speeds (0.01-0.05 m/s) for precision contact tasks such as part insertion or surface probing to minimise impact force on contact. Keep acceleration low (e.g. 0.1) for the same reason - a slower ramp-up means less energy behind the TCP at the moment of touchdown.

Set unused components of cartesian_velocity to zero to constrain the approach to the intended direction. For direction, leaving all elements at zero detects contact from any direction, while restricting to a specific axis (e.g. [0, 0, -1, 0, 0, 0]) ignores incidental contacts along axes the approach path is expected to brush past.

Where to Use the Skill

• Surface probing - Detect the surface of a workpiece by moving the TCP toward it at low speed
• Guarded approach - Approach a target position and stop safely when an obstacle is encountered
• Part insertion - Drive a part into a socket or fixture and stop when the part seats
• Calibration - Touch known reference surfaces to determine their position in the robot frame

When Not to Use the Skill

Do not use Move Until Contact when:

• A one-shot contact check is sufficient - use Is Tool in Contact to query the controller's contact state without commanding motion
• The approach path involves obstacles - this skill moves linearly without collision awareness; plan a clear approach path upstream
• High-speed approach is needed - fast impacts generate large contact forces; use trajectory planning with controlled deceleration instead