Freedrive Mode

SUMMARY

Freedrive mode is used for teach-by-demonstration workflows, operator-guided pose capture, and constrained manual positioning.

start_freedrive_mode puts the robot into gravity-compensated, back-drivable mode along the specified axes, and the robot stays powered but offers no active resistance to manual motion.

stop_freedrive_mode restores normal stiff position control.

SUPPORTED ROBOTS

Currently supported only on Universal Robots.

UNITS

free_axes is a unitless 6-element mask [x, y, z, rx, ry, rz] (0 = locked, 1 = free). feature is a compliance-frame pose in meters and Euler XYZ degrees.

The Skill

# Start freedrive mode on all axes
robot.start_freedrive_mode(free_axes=[1, 1, 1, 1, 1, 1])

# Stop freedrive mode and restore normal control.
robot.stop_freedrive_mode()

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: Start, Use, and Stop a Freedrive Session

Enable freedrive on all axes, allow 10 seconds of manual interaction, then exit cleanly.

"""
Freedrive mode example for the Synapse SDK.

``start_freedrive_mode`` puts the robot into hand-guiding mode — the operator
can physically push the arm and it complies. ``free_axes`` is a 6-element
mask ``[x, y, z, rx, ry, rz]`` where ``1`` means the axis is free and ``0``
means it is locked. ``stop_freedrive_mode`` returns the controller to normal
motion control.

Currently supported only for Universal Robots (UR10e).

Usage:
    python freedrive_mode.py --ip <ROBOT_IP>
"""

import argparse
import time
from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(robot_ip: str):
    """Enter freedrive for 10 seconds, then exit."""

    # Create robot instance
    robot = universal_robots.UniversalRobotsUR10E()

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

    # Enter freedrive with all axes free
    free_axes = [1, 1, 1, 1, 1, 1]
    logger.info(f"Starting freedrive - free axes: {free_axes}")
    robot.start_freedrive_mode(free_axes=free_axes)

    # Hold freedrive open for hand-guiding
    time.sleep(10)

    # Exit freedrive
    robot.stop_freedrive_mode()
    logger.success("Freedrive mode stopped.")

    # Disconnect
    robot.disconnect()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="UR robot freedrive mode 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

start_freedrive_mode puts the robot into gravity-compensated freedrive. free_axes is a 6-element mask [x, y, z, rx, ry, rz] where 1 means the axis is free (compliant) and 0 means it is locked. feature specifies the compliance frame pose [x, y, z, rx, ry, rz]; the default [0, 0, 0, 0, 0, 0] means the base frame.

stop_freedrive_mode sends the exit command to the controller, restoring normal stiff position control. Always call it before issuing programmed motion commands after a freedrive session.

How to Tune the Parameters

start_freedrive_mode

Parameter	Type	Default	Description
free_axes	list[int]	[1, 1, 1, 1, 1, 1]	Six-element mask - 1 = free, 0 = locked, for [x, y, z, rx, ry, rz].
feature	list[float]	[0, 0, 0, 0, 0, 0]	Compliance frame pose [x, y, z, rx, ry, rz] in meters and degrees.

stop_freedrive_mode

This skill takes no input parameters.

Return Value

Method	Type	Description
start_freedrive_mode	None	Returns after freedrive mode is activated.
stop_freedrive_mode	None	Returns after freedrive mode is deactivated.

Where to Use the Skill

• Teach-by-demonstration workflows.
• Operator-guided pose capture.
• Constrained manual positioning along specific axes.

When Not to Use the Skill

• Unconstrained back-drive - use Teach Mode instead when you do not need to configure a compliance frame or axis mask.