Add tutorial on how to add a new move group capability by JafarAbdi · Pull Request #295 · moveit/moveit2_tutorials

JafarAbdi · 2022-01-14T23:49:27Z

Description

I think the intro needs some tweaking but other than that I think this's ready for a review

Checklist

Required by CI: Code is auto formatted using clang-format
While waiting for someone to review your request, please consider reviewing another open pull request to support the maintainers

JafarAbdi · 2022-01-14T23:51:55Z

+-------------------------------
+`This Page <http://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.
+
+In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.


Hopefully, this's a good example, let me know if you have a better one

nbbrooks

Looking good, the gif is nice! My review is just lots of small stuff.

Also, could you have each sentence start on its own line in the .rst files? Makes for much better version control/review of the files. (when it is rendered, the sentences will stay in the same paragraph and it will add a space between the two sentences.)

nbbrooks · 2022-01-19T06:33:05Z

+Creating a new MoveGroup capability
+===================================
+
+In :doc:`Move Group C++ Interface </doc/examples/move_group_interface/move_group_interface_tutorial>` we saw how MoveGroup node make it easy to use MoveIt through ROS interfaces, this node have a list of `default capabilities <https://github.com/ros-planning/moveit2/blob/main/moveit_ros/move_group/default_capabilities_plugin_description.xml>`_ that provide common used action/services to interact with its internal components, sometimes we need to extend it for our own specific applications which could be done easily by creating MoveGroup capability.


Suggested change

In :doc:`Move Group C++ Interface </doc/examples/move_group_interface/move_group_interface_tutorial>` we saw how MoveGroup node make it easy to use MoveIt through ROS interfaces, this node have a list of `default capabilities <https://github.com/ros-planning/moveit2/blob/main/moveit_ros/move_group/default_capabilities_plugin_description.xml>`_ that provide common used action/services to interact with its internal components, sometimes we need to extend it for our own specific applications which could be done easily by creating MoveGroup capability.

In :doc:`Move Group C++ Interface </doc/examples/move_group_interface/move_group_interface_tutorial>` we saw how the MoveGroup node makes it easy to use MoveIt through ROS interfaces.

This node has a list of `default capabilities <https://github.com/ros-planning/moveit2/blob/main/moveit_ros/move_group/default_capabilities_plugin_description.xml>`_ that provide commonly used action/services to interact with its internal components.

Sometimes we need to extend it for our own specific applications which could be done easily by creating a MoveGroup capability.

nit

nbbrooks · 2022-01-19T06:34:53Z

+
+Creating a MoveGroup Capability
+-------------------------------
+`This Page <http://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.


Suggested change

`This Page <http://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.

`This page <https://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.

nbbrooks · 2022-01-19T06:35:23Z

+-------------------------------
+`This Page <http://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.
+
+In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.


Suggested change

In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.

In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provides a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.

nbbrooks · 2022-01-19T06:44:14Z

+-------------------------------
+`This Page <http://wiki.ros.org/pluginlib>`_ gives a detailed explanation of how to add plugins in ROS in general. The two necessary elements are base and plugin classes. The plugin class inherits from the base class and overrides its virtual functions. The main library used for this purpose is pluginlib.
+
+In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.


Suggested change

In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.

In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <examples/move_group_capabilities/src>`.

I think we need to prefix this, codedir does an external link though so hard to be sure

nbbrooks · 2022-01-19T06:44:52Z

+
+In this section, we will show how to add a new MoveGroup capability. For demonstration purposes, we will create a capability which provide a service to query the collision objects in MoveGroup's planning scene. The final source files designed in this tutorial are available :codedir:`here <move_group_capabilities/src>`.
+
+First we start by creating a class GetCollisionObjects by inheriting from move_group::MoveGroupCapability, to do so we create a file named ``get_collision_objects_service_capability.cpp`` in src folder. the minimal requirement is to pass the plugin name to the base class constructor ``MoveGroupCapability``, override the ``initialize`` function, and register the class as a plugin by using ``PLUGINLIB_EXPORT_CLASS``.


Suggested change

First we start by creating a class GetCollisionObjects by inheriting from move_group::MoveGroupCapability, to do so we create a file named ``get_collision_objects_service_capability.cpp`` in src folder. the minimal requirement is to pass the plugin name to the base class constructor ``MoveGroupCapability``, override the ``initialize`` function, and register the class as a plugin by using ``PLUGINLIB_EXPORT_CLASS``.

First we start by creating a class GetCollisionObjects by inheriting from move_group::MoveGroupCapability, to do so we create a file named ``get_collision_objects_service_capability.cpp`` in src folder.

The minimal requirement is to pass the plugin name to the base class constructor ``MoveGroupCapability``, override the ``initialize`` function, and register the class as a plugin by using ``PLUGINLIB_EXPORT_CLASS``.

nbbrooks · 2022-01-19T06:47:59Z

+
+The ``plugin_description.xml`` need to be added to the ament index to be found at runtime, in ``CMakeLists.txt`` add
+
+**NOTE** Make sure to add it to the top-level ``CMakeLists.txt`` file otherwise it will not be detected bu ROS


I think this line and the one above it are meant to be consolidated?

nbbrooks · 2022-01-19T06:48:40Z

+
+  ros2 run moveit_ros_move_group list_move_group_capabilities
+
+you should see ``move_group/GetCollisionObjectsCapability`` as a capability


I think it would be nice to have the expected output here. The downside is it could get out of sync if the default move group plugins change in the future.

nbbrooks · 2022-01-19T06:50:55Z

+
+.. code-block:: bash
+
+  ros2 run moveit_ros_move_group list_move_group_capabilities


Should we instruct them to copy the examples/move_group_capabilities folder into their workspace first?

nbbrooks · 2022-01-19T06:51:44Z

+
+Capability usage
+^^^^^^^^^^^^^^^^
+To use the capability we need first to tell move_group to use it as follow


Suggested change

To use the capability we need first to tell move_group to use it as follow

To use the capability we need first to tell move_group to use it:

nbbrooks · 2022-01-19T06:53:22Z

+^^^^^^^^^^^^^^^^
+To use the capability we need first to tell move_group to use it as follow
+
+.. code-block:: python


Is our recommendation here to add this to moveit2_tutorials move_group.launch.py? If so let's be explicit.

tylerjw · 2022-01-19T21:44:12Z

Do you think you could re-work this to be either a tutorial or a how-to guide? My hope was that new content would not be added to the examples section.

JafarAbdi · 2022-01-20T15:14:46Z

Do you think you could re-work this to be either a tutorial or a how-to guide? My hope was that new content would not be added to the examples section.

Yes, how-to guide makes more sense for this, I'll update it later this week

mergify · 2022-06-16T18:43:42Z