From ce58a19a34b59e4ecf176161bc2b8b7a7cd811eb Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Tue, 16 Apr 2019 14:43:54 -0500 Subject: [PATCH 1/5] Update composition tutorials for new tooling. Signed-off-by: Michael Carroll --- source/Tutorials/Composition.rst | 179 +++++++++++++++++++++++++++---- 1 file changed, 159 insertions(+), 20 deletions(-) diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst index 0d9fe427de..3d4bf5f846 100644 --- a/source/Tutorials/Composition.rst +++ b/source/Tutorials/Composition.rst @@ -40,49 +40,83 @@ Writing a Component ------------------- Since a component is only built into a shared library it doesn't have a ``main`` function (see `Talker source code `__). -A component subclasses from ``rclcpp::Node``. +A component is commonly a subclass of ``rclcpp::Node``. Since it is not in control of the thread it shouldn't perform any long running or even blocking tasks in its constructor. Instead it can use timers to get periodic notification. Additionally it can create publishers, subscribers, servers, and clients. -An important aspect of making such a class a component is that the class registers itself using the package ``class_loader`` (see last line in the source code). +An important aspect of making such a class a component is that the class registers itself using macros from the package ``rclcpp_components`` (see last line in the source code). This makes the component discoverable when its library is being loaded into a running process - it acts as kind of an entry point. +Additionally, once a component is created, it must be registered with the index to be discoverable by the tooling. + +.. code-block:: cmake + + add_library(talker_component SHARED + src/talker_component.cpp) + rclcpp_components_register_nodes(talker_component "composition::Talker") + # To register multiple components in the same shared library, use multiple calls + # rclcpp_components_register_nodes(talker_component "composition::Talker2") + .. _composition-using-components: Using Components ---------------- The `composition `__ package contains a couple of different approaches how to use components. -The two most common ones are: +The three most common ones are: -#. You start a generic container process (`1 `__) and call the ROS service `load_node `__ offered by the container. +#. You start a generic container process (`1 `__) and call the ROS service `load_node `__ offered by the container. The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. - Instead of calling the ROS service programmatically you can also use a `command line tool `__ to invoke the ROS service with the passed command line arguments + Instead of calling the ROS service programmatically you can also use a `command line tool `__ to invoke the ROS service with the passed command line arguments #. You create a `custom executable `__ containing multiple nodes which are known at compile time. This approach requires that each component has a header file (which is not strictly needed for the first case). +#. Create a launch file and use ``ros2 launch`` to create a container process with multiple components loaded. Run the demos ------------- -The executables from the `composition `__ packages can be run with the following commands: +The demos use executables from `rclcpp_components `__, `ros2component `__, and `composition `__ packages, and can be run with the following commands. + + +Discover available components +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To see what components are registered and available in the workspace, execute the following in a shell: + +.. code-block:: bash + + $ ros2 component types + composition + composition::Talker + composition::Listener + composition::Server + composition::Client Run-time composition using ROS services (1.) with a publisher and subscriber ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In the first shell: +In the first shell, start the component container: .. code-block:: bash - ros2 run composition api_composition + ros2 run rclcpp_components component_container + +Verify that the container is running via ``ros2`` command line tools: +.. code-block:: bash -In the second shell (see `talker `__ source code): + $ ros2 component list + /ComponentManager + +In the second shell (see `talker `__ source code). +The command will return the unique ID of the loaded component as well as the node name. .. code-block:: bash - ros2 run composition api_composition_cli composition composition::Talker + $ ros2 component load /ComponentManager composition composition::Talker + 1 /talker Now the first shell should show a message that the component was loaded as well as repeated message for publishing a message. @@ -91,16 +125,20 @@ Another command in the second shell (see `listener `__ and `client `__ source code): .. code-block:: bash - ros2 run composition api_composition_cli composition composition::Server - ros2 run composition api_composition_cli composition composition::Client - + ros2 component load /ComponentManager composition composition::Server + ros2 component load /ComponentManager composition composition::Client In this case the client sends a request to the server, the server processes the request and replies with a response, and the client prints the received response. @@ -136,8 +173,8 @@ In the shell call (see `source code `__ source code). +The command will return the unique ID of the loaded component as well as the node name. + +.. code-block:: bash + + $ ros2 component load /ComponentManager composition composition::Talker + 1 /talker + $ ros2 component load /ComponentManager composition composition::Listener + 2 /listener + +Use the unique ID to unload the node from the component container. + +.. code-block:: bash + + $ ros2 component unload /ComponentManager 1 2 + Unloaded component 1 from /ComponentManager container + Unloaded component 2 from /ComponentManager container + +In the first shell, verify that the repeated messages from talker and listener have stopped. + + +Remapping container name and namespace +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The component manager name and namespace can be remapped via standard command line arguments: + +.. code-block:: bash + + ros2 run rclcpp_components component_container __node:=MyContainer __ns:=/ns + +In a second shell, components can be loaded by using the updated container name: + +.. code-block:: bash + + component load /ns/MyContainer composition composition::Listener + +Note: Namespace remappings of the container do not affect loaded components. + + +Remap component names and namespaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Component names and namespaces may be adjusted via arguments to the load command. + +In the first shell, start the component container: + +.. code-block:: bash + + ros2 run rclcpp_components component_container + + +Some examples of how to remap names and namespaces + +.. code-block:: bash + + # Remap node name + ros2 component load /ComponentManager composition composition::Talker --node-name talker2 + # Remap namespace + ros2 component load /ComponentManager composition composition::Talker --node-namespace /ns + # Remap both + ros2 component load /ComponentManager composition composition::Talker --node-name talker3 --node-namespace /ns2 + +The corresponding entries appear in ``ros2 component list`` + +.. code-block:: bash + $ ros2 component list + /ComponentManager + 1 /talker2 + 2 /ns/talker + 3 /ns2/talker3 + +Note: Namespace remappings of the container do not affect loaded components. + From f134d370232b55c480b99eac2c39932779fc2895 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Tue, 16 Apr 2019 15:26:51 -0500 Subject: [PATCH 2/5] Address reviewer feedback. Signed-off-by: Michael Carroll --- source/Tutorials/Composition.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst index 3d4bf5f846..67e9d1805a 100644 --- a/source/Tutorials/Composition.rst +++ b/source/Tutorials/Composition.rst @@ -67,7 +67,7 @@ The `composition `__ pack The three most common ones are: -#. You start a generic container process (`1 `__) and call the ROS service `load_node `__ offered by the container. +#. You start a (`generic container process `__) and call the ROS service `load_node `__ offered by the container. The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. Instead of calling the ROS service programmatically you can also use a `command line tool `__ to invoke the ROS service with the passed command line arguments #. You create a `custom executable `__ containing multiple nodes which are known at compile time. @@ -274,7 +274,7 @@ In a second shell, components can be loaded by using the updated container name: .. code-block:: bash - component load /ns/MyContainer composition composition::Listener + ros2 component load /ns/MyContainer composition composition::Listener Note: Namespace remappings of the container do not affect loaded components. @@ -291,7 +291,7 @@ In the first shell, start the component container: ros2 run rclcpp_components component_container -Some examples of how to remap names and namespaces +Some examples of how to remap names and namespaces: .. code-block:: bash @@ -302,7 +302,7 @@ Some examples of how to remap names and namespaces # Remap both ros2 component load /ComponentManager composition composition::Talker --node-name talker3 --node-namespace /ns2 -The corresponding entries appear in ``ros2 component list`` +The corresponding entries appear in ``ros2 component list``: .. code-block:: bash $ ros2 component list From 646e4c712eaab2cb31d9a8d44b4e069a22801f3d Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Tue, 23 Apr 2019 09:36:36 -0500 Subject: [PATCH 3/5] Add note about component visibility. Signed-off-by: Michael Carroll --- source/Tutorials/Composition.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst index 67e9d1805a..02ad4d4a69 100644 --- a/source/Tutorials/Composition.rst +++ b/source/Tutorials/Composition.rst @@ -58,6 +58,8 @@ Additionally, once a component is created, it must be registered with the index # To register multiple components in the same shared library, use multiple calls # rclcpp_components_register_nodes(talker_component "composition::Talker2") +Note: In order for the component_container to be able to find desired components, it must be executed or launched from a shell that has sourced the corresponding workspace. + .. _composition-using-components: Using Components @@ -74,6 +76,7 @@ The three most common ones are: This approach requires that each component has a header file (which is not strictly needed for the first case). #. Create a launch file and use ``ros2 launch`` to create a container process with multiple components loaded. + Run the demos ------------- From b44e8d855a6daa9496f5b96030246b463f9a3da2 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Wed, 24 Apr 2019 18:47:28 -0500 Subject: [PATCH 4/5] Minor updates. Signed-off-by: Michael Carroll --- source/Tutorials/Composition.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst index 02ad4d4a69..aa7a892b7e 100644 --- a/source/Tutorials/Composition.rst +++ b/source/Tutorials/Composition.rst @@ -34,7 +34,8 @@ By making the process layout a deploy-time decision the user can choose between: * running multiple nodes in separate processes with the benefits of process/fault isolation as well as easier debugging of individual nodes and * running multiple nodes in a single process with the lower overhead and optionally more efficient communication (see `Intra Process Communication `). -The vision is that a future version of ``ros2 launch`` will support making these different deployments easily configurable. +Additionally ``ros2 launch`` can be used to automate these actions through specialized launch actions. + Writing a Component ------------------- @@ -220,6 +221,9 @@ Note: dlopen-composed components will not be reflected in the ``ros2`` command l Composition using launch actions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +While the command line tools are useful for debugging and diagnosing component configurations, it is frequently more convenient to start a set of components at the same time. +To automate this action, we can use the functionality in ``ros2 launch``. + Advanced Topics --------------- From 776dfc6a9bdae45aa64674f2fec8754cac4196d5 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Wed, 24 Apr 2019 18:49:07 -0500 Subject: [PATCH 5/5] Add lauch command. Signed-off-by: Michael Carroll --- source/Tutorials/Composition.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst index aa7a892b7e..949852356e 100644 --- a/source/Tutorials/Composition.rst +++ b/source/Tutorials/Composition.rst @@ -224,6 +224,10 @@ Composition using launch actions While the command line tools are useful for debugging and diagnosing component configurations, it is frequently more convenient to start a set of components at the same time. To automate this action, we can use the functionality in ``ros2 launch``. +.. code-block:: bash + + ros2 launch composition composition_demo.launch + Advanced Topics ---------------