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.

SUPPORTED ROBOTS

Currently supported only on Universal Robots.

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.

"""
Move until Contact example for the Synapse SDK.

Drives a real robot downwards in z direction until contact is detected,
then stops and reports the result.

Currently supported only for Universal Robots (UR10e).

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(robot_ip: str):
    """
    Main function to demonstrate how to create an instance of a robot using the Universal Robots module in Python.
    """

    # Create robot instance
    robot = universal_robots.UniversalRobotsUR10E()

    # Connect to the robot
    robot.connect(ip=robot_ip)

    # Move by the cartesian velocity until contact
    contacted = robot.move_until_contact(
        cartesian_velocity=[0, 0, -0.02, 0, 0, 0],
        direction=[0, 0, 0, 0, 0, 0],
        acceleration=0.1,
    )

    # Stop when the robot contact
    if contacted is True:
        logger.info(f"Robot is contacted: {contacted}")
        robot.disconnect()


if __name__ == "__main__":
    # args parser to get ip
    parser = argparse.ArgumentParser(description="UR10e robot move until contact example")
    parser.add_argument("--ip", type=str, required=True, help="IP address of the UR robot")
    args = parser.parse_args()

    main(args.ip)

The Explanation of the Code

move_until_contact moves the TCP linearly at the commanded cartesian_velocity until the controller detects a contact force or the move is aborted (e.g. joint limit reached). The call blocks until the motion terminates and returns a boolean: True when contact was detected, False when the move ended without contact.

Cartesian velocity. cartesian_velocity is a 6D vector [xd, yd, zd, rxd, ryd, rzd] specifying the desired TCP velocity. Position components are in m/s; rotational components are in deg/s. Set unused components to zero to constrain the approach to the intended direction.

Contact direction. direction is a 6D vector defining which directions trigger a contact stop, expressed in the robot base frame. Setting all elements to zero detects contacts from any direction. Setting a specific axis (e.g. [0, 0, -1, 0, 0, 0]) restricts detection to that axis only - useful when the approach path runs close to a surface that should not trigger a stop.

Acceleration. acceleration is the TCP acceleration in m/s². Keep it low (e.g. 0.1) for delicate contact tasks to avoid large impact forces on touchdown.

How to Tune the Parameters

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².

Return Value

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).

Approach speed

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.

WARNING

move_until_contact raises a RuntimeError if the robot is not connected or if the command fails. Always call connect before use and wrap calls in a try/except block in production code.

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