Service Reference

All services are in the motion_planning_interfaces package. Service names are relative to the node namespace (default: /).

Service Summary

Service	Interface Type	Description
/compute_fk	ComputeFK	Forward kinematics for a single state
/compute_fk_batch	ComputeFKBatch	Forward kinematics for a trajectory or vector of states
/compute_ik	ComputeIK	Inverse kinematics for a single target pose
/compute_ik_batch	ComputeIKBatch	Inverse kinematics for multiple target poses
/compute_motion_plan	ComputeMotionPlan	Full plan + optional time-parameterization
/compute_parameterize	ComputeParameterize	Time-parameterize an existing waypoint path
/check_robot_collision	CheckRobotCollision	Collision check for a single robot state
/check_path_collision	CheckPathCollision	Collision check for a full path
/get_manipulability	GetManipulability	Manipulability scalar for a robot state
/update_objects	UpdateObjects	Refresh collision objects from WorkcellDescription
/set_planner	SetPlanner	Add or replace a named OMPL planner at runtime
/remove_planner	RemovePlanner	Remove a named OMPL planner
/replace_planner	ReplacePlanner	Update parameters of an existing planner

---

ComputeFK

Compute the Cartesian pose of tip_frame relative to root_frame for a given joint state.

Request

Field	Type	Description
robot_state	common_msgs/RobotState	Joint positions (joint_state.name + joint_state.position).
root_frame	string	Root link name from URDF.
tip_frame	string	Tip link name from URDF.

Response

Field	Type	Description
tf	geometry_msgs/TransformStamped	Output transform from root to tip.
error_code	ErrorCodes	SUCCESS or INVALID_LINK_NAME / INVALID_ROBOT_STATE.

---

ComputeFKBatch

Forward kinematics for an entire trajectory or vector of states.

Request

Field	Type	Description
trajectory	trajectory_msgs/JointTrajectory	Input when type=TRAJECTORY (default).
robot_states	common_msgs/RobotState[]	Input when type=ROBOT_STATES.
type	uint8	TRAJECTORY=1 (default), ROBOT_STATES=2.
root_frame	string	Root link name.
tip_frame	string	Tip link name.
do_fk_position	bool (default 1)	Compute Cartesian positions.
do_fk_velocity	bool (default 0)	Compute Cartesian velocities. Requires velocity fields in the trajectory.
do_fk_acceleration	bool (default 0)	Compute Cartesian accelerations. Requires acceleration fields in the trajectory.

Response

Field	Type	Description
root_frame	string	Echo of request root_frame.
tip_frame	string	Echo of request tip_frame.
transforms	geometry_msgs/Transform[]	Cartesian positions (populated when do_fk_position=true).
cartesian_velocities	geometry_msgs/Twist[]	Cartesian velocities (populated when do_fk_velocity=true).
cartesian_accelerations	geometry_msgs/Twist[]	Cartesian accelerations (populated when do_fk_acceleration=true).
error_code	ErrorCodes	SUCCESS if all points were computed successfully.

---

ComputeIK

Inverse kinematics for a single target Cartesian pose. Returns multiple solutions sorted by proximity to reference_state.

Request

Field	Type	Description
update_objects	bool (default 1)	Refresh collision objects from WorkcellDescription before solving.
append_collision_concept	AppendCollisionConcept	Stateless collision overrides (additional touching links, extra objects, etc.).
root_to_tip_tf	geometry_msgs/TransformStamped	Target pose. header.frame_id = root frame, child_frame_id = tip frame.
reference_state	common_msgs/RobotState	Optional. Solutions are sorted by distance from this state.
fixed_state	common_msgs/RobotState	Optional. Joints listed here are held fixed during IK.
joint_position_constraint	common_msgs/RealVectorConstraint	Optional joint limits override. Defaults to WorkcellDescription limits.
config	IKConfig	IK settings (check_collision, max_output_num, timeout_sec).

Response

