diff --git a/doc/examples/moveit_cpp/moveitcpp_tutorial.rst b/doc/examples/moveit_cpp/moveitcpp_tutorial.rst index be4b588297..4084339c09 100644 --- a/doc/examples/moveit_cpp/moveitcpp_tutorial.rst +++ b/doc/examples/moveit_cpp/moveitcpp_tutorial.rst @@ -29,4 +29,50 @@ The entire code can be seen :codedir:`here in the MoveIt GitHub project` on GitHub. All the code in this tutorial can be run from the **moveit2_tutorials** package that you have as part of your MoveIt setup. +The entire launch file is :codedir:`here` on GitHub. +Notably, the launch file contains the following node + +.. code-block:: python + + # MoveItCpp demo executable + moveit_cpp_node = Node( + name="moveit_cpp_tutorial", + package="moveit2_tutorials", + executable="moveit_cpp_tutorial", + output="screen", + parameters=[moveit_config.to_dict()], + ) +This node contains parameters which are passed to the executable associated with moveit_cpp_tutorial. + +The CMakeLists.txt File +----------------------- +During the build process, the CMakeLists.txt file assigns where the launcher will look for the executable. +Below is the CMakeLists.txt file for this tutorial: + +.. code-block:: cmake + + add_executable(moveit_cpp_tutorial src/moveit_cpp_tutorial.cpp) + target_include_directories(moveit_cpp_tutorial PUBLIC include) + ament_target_dependencies(moveit_cpp_tutorial ${THIS_PACKAGE_INCLUDE_DEPENDS} Boost) + + install(TARGETS moveit_cpp_tutorial + DESTINATION lib/${PROJECT_NAME} + ) + install(DIRECTORY launch + DESTINATION share/${PROJECT_NAME} + ) + install(DIRECTORY config + DESTINATION share/${PROJECT_NAME} + ) + +``add_executable`` builds the executable named moveit_cpp_tutorial from the source file ``src/moveit_cpp_tutorial.cpp``. + +``target_include_directories`` specifies the directories to search for header files during compilation. +``PUBLIC`` makes the include directory available to targets that depend on ``moveit_cpp_tutorial``. + +``ament_target_dependencies`` specifies dependencies for the moveit_cpp_tutorial executable. +``${THIS_PACKAGE_INCLUDE_DEPENDS}`` is a variable defined in the ``moveit2_tutorials`` root directory's CMakeLists.txt file, which list common dependencies used in moveit2_tutorials. + +``install(TARGET ...)`` and ``install(DIRECTORY ...)`` specify where to put the built executable and directories needed to run your program. + +For more details about custom executables, please browse the other examples on this site as well as the ROS documentation. diff --git a/doc/how_to_guides/moveit_configuration/moveit_configuration_tutorial.rst b/doc/how_to_guides/moveit_configuration/moveit_configuration_tutorial.rst index 3b922fa81f..ce6baee2ee 100644 --- a/doc/how_to_guides/moveit_configuration/moveit_configuration_tutorial.rst +++ b/doc/how_to_guides/moveit_configuration/moveit_configuration_tutorial.rst @@ -167,21 +167,68 @@ or you can include selected sub-components as follows: Note that the above syntax will automatically look for configuration files that match the default file naming patterns described in this document. If you have a different naming convention, you can use the functions available in ``MoveItConfigsBuilder`` to directly set file names. -For example, to use a non-default robot description and IK solver file path, and configure planning pipelines: +Using the launch file from :doc:`/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial` as an example: .. code-block:: python from moveit_configs_utils import MoveItConfigsBuilder + # Define xacro mappings for the robot description file + launch_arguments = { + "robot_ip": "xxx.yyy.zzz.www", + "use_fake_hardware": "true", + "gripper": "robotiq_2f_85", + "dof": "7", + } + + # Load the robot configuration moveit_config = ( - MoveItConfigsBuilder("my_robot") - .robot_description(file_path="config/my_robot.urdf.xacro") - .robot_description_kinematics(file_path="config/my_kinematics_solver.yaml") + MoveItConfigsBuilder( + "gen3", package_name="kinova_gen3_7dof_robotiq_2f_85_moveit_config" + ) + .robot_description(mappings=launch_arguments) + .trajectory_execution(file_path="config/moveit_controllers.yaml") + .planning_scene_monitor( + publish_robot_description=True, publish_robot_description_semantic=True + ) .planning_pipelines( - pipelines=["ompl", "pilz_industrial_motion_planner"], - default_planning_pipeline="pilz_industrial_motion_planner", + pipelines=["ompl", "stomp", "pilz_industrial_motion_planner"] ) .to_moveit_configs() ) + +``MoveItConfigsBuilder`` (`defined here `_) can take a few different types of arguments. + +* ``MoveItConfigsBuilder(package_name="package_name")`` will search for a package named "package_name". +* ``MoveItConfigsBuilder("robot_name")`` will search for an explicitly given package name. +Both arguments can be given, in which case the robot name is stored and the package with the explicitly given name will be loaded. +As seen above, ``gen3`` is the robot name, and MoveIt looks for the package ``kinova_gen3_7dof_robotiq_2f_85_moveit_config`` instead of ``gen3_moveit_config``. + +``.robot_description`` can optionally take a file path to ``robot_name.urdf`` and/or assign a dictionary of argument mappings that are passed to the robot's urdf.xacro file. +The file path to ``robot_name.urdf`` must be relative to your robot package, so if your robot package is ``/robot_package`` and the urdf (or urdf xacro) file is ``robot_package/config/robot_name.urdf`` +you would pass ``.robot_description(filepath="config/robot_name.urdf")``. +If you don't provide a file path, but you do give ``MoveItConfigsBuilder`` a robot name (see above paragraph), MoveIt will look for ``robot_package/config/robot_name.urdf``. + +``.trajectory_execution`` loads trajectory execution and MoveIt controller manager's parameters from an optionally provided file path. +If a file path isn't given, MoveIt looks for files in the package's ``config`` folder for files ending with ``controllers.yaml``. + +``.planning_scene_monitor`` allows you to set various parameters about what scene information is published and how often is it published. + +``.planning_pipelines`` allows to you to list the names of the planners you want available to be used by your robot. +If you opt to not list pipelines, as in ``.planning_pipelines()``, MoveIt will look in the config folder of your package for files that end with "_planning.yaml". +Additionally, if no pipelines are listed, MoveIt will load a set of planners from its own library - this can be disabled adding ``load_all=False`` as an argument to ``.planning_pipelines``. +Listing the planner names specifiies which planners MoveIt should load; again these should be in your config folder. +MoveIt will also pick one of your planners to be the default planner. +If OMPL is one of your planners, it will be the default planner unless you set ``default_planning_pipeline`` to your desired default planner as in + +.. code-block:: python + + .planning_pipelines( + pipelines=["ompl", "your_favorite_planner"], + default_planning_pipeline="your_favorite_planner", + ) + +If OMPL is not in your planner list and you don't set a default planner, MoveIt will pick the first planner in the list. + Now that you have read this page, you should be able to better understand the launch files available throughout the MoveIt 2 tutorials, and when encountering other MoveIt configuration packages in the wild. diff --git a/doc/how_to_guides/moveit_launch_files/moveit_launch_files_tutorial.rst b/doc/how_to_guides/moveit_launch_files/moveit_launch_files_tutorial.rst index c40d222b6a..bdcb94290b 100644 --- a/doc/how_to_guides/moveit_launch_files/moveit_launch_files_tutorial.rst +++ b/doc/how_to_guides/moveit_launch_files/moveit_launch_files_tutorial.rst @@ -47,7 +47,7 @@ A handy way to refer to a MoveIt configuration package is to use the ``MoveItCon Launching Move Group -------------------- -Once all the MoveIt configuration parameters have been loaded, you can launch the :ref:`Move Group Interface` using the entire set of loaded MoveIt parameters. +Once all the MoveIt configuration parameters have been loaded, you can define the :ref:`Move Group Interface` Node using the entire set of loaded MoveIt parameters. .. code-block:: python @@ -187,6 +187,7 @@ In our example, we have: arguments=["robotiq_gripper_controller", "-c", "/controller_manager"], ) + Launching all the nodes ----------------------- @@ -213,3 +214,8 @@ Finally, we can tell our launch file to actually launch everything we described hand_controller_spawner, ] ) + +Launching a custom executable +---------------------------- + +Later on these tutorials (:doc:`/doc/examples/moveit_cpp/moveit_cpp_tutorial`), you will learn how to create and launch a custom executable.