Tutorial on setting multicast on user topics (#138)

* Refs #16524: Tutorial on setting multicast on user topics Signed-off-by: Eduardo Ponz <[email protected]> * Refs #16524: Apply suggestions Signed-off-by: Eduardo Ponz <[email protected]> --------- Signed-off-by: Eduardo Ponz <[email protected]>
eProsima · Jun 30, 2023 · e5e413f · e5e413f
1 parent 966ce71
commit e5e413f
Show file tree

Hide file tree

Showing 5 changed files with 130 additions and 0 deletions.
diff --git a/docs/resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.xml b/docs/resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+    <profiles>
+        <!-- Profile name shall match topic name -->
+        <data_reader profile_name="/chatter">
+            <!--
+                Set the chatter subscriptions listening address and port to a multicast locator
+            -->
+            <multicastLocatorList>
+                <locator>
+                    <udpv4>
+                        <address>239.255.0.4</address>
+                        <port>7900</port>
+                    </udpv4>
+                </locator>
+            </multicastLocatorList>
+        </data_reader>
+    </profiles>
+</dds>
diff --git a/...tatic/resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.mp4 b/...tatic/resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.mp4
diff --git a/docs/rst/tutorials/core/deployment/deployment_tutorials.rst b/docs/rst/tutorials/core/deployment/deployment_tutorials.rst
@@ -18,3 +18,4 @@ For tutorials related to cloud or cloud-edge deployments, please refer :ref:`tut
     static_edp/static_edp
     ds_locators_runtime/ds_locators_runtime
     ds_wan_tcp/ds_wan_tcp
+    user_topics_multicast/user_topics_multicast
diff --git a/docs/rst/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.rst b/docs/rst/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.rst
@@ -0,0 +1,108 @@
+.. _tutorials_core_deployment_user_topics_multicast:
+
+Enabling multicast communication
+================================
+
+.. contents::
+    :depth: 2
+    :local:
+    :backlinks: none
+
+.. _tutorials_core_deployment_user_topics_multicast_background:
+
+Background
+----------
+
+.. note::
+
+   This documentation assumes basic knowledge of UDP/TCP/IP concepts, namely unicast and multicast.
+
+When communicating nodes across different hosts, Vulcanexus applications, by default, utilize UDPv4 based unicast communication with one another (between nodes on the same host, the shared memory transport is used by default, which defaults to multicast communications).
+This is because multicast based communication is not always a possibility in certain deployment for a myriad of reasons, among them multicast not performing well over certain WiFi networks or IT constrains.
+However, for deployments in which multicast is an available and reliable means of communication, Vulcanexus generated network traffic can be significantly reduced by leveraging multicast communications, which may also reduce Vulcanexus overhead in terms of CPU utilization and latency while increasing message throughput as the messages need to be copied to the network buffer but once (in opposition to unicast based communications, in which each message needs to be copied once per recipient).
+
+This tutorial showcases how to enable multicast communication between Vulcanexus nodes communicating over a UDPv4 transport by :ref:`tutorials_xml_profiles_intro`.
+
+.. _tutorials_core_deployment_user_topics_multicast_prerequisites:
+
+Prerequisites
+-------------
+
+For accomplishing this tutorial, two available hosts with Docker and a Vulcanexus image are required.
+Please refer to the installation steps detailed in :ref:`docker_installation`.
+
+.. _tutorials_core_deployment_user_topics_multicast_config:
+
+XML Configuration
+-----------------
+
+Save the following XML configuration file at the desired location, which will be referred as ``<path_to_xml_config_file>`` from here onwards.
+
+.. important::
+
+    The Data Reader profile name shall match the topic's Fully Qualified Name (FQN) (see :ref:`vulcanexus_configure_pubsub_profile_names`)
+
+.. literalinclude:: /resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.xml
+    :language: xml
+
+.. _tutorials_core_deployment_user_topics_multicast_example:
+
+Run the example
+---------------
+
+This tutorial leverages the Vulcanexus `humble-desktop` Docker image to demonstrate the use of the aforementioned XML
+configuration file to achieve multicast communication across different hosts.
+
+First, run two Vulcanexus `humble-desktop` with:
+
+.. tabs::
+
+  .. tab:: Container one (Subscription)
+
+    .. code-block:: bash
+
+        docker run \
+            --interactive \
+            --tty \
+            --rm \
+            --volume <path_to_xml_config_file_dir>:/root/xml_config \
+            ubuntu-vulcanexus:humble-desktop
+
+  .. tab:: Container two (Publication)
+
+    .. code-block:: bash
+
+        docker run \
+            --interactive \
+            --tty \
+            --rm \
+            ubuntu-vulcanexus:humble-desktop
+
+Then, within the container, run the talker-listener demo.
+
+.. tabs::
+
+  .. tab:: Container one (Subscription)
+
+    .. code-block:: bash
+
+        source /vulcanexus_entrypoint.sh
+        export FASTRTPS_DEFAULT_PROFILES_FILE=/root/xml_config/<xml_config_file>
+        ros2 run demo_nodes_cpp listener
+
+  .. tab:: Container two (Publication)
+
+    .. code-block:: bash
+
+        source /vulcanexus_entrypoint.sh
+        ros2 run demo_nodes_cpp talker
+
+Optionally, as shown in the following video, it is possible to use Wireshark to sniff the RTPS traffic and corroborate that the specified multicast address and port are indeed used:
+
+.. raw:: html
+
+    <video width=100% height=auto autoplay loop controls>
+        <source src="../../../../../_static/resources/tutorials/core/deployment/user_topics_multicast/user_topics_multicast.mp4">
+        Your browser does not support the video tag.
+    </video>
+
diff --git a/docs/rst/tutorials/core/qos/xml_profiles/xml_profiles.rst b/docs/rst/tutorials/core/qos/xml_profiles/xml_profiles.rst
@@ -163,6 +163,8 @@ Applying different profiles to different entities
 *rmw_fastrtps* allows for the configuration of different entities with different QoS using the same XML file.
 For doing so, *rmw_fastrtps* locates profiles in the XML based on topic names.
 
+.. _vulcanexus_configure_pubsub_profile_names:
+
 Creating publishers/subscribers with different profiles
 .......................................................