Code Used in this Tutorial Available
Code can be found at moveit_tutorials repository in doc folder. Use kinetic-devel branch.
Setup Assistant Tutorial¶
The MoveIt! Setup Assistant is a graphical user interface for configuring any robot for use with MoveIt!. Its primary function is generating a Semantic Robot Description Format (SRDF) file for your robot. Additionally, it generates other necessary configuration files for use with the MoveIt! pipeline. To learn more about the SRDF, you can go through the SRDF Overview page.
MoveIt! and ROS
Step 1: Start¶
To start the MoveIt! Setup Assistant:
roslaunch moveit_setup_assistant setup_assistant.launch
This will bring up the start screen with two choices: Create New MoveIt! Configuration Package or Edit Existing MoveIt! Configuration Package.
Click on the Create New MoveIt! Configuration Package button to bring up the following screen:
- Click on the browse button and navigate to the pr2.urdf.xacro file installed when you installed the pr2 package above. (This file gets installed in /opt/ros/kinetic/share/pr2_description/robots/pr2.urdf.xacro on Ubuntu with ROS Kinetic.) Choose that file and then click Load Files. The Setup Assistant will load the files (this might take a few seconds) and present you with this screen:
Step 2: Generate Self-Collision Matrix¶
The Default Self-Collision Matrix Generator searches for pairs of links on the robot that can safely be disabled from collision checking, decreasing motion planning processing time. These pairs of links are disabled when they are always in collision, never in collision, in collision in the robot’s default position or when the links are adjacent to each other on the kinematic chain. The sampling density specifies how many random robot positions to check for self collision. Higher densities require more computation time while lower densities have a higher possibility of disabling pairs that should not be disabled. The default value is 10,000 collision checks. Collision checking is done in parallel to decrease processing time.
- Click on the Self-Collisions pane selector on the left-hand side and click on the Generate Collision Matrix button. The Setup Assistant will work for a few second before presenting you the results of its computation in the main table.
Step 3: Add Virtual Joints¶
Virtual joints are used primarily to attach the robot to the world. For the PR2 we will define only one virtual joint attaching the base_footprint of the PR2 to the odom_combined world frame. This virtual joint represents the motion of the base of the robot in a plane.
- Click on the Virtual Joints pane selector. Click on Add Virtual Joint
- Set the joint name as “virtual_joint”
- Set the child link as “base_footprint” and the parent frame name as “odom_combined”.
- Set the Joint Type as “planar”.
- Click Save and you should see this screen:
Step 4: Add Planning Groups¶
Planning groups are used for semantically describing different parts of your robot, such as defining what an arm is, or an end effector.
- Click on the Planning Groups pane selector.
- Click on Add Group and you should see the following screen:
Add the right arm
- We will first add the PR2 right arm as a planning group
- Enter Group Name as right_arm
- Choose kdl_kinematics_plugin/KDLKinematicsPlugin as the kinematics solver. Note: if you have a custom robot and would like a powerful custom IK solver, see Kinematics/IKFast
- Let Kin. Search Resolution and Kin. Search Timeout stay at their default values.
- Now, click on the Add Joints button. You will see a
list of joints on the left hand side. You need to choose all the
joints that belong to the right arm and add them to the right hand
side. The joints are arranged in the order that they are stored in
an internal tree structure. This makes it easy to select a serial
chain of joints.
- Click on r_shoulder_pan_joint, hold down the Shift button on your keyboard and then click on the r_wrist_roll_joint. Now click on the > button to add these joints into the list of selected joints on the right.
- Click Save to save the selected group. Note that each arm of the PR2 has only 7 joints and yet we added 11 joints here. Some of the joints (r_upper_arm_joint, r_forearm_joint, r_forearm_cam_frame_joint, r_forearm_cam_optical_frame_joint) are Fixed joints and will not be used for planning or kinematics.
Add the left arm
Now, add the left arm in a similar manner choosing the joints from the l_shoulder_pan_joint to the l_wrist_roll_joint.
Add the grippers
- We will also add two groups for the right and left end
effectors. NOTE that you will do this using a different procedure
than adding the arms.
- Click on the Add Group button.
- Enter Group Name as right_gripper
- Let Kin. Search Resolution and Kin. Search Timeout stay at their default values.
- Click on the Add Links button.
- Choose all links that start with right_gripper and add them to the list of Selected Links on the right hand side.
- Click Save
- Repeat the same procedure for the left arm of the PR2, choosing links that start with left_gripper instead of right_gripper this time.
Step 5: Add Robot Poses¶
The Setup Assistant allows you to add certain fixed poses into the configuration. This helps if, for example, you want to define a certain position of the robot as a Home position.
- Click on the Robot Poses pane.
- Click Add Pose. Choose a name for the pose. The robot will be in its Default position where the joint values are set to the mid-range of the allowed joint value range. Move the individual joints around until you are happy and then Save the pose. Note how poses are associated with particular groups. You can save individual poses for each group.
- IMPORTANT TIP: Try to move all the joints around. If there is something wrong with the joint limits in your URDF, you should be able to see it immediately here.
Step 6: Label End Effectors¶
We have already added the right and left grippers of the PR2. Now, we will designate these two groups as special groups: end effectors. Designating these groups as end effectors allows some special operations to happen on them internally.
- Click on the End Effectors pane.
- Click Add End Effector.
- Choose right_eef as the End Effector Name for the right gripper.
- Select right_gripper as the End Effector Group.
- Select r_wrist_roll_link as the Parent Link for this end-effector.
- Leave Parent Group blank.
- Add the left_eef in a similar manner.
Step 7: Add Passive Joints¶
The passive joints tab is meant to allow specification of any passive joints that might exist in a robot. These are joints that are unactuated on a robot (e.g. passive casters.) This tells the planners that they cannot (kinematically) plan for these joints because they can’t be directly controlled. The PR2 does not have any passive joints so we will skip this step.
Step 8: Add Author Information
- catkin requires author information for publishing purposes. You can enter your name and email address in the Author Information pane.
Step 8: Generate Configuration Files¶
You are almost there. One last step - generating all the configuration files that you will need to start using MoveIt!
- Click on the Configuration Files pane. Choose a location and name for the ROS package that will be generated containing your new set of configuration files. Click browse, select a good location (for example, your home dir), click Create New Folder, call it “pr2_moveit_config”, and click Choose. “pr2_moveit_config” is the location used in the rest of the documentation on this wiki. This package does not have to be within your ROS package path. All generated files will go directly into the directory you have chosen.
- Click on the Generate Package button. The Setup Assistant will now generate and write a set of launch and config files into the directory of your choosing. All the generated files will appear in the Generated Files/Folders tab and you can click on each of them for a description of what they contain.
- Congratulations!! - You are now done generating the configuration files you need for MoveIt!
The MoveIt! Rviz plugin
- Start looking at how you can use the generated configuration files to play with MoveIt! using the MoveIt! Rviz Plugin.
Setup IKFast Inverse Kinematics Solver
- A faster IK solver than the default KDL solver, but takes some additional steps to setup: Kinematics/IKFast
- See the SRDF page for more details on the components of the SRDF mentioned in this tutorial.
- The URDF is the native robot description format in ROS and allows you to describe the kinematics, inertial, visual and sensing properties of your robot. Read through the URDF specific documentation to see how the URDF is used with MoveIt!
Open Source Feedback
See something that needs improvement? Please open a pull request on this GitHub page