Feature: Fast DDS ROS2_EASY_MODE (#1020)

* Refs #22627: Update CLI docs Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Update ports parameters Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Update env. vars. Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Update dependencies Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Mention mesh topology Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Clarify domain with EASY_MODE Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Review & Line length Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Review - NIT Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Review - CLI improvement & minor fixes Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: ROS2_EASY_MODE Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #22627: Revision - Change Link Co-authored-by: Mario Domínguez López <116071334+Mario-DL@users.noreply.github.com> Signed-off-by: Carlos Ferreira González <carloos.499@gmail.com> --------- Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> Signed-off-by: Carlos Ferreira González <carloos.499@gmail.com> Co-authored-by: Mario Domínguez López <116071334+Mario-DL@users.noreply.github.com>
eProsima · Jan 23, 2025 · 8e9a8da · 8e9a8da
1 parent f0cc847
commit 8e9a8da
Show file tree

Hide file tree

Showing 7 changed files with 252 additions and 82 deletions.
diff --git a/.github/workflows/reusable-ubuntu-ci.yml b/.github/workflows/reusable-ubuntu-ci.yml
@@ -112,7 +112,7 @@ jobs:
       - name: Install Python dependencies
         uses: eProsima/eProsima-CI/multiplatform/install_python_packages@v0
         with:
-          packages: vcstool xmlschema
+          packages: vcstool xmlschema psutil
           upgrade: false
 
       - name: Install Fast DDS Docs required python packages

diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include
@@ -737,6 +737,7 @@
 .. |PortParameters::offsetd1-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd1<eprosima::fastdds::rtps::PortParameters::offsetd1>`
 .. |PortParameters::offsetd2-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd2<eprosima::fastdds::rtps::PortParameters::offsetd2>`
 .. |PortParameters::offsetd3-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd3<eprosima::fastdds::rtps::PortParameters::offsetd3>`
+.. |PortParameters::offsetd4-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd4<eprosima::fastdds::rtps::PortParameters::offsetd4>`
 
 .. |WriterResourceLimitsQos-api| replace:: :cpp:class:`WriterResourceLimitsQos<eprosima::fastdds::dds::WriterResourceLimitsQos>`
 .. |WriterResourceLimitsQos::matched_subscriber_allocation-api| replace:: :cpp:member:`matched_subscriber_allocation<eprosima::fastdds::dds::WriterResourceLimitsQos::matched_subscriber_allocation>`

diff --git a/docs/fastdds/discovery/discovery_server.rst b/docs/fastdds/discovery/discovery_server.rst
@@ -16,7 +16,8 @@ ease Discovery Server setup and testing.
 
 .. note::
 
-  :ref:`DDS Domain <dds_layer_domain>` concept does not apply when enabling the Discovery Server mechanism.
+  :ref:`DDS Domain <dds_layer_domain>` concept does not apply when enabling the default Discovery Server mechanism,
+  but it applies when using :ref:`ROS2_EASY_MODE<env_vars_easy_mode>`.
 
 .. contents::
     :local:
@@ -50,6 +51,7 @@ In this architecture there are several key concepts to understand:
     * A *server* also announces the existence of a new *server* to its known *servers*, and vice versa.
       In this way, a new server can connect to every other existing *server* in the network by just knowing the
       existence of one of them.
+      In this way, a mesh topology between servers is created with minimal configuration.
     * The discovery information that is redistributed might come from a **direct** *client* connected to the |SERVER|,
       or from another *server* that is redirecting the discovery data from **its** *clients*.
     * Known *servers* will receive all the information from the **direct** *clients* known by the *server* and the

diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst
@@ -252,6 +252,44 @@ The following example shows how to set the address of two remote discovery serve
     (that has been initialized with this environment variable previously) if loaded from an environment file using
     :ref:`env_vars_fastdds_environment_file`.
 
+.. _env_vars_easy_mode:
+
+``ROS2_EASY_MODE``
+------------------
+
+Setting ``ROS2_EASY_MODE`` to an IP value allows a participant to automatically enter the
+`Discovery Server Easy Mode <https://docs.vulcanexus.org/en/latest/rst/enhancements/easy_mode/easy_mode.html>`__.
+This mode completely disables **multicast communication**, and relies on Discovery Servers for discovery purposes.
+
+With ``ROS2_EASY_MODE`` a new Discovery Server will be automatically spawned locally in the given
+:ref:`domain<dds_layer_domain>`, pointing to another Discovery Server located in the specified IP.
+If the specified IP belongs to the same host, it will only work in localhost, until another host connects to it.
+If there exists a Discovery Server for that domain, the spawn process will be skipped, relying on the existing server
+for discovery purposes.
+Therefore, only one Discovery Server per host will be present in the domain.
+
+In order for this variable to take effect, the participant must have its
+:ref:`discovery protocol<discovery_protocol>` set to |SIMPLE| (default), to automatically enter the
+`Discovery Server Easy Mode <https://docs.vulcanexus.org/en/latest/rst/enhancements/easy_mode/easy_mode.html>`__.
+If this happens, the participant will be configured as a |SUPER_CLIENT| pointing to the local server.
+
+The following example will configure participants as |SUPER_CLIENT| pointing to a local Discovery Server,
+which will try to connect to another Discovery Server located in the host ``10.0.0.1``.
+
+.. code-block:: bash
+
+    export ROS2_EASY_MODE=10.0.0.1
+
+The port of the Discovery Server is calculated using the rules explained in the :ref:`listening_locators_defaultPorts`.
+The transports configured in this new mode include :ref:`UDP<transport_udp_udp>` unicast for discovery and
+:ref:`TCP<transport_tcp_tcp>` and :ref:`Shared Memory<transport_sharedMemory_sharedMemory>` for user data.
+
+A detailed tutorial can be found in the
+`Vucanexus Easy Mode Tutorial <https://docs.vulcanexus.org/en/latest/rst/tutorials/core/wifi/easy_mode/easy_mode.html>`__ documentation.
+
+.. warning::
+    Discovery Server ``ROS2_EASY_MODE`` is not yet available for Windows platforms.
+
 .. _env_vars_ros_super_client:
 
 ``ROS_SUPER_CLIENT``

diff --git a/docs/fastdds/transport/listening_locators.rst b/docs/fastdds/transport/listening_locators.rst
@@ -210,6 +210,8 @@ Well-known ports are calculated using the following predefined rules:
      - ``PB`` + ``DG`` * *domainId* + ``offsetd2``
    * - User unicast
      - ``PB`` + ``DG`` * *domainId* + ``offsetd3`` + ``PG`` * *participantId*
+   * - Discovery Server (Easy Mode)
+     - ``PB`` + ``DG`` * *domainId* + ``offsetd4``
 
 
 The values used in these rules are explained on the following table.
@@ -262,3 +264,7 @@ The default values can be modified using the |WireProtocolConfigQos::port-api| m
      - Additional offset
      - 11
      - |PortParameters::offsetd3-qos-api|
+   * - ``offsetd4``
+     - Additional offset
+     - 2
+     - |PortParameters::offsetd4-qos-api|