Multicast PDP + TCP data use case (#594)

* Refs #19762: Introduction Signed-off-by: EduPonz <[email protected]> * Refs #19762: TCP with multicast discovery Signed-off-by: EduPonz <[email protected]> * Refs #19762: Add Troubleshooting section Signed-off-by: EduPonz <[email protected]> * Refs #19762: Apply Carlos' suggestions Signed-off-by: EduPonz <[email protected]> --------- Signed-off-by: EduPonz <[email protected]>
eProsima · Nov 13, 2023 · 89c199c · 89c199c
1 parent 8acb4bb
commit 89c199c
Show file tree

Hide file tree

Showing 9 changed files with 211 additions and 3 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -5943,6 +5943,49 @@ void dds_waitset_example()
  //!
 }
 
+void tcp_use_cases()
+{
+ {
+ //PDP-MULTICAST-DATA-TCP
+ eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;
+
+ /* Transports configuration */
+ // UDPv4 transport for PDP over multicast
+ auto pdp_transport = std::make_shared<eprosima::fastdds::rtps::UDPv4TransportDescriptor>();
+ pqos.transport().user_transports.push_back(pdp_transport);
+
+ // TCPv4 transport for EDP and application data (The listening port must to be unique for
+ // each participant in the same host)
+ constexpr uint16_t tcp_listening_port = 12345;
+ auto data_transport = std::make_shared<eprosima::fastdds::rtps::TCPv4TransportDescriptor>();
+ data_transport->add_listener_port(tcp_listening_port);
+ pqos.transport().user_transports.push_back(data_transport);
+
+ pqos.transport().use_builtin_transports = false;
+
+ /* Locators */
+ // Define locator for PDP over multicast
+ eprosima::fastrtps::rtps::Locator_t pdp_locator;
+ pdp_locator.kind = LOCATOR_KIND_UDPv4;
+ eprosima::fastrtps::rtps::IPLocator::setIPv4(pdp_locator, "239.255.0.1");
+ pqos.wire_protocol().builtin.metatrafficMulticastLocatorList.push_back(pdp_locator);
+
+ // Define locator for EDP and user data
+ eprosima::fastrtps::rtps::Locator_t tcp_locator;
+ tcp_locator.kind = LOCATOR_KIND_TCPv4;
+ eprosima::fastrtps::rtps::IPLocator::setIPv4(tcp_locator, "0.0.0.0");
+ eprosima::fastrtps::rtps::IPLocator::setPhysicalPort(tcp_locator, tcp_listening_port);
+ eprosima::fastrtps::rtps::IPLocator::setLogicalPort(tcp_locator, tcp_listening_port);
+ pqos.wire_protocol().builtin.metatrafficUnicastLocatorList.push_back(tcp_locator);
+ pqos.wire_protocol().default_unicast_locator_list.push_back(tcp_locator);
+
+ /* Create participant as usual */
+ eprosima::fastdds::dds::DomainParticipant* participant =
+ eprosima::fastdds::dds::DomainParticipantFactory::get_instance()->create_participant(0, pqos);
+ //!
+ }
+}
+
 bool dds_permissions_test(
  std::string main_ca_file,
  std::string appcert_file,

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -3431,6 +3431,93 @@
 </profiles>
 -->
 <!--><-->
+
+<!-->PDP-MULTICAST-DATA-TCP<-->
+<!--
+<?xml version="1.0" encoding="UTF-8" ?>
+<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+ <profiles>
+-->
+ <transport_descriptors>
+ <!--
+ UDP transport for PDP
+ -->
+ <transport_descriptor>
+ <transport_id>pdp_transport</transport_id>
+ <type>UDPv4</type>
+ </transport_descriptor>
+ <!--
+ TCP transport for both EDP and application data
+ -->
+ <transport_descriptor>
+ <transport_id>data_transport</transport_id>
+ <type>TCPv4</type>
+ <!--
+ Set listening port for the transport.
+ This needs to be unique for each participant in the host
+ -->
+ <listening_ports>
+ <port>12345</port>
+ </listening_ports>
+ </transport_descriptor>
+ </transport_descriptors>
+
+ <participant profile_name="udp_multicast_pdp_w_tcp_data" is_default_profile="true">
+ <rtps>
+ <!--
+ Set participant transports
+ -->
+ <userTransports>
+ <transport_id>pdp_transport</transport_id>
+ <transport_id>data_transport</transport_id>
+ </userTransports>
+ <useBuiltinTransports>false</useBuiltinTransports>
+ <!--
+ Discovery configuration
+ -->
+ <builtin>
+ <!--
+ PDP over UDP multicast
+ -->
+ <metatrafficMulticastLocatorList>
+ <locator>
+ <udpv4>
+ <address>239.255.0.1</address>
+ </udpv4>
+ </locator>
+ </metatrafficMulticastLocatorList>
+ <!--
+ EDP over TCP
+ -->
+ <metatrafficUnicastLocatorList>
+ <locator>
+ <tcpv4>
+ <address>0.0.0.0</address>
+ <physical_port>12345</physical_port>
+ <port>12345</port>
+ </tcpv4>
+ </locator>
+ </metatrafficUnicastLocatorList>
+ </builtin>
+ <!--
+ Application data over TCP
+ -->
+ <defaultUnicastLocatorList>
+ <locator>
+ <tcpv4>
+ <address>0.0.0.0</address>
+ <physical_port>12345</physical_port>
+ <port>12345</port>
+ </tcpv4>
+ </locator>
+ </defaultUnicastLocatorList>
+ </rtps>
+ </participant>
+<!--
+ </profiles>
+</dds>
+-->
+<!--><-->
 </profiles>
 
 <!-->CONF-LIBRARY-SETTINGS<-->

diff --git a/docs/fastdds/discovery/simple.rst b/docs/fastdds/discovery/simple.rst
@@ -111,7 +111,7 @@ Simple EDP Attributes
 | :end-before: <!--><--> |
 +----------------------------------------------------------------------------------------------------------------------+
 
- .. _`Simple Initial Peers`:
+.. _`Simple Initial Peers`:
 
 Initial peers
 ^^^^^^^^^^^^^

diff --git a/docs/fastdds/troubleshooting/troubleshooting.rst b/docs/fastdds/troubleshooting/troubleshooting.rst
@@ -0,0 +1,10 @@
+.. _troubleshooting:
+
+Troubleshooting
+===============
+
+This section offers hints and pointers to help users with navigating through the documentation while troubleshooting
+issues.
+
+* Problems with transmitting **large samples such as video or point clouds**? Please refer to
+ :ref:`use-case-largeData`.
diff --git a/docs/fastdds/use_cases/large_data/large_data.rst b/docs/fastdds/use_cases/large_data/large_data.rst
@@ -7,11 +7,17 @@ Large Data Rates
 ================
 
 When the amount of data exchanged between a :ref:`dds_layer_publisher` and a :ref:`dds_layer_subscriber`
-is large, some tuning may be required to compensate for side effects on the network and CPU load.
+is large, some extra configuration may be required to compensate for side effects on the network and CPU load.
 This large amount of data can be a result of the data types being large, a high message rate, or
 a combination of both.
 
-In this scenario, several limitations have to be taken into account:
+In this scenario, several approaches can be considered depending on the problem:
+
+* For the cases in which the data samples are large (in the order of MB) such as transmitting raw video frames,
+ point clouds, images, etc. between different hosts, TCP based communications may yield better reception rates
+ with lower message loss, specially in the cases where a best effort transport layer is more susceptible to
+ data loss, such as WiFi.
+ To tackle these cases, :ref:`use-case-tcp` documents several ways to configure Fast DDS to communicate over TCP.
 
 * Network packages could be dropped because the transmitted amount of data fills the socket buffer
  before it can be processed.

diff --git a/docs/fastdds/use_cases/tcp/tcp_use_case.rst b/docs/fastdds/use_cases/tcp/tcp_use_case.rst
@@ -0,0 +1,27 @@
+.. include:: ../../../03-exports/aliases.include
+
+.. _use-case-tcp:
+
+Fast DDS over TCP
+=================
+
+As explained in :ref:`transport_tcp_tcp`, Fast DDS offers the possibility to communicate nodes within distributed
+applications with DDS over a TCP transport layer.
+This has the advantage of leveraging the builtin flow control and reliability of the TCP protocol, which in the
+context of DDS applications is best suited for the transmission of large payloads, i.e. large data samples, over
+lossy networks.
+Examples of such cases would be transmitting video or large point clouds resulting from laser scanning over WiFi
+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
+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.
+
+.. toctree::
+ :maxdepth: 2
+
+ /fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
diff --git a/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst b/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
@@ -0,0 +1,31 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+
+.. _use-case-tcp-multicast:
+
+TCP Communication with Multicast Discovery
+==========================================
+
+The following snippets show how to configure *Fast DDS* |DomainParticipants| to run the
+:ref:`PDP discovery<disc_phases>` phase over UDP multicast and communicate application data over a
+:ref:`transport_tcp_tcp` transport.
+With this approach, applications managing large samples can benefit from transmitting their data over TCP, while
+at the same time have the flexibility of automatic discovery.
+
+.. tabs::
+
+ .. tab:: C++
+
+ .. literalinclude:: ../../../../code/DDSCodeTester.cpp
+ :language: c++
+ :dedent: 8
+ :start-after: //PDP-MULTICAST-DATA-TCP
+ :end-before: //!
+
+ .. tab:: XML
+
+ .. literalinclude:: /../code/XMLTester.xml
+ :language: xml
+ :start-after: <!-->PDP-MULTICAST-DATA-TCP<-->
+ :end-before: <!--><-->
+ :lines: 2-4, 6-80, 82-83
diff --git a/docs/fastdds/use_cases/use_cases.rst b/docs/fastdds/use_cases/use_cases.rst
@@ -37,6 +37,8 @@ with distributed systems:
  or because the message rate.
  The examples describe how to:
 
+ - Use TCP based communications (see :ref:`use-case-tcp`).
+
  - Configure the socket buffer size (see :ref:`increase the buffers size<tuning-socket-buffer>`).
 
  - Limit the publication rate (see :ref:`flow-controllers`).
@@ -100,6 +102,7 @@ with distributed systems:
  /fastdds/use_cases/realtime/realtime.rst
  /fastdds/use_cases/reduce_memory/reduce_memory.rst
  /fastdds/use_cases/zero_copy/zero_copy.rst
+ /fastdds/use_cases/tcp/tcp_use_case.rst
  /fastdds/use_cases/unique_network_flows/unique_network_flows.rst
  /fastdds/use_cases/statistics_module/statistics_module.rst
  /fastdds/use_cases/dynamic_network_interfaces/dynamic_network_interfaces.rst

diff --git a/docs/index.rst b/docs/index.rst
@@ -52,6 +52,7 @@
  /fastdds/dynamic_types/dynamic_types
  /fastdds/use_cases/use_cases
  /fastdds/ros2/ros2
+ /fastdds/troubleshooting/troubleshooting
  /fastdds/api_reference/api_reference
  /fastdds/python_api_reference/python_api_reference