diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index b31558f2b..8ae1e0b90 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -6080,6 +6080,62 @@ void tcp_use_cases() eprosima::fastdds::dds::DomainParticipantFactory::get_instance()->create_participant(0, pqos); //! } + + { + //TCP-AND-DISCOVERY-SERVER-SERVER + eprosima::fastdds::dds::DomainParticipantQos qos = PARTICIPANT_QOS_DEFAULT; + + // Configure the current participant as SERVER + qos.wire_protocol().builtin.discovery_config.discoveryProtocol = eprosima::fastrtps::rtps::DiscoveryProtocol_t::SERVER; + + // Add custom user transport with TCP port 12345 + auto data_transport = std::make_shared(); + data_transport->add_listener_port(12345); + qos.transport().user_transports.push_back(data_transport); + + // Define the listening locator to be on interface 192.168.10.57 and port 12345 + constexpr uint16_t tcp_listening_port = 12345; + eprosima::fastrtps::rtps::Locator_t listening_locator; + eprosima::fastrtps::rtps::IPLocator::setIPv4(listening_locator, "192.168.10.57"); + eprosima::fastrtps::rtps::IPLocator::setPhysicalPort(listening_locator, tcp_listening_port); + eprosima::fastrtps::rtps::IPLocator::setLogicalPort(listening_locator, tcp_listening_port); + qos.wire_protocol().builtin.metatrafficUnicastLocatorList.push_back(listening_locator); + + // Set the GUID prefix to identify this server + std::istringstream("44.53.00.5f.45.50.52.4f.53.49.4d.41") >> qos.wire_protocol().prefix; + //!-- + } + + { + //TCP-AND-DISCOVERY-SERVER-CLIENT + eprosima::fastdds::dds::DomainParticipantQos qos = PARTICIPANT_QOS_DEFAULT; + + // Configure the current participant as SERVER + qos.wire_protocol().builtin.discovery_config.discoveryProtocol = eprosima::fastrtps::rtps::DiscoveryProtocol_t::CLIENT; + + // Add custom user transport with TCP port 0 (automatic port assignation) + auto data_transport = std::make_shared(); + data_transport->add_listener_port(0); + qos.transport().user_transports.push_back(data_transport); + + // Define the server locator to be on interface 192.168.10.57 and port 12345 + constexpr uint16_t server_port = 12345; + eprosima::fastrtps::rtps::Locator_t server_locator; + eprosima::fastrtps::rtps::IPLocator::setIPv4(server_locator, "192.168.10.57"); + eprosima::fastrtps::rtps::IPLocator::setPhysicalPort(server_locator, server_port); + eprosima::fastrtps::rtps::IPLocator::setLogicalPort(server_locator, server_port); + + // Define the server attributes + eprosima::fastrtps::rtps::RemoteServerAttributes remote_server_att; + remote_server_att.metatrafficUnicastLocatorList.push_back(server_locator); + + // Set the GUID prefix to identify this server + std::istringstream("44.53.00.5f.45.50.52.4f.53.49.4d.41") >> remote_server_att.guidPrefix; + + // Add the server + qos.wire_protocol().builtin.discovery_config.m_DiscoveryServers.push_back(remote_server_att); + //!-- + } } bool dds_permissions_test( diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 79529b1d0..804097799 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -3787,6 +3787,109 @@ --> <--> + +TCP-AND-DISCOVERY-SERVER-SERVER<--> + + + + server_tcp_transport + TCPv4 + + + 12345 + + + + + + + + SERVER + + + + +
192.168.10.57
+ 12345 + 12345 + + + + + 44.53.00.5f.45.50.52.4f.53.49.4d.41 + false + + server_tcp_transport + + + + +<--> + +TCP-AND-DISCOVERY-SERVER-CLIENT<--> + + + + client_tcp_transport + TCPv4 + + + 0 + + + + + + + + CLIENT + + + + + + +
192.168.10.57
+ 12345 + 12345 + + + + + + + + false + + client_tcp_transport + + + + +<--> + CONF-LIBRARY-SETTINGS<--> diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst index aee4703b2..21ba86554 100644 --- a/docs/fastdds/env_vars/env_vars.rst +++ b/docs/fastdds/env_vars/env_vars.rst @@ -68,17 +68,23 @@ For more information about XML profiles, please refer to :ref:`xml_profiles`. Setting this variable configures the :ref:`DomainParticipant` to connect to one or more *servers* using the :ref:`Discovery Server` discovery mechanism. -* If ``ROS_DISCOVERY_SERVER`` is defined, and the ``DomainParticipant``'s :ref:`discovery protocol`, +* If ``ROS_DISCOVERY_SERVER`` is defined, and the ``DomainParticipant``'s :ref:`discovery protocol` is set to |SIMPLE|, then Fast DDS will instead configure it as |CLIENT| of the given *server*. * If ``ROS_DISCOVERY_SERVER`` is defined, and the ``DomainParticipant``'s :ref:`discovery protocol` - is |SERVER| or |BACKUP|, then the variable is used to add remote *servers* to the given *server*, leaving the + is set to |SERVER| or |BACKUP|, then the variable is used to add remote *servers* to the given *server*, leaving the :ref:`discovery protocol` as |SERVER| or |BACKUP| respectively. * The value of the variable must list the locator of the server in the form of: - + An IPv4 address like ``192.168.2.23``. The UDP port can be appended using `:` as in ``192.168.2.23:35665``. - + An IPv6 address that follows RFC3513_ address convention like ``1080::8:800:200C:417A``. Again a UDP port can be - appended like in ``[1080::8:800:200C:417A]:35665``. Note the use of square brackets to avoid ambiguities. + + An IPv4 address like ``192.168.2.23``. The UDP protocol is used by default. The UDP port can be appended using `:` + as in ``192.168.2.23:35665``. + + An IPv6 address that follows RFC3513_ address convention like ``1080::8:800:200C:417A``. Again, it uses the UDP + protocol by default. An UDP port can be appended like in ``[1080::8:800:200C:417A]:35665``. Note the use of square + brackets to avoid ambiguities. + + TCPv4 specifier + IPv4 address like ``TCPv4:[127.0.0.1]``. The TCP protocol is used to communicate with the server. + The TCP port can be appended using `:` as in ``TCPv4:[127.0.0.1]:42100``. + + TCPv6 specifier + IPv6 address like ``TCPv6:[::1]``. The TCP protocol is used to communicate with the server. The + TCP port can be appended using `:` as in ``TCPv6:[::1]:42100``. + A DNS name can be specified. This name will be used to query known hosts and available DNS servers to try to resolve valid IP addresses. Several formats are acceptable: @@ -86,13 +92,20 @@ Setting this variable configures the :ref:`DomainParticipant]``. Only the first IPv6 address resolved will be used. + - UDPv6 specifier + domain name + port: ``UDPv6:[]:35665``. As above but using a specific port. + - TCPv4 specifier + domain name: ``TCPv4:[eprosima.com]``. Only the first IPv4 address resolver will be used. + - TCPv4 specifier + domain name + port: ``TCPv4:[eprosima.com]:42100``. As above but using a specific port. + - TCPv6 specifier + domain name: ``TCPv6:[]``. Only the first IPv4 address resolver will be used. + - TCPv6 specifier + domain name + port: ``TCPv6:[]:42100``. As above but using a specific port. + +* If no port is specified when using default UDP transport, the default port 11811 is used. +* If no port is specified when using TCP transport, the default port 42100 is used. * To set more than one *server*'s address, they must be separated by semicolons. * The server's ID is determined by their position in the list. Two semicolons together means the corresponding ID is free. +* When using IPv6 with DNS, the specified domain name space (**) must be able to resolve to an IPv6 + address. Otherwise an error will be raised. The following example shows how to set the address of two remote discovery servers with addresses '84.22.259.329:8888' and 'localhost:1234' and IDs 0 and 2 respectively. @@ -113,8 +126,9 @@ The following example shows how to set the address of two remote discovery serve .. important:: IP addresses specified in ``ROS_DISCOVERY_SERVER`` must be either valid IPv4/IPv6 addresses or domain names. - If a name can be resolved into several addresses it is possible to either use them all or restrict the selection to - the first IPv4 or IPv6 address using the `UDPv4:` and `UDPv6:` prefixes respectively. + If a name can be resolved into several addresses, it is possible to either use them all or restrict the selection to + the first IPv4 using the `UDPv4:` or `TCPv4` prefixes or to the first IPv6 address using the `UDPv6:` or `TCPv6` + prefixes. .. important:: This environment variable is meant to be used in combination with :ref:`Fast DDS discovery CLI`. diff --git a/docs/fastdds/use_cases/tcp/tcp_use_case.rst b/docs/fastdds/use_cases/tcp/tcp_use_case.rst index a0e4207e4..fe9a658e0 100644 --- a/docs/fastdds/use_cases/tcp/tcp_use_case.rst +++ b/docs/fastdds/use_cases/tcp/tcp_use_case.rst @@ -16,12 +16,14 @@ links. The configuration of the TCP transport typically involves an *a priori* knowledge of the deployment in order to set :ref:`Simple Initial Peers` for :ref:`discovery`, which may not always be possible and creates difficulties when reallocating nodes of the distributed applications, as the entire discovery configuration needs to be changed. -To overcome this problem, this use case presents an approach for leveraging the Fast DDS' TCP transport capabilities +To overcome this problem, these use cases present an approach for leveraging the Fast DDS' TCP transport capabilities while at the same time not requiring configuration modifications when the deployment changes over time. -It does so by configuring the participant discovery phase (see :ref:`disc_phases`) to occur over UDP multicast, while -the application data delivery occurs over TCP. +One option is to configure the participant discovery phase (see :ref:`disc_phases`) to occur over UDP multicast, while +the application data delivery occurs over TCP. Also, it is possible to enable TCP communication while using +:ref:`discovery-server-use-case` to manage :ref:`discovery`. .. toctree:: :maxdepth: 2 /fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst + /fastdds/use_cases/tcp/tcp_with_discovery_server.rst diff --git a/docs/fastdds/use_cases/tcp/tcp_with_discovery_server.rst b/docs/fastdds/use_cases/tcp/tcp_with_discovery_server.rst new file mode 100644 index 000000000..6d6af1d93 --- /dev/null +++ b/docs/fastdds/use_cases/tcp/tcp_with_discovery_server.rst @@ -0,0 +1,98 @@ +.. include:: ../../../03-exports/aliases.include +.. include:: ../../../03-exports/aliases-api.include + +.. _use-case-tcp-discovery-server: + +TCP Communication with Discovery Server +========================================== + +*Fast DDS* :ref:`discovery-server-use-case` consists on a client-server discovery mechanism, in which a server +|DomainParticipant| operates as the central point of communication. It collects and processes the metatraffic +sent by the client DomainParticipants, and then distributes the appropriate information among the rest of +the clients. An extended description of the feature can be found at :ref:`discovery_server`. + +To use TCP communication along with Discovery Server, both the server participant and the client participant +need to use custom user transports. There exists several ways of configuring the server participant, being +*Fast DDS* :ref:`ffastddscli_cli` the fastest solution: + +.. tabs:: + + .. tab:: Fast DDS CLI + + It can be configured to work over a TCP transport layer by using the arguments ``-t`` and ``-q`` to set + up the IP address and the TCP port, respectively. After sourcing the environment, the following command + can be used to instantiate a server listening on localhost and port 12345 (see :ref:`ffastddscli_cli`). + + .. code-block:: bash + + fastdds discovery -i 0 -t 127.0.0.1 -q 12345 + + .. tab:: C++ + + The following snippet can be used to instantiate a server on IP 192.168.10.57 listening on port 12345. + + .. literalinclude:: ../../../../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //TCP-AND-DISCOVERY-SERVER-SERVER + :end-before: //! + + .. tab:: XML + + The following snippet can be used to instantiate a server on IP 192.168.10.57 listening on port 12345. + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: TCP-AND-DISCOVERY-SERVER-SERVER<--> + :end-before: <--> + :lines: 2-4, 6-41, 43-44 + + .. tab:: Fast DDS Discovery Server Example + + It can be configured to work over a TCP transport layer by using the argument ``--transport tcpv4``. The IP + address and the TCP port can be set up with arguments ``--listening-address`` and ``--listening-port``, + respectively. From the *DiscoveryServerExample* folder, the following command can be used to instantiate a + server listening on localhost and port 12345. + + .. code-block:: bash + + ./DiscoveryServerExample server --transport tcpv4 --listening-address 127.0.0.1 --listening-port 12345 + + +The client participant can be configured by either using the ``ROS_DISCOVERY_SERVER`` environment variable (see +:ref:`env_vars_ros_discovery_server`) or by manually setting it. + +.. tabs:: + + .. tab:: Environment Variable + + To configure a client participant to communicate over the TCP transport layer with the + ``ROS_DISCOVERY_SERVER`` environment variable, the prefix `TCPv4` needs to be used. The following command + can be used to configure the variable to set up a client using TCP communication and connecting to a + server on localhost and port 12345. + + .. code-block:: bash + + export ROS_DISCOVERY_SERVER=TCPv4:[127.0.0.1]:12345 + + .. tab:: C++ + + The following snippet can be used to instantiate a client that will try to connect to a server on IP + 192.168.10.57 and port 12345, that is, the server instantiated above. + + .. literalinclude:: ../../../../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //TCP-AND-DISCOVERY-SERVER-CLIENT + :end-before: //! + + .. tab:: XML + + The following snippet can be used to instantiate a client that will try to connect to a server on IP + 192.168.10.57 and port 12345, that is, the server instantiated above. + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: TCP-AND-DISCOVERY-SERVER-CLIENT<--> + :end-before: <--> + :lines: 2-4, 6-47, 49-50 diff --git a/docs/fastddscli/cli/cli.rst b/docs/fastddscli/cli/cli.rst index 42ada76db..8d76e89fc 100644 --- a/docs/fastddscli/cli/cli.rst +++ b/docs/fastddscli/cli/cli.rst @@ -79,16 +79,22 @@ Where the parameters are: +--------------------------+-------------------------------------------------------------------------------------------+ | Option | Description | +==========================+===========================================================================================+ +| ``-h -help`` | Produce help message. | ++--------------------------+-------------------------------------------------------------------------------------------+ | ``-i --server-id`` | Unique server identifier. Specifies zero based server position in |br| | | | ``ROS_DISCOVERY_SERVER`` environment variable. Must be an integer in range [0, 255] |br| | | | If not specified, it must be defined using a XML configuration file. | +--------------------------+-------------------------------------------------------------------------------------------+ -| ``-h -help`` | Produce help message. | +| ``-l --udp-address`` | IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any |br| | +| | (0.0.0.0/::0). Instead of an address, a DNS domain name can be specified. | ++--------------------------+-------------------------------------------------------------------------------------------+ +| ``-p --udp-port`` | UDP port chosen to listen the clients. Defaults to '11811'. | +--------------------------+-------------------------------------------------------------------------------------------+ -| ``-l --ip-address`` | IPv4/IPv6 address chosen to listen the clients. Defaults to any (0.0.0.0/::0). |br| | -| | Instead of an address, a DNS domain name can be specified. | +| ``-t --tcp-address`` | IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an |br| | +| | address, a DNS domain name can be specified. Defaults to localhost (127.0.0.1). | +--------------------------+-------------------------------------------------------------------------------------------+ -| ``-p --port`` | UDP port chosen to listen the clients. Defaults to '11811'. | +| ``-q --tcp-port`` | TCP port chosen to listen the clients. Defaults to '42100'. Only one server can be |br| | +| | configured using the default port. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-b --backup`` | Creates a BACKUP *server* (see :ref:`discovery_protocol`) | +--------------------------+-------------------------------------------------------------------------------------------+ @@ -109,6 +115,8 @@ The output is: Server GUID prefix: 44.53..5f.45.50.52.4f.53.49.4d.41 Server Addresses: 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 @@ -275,6 +283,72 @@ Examples Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[0.0.0.0]:11811 +8. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) reading + specific `profile_name` configuration from XML file. + + .. code-block:: bash + + fastdds discovery -i 0 -x profile_name@[PATH_TO_FILE]/config.xml + + Output: + + .. code-block:: bash + + ### Server is running ### + Participant Type: SERVER + Security: NO + Server ID: 0 + Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 + Server Addresses: UDPv4:[127.0.0.1]:56542 + +9. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening + on localhost on default TCP port '42100'. + + .. code-block:: bash + + fastdds discovery -i 0 -t 127.0.0.1 + + Output: + + .. code-block:: bash + + ### Server is running ### + Participant Type: SERVER + Security: NO + Server ID: 0 + Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 + Server Addresses: TCPv4:[127.0.0.1]:42100-42100 + +10. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening + on localhost and WiFi (192.163.6.34). Two TCP ports need to be + specified because TCP transports cannot share ports. + + .. code-block:: bash + + fastdds discovery -i 0 -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101 + + Output: + + .. code-block:: bash + + ### Server is running ### + Participant Type: SERVER + Security: NO + Server ID: 0 + Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 + Server Addresses: 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 + refers to the TCP Physical port and the second one to the TCP Logical + port (see :ref:`transport_tcp_tcp`). + +.. 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 ``127.0.0.1`` for TCP. + .. _cli_shm: shm