Set Joint Position in Cartesian Space

SUMMARY

Set Joint Position in Cartesian Space drives the robot to a target joint configuration (degrees) using a trajectory that is linear in Cartesian space.

UNITS

joint_positions in degrees. speed in m/s, acceleration in m/s² (Cartesian-space limits drive the interpolation).

OFFLINE

To run set_joint_position_in_cartesian_space 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_position_in_cartesian_space(
    joint_positions=target_joint_positions,
    speed=0.25,
    acceleration=0.25,
    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.

Drive a real UR10e to an absolute joint configuration via a Cartesian-linear trajectory. The synchronous call blocks until the TCP reaches the FK-derived target pose.

"""
Move to a target joint configuration along a Cartesian motion trajectory.

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

Usage:
    python set_joint_position_in_cartesian_space.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 to a target joint configuration along a Cartesian trajectory."""

    #===================== 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
        target_joint_positions = robot.get_joint_positions().copy()
        target_joint_positions[0] += 5

        # ==================== Run Skill ============================================
        robot.set_joint_position_in_cartesian_space(
            joint_positions=target_joint_positions,
            speed=1.05,
            acceleration=1.4,
        )
        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 to a target joint configuration along a Cartesian trajectory")
    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_position_in_cartesian_space.py

Isaac Sim

python set_joint_position_in_cartesian_space.py --prim_path /World/ur10e

Real

python set_joint_position_in_cartesian_space.py --ip 192.168.1.100

For all options:

python set_joint_position_in_cartesian_space.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	1.05	TCP linear speed in m/s. Keep low (0.05-0.25) during contact tasks and near obstacles.
acceleration	float	1.4	TCP linear acceleration in m/s². Tune in tandem with speed.
asynchronous	bool	False	If True, the call returns immediately. Use Stop Cartesian 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() or robot.get_cartesian_pose() 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
NotImplementedError	Connected to real hardware on a brand that does not implement Cartesian motion to a joint-derived target (currently only Universal Robots does)
RuntimeError	The hardware backend rejects or fails the move during execution - e.g. the FK-derived TCP path passes near a kinematic singularity

How to Tune the Parameters

speed and acceleration bound the Cartesian TCP speed (m/s, m/s²) even though the target is specified in joint space - the controller FKs joint_positions and moves the TCP along a straight line to the resulting pose. Keep both low (0.05-0.25 m/s) during contact tasks or near fixtures, and validate the joint target with In Joint Limits plus Forward Kinematics first, since the FK-derived path may pass near a singularity depending on the target. Use asynchronous=True with Stop Cartesian Motion when the move needs to be interruptible mid-trajectory.

Where to Use the Skill

• Straight TCP paths to a joint-defined target - When you know the target in joint space but need a Cartesian-linear approach.
• Assembly and insertion tasks - Straight-line approach paths reduce the risk of collisions near fixtures.

When Not to Use the Skill

• A smooth joint-interpolated path is preferred - use Set Cartesian Pose in Joint Space for faster, smoother motion through large reorientations.
• The target is defined in Cartesian coordinates - use Set Cartesian Pose directly.
• You only need joint-space motion - use Set Joint Positions to skip the FK + Cartesian path generation.