diff --git a/docs/resources/tutorials/cloud/change_domain/change_domain.yaml b/docs/resources/tutorials/cloud/change_domain/change_domain.yaml index 5659797b..09846364 100644 --- a/docs/resources/tutorials/cloud/change_domain/change_domain.yaml +++ b/docs/resources/tutorials/cloud/change_domain/change_domain.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/change_domain/change_domain_4.yaml b/docs/resources/tutorials/cloud/change_domain/change_domain_4.yaml index 58b97a61..748ce464 100644 --- a/docs/resources/tutorials/cloud/change_domain/change_domain_4.yaml +++ b/docs/resources/tutorials/cloud/change_domain/change_domain_4.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/change_domain/change_domain_with_echo.yaml b/docs/resources/tutorials/cloud/change_domain/change_domain_with_echo.yaml index 8d8d944b..dc0dfbb1 100644 --- a/docs/resources/tutorials/cloud/change_domain/change_domain_with_echo.yaml +++ b/docs/resources/tutorials/cloud/change_domain/change_domain_with_echo.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_client.yaml b/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_client.yaml index 0136a197..d724f9e6 100644 --- a/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_client.yaml +++ b/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_client.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_server.yaml b/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_server.yaml index a2b99c24..b01245c3 100644 --- a/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_server.yaml +++ b/docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_server.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_1.yaml b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_1.yaml index 8ee7e66b..8aacc3e5 100644 --- a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_1.yaml +++ b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_1.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_lan.yaml b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_lan.yaml index f34dd979..72e98dc4 100644 --- a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_lan.yaml +++ b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_lan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_wan.yaml b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_wan.yaml index d8287f17..c665a8eb 100644 --- a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_wan.yaml +++ b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_2_wan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_repeater.yaml b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_repeater.yaml index 07342cb8..78170680 100644 --- a/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_repeater.yaml +++ b/docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_repeater.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/kubernetes/ConfigMap.yaml b/docs/resources/tutorials/cloud/kubernetes/ConfigMap.yaml index 428c270e..8fbd8c0e 100644 --- a/docs/resources/tutorials/cloud/kubernetes/ConfigMap.yaml +++ b/docs/resources/tutorials/cloud/kubernetes/ConfigMap.yaml @@ -4,7 +4,7 @@ metadata: name: ddsrouter-config data: ddsrouter.config.file: |- - version: v3.0 + version: v3.1 allowlist: - name: rt/chatter diff --git a/docs/resources/tutorials/cloud/kubernetes/local-ddsrouter.yaml b/docs/resources/tutorials/cloud/kubernetes/local-ddsrouter.yaml index b0c4e1e7..78c74e88 100644 --- a/docs/resources/tutorials/cloud/kubernetes/local-ddsrouter.yaml +++ b/docs/resources/tutorials/cloud/kubernetes/local-ddsrouter.yaml @@ -1,6 +1,6 @@ # local-ddsrouter.yaml -version: v3.0 +version: v3.1 allowlist: - name: "rt/chatter" diff --git a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_lan.yaml b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_lan.yaml index 7f5a1562..2b299e42 100644 --- a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_lan.yaml +++ b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_lan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_wan.yaml b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_wan.yaml index 8efea194..a58af14d 100644 --- a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_wan.yaml +++ b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_wan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_edge.yaml b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_edge.yaml index 2c6c33c2..66d97728 100644 --- a/docs/resources/tutorials/cloud/microservices_cloud/dds_router_edge.yaml +++ b/docs/resources/tutorials/cloud/microservices_cloud/dds_router_edge.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml b/docs/resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml new file mode 100644 index 00000000..0e2a4ca6 --- /dev/null +++ b/docs/resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml @@ -0,0 +1,23 @@ +version: v3.1 + +xml: + files: + - "./xml_configuration.xml" + raw: | + + + + 1 + + + + +participants: + + - name: ROS_2_Domain_0 + kind: local + domain: 0 + + - name: ROS_2_Domain_1 + kind: xml + profile: custom_participant_configuration diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_lan.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_lan.yaml index 7f5a1562..2b299e42 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_lan.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_lan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_wan.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_wan.yaml index 8efea194..a58af14d 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_wan.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_wan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_edge.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_edge.yaml index 2c6c33c2..66d97728 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_edge.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_edge.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_lan.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_lan.yaml index 5279fe6e..0d36b2ea 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_lan.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_lan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_wan.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_wan.yaml index 9c9ac240..cd9c62c7 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_wan.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_wan.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_edge.yaml b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_edge.yaml index 31d2fb95..69e825d1 100644 --- a/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_edge.yaml +++ b/docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_edge.yaml @@ -1,4 +1,4 @@ -version: v3.0 +version: v3.1 participants: diff --git a/docs/rst/figures/tutorials/cloud/change_domain_xml.png b/docs/rst/figures/tutorials/cloud/change_domain_xml.png new file mode 100644 index 00000000..51e5cf24 Binary files /dev/null and b/docs/rst/figures/tutorials/cloud/change_domain_xml.png differ diff --git a/docs/rst/installation/docker.rst b/docs/rst/installation/docker.rst index 69333302..1030291f 100644 --- a/docs/rst/installation/docker.rst +++ b/docs/rst/installation/docker.rst @@ -29,6 +29,8 @@ And then load the image with: docker run \ -it \ --privileged \ + --net host \ + --ipc host \ -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ ubuntu-vulcanexus:iron-desktop diff --git a/docs/rst/tutorials/cloud/change_domain/change_domain.rst b/docs/rst/tutorials/cloud/change_domain/change_domain.rst index 58096bc8..c242f271 100644 --- a/docs/rst/tutorials/cloud/change_domain/change_domain.rst +++ b/docs/rst/tutorials/cloud/change_domain/change_domain.rst @@ -18,8 +18,8 @@ Background That is, ROS 2 nodes such as publishers and subscriptions, or clients and services, deployed in one geographic location and using a dedicated local network will be able to communicate with other ROS 2 nodes deployed in different geographic areas on their own dedicated local networks as if they were all on the same network through the use of |rosrouter|. This tutorial explains how to use the |rosrouter| to communicate ROS 2 nodes in different Domain Ids. -The DDS protocol define Domain Id as a parameter for every *DomainParticipant*. -Different entities in different Domain Ids will never discover each other, and thus they will not communicate to each other. +The DDS protocol defines Domain Id as a parameter for every *DomainParticipant*. +Different entities in different Domain Ids will never discover each other, and thus they will not communicate with each other. Using the |rosrouter| as a bridge between ROS 2 Domains, every node will be able to communicate with any other node independently of the Domain where they are deployed. As already mentioned, the approach of this tutorial is straightforward and is illustrated in the following figure: @@ -119,7 +119,7 @@ Then, create the |rosrouter| configuration file as the one shown below. This configuration defines 2 different *Router Participants*, internal "interfaces" for the |rosrouter|. Each of this Participants will create DDS Entities in each of the domains, and they will forward all the data received from one Domain to the other. -Topics, Data Types, Quality of Services and order of messages will be respected when redirecting the data. +Topics, Data Types, Quality of Services and the order of messages will be respected when redirecting the data. Running ROS 2 Router ^^^^^^^^^^^^^^^^^^^^ @@ -146,7 +146,7 @@ Communicating multiple Domains The |rosrouter| can equally inter-communicate 2 or more Domain Ids. Just add as many Participants as desired to the configuration file and this will redirect all messages from every Domain to all the others. -In the following figure we could see the use case and the configuration required for communicating 4 different Domains. +The following figure illustrates the use case and the configuration required to communicate four different Domains. .. figure:: /rst/figures/tutorials/cloud/change_domain_4.png :align: center diff --git a/docs/rst/tutorials/cloud/cloud_tutorials.rst b/docs/rst/tutorials/cloud/cloud_tutorials.rst index 5c7fed7f..3ca0f516 100644 --- a/docs/rst/tutorials/cloud/cloud_tutorials.rst +++ b/docs/rst/tutorials/cloud/cloud_tutorials.rst @@ -3,7 +3,7 @@ Vulcanexus Cloud Tutorials ========================== -This tutorials aims to show the user how to recreate a robot deployment in a distributed network with the capability of monitoring, control and tracking through the Cloud. +These tutorials aim to show the user how to recreate a robot deployment in a distributed network with the capability of monitoring, controlling, and tracking through the Cloud. This way, a series of tutorials are presented that intend to build a complex final architecture step by step, explaining in detail the different steps of the process and the configuration of the different Vulcanexus nodes and WAN communication enabling components. The following are the tutorials that make up this course on communication in distributed scenarios using the Vulcanexus framework. @@ -20,3 +20,4 @@ The following are the tutorials that make up this course on communication in dis wan_edge_cloud_tls/wan_edge_cloud_tls edge_edge_repeater_cloud/edge_edge_repeater_cloud microservices_cloud/microservices_cloud + router_conf_via_xml_profiles/router_conf_via_xml_profiles diff --git a/docs/rst/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.rst b/docs/rst/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.rst new file mode 100644 index 00000000..8e4fdc61 --- /dev/null +++ b/docs/rst/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.rst @@ -0,0 +1,165 @@ +.. include:: ../../../exports/alias.include + +.. _tutorials_cloud_xml_participant_configuration: + +ROS 2 Router configuration via XML profiles +=========================================== + +.. contents:: + :depth: 2 + :local: + :backlinks: none + + +Background +---------- + +*eProsima ROS 2 Router*, a.k.a `DDS Router `_, is an end-user software application that enables the connection of distributed ROS 2 networks (see the |rosrouter| documentation :ref:`here `). +That is, ROS 2 nodes such as publishers and subscriptions, or clients and services, deployed in one geographic location and using a dedicated local network will be able to communicate with other ROS 2 nodes deployed in different geographic locations on their own dedicated local networks as if they were all on the same network through the use of |rosrouter|. + +This tutorial explains how to configure a Participant with XML. In particular, we will configure two Participants, one without XML on domain ``0`` and one with XML on domain ``1``, and use the |rosrouter| to allow them to communicate between each other. + +.. note:: + + This tutorial is similar to the :ref:`tutorials_router_change_domain` tutorial, since we will launch a *talker* and a *listener* on different domains and connect them with the |rosrouter|. The difference between both tutorials is that, in this one, one of the Participants will be configured using Fast DDS XML profiles. + +The DDS protocol defines Domain Id as a parameter for every *DomainParticipant*. +Different entities in different Domain Ids will never discover each other, and thus they will not communicate with each other. +The |rosrouter| can be used as a bridge between ROS 2 Domains, so that every node in a domain can communicate with every other node on another domain, as illustrated in the following figure: + +.. figure:: /rst/figures/tutorials/cloud/change_domain_xml.png + :align: center + +This tutorial will use the ``demo_nodes_cpp`` package, available in the Vulcanexus Desktop distribution. +Two ROS 2 nodes, a *talker* and a *listener*, will be launched on different ROS 2 Domains, so that they cannot communicate between each other. +Then, the |rosrouter| will be used as a bridge between the two Domains, allowing the *listener* to receive the messages from the *talker*. + + +Prerequisites +------------- + +To proceed, please install Vulcanexus with one of the following installation methods: + +* :ref:`linux_binary_installation` +* :ref:`linux_source_installation` +* :ref:`docker_installation` + +Deploy ROS 2 nodes +------------------ + +Let us start by running the ROS 2 *talker* and *listener* nodes. + +Environment setup +^^^^^^^^^^^^^^^^^ + +To run the nodes, we need to set up the Vulcanexus environment so that the ``demo_nodes_cpp`` package is available. +There are two ways to achieve this: + +#. Running the Vulcanexus Docker image. + + Run the Vulcanexus Docker image by executing: + + .. code-block:: bash + + docker run -it ubuntu-vulcanexus:iron-desktop + + And then, source the Vulcanexus installation by executing (inside the container): + + .. code-block:: bash + + source /opt/vulcanexus/iron/setup.bash + +#. Setting up a development environment on the local host. + + To do this, the ``vucanexus-iron-desktop`` package is needed, since it includes all the simulation tools, demos, and tutorials. + + Set up the Vulcanexus environment by executing: + + .. code-block:: bash + + source /opt/vulcanexus/iron/setup.bash + +Running ROS 2 nodes +^^^^^^^^^^^^^^^^^^^ + +Run a ROS 2 ``demo_nodes_cpp`` *talker* on domain ``0``: + +.. code-block:: bash + + ROS_DOMAIN_ID=0 ros2 run demo_nodes_cpp talker + +Run a ROS 2 ``demo_nodes_cpp`` *listener* on domain ``1``: + +.. code-block:: bash + + ROS_DOMAIN_ID=1 ros2 run demo_nodes_cpp listener + + +At this point, the *listener* should not receive any data from the *talker* since they are in different domains. To connect them, we will use the |rosrouter|. + + +Deploy ROS 2 Router +------------------- + +To deploy the router, we need to create the |rosrouter| configuration. + +The following YAML configuration file configures a |rosrouter| to create a Simple Participant on domain ``0`` +and a Participant configured by XML on domain ``1``. +This configuration is similar to the one in :ref:`tutorials_router_change_domain`: it generates a bridge between two domains (``0`` and ``1``). + +.. literalinclude:: /resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml + :language: yaml + +Participant XML Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +|rosrouter| supports loading XML configuration files to load profiles. +These profiles are used to configure different DomainParticipants using profile names. +Loading an XML file or setting the raw xml file in the |ddsrouter| YAML configuration file allows to load such profiles. +Here there are the two ways to load them. +For more information check the `Load XML Configuration `. + +.. literalinclude:: /resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml + :language: yaml + :lines: 3-13 + + +Simple Participant Domain 0 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Simple Participant is configured with a name, a kind, and a domain id (``0`` in this case). + +.. literalinclude:: /resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml + :language: yaml + :lines: 17-19 + + +XML Participant Domain 1 +^^^^^^^^^^^^^^^^^^^^^^^^ + +The XML Participant is configured with a name, a kind, and an XML ``profile`` tag that will be used to configure it. +The XML configures the profile ``custom_participant_configuration`` as a default Participant on domain ``1``, so this Participant will run as a ``local`` participant on domain ``1``. + +.. literalinclude:: /resources/tutorials/cloud/router_conf_via_xml_profiles/router_conf_via_xml_profiles.yaml + :language: yaml + :lines: 21-23 + + +Running ROS 2 Router +^^^^^^^^^^^^^^^^^^^^ + +Run the |ddsrouter| with the configuration file available at ``/ros_2_router_xml_config.yaml``. + +.. code-block:: bash + + ddsrouter --config-path /ros_2_router_xml_config.yaml + +The output from the |rosrouter| should be something like: + +.. code-block:: bash + + Starting DDS Router Tool execution. + DDS Router running. + +If so, the |rosrouter| has started correctly and it is currently running. Once the |ddsrouter| is running, it will forward the messages from the *talker* on domain 0 to the *listener* on domain 1. +In order to close the execution, press ^C or send a signal (:code:`SIGINT 2` or :code:`SIGTERM 15`) to close it. diff --git a/docs/rst/tutorials/core/ros2_tutorials.rst b/docs/rst/tutorials/core/ros2_tutorials.rst index 5fc7c403..b423c885 100644 --- a/docs/rst/tutorials/core/ros2_tutorials.rst +++ b/docs/rst/tutorials/core/ros2_tutorials.rst @@ -6,7 +6,7 @@ Vulcanexus Core Tutorials A set of :doc:`ROS 2 tutorials <../../../ros2_documentation/source/Tutorials>` are provided in the *ROS 2* Documentation. *Vulcanexus* documentation includes additional *ROS 2* tutorials, along with middleware specific user features only available in *Fast DDS*. -This section will provide a collection of tutorials both on the use and application of the basic functionality, as well as on the exploitation of *ROS 2* for more advanced users. +This section provides a collection of tutorials on the use and application of the basic functionality and, for more advanced users, on the exploitation of *ROS 2*. .. toctree:: :maxdepth: 1