Build moveit config of any manipulator
This tutorial shows the general workflow for creating a MoveIt configuration for a manipulator with a gripper. Start with a working URDF or Xacro model in which the arm and gripper form one valid robot tree.
The generated package is a starting point. Its joint limits, controllers, kinematics, and launch files must still match the real robot.
Dependencies
This workshop targets ROS 2 Humble and uses the following packages:
Package |
Why it is needed |
|---|---|
|
Builds the ROS 2 workspace. |
|
Installs dependencies declared by ROS packages. |
|
Imports source repositories from |
|
Publishes test joint values while checking the robot description. |
|
Provides planning, collision checking, trajectory execution, and RViz integration. |
|
Generates the robot-specific MoveIt configuration package. |
|
Publishes the robot TF tree from its description and joint states. |
|
Provides the controller and hardware-interface framework. |
|
Provides standard arm and gripper controllers. |
|
Expands Xacro descriptions into URDF. |
Install the dependencies declared by the packages in your workspace:
source /opt/ros/humble/setup.bash
cd /home/ros/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build
source install/setup.bash
Robot-description sources include:
1. Prepare the robot description
Before using MoveIt Setup Assistant, check that:
the manipulator and gripper are connected in one URDF tree;
every actuated joint has the correct type, axis, and limits;
visual and collision geometry use the correct scale;
mimic joints are defined for mechanically coupled gripper fingers; and
the base link and intended tool link are known.
Expand and validate the Xacro before continuing:
xacro /path/to/robot_with_gripper.urdf.xacro > /tmp/robot.urdf
check_urdf /tmp/robot.urdf
Resolve Xacro and URDF errors here. The Setup Assistant cannot repair a broken robot description.
2. Define a tool center point
MoveIt plans poses for a link. If the required tool center point (TCP) is not already represented, add an empty link and attach it to a stable tool or gripper link with a fixed joint:
<link name="tool_tcp"/>
<joint name="tool_tcp_joint" type="fixed">
<origin xyz="0 0 0.10" rpy="0 0 0"/>
<parent link="gripper_base"/>
<child link="tool_tcp"/>
</joint>
Replace the example offset with a value measured from CAD or the physical tool. Do not attach the TCP to a moving finger.
3. Start MoveIt Setup Assistant
ros2 run moveit_setup_assistant moveit_setup_assistant
Select Create New MoveIt Configuration Package and load the combined robot and gripper URDF or Xacro.
4. Configure collision checking
Generate the self-collision matrix. It disables checks for adjacent links and for pairs that never collide in the sampled configurations. Review the result instead of disabling additional collisions without verification.
Add a virtual joint only when the robot needs one. A fixed industrial arm whose base is already fixed in the description usually does not require it. Mobile bases commonly use a planar or floating virtual joint.
5. Create planning groups
Create an arm group as a kinematic chain:
Base link: the manipulator base
Tip link: the TCP or tool link
Kinematics solver: for example,
kdl_kinematics_plugin/KDLKinematicsPlugin
Create a separate gripper group containing its actuated joints or links. The gripper group normally has no kinematics solver.
6. Configure the end effector and poses
Add an end effector with:
the gripper planning group as its End Effector Group;
the arm group as its Parent Group; and
the TCP or gripper mounting link as its Parent Link.
Add useful named poses such as home, ready, open, and closed. Confirm
that each pose belongs to the correct planning group and respects joint limits.
7. Configure ros2_control and MoveIt controllers
For the arm, add the required command and state interfaces and create a
joint_trajectory_controller/JointTrajectoryController. Map it to a MoveIt
controller using FollowJointTrajectory.
A corresponding entry in moveit_controllers.yaml typically contains:
arm_controller:
default: true
action_ns: follow_joint_trajectory
type: FollowJointTrajectory
Configure the gripper with a controller matching its hardware interface. A
common choice is position_controllers/GripperActionController, exposed to
MoveIt as a gripper command controller.
Skip perception when no 3D sensor is available. It can be added later without regenerating the whole package.
8. Generate the configuration package
Enter the author information, select the required launch files, and generate a package under the workspace source directory, for example:
/home/ros/ros2_ws/src/my_robot_moveit_config
Important generated files include:
File |
Purpose |
|---|---|
|
Planning groups, end effectors, named poses, and disabled collisions. |
|
IK solver settings for each planning group. |
|
MoveIt velocity, acceleration, and position-limit overrides. |
|
Maps MoveIt groups to controller actions. |
|
Configures the ros2_control controllers used by the robot. |
|
Initial joint values used by fake hardware or demos. |
On ROS 2 Humble, use floating-point joint-limit values such as 5.0 and 0.0
rather than integers such as 5 and 0.
9. Build and test
cd /home/ros/ros2_ws
colcon build --packages-select my_robot_moveit_config
source install/setup.bash
ros2 launch my_robot_moveit_config demo.launch.py
In RViz, select the arm planning group. Confirm that the interactive marker is located at the TCP, then test Plan before using Plan & Execute.
If the package cannot be found, source the workspace again. If no interactive
marker appears, check the selected planning group, the chain tip, and
kinematics.yaml. If execution fails, verify that the controller name, joints,
action type, and action_ns agree with the running ros2_control controller.
For details, see the official MoveIt Setup Assistant tutorial and MoveIt configuration guide.