Control End-Effector Speed

MoveIt Pro offers several ways to control how fast the end-effector moves. Which one applies depends on what you are trying to do: hold a tool at a fixed speed along a path, slow an entire Objective down, adjust speed while the robot is already moving, or stream velocities directly to the controller.

This guide routes you to the right mechanism. Each section links to the guide that covers it in depth.

Choosing a mechanism

If you want to...	Use	Configured in
Hold a constant tool speed in m/s along a Cartesian path	PlanCartesianPath's trajectory_timing port (Cartesian trapezoidal, constant-speed profile)	Behavior Tree editor
Slow down a joint-space motion	velocity_scale_factor and acceleration_scale_factor ports on PlanToJointGoal or the MTC setup stages	Behavior Tree editor
Change speed while a trajectory is executing	time_scale_percentage parameter (JTAC only)	ROS 2 parameter, at runtime
Stream Cartesian velocities directly, without planning	Velocity Force Controller (VFC) or PoseJog	Behavior Tree, or teleoperation
Change how fast jogging feels in the UI	Speed slider and jog settings	Web UI
Raise or lower the joint limits that planning-time scaling multiplies against	moveit_params.joint_limits	config.yaml

Constant tool speed along a Cartesian path

Applications such as welding, dispensing, grinding, and inspection need the tool to travel at a steady Cartesian speed rather than as fast as the joint limits allow. The trajectory_timing input port on PlanCartesianPath chooses between two profiles: time-optimal timing, which runs as fast as the joint limits allow and does not hold a constant Cartesian speed, and a Cartesian trapezoidal profile, which cruises at a constant Cartesian speed with acceleration and deceleration ramps at the ends. For steady tool speed, select the trapezoidal profile and give it a cruise translational speed in m/s and rotational speed in rad/s, plus the ramp accelerations.

This is the only planning-time mechanism that lets you specify end-effector speed in real units rather than as a fraction of the robot's joint limits. Streaming Cartesian velocities to the controller, covered below, also uses real units but does not plan a trajectory in advance.

See Controlling tip speed with trajectory timing for the full walkthrough, the parameter reference, and how to interpret infeasible-speed errors.

Required Version

This feature will not be released until MoveIt Pro version 10.0.

Scaling joint-space motions

Behaviors that plan in joint space expose velocity_scale_factor and acceleration_scale_factor input ports. Each takes a value from 0 to 1 and scales, for that motion only, the robot's motion-planning joint velocity and acceleration limits (moveit_params.joint_limits, see The joint-limit ceiling below), which can differ from the URDF limits. The main ones are PlanToJointGoal and the MTC setup stages, such as SetupMTCPlanToPose and SetupMTCPlanToJointState.

The shipped Objectives that wrap them, including Move to Pose, Move to Waypoint, and Move to Joint State, expose the same two values as Subtree inputs. If you are editing one of those Objectives rather than a Behavior directly, set the scale factors there.

These are joint-space fractions, not end-effector speeds. A velocity_scale_factor of 0.5 halves every joint's velocity limit, which slows the end-effector down but does not pin it to any particular Cartesian speed. The resulting tool speed still varies along the trajectory and depends on the arm's configuration.

Set them per-Behavior in the Behavior Tree editor, or wire them to a blackboard variable to drive several motions from one value.

Adjusting speed during execution

The mechanisms above are applied at planning time. To change speed while a trajectory is already executing, set the time_scale_percentage parameter on the joint trajectory admittance controller (JTAC), where 100.0 executes at the planned speed and 0.0 effectively pauses the robot:

ros2 param set joint_trajectory_admittance_controller time_scale_percentage 50.0

This scales the trajectory in time, so it slows all joints together and preserves the planned path. It is a global override, not a per-Behavior setting.

note

This parameter is only available for robot configurations that use JTAC, such as lab_sim. Configurations that use other controllers, such as hangar_sim, do not support it.

Required Version

