Service Reference ================= All services are in the ``motion_planning_interfaces`` package. Service names are relative to the node namespace (default: ``/``). .. list-table:: Service Summary :header-rows: 1 :widths: 38 32 30 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 35 30 35 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - Field - Type - Description * - ``trajectory`` - ``trajectory_msgs/JointTrajectory`` - Parameterized trajectory with timestamps, velocities, and accelerations. * - ``error_code`` - ``ErrorCodes`` - ``SUCCESS`` or ``PARAMETERIZATION_FAILED``. ---- CheckRobotCollision ------------------- **Request** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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** .. list-table:: :header-rows: 1 :widths: 30 30 40 * - 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``. .. list-table:: :header-rows: 1 :widths: 42 10 48 * - 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.