Field	Type	Description
goal_states	common_msgs/RobotState[]	IK solutions, sorted closest-to-reference first.
error_code	ErrorCodes	SUCCESS, NO_IK_SOLUTION, or GOAL_IN_COLLISION.

---

ComputeIKBatch

Inverse kinematics for multiple target poses in one call.

Request — same as ComputeIK but:

• root_to_tip_tfs (geometry_msgs/TransformStamped[]) — replaces single root_to_tip_tf.

Response

Field	Type	Description
goal_states_vec	RobotStateVec[]	One RobotStateVec per input TF. Each contains all solutions for that pose.
error_code	ErrorCodes	SUCCESS if all TFs found solutions; PARTIAL_SUCCESS if some failed; FAILURE if all failed.

---

ComputeMotionPlan

Plan a collision-free joint-space or Cartesian path and optionally time-parameterize it.

Request

Field	Type	Description
update_objects	bool (default 1)	Refresh collision objects.
append_collision_concept	AppendCollisionConcept	Stateless collision overrides.
start_state	common_msgs/RobotState	Starting joint configuration.
goals	Goal[]	Ordered list of goal states or poses.
path_plan_types	uint8[]	Plan type per goal. JOINT_PLAN=1, CARTESIAN_INTERPOLATE=2, JOINT_COUPLED_PLAN=3. Length must equal goals.
fixed_state	common_msgs/RobotState	Optional fixed joints.
joint_position_constraint	common_msgs/RealVectorConstraint	Optional joint limits override.
do_parameterize	bool (default 1)	Enable time parameterization.
ik_config	IKConfig	IK settings used when goals are Cartesian poses.
joint_plan_config	JointPlanConfig	Joint-space planning settings (path constraints).
cartesian_interpolate_config	CartesianInterpolateConfig	Cartesian interpolation settings (type, n_points).
joint_coupled_plan_config	JointCoupledPlanConfig	Joint coupling settings.
parameterize_config	ParameterizeConfig	Time-parameterization settings. Required when do_parameterize=true.

Response

Field	Type	Description
trajectory	trajectory_msgs/JointTrajectory	Parameterized trajectory (or raw path if do_parameterize=false).
reached_goals	uint16	Number of goals successfully reached.
goal_state	common_msgs/RobotState	Final joint state reached.
error_code	ErrorCodes	SUCCESS (full plan), PARTIAL_SUCCESS (partial), or failure code.
planning_error_code	ErrorCodes	When error_code=PARTIAL_SUCCESS, this contains the specific planning failure reason.

---

ComputeParameterize

Time-parameterize an existing waypoint path. Minimum 2 points with positions filled.

Request

Field	Type	Description
update_objects	bool (default 1)	Refresh collision objects (used for collision-aware parameterizers).
append_collision_concept	AppendCollisionConcept	Stateless collision overrides.
path	trajectory_msgs/JointTrajectory	Input waypoints (positions required; velocities/accelerations ignored).
base_tfs	geometry_msgs/Transform[≤1]	Optional base pose override for collision checking.
config	ParameterizeConfig	Parameterization type (TOTG, TOPPRA, or IPTP) plus velocity/acceleration constraints.

Response

Field	Type	Description
trajectory	trajectory_msgs/JointTrajectory	Parameterized trajectory with timestamps, velocities, and accelerations.
error_code	ErrorCodes	SUCCESS or PARAMETERIZATION_FAILED.

---

CheckRobotCollision

Request

Field	Type	Description
update_objects	bool (default 1)	Refresh collision objects.
append_collision_concept	AppendCollisionConcept	Stateless collision overrides.
robot_state	common_msgs/RobotState	Joint state to check.
get_contact_infos	bool (default 0)	Retrieve detailed contact information (positions, normals, distances).

Response

Field	Type	Description
is_in_collision	bool	true if any collision detected.
contact_infos	ContactInfo[]	Collision details. Populated only when get_contact_infos=true.
error_code	ErrorCodes	SUCCESS or FAILED_TO_UPDATE_OBJECTS.

---

CheckPathCollision

Request

