Jog Mode

SUMMARY

Jog mode is Cartesian Jogging and drives the TCP continuously at a Cartesian twist expressed in the selected feature frame - equivalent to holding a direction button on the teach pendant.

start_jog begins the continuous motion; the robot keeps moving at speeds until stop_jog is called.

stop_jog decelerates and halts the jog.

UNITS

cartesian_velocity is [vx, vy, vz, ωx, ωy, ωz] in m/s and deg/s.

The Skill

# Start jogging the TCP in the base frame
robot.start_jog(speeds=[0.0, 0.0, 0.05, 0.0, 0.0, 0.0], feature=0, acc=0.5)

# Stop the jog and decelerate to a halt
robot.stop_jog()

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 Jog Session

Jog the TCP at 5 cm/s along -Z in the base frame for 5 seconds, then stop cleanly.

"""
Jogs the TCP +Z at 5 cm/s in the base frame for 5 seconds, then stops.

Supports Universal Robots (UR).

Usage:
    python start_and_stop_jog_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:
    """Jog the TCP +Z (upward) at 5 cm/s in the base frame for 5 seconds, then stop."""

    #===================== 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 ============================================
        # Cartesian twist [vx, vy, vz (m/s), ωx, ωy, ωz (deg/s)] in the base frame
        cartesian_velocity = [0.0, 0.0, 0.05, 0.0, 0.0, 0.0]
        logger.info(f"Starting jog - cartesian_velocity [m/s, deg/s]: {cartesian_velocity}")
        robot.start_jog(
            cartesian_velocity=cartesian_velocity,
            feature=0,
            cartesian_acceleration=0.5,
        )

        # Let the jog run, then stop
        time.sleep(5.0)
        robot.stop_jog()
        logger.success("Jog 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 Cartesian jog 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_jog_mode.py --ip 192.168.1.100

For all options:

python start_and_stop_jog_mode.py --help

Parameter Configuration

start_jog

Parameter	Type	Default	Description
cartesian_velocity	list[float]	-	Cartesian twist [vx, vy, vz, ωx, ωy, ωz]. Linear in m/s, angular in deg/s, expressed in the feature frame.
feature	int	0	Reference frame: 0 = base, 1 = tool, 2 = custom.
cartesian_acceleration	float	0.5	TCP acceleration.
custom_frame	list[float]	[]	Pose [x, y, z, rx, ry, rz] of the custom reference frame. Used only when feature=2.

stop_jog

This skill takes no input parameters.

Returns

Method	Type	Description
start_jog	None	Returns after the jog command is sent.
stop_jog	None	Returns after the stop command is sent.

Raises

start_jog

Exception	Condition
RuntimeError	The robot is not connected.
ValueError	cartesian_velocity does not have exactly 6 elements.

stop_jog

Exception	Condition
RuntimeError	The robot is not connected.

How to Tune the Parameters

Keep cartesian_velocity conservative when jogging near obstacles or workspace boundaries - jog mode moves continuously until stop_jog is called, so a fast twist needs more time and distance to react and halt safely. cartesian_acceleration controls how quickly the commanded velocity ramps up and down; lower values give smoother, more predictable starts and stops, while higher values make the jog feel more responsive at the cost of a sharper ramp.

Choose feature=1 (tool frame) for jogs that should track the tool's own orientation (e.g., driving straight down the tool's Z axis regardless of how the wrist is oriented), and feature=0 (base frame) for jogs referenced to the fixed world frame. Use feature=2 with custom_frame when jogging relative to a fixture or workpiece frame that doesn't align with either the base or the tool.

Where to Use the Skill

• Interactive Cartesian positioning workflows.
• Aligning the TCP to a fixture or sensor with continuous motion in a chosen frame.
• Teach-pendant-style operator-guided motion from code.

When Not to Use the Skill

• Repeatable, waypoint-based positioning - use Set Cartesian Pose or Set Joint Positions.
• High-frequency real-time control - use Servo Joint or Servo Cartesian for streamed servo commands.