Set Joint Positions

SUMMARY

Set Joint Positions commands the robot to a target joint configuration (degrees, length equal to the robot's DOF).

UNITS

joint_positions in degrees, ordered base to wrist. speed in deg/s, acceleration in deg/s².

OFFLINE

To run set_joint_positions purely on the kinematic model and visualize the result in Rerun, follow the Synapse Quickstart - one offline example is shipped for every supported brand.

The Skill

robot.set_joint_positions(
    joint_positions=target_joint_positions,
    speed=60,
    acceleration=80,
    asynchronous=False,
)

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.

"""
Move the robot to a target joint configuration defined relative to its current one.

Supports Universal Robots (UR), Epson, virtual, and Isaac Sim.

Usage:
    python set_joint_positions.py [--ip <ROBOT_IP>] [--prim_path <PRIM_PATH>]
"""

import argparse

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(ip: str | None, prim_path: str | None) -> None:
    """Move the robot to a target joint configuration."""

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

    # ==================== Visualization (Optional) =============================
    # Live: subscribes to the robot's state topic and redraws as it moves.
    robot.visualize_rerun(live=True)

    try:
        #===================== Connect Robot ==========================================
        if ip:
            robot.connect(ip=ip)
        elif prim_path:
            robot.connect(simulation_prim_path=prim_path)
            robot.set_joint_positions(robot.default_joint_configuration)

        #===================== Prepare Target ==========================================
        # Target: current joint configuration with the base joint rotated +5 deg
        target_joint_positions = robot.get_joint_positions().copy()
        target_joint_positions[0] += 5

        # ==================== Run Skill ============================================
        robot.set_joint_positions(
            joint_positions=target_joint_positions,
            speed=60,
            acceleration=80,
            asynchronous=False,
        )
        logger.info(f"Moved to target joint positions: {target_joint_positions}")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        robot.disconnect()
        robot.shutdown()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Move the robot to a target joint configuration")
    parser.add_argument("--ip", type=str, default=None,
                         help="UR robot IP address for real hardware, e.g. 192.168.1.100")
    parser.add_argument("--prim_path", type=str, default=None,
                         help='Isaac Sim articulation prim path, e.g. "/World/ur10e"')
    args = parser.parse_args()

    main(ip=args.ip, prim_path=args.prim_path)

Running the Example

Virtual

python set_joint_positions.py

Isaac Sim

python set_joint_positions.py --prim_path /World/ur10e

Real

python set_joint_positions.py --ip 192.168.1.100

For all options:

python set_joint_positions.py --help

Parameter Configuration

Parameter	Type	Default	Description
joint_positions	list[float] | np.ndarray	required	Target joint angles in degrees. Length must equal the robot's DOF.
speed	float	60	Joint speed in deg/s. Start conservative (20-30) when validating a new trajectory; raise once the path is verified.
acceleration	float	80	Joint acceleration in deg/s². Tune in tandem with speed.
asynchronous	bool	False	If True, the call returns immediately. Use Stop Joint Motion to interrupt the move before it completes.

Returns

Type	Description
None	Blocks until the move completes when asynchronous=False; returns immediately when asynchronous=True. Read robot.get_joint_positions() afterward to confirm the result.

Raises

Exception	Condition
TypeError	joint_positions, speed, acceleration, or asynchronous is not the expected type
ValueError	joint_positions is not a 1D vector matching the robot's DOF, or the configuration is outside joint limits
RuntimeError	The hardware backend rejects or fails the move during execution

How to Tune the Parameters

speed and acceleration are the leading joint's speed and acceleration in deg/s and deg/s², so they scale directly with how fast each joint sweeps toward the target. Start conservative (20-30 deg/s) when validating a new trajectory, then raise once the path is confirmed collision-free. Validate the target with In Joint Limits before commanding motion — out-of-limits configurations raise a ValueError rather than moving the robot. Use asynchronous=True with Stop Joint Motion when the move needs to be interruptible mid-trajectory.

Where to Use the Skill

• Homing and reset - Return the robot to a known safe configuration between tasks.
• State transitions - Move to a pre-grasp or pre-place configuration before initiating a Cartesian move.
• Deterministic positioning - Reproduce an exact joint configuration recorded during teach-in.
• Joint-space sequencing - Chain joint-space waypoints to build a repeatable motion sequence.

When Not to Use the Skill

• The target is defined in Cartesian space - use Set Cartesian Pose or Inverse Kinematics to convert first.
• A straight-line TCP path is required - joint-space interpolation does not guarantee a linear tool path; use Set Cartesian Pose instead.
• Collision avoidance along the path is needed - joint-space moves do not account for obstacles; plan the trajectory upstream before commanding motion.