Field	Type	Description
update_objects	bool (default 1)	Refresh collision objects.
append_collision_concept	AppendCollisionConcept	Stateless collision overrides.
path	trajectory_msgs/JointTrajectory	Path to check. Minimum 2 points with positions filled.
type	uint8	CHECK_ALL_POINTS=1 — check every point. CHECK_UNTIL_COLLISION=2 — stop at first collision (faster).

Response

Field	Type	Description
index_ranges_in_collision	IntRange[]	Ranges of path indices in collision. Empty = collision-free. A range with upper=-1 means the extent is unknown (quick-check mode).
error_code	ErrorCodes	SUCCESS or failure code.

---

GetManipulability

Returns a scalar manipulability measure (Yoshikawa index) for a given robot state.

Request

Field	Type	Description
robot_state	common_msgs/RobotState	Joint state to evaluate.
joint_position_limit	common_msgs/RealVectorConstraint	Joint position limits used for the manipulability calculation.

Response

Field	Type	Description
manipulability	float64	Scalar manipulability. 0 = singular configuration.

---

UpdateObjects

Manually trigger an update of collision objects from the WorkcellDescription service. Normally called automatically on each planning request via update_objects=true.

Request — empty.

Response

Field	Type	Description
is_success	bool	true if WorkcellDescription responded successfully.

---

Error Codes

All services return an ErrorCodes message in their response. The val field is an int32.

Constant	Value	When returned
SUCCESS	1	Operation completed successfully.
PARTIAL_SUCCESS	2	Part of the trajectory was computed. Check planning_error_code for details.
FAILURE	99999	Catch-all for complete failure.
PLANNING_FAILED	-1	OMPL path planning algorithm failed to find a solution.
MOTION_PLAN_INVALIDATED_BY_ENVIRONMENT_CHANGE	-3	A previously valid plan is no longer valid due to scene changes.
TIMED_OUT	-6	Planning exceeded the configured time budget.
GOALS_AND_PLAN_TYPES_SIZE_NOT_EQUAL	-7	goals and path_plan_types vectors have different lengths.
CART_INTP_RETURNS_MORE_THAN_N_POINTS	-9	Cartesian interpolation exceeded the maximum allowed point count.
START_STATE_IN_COLLISION	-10	Start state is in collision with the environment.
START_STATE_VIOLATES_PATH_CONSTRAINTS	-11	Start state violates the specified path constraints.
COUPLED_START_STATE_NOT_VALID	-12	Start state is not valid for coupled planning.
COUPLED_START_STATE_IN_COLLISION	-13	Start state is in collision (coupled planner).
GOAL_IN_COLLISION	-14	Goal state is in collision with the environment.
GOAL_VIOLATES_PATH_CONSTRAINTS	-15	Goal state violates the specified path constraints.
INVALID_JOINT_CONSTRAINT	-16	Malformed or out-of-range joint constraint.
INVALID_ROBOT_STATE	-17	Robot state contains invalid or inconsistent data.
INVALID_LINK_NAME	-18	Link name does not exist in the robot URDF.
INVALID_OBJECT_NAME	-19	Object name does not exist in the scene.
INVALID_GOAL_TYPE	-20	Unsupported goal type specified.
UNSPECIFIED_GOAL_TYPE	-21	Goal type was not specified.
INVALID_PATH	-22	Computed or provided path is invalid.
START_AND_GOAL_STATE_TOO_CLOSE	-23	Start and goal are within the minimum joint-space separation threshold.
START_AND_GOAL_POSE_TOO_CLOSE	-24	Start and goal are within the minimum Cartesian separation threshold.
PARAMETERIZATION_FAILED	-25	Time-parameterization failed (TOPPRA / TOTG / IPTP).
NO_IK_SOLUTION	-31	No inverse kinematics solution found for the requested pose.
FAILED_TO_UPDATE_OBJECTS	-36	Failed to retrieve or update collision objects from WorkcellDescription.
INVALID_INPUT_TYPE	-40	Invalid input type specified in batch requests.