From 42881509f32cf1888e214844863bac7613e3c244 Mon Sep 17 00:00:00 2001 From: Jakeisthesnake <28656653+Jakeisthesnake@users.noreply.github.com> Date: Wed, 15 Jan 2025 08:22:19 -0800 Subject: [PATCH 1/4] Added to Launch Files tutorial explination of MoveitConfigsBuilder member funtions. Added note to Launch FIles tutorial about nodes for custom cpp files. Added note to README.md that building Moveit is not needed if only adding explinations, not exectuable code. This is mostly addressing the pain I feel of building MoveIt (3-4 hours on my laptop). Maybe I am an anomily. --- README.md | 2 +- .../moveit_launch_files_tutorial.rst | 57 ++++++++++++++++++- 2 files changed, 57 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7cd4f21811..1b7fab5868 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Below are some links to help with the ports. * [rclcpp](https://docs.ros2.org/latest/api/rclcpp/index.html) -## MoveIt Tutorials Source Build +## MoveIt Tutorials Source Build (only needed if contrinuting executable code) Follow the [MoveIt Source Build](https://moveit.ros.org/install-moveit2/source/) instructions to set up a colcon workspace with MoveIt from the source. 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..0c5ae2c496 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 @@ -44,10 +44,44 @@ A handy way to refer to a MoveIt configuration package is to use the ``MoveItCon .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_descrition(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 managers' parameters from an optionally provided file path. +If a file path isn't given, MoveIt looks for files in the packages ``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 pipelinesare 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 plaaner names specifiies which planners MoveIt should load; again these should be in your config folder. +MoveIt will also pick one of ypur 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. + + + 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 +221,7 @@ In our example, we have: arguments=["robotiq_gripper_controller", "-c", "/controller_manager"], ) + Launching all the nodes ----------------------- @@ -213,3 +248,23 @@ Finally, we can tell our launch file to actually launch everything we described hand_controller_spawner, ] ) + +Launching a custom .cpp file +---------------------------- + +While not part of the the Getting Started tutorial, another common node to luanch is one that executes a custom .cpp file: + +.. code-block:: python + + moveit_cpp_node = Node( + name="custom_program", + package="custom_program_package", + executable="custom_program", + output="screen", + parameters=[your, + parameters, + here], + ) + +where ``moveit_cpp_node_parameters`` is a list of parameters for that node. See Ros2 documentation for more information on launching .cpp files. +Additionally, the tutorials on this site provide more examples on how to create programs to customize MoveIt's capabilities for your project. From d61561a6372c991646e1d8720b62746b7a14f80b Mon Sep 17 00:00:00 2001 From: Jakeisthesnake <28656653+Jakeisthesnake@users.noreply.github.com> Date: Wed, 15 Jan 2025 08:43:37 -0800 Subject: [PATCH 2/4] Corrected some spelling. --- README.md | 4 +++- .../moveit_launch_files_tutorial.rst | 10 +++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1b7fab5868..f03e8769db 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,9 @@ Below are some links to help with the ports. * [rclcpp](https://docs.ros2.org/latest/api/rclcpp/index.html) -## MoveIt Tutorials Source Build (only needed if contrinuting executable code) +## MoveIt Tutorials Source Build + +(This section can be skipped if you aren't adding executable code. You don't need to build MoveIt to add an explanation about something.) Follow the [MoveIt Source Build](https://moveit.ros.org/install-moveit2/source/) instructions to set up a colcon workspace with MoveIt from the source. 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 0c5ae2c496..e5a40b27a1 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 @@ -55,16 +55,16 @@ The file path to ``robot_name.urdf`` must be relative to your robot package, so you would pass ``.robot_descrition(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 managers' parameters from an optionally provided file path. -If a file path isn't given, MoveIt looks for files in the packages ``config`` folder for files ending with ``controllers.yaml``. +``.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 pipelinesare 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 plaaner names specifiies which planners MoveIt should load; again these should be in your config folder. -MoveIt will also pick one of ypur planners to be the default planner. +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 From 699f177a9b287ddcd62f2511328087157781119e Mon Sep 17 00:00:00 2001 From: Jakeisthesnake <28656653+Jakeisthesnake@users.noreply.github.com> Date: Wed, 15 Jan 2025 08:49:26 -0800 Subject: [PATCH 3/4] Spelling corrections. --- .../moveit_launch_files/moveit_launch_files_tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 e5a40b27a1..99b7a410c8 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 @@ -52,7 +52,7 @@ As seen above, ``gen3`` is the robot name, and MoveIt looks for the package ``ki ``.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_descrition(filepath="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. @@ -252,7 +252,7 @@ Finally, we can tell our launch file to actually launch everything we described Launching a custom .cpp file ---------------------------- -While not part of the the Getting Started tutorial, another common node to luanch is one that executes a custom .cpp file: +While not part of the Getting Started tutorial, another common node to launch is one that executes a custom .cpp file: .. code-block:: python From 4c4587bf068da2e95e9df5f5dcafbb953cb599f6 Mon Sep 17 00:00:00 2001 From: Jakeisthesnake <28656653+Jakeisthesnake@users.noreply.github.com> Date: Mon, 27 Jan 2025 08:58:47 -0800 Subject: [PATCH 4/4] Moved most of the config specific edits to the configuration tutorial. Added a link in the launch tutorial to the moveit_cpp tutorial. Added the CMakeLists.txt code and expliantions to the moveit_cpp tutorial. --- README.md | 2 - .../moveit_cpp/moveitcpp_tutorial.rst | 48 ++++++++++++++- .../moveit_configuration_tutorial.rst | 59 +++++++++++++++++-- .../moveit_launch_files_tutorial.rst | 53 +---------------- 4 files changed, 102 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index f03e8769db..7cd4f21811 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,6 @@ Below are some links to help with the ports. ## MoveIt Tutorials Source Build -(This section can be skipped if you aren't adding executable code. You don't need to build MoveIt to add an explanation about something.) - Follow the [MoveIt Source Build](https://moveit.ros.org/install-moveit2/source/) instructions to set up a colcon workspace with MoveIt from the source. Open a command line to your colcon workspace: 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 99b7a410c8..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 @@ -44,40 +44,6 @@ A handy way to refer to a MoveIt configuration package is to use the ``MoveItCon .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. - - - Launching Move Group -------------------- @@ -249,22 +215,7 @@ Finally, we can tell our launch file to actually launch everything we described ] ) -Launching a custom .cpp file +Launching a custom executable ---------------------------- -While not part of the Getting Started tutorial, another common node to launch is one that executes a custom .cpp file: - -.. code-block:: python - - moveit_cpp_node = Node( - name="custom_program", - package="custom_program_package", - executable="custom_program", - output="screen", - parameters=[your, - parameters, - here], - ) - -where ``moveit_cpp_node_parameters`` is a list of parameters for that node. See Ros2 documentation for more information on launching .cpp files. -Additionally, the tutorials on this site provide more examples on how to create programs to customize MoveIt's capabilities for your project. +Later on these tutorials (:doc:`/doc/examples/moveit_cpp/moveit_cpp_tutorial`), you will learn how to create and launch a custom executable.