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.

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.

"""
Enters teach mode, captures TCP poses on each Enter press, and exits on Ctrl-C.

Supports Universal Robots (UR).

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

import argparse

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


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

    #===================== 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 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
        robot.stop_teach_mode()
        logger.success("Teach 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="Teach mode with manual TCP waypoint capture")
    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_teach_mode.py --ip 192.168.1.100

For all options:

python start_and_stop_teach_mode.py --help

Parameter Configuration

Neither start_teach_mode nor stop_teach_mode takes any input parameters.

Returns

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

Raises

Exception	Condition
RuntimeError	The robot is not connected (applies to both start_teach_mode and stop_teach_mode)

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.