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.

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.

"""
Enters freedrive (hand-guiding) mode for 10 seconds, then exits.

Supports Universal Robots (UR).

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

import argparse
import time

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(ip: str) -> None:
    """Enter freedrive for 10 seconds, then exit."""

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

    # ==================== Visualization (Optional) =============================
    robot.visualize_rerun(live=True)

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

        # ==================== Run Skill ============================================
        # 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.")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        robot.disconnect()
        robot.shutdown()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Start freedrive (hand-guiding) mode, then stop it")
    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 start_and_stop_freedrive_mode.py --ip 192.168.1.100

For all options:

python start_and_stop_freedrive_mode.py --help

Parameter Configuration

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.

Returns

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

Raises

start_freedrive_mode

Exception	Condition
RuntimeError	The robot is not connected
ConnectionError / OSError	The connection to the controller fails or drops during the surrounding hardware session

stop_freedrive_mode

Exception	Condition
RuntimeError	The robot is not connected
ConnectionError / OSError	The connection to the controller fails or drops during the surrounding hardware session

How to Tune the Parameters

Lock axes in free_axes (set them to 0) to constrain manual guidance to a plane or line - for example locking rotation ([1, 1, 1, 0, 0, 0]) lets an operator freely reposition the TCP while keeping its orientation fixed. feature changes which frame those axes are defined in: leave it at the default base-frame pose for locking axes aligned with the robot base, or pass a tool-aligned pose so "free in Z" means free along the tool's own approach direction rather than the world's vertical axis.

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.