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.

SUPPORTED ROBOTS

Available on all supported manipulators in offline mode. Hardware execution is currently supported only on Universal Robots.

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.

"""
Set Joint Position in Cartesian Space example for the Synapse SDK.

Moves to a target joint configuration using a trajectory that is linear in
Cartesian space.

Currently supported only for Universal Robots (UR10e).

Usage:
    python set_joint_position_in_cartesian_space.py --ip <ROBOT_IP>
"""
import argparse

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main(robot_ip: str):
    """Move to a target joint configuration via Cartesian-space motion."""

    # Create robot instance
    robot = universal_robots.UniversalRobotsUR10E()

    # Target joint positions in degrees
    q_target = [0, -90, 0, -90, 0, 0]

    # Safety warning before commanding real motion
    logger.warning(
        f"About to move real robot to joint positions {q_target}. "
        "Make sure it's safe to move there, otherwise use the advanced example."
    )

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

    try:
        robot.set_joint_position_in_cartesian_space(
            joint_positions=q_target,
        )
        logger.info(f"Moved to target joint positions: {q_target}")
    finally:
        robot.disconnect()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="UR10e set_joint_position_in_cartesian_space 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

from telekinesis.synapse.robots.manipulators import universal_robots

robot = universal_robots.UniversalRobotsUR10E()

Create the robot. UR10e is used here for illustration; the same pattern works for every supported brand.

robot.connect(ip=robot_ip)

Connect to the robot at the given IP - required for hardware execution.

robot.set_joint_position_in_cartesian_space(
    joint_positions=q_target,
)

Drive the robot to the target joint configuration using a Cartesian-linear trajectory - the controller FKs the target joint vector and moves the TCP along a straight line to the resulting pose. joint_positions is in degrees; speed and acceleration (when provided) are in Cartesian units (m/s, m/s²). With asynchronous=False (default) the call blocks until the move completes.

finally:
    robot.disconnect()

Release the controller link in a finally block so a fault mid-motion still cleans up the connection.

Advanced usage

For relative moves, asynchronous execution, mid-motion stop_cartesian_motion, and live Rerun visualization, follow the same patterns shown in the Set Joint Positions examples - just swap set_joint_positions for set_joint_position_in_cartesian_space, and use Stop Cartesian Motion (the TCP moves linearly) instead of stop_joint_motion.

How to Tune the Parameters

Parameter	Type	Default	Description
joint_positions	list[float] | np.ndarray	-	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.

WARNING

The FK-derived TCP path may pass near kinematic singularities depending on the joint target, which raises a RuntimeError at runtime. Validate the joint target with In Joint Limits and inspect the FK pose with Forward Kinematics before commanding motion.

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.