---
title: "Robot move until contact"
slug: "robot-move-until-contact"
updated: 2026-07-28T23:37:33Z
published: 2026-07-28T23:37:33Z
canonical: "docs.vention.com/robot-move-until-contact"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Robot move until contact

The **Move Until Tool Contact** instruction lets a robot move slowly along a defined direction and automatically stop when its tool touches an object. Contact is detected using the robot's built-in force/torque sensing: the robot stops as soon as a force or torque threshold is exceeded, or when it has traveled a maximum distance without detecting contact.

This is useful whenever the exact position of a part is not perfectly repeatable, letting the robot "probe" its environment instead of relying on fixed positions:

- **Surface finding**: locate the top of a stack of parts before picking (stacking / de-stacking)
- **Machine tending**: index stock parts in machine vises
- **Guarded moves**: press against a door, drawer, or fixture with a controlled force
- **Insertion and inspection tasks**: find a contact reference before a precise operation

The feature is available in both **MachineLogic Code-Free** (instruction card) and the **MachineLogic Python SDK** (synchronous and asynchronous methods), and behaves the same way in simulation and on the physical machine.

## Compatibility and Requirements

| Requirement | Details |
| --- | --- |
| Controller software | MachineMotion AI **v3.5.0** or later |
| Supported robots | **Universal Robots only** (e-Series, UR20, UR30). The instruction is hidden/disabled for unsupported robots (e.g., Fanuc). Fanuc CRX support is planned for a later release. |
| Programming interfaces | MachineLogic Code-Free instruction, Python SDK (sync + async) |
| Simulation | Supported — contact is simulated at the tool flange using physics-based force/torque modeling |

## How It Works

1. The robot moves **linearly** at the configured speed along the chosen direction, relative to the selected reference frame.
2. While moving, the controller continuously monitors the force (and optionally torque) measured at the robot flange.
3. The motion ends when the first of the following occurs:
  - **Contact detected:** the force or torque threshold is exceeded. The robot stops immediately **without triggering a protective stop**.
  - **Maximum travel reached:** the robot traveled the full configured distance without contact.
4. On contact, the robot can optionally **retract** by a configured distance at a configured speed.
5. The instruction reports its **result**, which you can use to branch your program logic (e.g., handle the "no contact" case).

> **Warning: Force overshoot at contact** The force threshold is a **detection trigger, not a limit on the force applied to the part**. When the threshold is reached, the robot still needs to decelerate to a full stop. During this braking phase the tool keeps pressing on the object, so the **peak force at contact can exceed the configured threshold**.
> 
> The overshoot increases with:
> 
> - **Approach speed**: higher speed means more kinetic energy to dissipate during deceleration
> - **Tool and payload mass**: heavier end-of-arm tooling carries more momentum
> - **Stiffness of the contacted object**: rigid surfaces produce a sharper force spike
> 
> To keep the applied force as close as possible to the threshold, **use the lowest approach speed practical for your application**. For delicate parts or fragile fixtures, size your threshold around the worst-case contact force (threshold + deceleration overshoot), not the threshold value alone.

> **Warning: Contact vs. collision** Move Until Tool Contact is designed for slow, intentional contact. Moving too fast can trigger the robot's protective stop before the instruction detects contact. Keep approach speeds low. Velocity must be positive and is capped at **100 mm/s**

## Using the Code-Free Instruction

### Step 1: Open your MachineLogic application

Open MachineLogic in a design that contains a supported robot.

### Step 2: Add the instruction

In your sequence, add a new instruction and select **Move Until Tool Contact** from the robot commands.

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(633).png)

### Step 3: Configure the instruction

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(634).png)

| Parameter | Description | Units / Default |
| --- | --- | --- |
| Reference frame | Frame in which the motion direction is defined (robot base, TCP, or a custom scene asset frame). At the protocol level, direction is interpreted in the tool (TCP) frame by default | — |
| Direction | Axis and sign of the linear motion relative to the reference frame (e.g., Z−) | — |
| Speed | Approach speed of the linear motion | mm/s — must be positive and non-zero; maximum **100 mm/s** |
| Maximum travel distance | Distance the robot will travel before stopping if no contact is detected | mm |
| Force threshold | Force at which contact is registered | N — default **5 N**, valid range **1–100 N** [TO VERIFY] |
| Torque threshold (optional) | Torque at which contact is registered. Leave unset to detect contact on force only | Nm — not used by default; must be positive and non-zero if set |
| Retract distance (optional) | Distance to move back along the approach direction after contact | mm — if not specified, no retraction |
| Retract speed (optional) | Speed of the retract motion | mm/s — defaults to **250 mm/s** |
| Asset to calibrate (optional) | Scene asset (frame or target) whose pose is updated to the active TCP pose at the point of contact | — |
| Result variable | Variable storing the outcome of the instruction so you can branch on it [TO VERIFY: exact type and values shown in UI] | — |

### Step 4: Calibrate a scene asset on contact (optional)

If you select an **asset to calibrate**, its position and orientation are updated to match the robot's active TCP pose at the precise point of contact. Any subsequent motion instruction referencing this asset automatically uses the updated pose — for example, a **Move to Target** using a child target offset from the calibrated frame.

