ROS2_EASY_MODE feature and tutorial docs (#233)

* Refs #22616: Auto Discovery Server Mode enhancement docs

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Auto Discovery Server Mode tutorial

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Spelling

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Apply Carlos review

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Last typos

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Apply Raul's review and refactor to ROS2_EASY_MODE env variable name

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #22616: Replace TODO with link to documentation

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

---------

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

docs/rst/enhancements/easy_mode/easy_mode.rst

@@ -0,0 +1,137 @@
+.. _easy_mode:
+
+Easy Mode
+=========
+
+The new ``Vulcanexus Easy Mode`` aims to simplify, enhance and optimize the deployment of any ROS 2 application reinforcing the overall out-of-the-box user experience.
+This section reveals its significance, operating mode and impact.
+
+Quick Overview
+^^^^^^^^^^^^^^
+
+The ``Vulcanexus Easy Mode`` is a builtin discovery mode that simplifies to the most the deployment of ROS 2 applications with the use of `Discovery Server <https://fast-dds.docs.eprosima.com/en/latest/fastdds/discovery/discovery_server.html>`_.
+To enable this feature the user only needs to set the environment variable ``ROS2_EASY_MODE=<ip>``.
+This ``<ip>`` can be either the IP address of the current host or the ``<ip>`` of an external host in the same LAN acting as the central point of discovery (``master``).
+By running a ROS 2 node with this environment variable, a new discovery server will be spawned in background.
+The following diagram illustrates the concept:
+
+.. image:: ../../figures/enhancements/easy_mode/easy_mode_quick_intro.png
+    :align: center
+    :width: 55%
+
+The advantages of the ``Vulcanexus Easy Mode`` can be explored in the next section.
+
+.. _easy_mode_benefits:
+
+Benefits
+^^^^^^^^
+
+The use of ``Vulcanexus Easy Mode`` brings the following benefits:
+
+* **Simplicity**: The user does not need to worry about configuring the middleware, enhancing the out-of-the-box experience.
+  The user easily manages connections between domains and hosts only when needed.
+* **Scalability**: The number of discovery packets is drastically reduced, and the system scalability improves.
+* **Reliability**: The new discovery mode is more reliable than Simple discovery with multicast, especially in WiFi scenarios, as it uses peer to peer TCP.
+
+Feature Insights
+^^^^^^^^^^^^^^^^
+
+This sub-section provides a detailed explanation of the ``Vulcanexus Easy Mode``.
+
+Motivation
+----------
+
+ROS 2 users frequently prefer ROS 2 applications to function seamlessly without requiring extensive middleware configuration or network setup.
+However, practical experience suggests that the default `DDS Simple discovery mechanism <https://fast-dds.docs.eprosima.com/en/latest/fastdds/discovery/simple.html#simple-discovery-settings>`_ using multicast may not be the most suitable option for many use cases.
+In contrast, `eProsima's Discovery Server <https://fast-dds.docs.eprosima.com/en/latest/fastdds/discovery/discovery_server.html>`_ mechanism offers an alternative by eliminating the need for multicast discovery traffic and providing a flexible solution adaptable to various network topologies.
+
+This method proposes a centralized discovery approach by means of a Discovery Server entity.
+`Investigation and comparison of both methods <https://fast-dds.docs.eprosima.com/en/2.14.x/fastdds/ros2/discovery_server/ros2_discovery_server.html#discovery-server-v2>`_ have shown that the number of discovery packets is drastically reduced and the system scalability improves when using the Discovery Server.
+The following image shows how Discovery Server simplifies the discovery graph compared with the default DDS Simple discovery for a localhost deployment of four ROS 2 nodes.
+
+.. list-table::
+   :width: 100%
+   :class: borderless
+
+   * - .. image:: ../../figures/enhancements/easy_mode/simple_discovery_multiple_hosts.png
+          :width: 100%
+
+     - .. image:: ../../figures/enhancements/easy_mode/easy_mode_multiple_hosts.png
+          :width: 100%
+
+Background
+----------
+
+*Vulcanexus* uses :ref:`Fast DDS as middleware <vulcanexus_middleware>`.
+Every ROS 2 node requires to have what is called *discovery information* of other nodes beforehand in order to communicate.
+Hence, before ROS 2 nodes (publishers, subscriptions, services,...) start exchanging messages, they must first discover each other.
+The *Simple Discovery Protocol* is the standard protocol defined in the DDS standard.
+However, it has known disadvantages in some scenarios:
+
+* Scalability, as the number of exchanged packets increases significantly as new nodes are added.
+* Requires multicast capabilities that may not work reliably in some scenarios, e.g. WiFi.
+
+The *Fast DDS Discovery Server* offers a Client-Server framework that enables nodes to connect through an intermediary server.
+Each node acts as a discovery client, transmitting its information to one or more discovery servers and obtaining discovery data from them.
+This approach minimizes network traffic associated with discovery and eliminates the need for multicast communication.
+
+Another relevant concept in ROS 2 is the `ROS_DOMAIN_ID <https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Domain-ID.html>`_.
+The *ROS_DOMAIN_ID* is a unique identifier that allows multiple ROS 2 applications to run on the same network without interfering with each other.
+It is a way of isolating different ROS 2 application groups that do not need to communicate with each other.
+Internally, it is directly related to the DDS Domain ID, which, in turn, selects different network port ranges for each domain.
+See the `ROS 2 documentation <https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Domain-ID.html>`_ for further explanation.
+
+Understanding Easy Mode
+-----------------------
+
+The new ``Vulcanexus Easy Mode`` can be enabled by simply setting the environment variable ``ROS2_EASY_MODE`` to an IP (later explained).
+The transports configured in this new mode include ``TCP`` for discovery and user data and ``Shared Memory`` for user data (in case it is `possible to use <https://fast-dds.docs.eprosima.com/en/latest/fastdds/transport/shared_memory/shared_memory.html>`_).
+
+When the first ROS 2 node is launched, it will automatically spawn a Discovery Server instance in the given domain, i.e., the one specified in the ``ROS_DOMAIN_ID`` (0 by default) and make the ROS 2 node a client pointing to it.
+If a Discovery Server is already running in the domain, the node will simply connect to it as a client, and no additional servers will be spawned.
+Therefore, only one Discovery Server will be present in each domain.
+The following diagram illustrates this concept:
+
+.. image:: ../../figures/enhancements/easy_mode/multiple_ds_domain.png
+    :align: center
+    :width: 45%
+
+Servers connection
+------------------
+
+A direct consequence of the ``Easy Mode`` is that the discovery scope of every ROS 2 node is determined by the value set in the ``<ip>`` parameter.
+By setting this value to the IP of a remote host, nodes can interconnect across hosts, as long as they share the same domain.
+However, if a local IP is selected, nodes will not try to discover other entities in different hosts.
+It is important to clarify that setting a local IP does not prevent your nodes from being discovered by other hosts.
+They can be discovered by any other host setting the ``ROS2_EASY_MODE`` variable to your local IP.
+
+The next image shows an example of this latter case:
+
+.. image:: ../../figures/enhancements/easy_mode/easy_mode_connecting_servers.png
+    :align: center
+    :width: 55%
+
+The dashed red arrow represents that the discovery server in Host B points to the master in Host A.
+Then, the solid arrow indicates that both servers will discover each other and, finally, the green arrow signifies the data exchange between the ROS 2 nodes in purple (meaning that they share the same topic).
+
+The act of connecting Discovery Servers can also be done in other fashions, such as:
+
+* Setting the environment variable ``ROS_STATIC_PEERS`` with the pair ``<ip_address:domain_id>`` of the server to connect to.
+* Using the ``fastdds discovery`` cli tool with the sub commands ``add`` or ``set`` followed by the domain and the ``<ip_address:domain_id>`` pair.
+
+Please, refer to the `Fast DDS documentation <https://fast-dds.docs.eprosima.com/en/latest/fastddscli/cli/cli.html#discovery-server-cli-easy-mode>`_ for further information in this regard.
+
+The figure below shows a general case where multiple Discovery Servers are connected to each other:
+
+.. image:: ../../figures/enhancements/easy_mode/easy_mode_general.png
+    :align: center
+    :width: 80%
+
+On the left part of the figure, when discovery servers in Hosts' B and C are connected to an external master server in Host A (i.e., setting ``ROS2_EASY_MODE=<host_a_ip>``), servers in Host B and C will automatically connect to each other.
+This exemplifies how connecting to a Discovery Server is equivalent to connecting to all the servers that this server is connected to, as connected servers automatically form a `mesh topology <https://www.bbc.co.uk/bitesize/guides/z7mxh39/revision/6>`_.
+See `Discovery Server documentation <https://fast-dds.docs.eprosima.com/en/latest/fastdds/discovery/discovery_server.html>`_.
+
+At the same time, the right part of the figure illustrates the case of a different domain in which Hosts B and C are operating in localhost, i.e., having the ``ROS2_EASY_MODE`` to their own host's IP.
+Which is perfectly valid and can coexist with the other domain.
+
+For a practical example demo, please refer to the :ref:`easy_mode_tutorial`.

docs/rst/enhancements/intro.rst

@@ -11,3 +11,4 @@ Vulcanexus Enhancements
 
    fastdds3/fastdds3.rst
    keys/topic-keys.rst
+   easy_mode/easy_mode.rst

docs/rst/tutorials/core/wifi/easy_mode/easy_mode.rst

@@ -0,0 +1,81 @@
+.. include:: ../../../../exports/alias.include
+
+.. _easy_mode_tutorial:
+
+Easy Mode Tutorial
+==================
+
+This tutorial aims to demonstrate the new :ref:`easy_mode` feature in *Vulcanexus* by running a simple talker-listener example demo.
+
+.. contents::
+    :depth: 2
+    :local:
+    :backlinks: none
+
+Prerequisites
+-------------
+
+* It is recommended to have a basic understanding of ``Vulcanexus Easy Mode`` introduced in the :ref:`easy_mode` section.
+* An up-to-date (latest) Vulcanexus installation using one of the following installation methods:
+
+  * :ref:`linux_binary_installation`
+  * :ref:`linux_source_installation`
+  * :ref:`docker_installation`
+
+Preparation
+-----------
+
+Lets start by setting up the Vulcanexus environment.
+First, create an isolated Docker network for the Vulcanexus containers:
+
+.. code-block:: bash
+
+        docker network create --subnet=172.18.0.0/16 vulcanexus_net
+
+Run two containers of the Vulcanexus Docker image and source the Vulcanexus installation with:
+
+.. code-block:: bash
+
+    # Terminal 1
+    docker run --net vulcanexus_net --ip 172.18.0.2 -it --rm ubuntu-vulcanexus:{DISTRO}-desktop
+    source /opt/vulcanexus/{DISTRO}/setup.bash
+
+    # Terminal 2
+    docker run --net vulcanexus_net --ip 172.18.0.3 -it --rm ubuntu-vulcanexus:{DISTRO}-desktop
+    source /opt/vulcanexus/{DISTRO}/setup.bash
+
+.. note::
+
+    It is also possible to run the tutorial between two hosts sharing the same network.
+
+Running the demo
+----------------
+
+The tutorial consists in two docker containers (hosts) running a ROS 2 talker - listener example with the new ``Vulcanexus Easy Mode`` enabled.
+Both hosts are in the same network and domain id as shown in the following diagram:
+
+.. image:: ../../../../figures/tutorials/core/easy_mode/easy_mode_tutorial.png
+    :align: center
+    :width: 55%
+
+Discovery server in Host A will serve as the master server.
+Hence, the IP address of Host A will be used to enable the ``Easy Mode`` in both containers.
+Run the following commands in each container:
+
+.. code-block:: bash
+
+    # Container 1
+    ROS2_EASY_MODE=172.18.0.2 ros2 run demo_nodes_cpp talker
+
+    # Container 2
+    ROS2_EASY_MODE=172.18.0.2 ros2 run demo_nodes_cpp listener
+
+.. note::
+
+    If the tutorial is run using two hosts, the IP address of the ``ROS2_EASY_MODE`` environment variable needs to be set to the IP address of the first host.
+    It is also possible to run the demo in a single host by opening two terminals and running the commands in each terminal.
+    In this case, the IP address should be set to the hosts's IP and only one discovery server will be spawned.
+
+After a moment, the listener should start receiving samples from the talker, meaning that both Discovery Servers are now connected to each other.
+As the talker and listener nodes share the same topic ``chatter``, nodes are discovered and data exchange can happen.
+Further benefits of using the new ``Easy Mode`` are detailed in the :ref:`easy_mode_benefits` section.

docs/rst/tutorials/core/wifi/wifi_tutorials.rst

@@ -9,6 +9,7 @@ This series of tutorials is designed to help address common issues that arise wh
 .. toctree::
     :maxdepth: 1
 
+    easy_mode/easy_mode
     wifi_issues_tutorial/wifi_issues_tutorial
     large_data/large_data
     image_compression/image_compression