Teach Mode

SUMMARY

Teach mode is the simplest back-drive mode for teach-by-demonstration workflows and pose capture during commissioning. All axes are always free and no compliance frame is set - no configuration required.

start_teach_mode puts the robot into zero-gravity teach mode; all joints become back-drivable by hand.

stop_teach_mode restores normal stiff position control.

SUPPORTED ROBOTS

Currently supported only on Universal Robots.

The Skill

# Enter teach mode - all axes back-drivable
robot.start_teach_mode()

# Exit teach mode and restore stiff position control
robot.stop_teach_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 Teach Session

Enter teach mode, allow 10 seconds of manual interaction, exit, then read the recorded pose.

"""
Teach mode + manual waypoint capture example for the Synapse SDK.

There is no built-in "save waypoint" feature in teach mode — but combining
``start_teach_mode`` (zero-gravity back-drive) with ``get_cartesian_pose``
gives the standard teach-and-repeat pattern: hand-guide the arm, press
Enter to bookmark the current TCP pose, Ctrl-C to finish.

Currently supported only for Universal Robots (UR10e).

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

import argparse
from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(robot_ip: str):
    """Enter teach mode, capture TCP poses on each Enter press, exit on Ctrl-C."""

    # Create robot instance
    robot = universal_robots.UniversalRobotsUR10E()

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

    # Enter teach mode (zero-gravity back-drive, all axes free)
    logger.info("Starting teach mode")
    robot.start_teach_mode()

    # Capture waypoints on demand
    waypoints: list[list[float]] = []
    logger.info("Hand-guide the arm. Press Enter to capture a waypoint, Ctrl-C to finish.")
    try:
        while True:
            input()
            waypoints.append(robot.get_cartesian_pose())
            logger.success(f"Saved waypoint {len(waypoints)}: {waypoints[-1]}")
    except KeyboardInterrupt:
        logger.info(f"Capture finished — {len(waypoints)} waypoint(s) recorded.")

    # Exit teach mode and disconnect
    robot.stop_teach_mode()
    logger.success("Teach mode stopped.")
    robot.disconnect()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="UR robot teach mode + manual waypoint capture 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

The above code demonstrates a simple teach-by-demonstration workflow using start_teach_mode and stop_teach_mode. The robot enters teach mode, allowing the operator to hand-guide the arm freely. Each time the operator presses Enter, the current TCP pose is captured and stored in a list. The session ends when the operator presses Ctrl-C, at which point teach mode is exited and normal position control is restored.

start_teach_mode is similar to freedrive but requires no configuration - all axes are always free and no compliance frame is set. Use it for simple teach-by-demonstration workflows where you want to record poses interactively.

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

How to Tune the Parameters

Neither start_teach_mode nor stop_teach_mode takes any input parameters.

Return Value

Method	Type	Description
start_teach_mode	None	Returns after teach mode is activated.
stop_teach_mode	None	Returns after teach mode is deactivated.

Where to Use the Skill

• Simple teach-by-demonstration workflows.
• Recording joint or Cartesian poses during commissioning.

When Not to Use the Skill

• Axis-constrained back-drive - use Freedrive Mode when you need to constrain specific axes or specify a compliance frame.