- If **no contact** is detected (max travel reached), the asset is **not** updated.
- The calibrated pose uses the **currently active TCP**, so make sure your TCP is configured correctly before probing.

### Step 5: Handle the result

Use the result of the instruction to branch your program:

- **Contact detected**: continue with the normal flow (e.g., pick the found part).
- **No contact (max travel reached)**: handle the failure case (e.g., alert an operator, retry, or move to a safe position).

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(635).png)

### Step 6: Simulate

Run your application in simulation. The simulated robot detects contact at the tool level and stops, mirroring the physical behavior, so you can validate your program before deploying.

### Step 7: Deploy and run

Deploy the program to the MachineMotion AI. During execution, the robot state shown in the Control Center (Alarms modal and Manual Mode page) reflects the Move Until operational state.

## Python SDK

The Python SDK exposes Move Until Tool Contact in **synchronous** and **asynchronous** forms: `move_until_tool_contact()` and `move_until_tool_contact_async()`.

### Synchronous example

python

```python
from machinelogic import Machine

machine = Machine()
robot = machine.get_robot("Robot")

# Probe 200 mm downward (base frame Z-) at 25 mm/s.
# Stop on 5 N of force, then retract 30 mm at 50 mm/s.
result = robot.move_until_tool_contact(
    max_travel=[0.0, 0.0, -200.0],   # mm, relative motion vector
    speed=25.0,                      # mm/s
    force_threshold=5.0,             # N
    retract_distance=30.0,           # mm (optional)
    retract_speed=50.0,              # mm/s (optional)
)
```

### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `max_travel` | list[float] | Relative motion vector (mm) defining direction and maximum travel distance |
| `speed` | float | Approach speed in mm/s |
| `force_threshold` | float | Force in N to register contact. Must be positive and non-zero |
| `torque_threshold` | float (optional) | Torque in Nm to register contact. Leave unset to disable torque-based detection — zero/negative values are rejected |
| `retract_distance` | float (optional) | Distance in mm to retract after contact. Defaults to no retraction |
| `retract_speed` | float (optional) | Retraction speed in mm/s. Defaults to 250 mm/s |
| reference frame | — | Motion can be defined relative to the robot base, the tool, or a custom reference frame [TO VERIFY: exact parameter name and accepted values] |

### Result and contact pose

The operation returns a **result code** and the **contact pose** — the robot pose at the point of contact, **expressed relative to the robot base frame**. If contact was not reached, the contact pose equals the final pose.

| Code | Result | Meaning |
| --- | --- | --- |
| 1 | Contact reached | Force or torque threshold exceeded — contact with an object |
| 2 | Max travel reached | The robot traveled the specified maximum distance without detecting contact |
| 3 | Cancelled by user | The operation was cancelled by the user before completion |
| 4 | Cancelled by state change | The operation was cancelled due to a robot state change (e.g., mode or safety transition) |
| 5 | Failed to start | The operation failed to start (e.g., invalid parameters or robot not ready) |
| 6 | Invalid direction | Direction vector magnitude is close to zero |
| 7 | Invalid threshold | A force or torque threshold is negative or zero |
| 8 | Invalid max travel | The maximum travel distance is negative or zero |
| 9 | Invalid velocity | The velocity is negative or zero |
| 10 | Singularity along path | A kinematic singularity exists along the requested path |

### Asynchronous example

```python
# Start the move without blocking, poll while it runs
robot.move_until_tool_contact_async(
    max_travel=[0.0, 0.0, -200.0],
    speed=25.0,
    force_threshold=5.0,
)

while not done:  # [TO VERIFY: completion/polling API]
    # read robot.state, monitor progress, run other logic
    ...
```

## Best Practices and Safety

- **Keep approach speeds low.** High speeds can trigger a protective stop on impact before contact is detected, and increase the force overshoot at contact. Reduce the speed if you see a warning state (yellow light / alert on the pendant) after contact.
- **Set your payload, CoM, and TCP correctly** before using the feature — contact detection compensates for gravity and inertia based on this configuration. At higher speeds, the inertial force from the mounted load can trigger a false contact.
- **Avoid very low force thresholds.** Force readings are noisy; thresholds below ~5 N may false-trigger. [TO VERIFY: published minimum]
- **Do not pass 0 for optional thresholds** in the Python SDK — leave them unset instead.
- Move Until Tool Contact **never overrides protective stops**: it detects intentional contact, it is not a collision-safety feature.

## Troubleshooting

| Symptom | Likely cause | Solution |
| --- | --- | --- |
| Robot enters a warning/protective state after contact | Approach speed too high | Reduce the instruction speed |
| Instruction completes immediately without moving | Torque threshold set to 0 (older custom releases); current versions reject zero/negative thresholds (code 7) | Leave the torque threshold unset |
| Contact triggers with nothing in the way | Threshold too low for sensor noise, or wrong payload/TCP configuration | Raise the threshold; verify payload, CoM, and TCP |
| Contact detected at high speed with heavy tool | Inertial force from acceleration exceeds threshold | Lower the speed or raise the threshold |