Set Joint Positions

SUMMARY

Set Joint Positions commands the robot to a target configuration in joint space.

This skill is useful for deterministic robot positioning, state transitions, and sequencing motions in control pipelines.

SUPPORTED ROBOTS

This skill is currently supported on Universal Robots only.

The Skill

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

The Code

Example 1: Synchronous joint motion

Read the current joint positions, shift the first joint by −5°, and block until the robot reaches the target.

from loguru import logger
from telekinesis.synapse.robots.manipulators import universal_robots

robot_ip = "192.168.1.2"  # replace with your robot's IP

robot = universal_robots.UniversalRobotsUR10E()
robot.connect(ip=robot_ip)

initial_joint_positions = robot.get_joint_positions()

new_joint_positions = initial_joint_positions[:]
new_joint_positions[0] -= 5

robot.set_joint_positions(
    joint_positions=new_joint_positions,
    speed=60,
    acceleration=80,
    asynchronous=False,
)
logger.info(f"Moved to target joint positions: {new_joint_positions}")

robot.disconnect()

Example 2: Asynchronous joint motion with early stop

Start the same motion without blocking, wait briefly, then stop the robot before it reaches the target.

import time
from loguru import logger
from telekinesis.synapse.robots.manipulators import universal_robots

robot_ip = "192.168.1.2"  # replace with your robot's IP

robot = universal_robots.UniversalRobotsUR10E()
robot.connect(ip=robot_ip)

actual_joint_positions = robot.get_joint_positions()

new_joint_positions = actual_joint_positions[:]
new_joint_positions[0] += 5

robot.set_joint_positions(
    joint_positions=new_joint_positions,
    speed=60,
    acceleration=80,
    asynchronous=True,
)
time.sleep(0.5)
robot.stop_joint_motion(stopping_speed=60)
logger.info(f"Stopped joint motion before reaching: {new_joint_positions}")

robot.disconnect()

The Explanation of the Code

set_joint_positions commands the robot controller to move each joint to the specified target angle. The call is blocking by default — it returns only after all joints reach the target.

Joint positions. joint_positions is a list or array with one angle per joint, expressed in degrees. Use get_joint_positions() to read the current state and build a relative offset, as shown above.

Speed and acceleration. speed is the joint speed in deg/s and acceleration is the joint acceleration in deg/s². Higher values produce faster, more aggressive motion.

Asynchronous mode. When asynchronous=True, the call returns immediately and the robot moves in the background. Use stop_joint_motion(stopping_speed) to decelerate and halt motion before the target is reached. stopping_speed controls how quickly the robot decelerates (in deg/s).

How to Tune the Parameters

Parameter	Type	Default	Description
joint_positions	list[float] or np.ndarray	—	Target joint angles in degrees. Length must equal the robot's DOF.
speed	float	60	Joint speed in deg/s. The default is a conservative safety value; see the examples above for typical usage.
acceleration	float	80	Joint acceleration in deg/s². The default is a conservative safety value; see the examples above for typical usage.
asynchronous	bool	False	If True, return immediately without waiting for the motion to complete.

Choosing speed and acceleration

Start with conservative values (e.g. speed=30, acceleration=40) when testing a new trajectory. Increase gradually once the motion path is validated.

WARNING

Passing joint positions outside the robot's joint limits will raise a ValueError or be rejected by the controller. Always validate target angles against the robot's specification before commanding motion.

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
• Sequencing — Chain joint-space waypoints to build a repeatable motion sequence

When Not to Use the Skill

Do not use Set Joint Positions when:

• 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