MoveIt! Setup Assistant

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 URDF/SRDF Overview page.

MoveIt! and ROS

  • Follow the instructions for installing MoveIt! first if you have not already done that.
  • If you haven’t already done so, make sure you have the MARA description package, it's included inside MARA_ROS1 directory:
    git clone https://github.com/AcutronicRobotics/MARA_ROS1.git
  • If you have the mara_moveit_config package already git-cloned from the Getting Started page, be sure to delete that now since this tutorial will teach you how to create it from scratch:
    cd ~/ws_moveit/src
    rm -rf mara_moveit_config
    catkin clean mara_moveit_config

  • 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 MARA_ROS1/mara_description/urdf/mara_robot_camera_top.urdf.xacro this file is included inside the cloned repository (MARA_ROS1). 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:

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.

Virtual joints are used primarily to attach the robot to the world. For the MARA we will define only one virtual joint attaching the base_link of the MARA to the world 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_link” and the parent frame name as “world”.
  • Set the Joint Type as “fixed”.
  • Click Save and you should see this screen:

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:
  • We will first add MARA's arm as a planning group

    • Enter Group Name as manipulator
    • 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 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 joint_base, hold down the Shift button on your keyboard and then click on the motor6. 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.

Add the gripper

  • We will also add a group for the end effector. NOTE that you will do this using a different procedure than adding the arm.
    • Click on the Add Group button.
    • Enter Group Name as mara_hand
    • Let Kin. Search Resolution and Kin. Search Timeout stay at their default values.
    • Click on the Add Links button.
    • Choose end_effector_adapter_to_robotiq, left_inner_knuckle_joint, left_outer_knuckle_joint , left_outer_finger_joint, left_inner_finger_joint, right_inner_knuckle_joint, right_outer_knuckle_joint , right_outer_finger_joint and right_inner_finger_joint and add them to the list of Selected Links on the right hand side.
    • Click Save

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.

We have already added the gripper of the MARA. Now, we will designate this group as a special group: end effectors. Designating this group as end effectors allows some special operations to happen on them internally.

  • Click on the End Effectors pane.
  • Click Add End Effector.
  • Choose mara_hand as the End Effector Name for the gripper.
  • Select mara_hand as the End Effector Group.
  • Select base_link as the Parent Link for this end-effector.
  • Leave Parent Group blank.

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 MARA does not have any passive joints so we will skip this step.

The 3D Perception tab is meant to set the parameters of the YAML configuration file for configuring the 3D sensors sensors_3d.yaml.

e.g. point_cloud parameters:

In case of sensors_3d.yaml was not needed, choose None.

ROS Control is a set of packages that include controller interfaces, controller managers, transmissions and hardware_interfaces, for more details please look at ros_control documentation

ROS Control tab can be used to auto generate simulated controllers to actuate the joints of your robot. This will allow us to provide the correct ROS interfaces MoveIt!.

  • Click on the ROS Control pane selector.
  • Click on Add Controller and you should see the following screen:
  • We will first add MARA's position controller
  • Enter Controller Name as mara_position_controller
  • Choose position_controllers/JointPositionController as the controller type
  • Next you have to choose this controller joints, you can add joints individually or add all the joints in a planning group all together.
  • Now, click on Add Planning Group Joints.
  • Choose "manipulator" planning group to add all the joints in that group to the arm controller.
  • Click Save to save the selected controller.

Catkin requires author information for publishing purposes

  • Click on the Author Information pane.
  • Enter your name and email address.

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 directory), click Create New Folder, call it “mara_moveit_config”, and click Choose. This package does not have to be within your ROS package path. All generated files will go directly into the directory you have chosen.
  • 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 URDF and SRDF page for more details on the components of the URDF and SRDF mentioned in this tutorial.