diff --git a/.github/workflows/reusable-ubuntu-ci.yml b/.github/workflows/reusable-ubuntu-ci.yml index 769c8d882..961f7f5fa 100644 --- 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 index dfe96f276..d4235f9bc 100644 --- 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` .. |PortParameters::offsetd2-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd2` .. |PortParameters::offsetd3-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd3` +.. |PortParameters::offsetd4-qos-api| replace:: :cpp:member:`wire_protocol().port.offsetd4` .. |WriterResourceLimitsQos-api| replace:: :cpp:class:`WriterResourceLimitsQos` .. |WriterResourceLimitsQos::matched_subscriber_allocation-api| replace:: :cpp:member:`matched_subscriber_allocation` diff --git a/docs/fastdds/discovery/discovery_server.rst b/docs/fastdds/discovery/discovery_server.rst index fb5d450a0..0c487ca4d 100644 --- 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 ` concept does not apply when enabling the Discovery Server mechanism. + :ref:`DDS Domain ` concept does not apply when enabling the default Discovery Server mechanism, + but it applies when using :ref:`ROS2_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 index 874db737c..a9f2775e7 100644 --- 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 `__. +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`, 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` 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``. + +.. 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` unicast for discovery and +:ref:`TCP` and :ref:`Shared Memory` for user data. + +A detailed tutorial can be found in the +`Vucanexus Easy Mode Tutorial `__ 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 index f635d645b..5955780ee 100644 --- 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| diff --git a/docs/fastddscli/cli/cli.rst b/docs/fastddscli/cli/cli.rst index 4b2a5445f..0cd47fde7 100644 --- a/docs/fastddscli/cli/cli.rst +++ b/docs/fastddscli/cli/cli.rst @@ -49,32 +49,172 @@ There are three verbs whose functionality is described in the following table: discovery --------- -This command launches a |SERVER| (or |BACKUP|) for :ref:`Discovery Server `. This *server* will manage -the discovery phases of the |CLIENTS| which are connected to it. -*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. -For more information on the different *Fast DDS* discovery mechanisms and how to configure them, please refer to -:ref:`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 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 ``ROS2_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. + *Servers* do not need any prior knowledge of their *clients*, but require the listening IP address and port + where they may be reached. + +.. _cli_discovery_easy_mode: + +Discovery Server CLI 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 ``ROS2_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 ``ROS2_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. + +Configuration of servers launched with ``ROS2_EASY_MODE`` is available by using the following command: -.. important:: - It is possible to interconnect *servers* (or *backup* servers) instantiated with ``fastdds discovery`` using - environment variable ``ROS_DISCOVERY_SERVER`` (see :ref:`env_vars_ros_discovery_server`) or a XML configuration - file. +.. code-block:: bash + + fastdds discovery [optional -d ] [optional ""] + +The following table lists the available commands for the *Fast DDS* Discovery Server CLI: + +.. list-table:: + :header-rows: 1 + :align: left + + * - Command + - Description + * - auto + - 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. + * - 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| + Example to add two new remote servers: add -d 7 "127.0.0.1:2;10.0.0.3:42". + * - set + - Rewrite the remote Discovery Servers connected to the local server. + This will replace |br| existing remote servers with the new connections. |br| + Example to replace remote servers with a new one: set -d 5 "10.0.0.3:42". + * - list + - List local active Discovery Servers created with the CLI Tool or the ``ROS2_EASY_MODE=``. + +.. list-table:: + :header-rows: 1 + :align: left + + * - Option parameters + - 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 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: ";;...". + +.. _easy_mode_discovery_examples: + +Examples +"""""""" + +1. Start a DS in the default domain 0: + + .. code-block:: bash + + fastdds discovery auto + +2. Stop all running DS and shut down Fast DDS daemon: + + .. code-block:: bash + + fastdds discovery stop + +3. Stop DS running in domain 0: + + .. code-block:: bash + + fastdds discovery stop -d 0 + +4. Start a DS in the domain 42: + + .. code-block:: bash + + fastdds discovery auto -d 42 + + OR -.. _cli_discovery_run: + .. code-block:: bash + + ROS_DOMAIN_ID=42 fastdds discovery auto + +5. Start a DS in domain 4 pointing to remote DS in domain 4: + + .. code-block:: bash + + fastdds discovery start -d 4 10.0.0.7:4 + +6. Add a new remote server to DS running in domain 4 : + + .. code-block:: bash + + fastdds discovery add -d 4 10.0.0.7:4 + +7. List all servers running locally: + + .. code-block:: bash -How to run -^^^^^^^^^^ + fastdds discovery list -On a shell, execute: +8. Starts a DS in domain 3 pointing to local DS in domain 6: + + .. code-block:: bash + + fastdds discovery start -d 3 127.0.0.1:6 + +.. _cli_discovery_cli: + +Discovery Server CLI Standard 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. +For more information on the different *Fast DDS* discovery mechanisms and how to configure them, please refer to +:ref:`discovery`. + +To use this mode, execute on a shell: .. code-block:: bash fastdds discovery [optional parameters] -Where the parameters are: +The following table lists the available parameters for the *Fast DDS* Discovery Server CLI mode: +--------------------------+-------------------------------------------------------------------------------------------+ | Option | Description | @@ -110,19 +250,22 @@ The output is: .. code-block:: bash - ### Server is running ### - Participant Type: - Security: - Server GUID prefix: |44.53..5f.45.50.52.4f.53.49.4d.41 - Server Addresses: UDPv4:[]: - UDPv6:[]: - TCPv4:[]:- - TCPv6:[]:- + #### Server started #### + GUID prefix: |44.53..5f.45.50.52.4f.53.49.4d.41 + Running on: UDPv4:[]: + UDPv6:[]: + TCPv4:[]:- + TCPv6:[]:- Once the *server* is instantiated, the *clients* can be configured either programmatically or by XML (see :ref:`discovery_server`), or using environment variable ``ROS_DISCOVERY_SERVER`` (see :ref:`env_vars_ros_discovery_server`) +.. important:: + It is possible to interconnect *servers* (or *backup* servers) instantiated with :ref:`cli_discovery_cli` using + environment variable ``ROS_DISCOVERY_SERVER`` (see :ref:`env_vars_ros_discovery_server`) or a XML configuration + file. + .. note:: The :ref:`security` configuration of the discovery server should be done through XML. See example below. @@ -130,7 +273,7 @@ Once the *server* is instantiated, the *clients* can be configured either progra .. _cli_discovery_examples: Examples -^^^^^^^^ +"""""""" 1. Launch a **default server** listening on all available interfaces on UDP port '11811'. Only one server can use default values per machine. @@ -143,11 +286,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: UDPv4:[0.0.0.0]:11811 + #### Server started #### + GUID prefix: + Running on: UDPv4:[0.0.0.0]:11811 2. Launch a default server listening on localhost with UDP port 14520. Only localhost clients can reach the server defining as `ROS_DISCOVERY_SERVER=127.0.0.1:14520`. @@ -160,11 +301,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: UDPv4:[127.0.0.1]:14520 + #### Server started #### + GUID prefix: + Running on: UDPv4:[127.0.0.1]:14520 This same output can be obtained loading the following XML configuration file ``DiscoveryServerCLI.xml``: @@ -188,11 +327,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: TCPv4:[0.0.0.0]:42100 + #### Server started #### + GUID prefix: + Running on: TCPv4:[0.0.0.0]:42100 .. _Deprecated_CLI: https://fast-dds.docs.eprosima.com/en/v2.14.0/fastddscli/cli/cli.html @@ -207,11 +344,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41 - Server Addresses: UDPv6:[2a02:ec80:600:ed1a::3]:14520 + #### Server started #### + GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41 + Running on: UDPv6:[2a02:ec80:600:ed1a::3]:14520 5. Launch a default server listening on WiFi (192.168.36.34) and Ethernet (172.20.96.1) local interfaces with UDP ports 8783 and 51083 respectively @@ -225,12 +360,10 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type SERVER - Security: NO - Server GUID prefix: - Server Addresses: UDPv4:[192.168.36.34]:8783 - UDPv4:[172.20.96.1]:51083 + #### Server started #### + GUID prefix: + Running on: UDPv4:[192.168.36.34]:8783 + UDPv4:[172.20.96.1]:51083 Using the same XML configuration file from the second example, the same output can be obtained loading a specific profile: `second_participant_profile_discovery_server_cli`. @@ -250,11 +383,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type BACKUP - Security: NO - Server GUID prefix: - Server Addresses: UDPv4:[172.30.144.1]:12345 + #### Backup Server started #### + GUID prefix: + Running on: UDPv4:[172.30.144.1]:12345 7. Launch a secure server listening on all available interfaces on UDP port '11811'. @@ -266,11 +397,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: YES - Server GUID prefix: - Server Addresses: UDPv4:[0.0.0.0]:11811 + #### Server started #### + GUID prefix: + Running on: UDPv4:[0.0.0.0]:11811 8. Launch a server reading specific `profile_name` configuration from XML file. @@ -282,11 +411,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: UDPv4:[127.0.0.1]:56542 + #### Server started #### + GUID prefix: + Running on: UDPv4:[127.0.0.1]:56542 9. Launch a server listening on localhost on default TCP port '42100'. @@ -298,11 +425,9 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: TCPv4:[127.0.0.1]:42100-42100 + #### Server started #### + GUID prefix: + Running on: TCPv4:[127.0.0.1]:42100-42100 10. Launch a server listening on localhost and WiFi (192.163.6.34). Two TCP ports need to be specified because transports cannot share ports. @@ -315,12 +440,10 @@ Examples .. code-block:: bash - ### Server is running ### - Participant Type: SERVER - Security: NO - Server GUID prefix: - Server Addresses: TCPv4:[127.0.0.1]:42100-42100 - TCPv4:[192.163.6.34]:42101-42101 + #### Server started #### + GUID prefix: + Running on: TCPv4:[127.0.0.1]:42100-42100 + TCPv4:[192.163.6.34]:42101-42101 .. note:: When using Discovery Server over TCP, the first port shown in the output @@ -330,7 +453,7 @@ Examples .. note:: A server can be instantiated just by passing the port arguments ``-p`` and ``-q``. Fast DDS CLI will use the default values of the IP addresses, - that is, ``0.0.0.0`` for UDP and ``0.0.0.0`` for TCP. + that is, ``0.0.0.0`` for both UDP and TCP. .. _cli_shm: diff --git a/docs/notes/previous_versions/v2.6.0.rst b/docs/notes/previous_versions/v2.6.0.rst index 4c7ee71c7..20081e29d 100644 --- a/docs/notes/previous_versions/v2.6.0.rst +++ b/docs/notes/previous_versions/v2.6.0.rst @@ -18,7 +18,7 @@ This minor release includes the following **features**: 4. Endpoint discovery RTPS API 5. ``on_sample_lost`` RTPS API 6. Transport layer API extension -7. :ref:`XML support for Fast DDS CLI ` +7. :ref:`XML support for Fast DDS CLI ` 8. :ref:`New exchange format to reduce bandwidth in Static Discovery ` It also includes the following **improvements**: