DDS Router configuration via XML profiles tutorial (#150)

* Run container on the local host

Signed-off-by: tempate <[email protected]>

* Update the YAML conf. version from v3.0 to v3.1

Signed-off-by: tempate <[email protected]>

* Add an XML Participant Configuration tutorial

Signed-off-by: tempate <[email protected]>

* Fix misspells in the tutorials

Signed-off-by: tempate <[email protected]>

* Fix misspells in the XML tutorial

Signed-off-by: tempate <[email protected]>

* Apply the changes suggested in the review

Signed-off-by: tempate <[email protected]>

* Apply the changes suggested in the review

Signed-off-by: tempate <[email protected]>

---------

Signed-off-by: tempate <[email protected]>

docs/resources/tutorials/cloud/change_domain/change_domain.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/change_domain/change_domain_4.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/change_domain/change_domain_with_echo.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_client.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/change_domain_to_ds/change_domain_server.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_edge_1.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

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:
 

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:
 

docs/resources/tutorials/cloud/edge_edge_repeater_cloud/dds_router_repeater.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

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

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"

docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_lan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/microservices_cloud/dds_router_cloud_wan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/microservices_cloud/dds_router_edge.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

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: |
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" >
+        <participant profile_name="custom_participant_configuration">
+            <domainId>1</domainId>
+            <rtps></rtps>
+        </participant>
+    </profiles>
+
+participants:
+
+  - name: ROS_2_Domain_0
+    kind: local
+    domain: 0
+
+  - name: ROS_2_Domain_1
+    kind: xml
+    profile: custom_participant_configuration

docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_lan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_cloud_wan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/wan_edge_cloud/dds_router_edge.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_lan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_cloud_wan.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

docs/resources/tutorials/cloud/wan_edge_cloud_tls/dds_router_edge.yaml

@@ -1,4 +1,4 @@
-version: v3.0
+version: v3.1
 
 participants:
 

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

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

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

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 <https://github.com/eProsima/DDS-Router>`_, is an end-user software application that enables the connection of distributed ROS 2 networks (see the |rosrouter| documentation :ref:`here <vulcanexus_router>`).
+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 <https://eprosima-dds-router.readthedocs.io/en/latest/rst/user_manual/configuration.html#user-manual-configuration-load-xml>`.
+
+.. 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 ``<path/to/file>/ros_2_router_xml_config.yaml``.
+
+.. code-block:: bash
+
+    ddsrouter --config-path <path/to/file>/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.

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