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

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.

Step 3: Configure the instruction

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

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

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

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.

Asynchronous example

# 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