Moveit2 Knowledge Patch

MoveIt 2 Knowledge Patch

Load this skill when implementing or migrating MoveIt 2 planning pipelines, planner plugins, MoveIt Task Constructor tasks, Servo integrations, trajectory processing, or downstream CMake linkage. Prefer the project's manifests, configuration, installed headers, and observed runtime behavior when they differ from this guidance.

Reference index

Breaking and migration-sensitive changes

Link exported CMake targets

Downstream packages should link MoveIt's exported namespaced targets. Do not pass MoveIt dependencies to ament_target_dependencies().

target_link_libraries(my_target
  moveit_ros_planning::moveit_ros_planning
)

See Core planning and pipelines.

Recheck planning-adapter integrations

The planning-pipeline API now represents request and response adapters more explicitly. Treat integrations written against the Humble-era API as migration-sensitive. Examples using Catkin, roslaunch, XML launch files, chomp/OptimizerAdapter, or stomp_moveit/StompSmoothingAdapter describe the legacy API and are not copy-paste MoveIt 2 configuration.

See Core planning and pipelines and Planner plugins and adapters.

Consume multi-DOF derivatives

Multi-DOF trajectories are executable, and newer trajectories populate their velocities and accelerations. Consumers must not assume those derivative arrays are empty.

See Core planning and pipelines.

moveit_py quick reference

Plan with a group and execute with MoveItPy

Obtain a group-specific component from MoveItPy, configure start and goal state on it, then execute the successful result's trajectory through the MoveItPy instance.

moveit = MoveItPy(node_name="moveit_py")
arm = moveit.get_planning_component("panda_arm")
arm.set_start_state_to_current_state()
arm.set_goal_state(pose_stamped_msg=goal, pose_link="panda_link8")

result = arm.plan()
if result:
    moveit.execute(result.trajectory, controllers=[])

Named SRDF states use set_start_state(configuration_name=...) or set_goal_state(configuration_name=...). A RobotState goal uses set_goal_state(robot_state=...).

Configure profiles before parallel planning

planning_pipelines.pipeline_names loads pipelines. Separately named top-level profiles contain plan_request_params and select the pipeline, planner ID, attempts, scaling factors, and planning time.

planning_pipelines:
  pipeline_names: [ompl, chomp]

ompl_fast:
  plan_request_params:
    planning_pipeline: ompl
    planner_id: RRTConnectkConfigDefault
    planning_attempts: 1
    planning_time: 1.0

Build MultiPipelinePlanRequestParameters from the MoveItPy instance and profile names, then pass it as multi_plan_parameters:

params = MultiPipelinePlanRequestParameters(moveit, ["ompl_fast", "chomp_profile"])
result = arm.plan(multi_plan_parameters=params)

Update states before collision checks

Use planning-scene monitor read_write() contexts for changes and read_only() contexts for checks. After changing the scene's current state or solving IK, call update() before transforms or collision checks.

See Core planning and pipelines.

Planner selection quick reference

OMPL objectives and termination

OMPL configurations can choose path length, mechanical work, minimum-clearance, state-cost-integral, or minimax objectives. A configured termination condition such as Iteration[...], CostConvergence[...], or ExactSolution does not replace allowed_planning_time; that remains the hard upper bound.

Persistent roadmaps

PRM-family planners reuse a roadmap across requests when multi_query_planning_enabled is set. store_planner_data and load_planner_data persist it at planner_data_path; storage happens when the planner instance is destroyed. Prefer lazy variants when modest scene changes require node and edge revalidation; reserve non-lazy variants for static scenes.

Pilz commands

Set MotionPlanRequest.planner_id to PTP, LIN, or CIRC. LIN and CIRC require a zero-velocity start and apply request scaling factors to Cartesian limits. For sequences, only the first item may specify a start state, adjacent blend spheres must not overlap, and any planning failure prevents all execution.

See Planner plugins and adapters for complete configuration, circular constraints, and sequence interfaces.

MoveIt Task Constructor quick reference

Respect result flow

Generators produce states in both directions, propagators extend neighboring results forward or backward, and connectors bridge independently generated states. Serial containers accept end-to-end child solutions; parallel containers select, fall back among, or merge alternatives.

Forward properties deliberately

Nested stages do not automatically inherit task properties. Expose selected properties to containers, configure them from Stage::PARENT, and let wrappers such as ComputeIK import generated values such as target_pose from Stage::INTERFACE.

Monitor the correct scene stage

GenerateGraspPose monitors the earlier CurrentState. GeneratePlacePose monitors the saved attach-object stage so it sees the attached-object transform. Move each generator into ComputeIK, then configure solution count, separation, IK frame, and property sources.

See MoveIt Task Constructor for lifecycle, planner, motion, planning-scene transition, and diagnostic details.

MoveIt Servo quick reference

Supply IK parameters explicitly

Pass robot_description_kinematics parameters to ServoNode. Parameters appear under robot_description_kinematics.<group_name>.<param_name>. A custom IK plugin must declare its own custom parameters because Servo does not accept undeclared values from kinematics.yaml.

Choose the command and output interfaces

Servo accepts JointJog, TwistStamped, and PoseStamped commands on its parameterized inputs. Twist and pose messages require header.frame_id; twist commands use the robot planning frame. command_out_type selects either JointTrajectory or Float64MultiArray output.

Choose smoothing by constraint needs

• ButterworthFilterPlugin is inexpensive and avoids joint-space overshoot, but does not explicitly constrain acceleration or jerk.
• AccelerationLimitedPlugin respects acceleration where feasible and preserves direction when kinematics allow, but may overshoot and does not constrain jerk.
• RuckigFilterPlugin gives the smoothest joint-limit- and acceleration-aware output, but may overshoot or swirl at sharp Cartesian corners.

See MoveIt Servo for collision behavior, scheduling, direct C++ control, services, status, and OSQP compatibility.