This feature requires MoveIt Pro version 8.7 or newer.

Streaming Cartesian velocities

The Velocity Force Controller (VFC) tracks a Cartesian twist you publish directly, in m/s and rad/s, with no planning step. Use it for visual servoing, compliant insertion, and teleoperation, where the target moves or the motion must react to sensed forces.

Commanded velocities are clamped to the max_cartesian_velocity and max_cartesian_acceleration parameters on the velocity_force_controller. Both are six-element arrays, one per Cartesian axis (x, y, z, rx, ry, rz), in m/s and rad/s for velocity and m/s² and rad/s² for acceleration. Set them in your robot configuration package's ros2_control.yaml; see the lab_sim example in moveit_pro_example_ws.

Clamping scales uniformly, so it reduces the speed of a motion without changing its direction. The commanded joint velocities and accelerations are clamped against max_joint_velocity and max_joint_acceleration in the same way.

These four limits are the controller's startup defaults, not a fixed ceiling. The VFC's ~/configure service overrides the Cartesian and joint velocity and acceleration limits at runtime while the controller is idle — it rejects a reconfigure request while a command is running — so you can raise or lower the ceiling without restarting. See the ~/configure service in Velocity Force Control.

PoseJog is the Behavior that streams these commands safely: it subscribes to VelocityForceCommand messages, rejects any that are kinematically infeasible or would collide, and forwards the rest to the VFCs. It can drive several planning groups at once, each with its own VFC. Configure which planning groups and controllers it uses under moveit_params.pose_jog (see MoveIt Parameters Configuration). Publish to the VFC directly for raw velocity streaming, or use PoseJog when you want its collision and feasibility checks.

See Velocity Force Control for controller setup and the CreateTwistStamped and PublishVelocityForceCommand Behaviors, and Visual Servoing for a worked example.

Jog speed in the user interface

The teleoperation panel's speed slider scales the Cartesian velocities sent while jogging, relative to the VFC's max_cartesian_velocity limits above. Raising those limits raises what the slider's maximum corresponds to.

See UI Teleoperation.

The joint-limit ceiling

The planning-time scale factors (velocity_scale_factor, acceleration_scale_factor) and the time-optimal Cartesian timing multiply against the robot's joint velocity and acceleration limits. If planned motions are uniformly too slow even at a scale factor of 1.0, those limits are the constraint. Override them under moveit_params.joint_limits in your robot configuration package's config.yaml.

This ceiling does not govern the VFC. That controller enforces its own max_cartesian_velocity, max_cartesian_acceleration, max_joint_velocity, and max_joint_acceleration parameters, which start from the controller config and can be overridden at runtime through its ~/configure service (see Streaming Cartesian velocities above).

See MoveIt Parameters Configuration.

Capabilities not currently available

The following are common requests that MoveIt Pro does not support today. If your application needs one of them, contact support so we can factor your use case into prioritization, or discuss a workaround for your configuration.

• A Cartesian speed limit on joint-space motions. PlanToJointGoal and the MTC setup stages expose only joint-space velocity and acceleration scale factors, not a Cartesian tip-speed limit. Even when the goal is a Cartesian pose, as with SetupMTCPlanToPose, you cannot cap tip speed in m/s. Constant Cartesian speed is available only through PlanCartesianPath, which requires expressing the motion as a Cartesian path.
• Constant-speed timing for more than one tip link. The Cartesian trapezoidal profile times a single tip link, so it does not cover dual-arm or multi-tip paths.
• Automatic slow-down when a requested speed is infeasible. PlanCartesianPath fails with a diagnostic naming how much too fast the request is rather than reducing the speed to something achievable. Lowering the requested speed, or increasing blending_radius when the acceleration limits bind, is a manual step.
• A runtime override expressed as an end-effector speed. time_scale_percentage scales a trajectory in time relative to its planned speed. There is no equivalent that sets a target tool speed in m/s during execution.