From 63c8b6f8af7e9d6a078d8c2e6470f69649e5ba7b Mon Sep 17 00:00:00 2001 From: cferreiragonz Date: Mon, 20 Jan 2025 15:09:25 +0100 Subject: [PATCH] Refs #22627: Review & Line length Signed-off-by: cferreiragonz --- docs/fastdds/env_vars/env_vars.rst | 30 ++++++----- docs/fastdds/transport/listening_locators.rst | 2 +- docs/fastddscli/cli/cli.rst | 53 +++++++++++-------- 3 files changed, 49 insertions(+), 36 deletions(-) diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst index 9d4a52b00..b449a341a 100644 --- a/docs/fastdds/env_vars/env_vars.rst +++ b/docs/fastdds/env_vars/env_vars.rst @@ -254,34 +254,38 @@ The following example shows how to set the address of two remote discovery serve .. _env_vars_easy_mode: -``EASY_MODE`` (Beta) --------------------- - -.. warning:: - Discovery Server ``EASY_MODE`` is a Beta feature. Its functionalities are still under development and they might contain bugs. - Its final version will be available soon. Any feedback is appreciated and can be provided at: +``EASY_MODE`` +------------- -Setting ``EASY_MODE`` to an IP value allows a participant to automatically enter the `Discovery Server EASY_MODE`__. +Setting ``EASY_MODE`` to an IP value allows a participant to automatically enter the +`Discovery Server Easy Mode `__. This mode completely disables **multicast communication**, and relies on Discovery Servers for discovery purposes. -In ``EASY_MODE`` a new Discovery Server will be automatically spawned locally in the given domain, pointing to another Discovery Server located in the specified IP. +With ``EASY_MODE`` a new Discovery Server will be automatically spawned locally in the given +:ref:`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. +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` set to |SIMPLE| (default), to automatically enter the `Discovery Server EASY_MODE`__. +In order for this variable to take effect, the participant must have its +:ref:`discovery protocol` set to |SIMPLE| (default), to automatically enter the +`Discovery Server Easy Mode `__. 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``. +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 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:`TCP` for discovery and user data and :ref:`Shared Memory` for user data. +The transports configured in this new mode include :ref:`TCP` for discovery and user data and +:ref:`Shared Memory` for user data. -A detailed tutorial can be found in the `Discovery Server EASY_MODE`__ documentation. +A detailed tutorial can be found in the +`Discovery Server Easy Mode `__ documentation. .. warning:: Discovery Server ``EASY_MODE`` is not yet available for Windows. diff --git a/docs/fastdds/transport/listening_locators.rst b/docs/fastdds/transport/listening_locators.rst index 8ae1a9038..5955780ee 100644 --- a/docs/fastdds/transport/listening_locators.rst +++ b/docs/fastdds/transport/listening_locators.rst @@ -210,7 +210,7 @@ Well-known ports are calculated using the following predefined rules: - ``PB`` + ``DG`` * *domainId* + ``offsetd2`` * - User unicast - ``PB`` + ``DG`` * *domainId* + ``offsetd3`` + ``PG`` * *participantId* - * - Discovery Server + * - Discovery Server (Easy Mode) - ``PB`` + ``DG`` * *domainId* + ``offsetd4`` diff --git a/docs/fastddscli/cli/cli.rst b/docs/fastddscli/cli/cli.rst index 5b96e4477..1c539fc4d 100644 --- a/docs/fastddscli/cli/cli.rst +++ b/docs/fastddscli/cli/cli.rst @@ -52,39 +52,44 @@ discovery This command provides a simple and direct way to launch a *Fast DDS* :ref:`Discovery Server `. It encompasses two main functionalities: -* **Discovery Server CLI with EASY_MODE (Beta)**: It launches a background daemon which will automatically handle the creation of servers. - The port of each server is calculated based on the Domain ID (``-d`` argument or ``ROS_DOMAIN_ID``), which is the only parameter that the user must specify. +* **Discovery Server CLI Easy Mode**: It launches a background daemon which will automatically handle the + creation of servers. + The port of each server is calculated based on the Domain ID (``-d`` argument or ``ROS_DOMAIN_ID``), which is the + only parameter that the user must specify. If no Domain ID is provided, the default value is 0. - It is intended to be used along with the ``EASY_MODE`` environment variable, which will manage clients connections automatically. - This CLI feature allows the user to dynamically manage servers from the network: launching, stopping, restarting and even modifying their remote servers connections. - For further information about this mode and its status refer to `Discovery Server EASY_MODE `__. + It is intended to be used along with the ``EASY_MODE`` environment variable, which will manage clients connections + automatically. + This CLI feature allows the user to dynamically manage servers from the network: launching, stopping, restarting + and even modifying their remote servers connections. + For further information about this mode refer to `Discovery Server Easy Mode `__. * **Discovery Server CLI Standard Mode**: It launches a server running in foreground with the specified parameters. Configurable parameters include IP address, port, transport protocol, XML profile, etc. - In this mode, *clients* must know how to reach the *server*, which is accomplished by specifying an IP address, a port and - a transport protocol like UDP or TCP. + In this mode, *clients* must know how to reach the *server*, which is accomplished by specifying an IP address, + a port and a transport protocol like UDP or TCP. *Servers* do not need any prior knowledge of their *clients*, but require the listening IP address and port where they may be reached. -.. warning:: - Discovery Server EASY_MODE is a Beta feature. Its functionalities are still under development and they might contain bugs. - Its final version will be available soon. Any feedback is appreciated and can be provided at: - - .. _cli_discovery_easy_mode: -Discovery Server EASY_MODE (Beta) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Discovery Server Easy Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^ -This mode aims to simplify the deployment and configuration of *Fast DDS* Discovery Servers by automatically handling the server's connections. -This mode of the CLI is meant to be used along with the ``EASY_MODE`` environment variable, which can be used to remove to **multicast announcements** from DDS entities and interconnect different hosts by just using the environment variable ``EASY_MODE=``. (Check `Discovery Server EASY_MODE`__ to see a detailed explanation of this feature). +This mode aims to simplify the deployment and configuration of *Fast DDS* Discovery Servers by automatically handling +the server's connections. +This mode of the CLI is meant to be used along with the ``EASY_MODE`` environment variable, which can be used to +remove to **multicast announcements** from DDS entities and interconnect different hosts by just using the environment +variable ``EASY_MODE=``. +(Check `Discovery Server Easy Mode `__ +to see a detailed explanation of this feature). In this way, the CLI provides an auxiliary tool to obtain more advanced configuration for specific cases of use. It can be used to manage running servers, modifying their remote connections, restarting them or stopping them. -*Fast DDS* Discovery servers are handled and monitored from a background daemon which is automatically spawned when required. +*Fast DDS* Discovery servers are handled and monitored from a background daemon which is automatically spawned when +required. -Configuration of servers launched with EASY_MODE is available by using the following command: +Configuration of servers launched with ``EASY_MODE`` is available by using the following command: .. code-block:: bash @@ -99,13 +104,15 @@ The following table lists the available commands for the *Fast DDS* Discovery Se * - Command - Description * - auto - - Handle the daemon start-up automatically and creates a Discovery Server in the specified |br| domain (0 by default). + - Handle the daemon start-up automatically and creates a Discovery Server in the specified + |br| domain (0 by default). * - start - Start the Discovery Server daemon with the remote connections specified. |br| (Example: start -d 1 "127.0.0.1:2;10.0.0.3:42"). * - stop - Stop the Discovery Server daemon if it is executed with no arguments. - If a domain is |br| specified with the ``-d`` argument it will only stop the corresponding server and the daemon |br| will remain alive. + If a domain is |br| specified with the ``-d`` argument it will only stop the corresponding server and the + daemon |br| will remain alive. * - add - Add new remote Discovery Servers to the local server. This will connect both servers and |br| their sub-networks without modifying existing remote servers. |br| @@ -125,7 +132,8 @@ The following table lists the available commands for the *Fast DDS* Discovery Se - Description * - ``-d --domain`` - Selects the domain of the server to target for this action. - It defaults to 0 if |br| this argument is missing and no value is found in the ``ROS_DOMAIN_ID`` environment variable. + It defaults to 0 if |br| this argument is missing and no value is found in the ``ROS_DOMAIN_ID`` + environment variable. * - "remote_server_list" - It is only accepted with the `start`, `add` and `set` commands. It is a list of |br| remote servers to connect to that follows this structure: ";;...". @@ -137,7 +145,8 @@ Discovery Server CLI Mode ^^^^^^^^^^^^^^^^^^^^^^^^^ This mode allows the user to deeply customize Discovery Servers initialization avoiding programming. -However, it requires manual configuration for clients to reach the server, as they must know the server's IP address, port and protocol. +However, it requires manual configuration for clients to reach the server, as they must know the server's +IP address, port and protocol. For more information on the different *Fast DDS* discovery mechanisms and how to configure them, please refer to :ref:`discovery`.