[23647] Add documentation for IP mobility

docs/fastdds/use_cases/dynamic_network_interfaces/dynamic_network_interfaces.rst

@@ -2,11 +2,17 @@
 .. include:: ../../../03-exports/aliases-api.include
 .. include:: ../../../03-exports/roles.include
 
+:orphan:
+
 .. _dynamic-network-interfaces:
 
 Dynamic network interfaces
 ==========================
 
+.. warning::
+
+   Starting in Fast DDS v3.4.0, this feature has been deprecated in favor of :ref:`IP mobility <ip-mobility>` |Pro|.
+
 DDS :ref:`Simple Discovery <simple_disc_settings>` relies on well-known multicast addresses and ports to relay the
 Participant announcement messages (see :ref:`disc_phases`).
 Such Participant announcement includes information about the unicast address-port pairs (a.k.a locators) where the

docs/fastdds/use_cases/ip_mobility/ip_mobility.rst

@@ -0,0 +1,50 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+.. include:: ../../../03-exports/roles.include
+
+.. _ip-mobility:
+
+IP mobility |Pro|
+=================
+
+DDS :ref:`Simple Discovery <simple_disc_settings>` relies on well-known multicast addresses and ports to relay
+the Participant announcement messages (see :ref:`disc_phases`).
+Such Participant announcement includes information about the unicast address-port pairs (a.k.a. locators) where
+the Participant is expecting to receive incoming metatraffic data.
+The list with these unicast locators is automatically initialized taking into account the network interfaces that
+are available when the *Fast DDS* DomainParticipant is enabled.
+
+Fast DDS Pro detects changes in the system's IP addresses, and automatically updates them through the discovery
+protocol, so other participants start sending data to the new addresses.
+
+.. important::
+
+   This feature is still under development and is only officially supported for UDPv4 Transport without whitelisting.
+
+   This feature is only available in Windows and Linux.
+   MacOS will be supported in future releases.
+
+Prerequisites
+-------------
+
+This feature is intended to be used when *Fast DDS* automatically sets the listening unicast locators.
+Consequently, all the locator lists in |DomainParticipantQos::wire_protocol-api| must be empty when the participant
+is created.
+If any of them is not empty, no updates will be transmitted to other participants, and communication with them will
+stop.
+
+These locator lists are:
+
+* |BuiltinAttributes::metatrafficUnicastLocatorList-api|
+* |BuiltinAttributes::metatrafficMulticastLocatorList-api|
+* |WireProtocolConfigQos::default_unicast_locator_list-api|
+* |WireProtocolConfigQos::default_multicast_locator_list-api|
+
+Please refer to :ref:`dds_layer_domainParticipantQos` for more information about these attributes.
+
+.. note::
+
+   Be aware of the remote locators' collections limits set within the |DomainParticipantQoS|
+   (please refer to :ref:`remotelocatorsallocationattributes`).
+   It is recommended to use the highest number of local addresses found on all the systems belonging to the same
+   domain.

docs/fastdds/use_cases/tsn/tsn.rst

@@ -40,7 +40,7 @@ The specification defines:
 Fast DDS TSN Implementation
 ---------------------------
 
-*Fast DDS* |Pro| provides the required scaffolding for using DDS over TSN compliant with the OMG specification.
+*Fast DDS Pro* provides the required scaffolding for using DDS over TSN compliant with the OMG specification.
 
 TSN flow configuration can be set via a mapping between a defined
 :ref:`TransportPriorityQosPolicy <transportpriorityqospolicy>` value and a set of tuple parameters.
@@ -55,12 +55,12 @@ sends.
 Supported transports
 ^^^^^^^^^^^^^^^^^^^^
 
-*Fast DDS* |Pro| currently supports two transports that can be used over TSN-capable networks:
+*Fast DDS Pro* currently supports two transports that can be used over TSN-capable networks:
 
 - **UDP Transport Support (UDPv4 / UDPv6)**
 
   *Fast DDS* supports DDSI-RTPS communication over standard POSIX `UDPv4` and `UDPv6` sockets.
-  *Fast DDS* |Pro| extends these transports to enable seamless operation on TSN-capable networks
+  *Fast DDS Pro* extends these transports to enable seamless operation on TSN-capable networks
   while preserving compatibility with existing DDS deployments.
 
   In this transport, the tuple parameters (`IPv4Tuple` / `IPv6Tuple`) are:
@@ -108,7 +108,7 @@ Supported transports
 
 - **Ethernet Transport Support**
 
-  *Fast DDS* |Pro| includes a custom `Ethernet` transport that operates directly at Layer 2 (data link layer),
+  *Fast DDS Pro* includes a custom `Ethernet` transport that operates directly at Layer 2 (data link layer),
   bypassing the TCP/IP stack for reduced latency and direct control over ethernet frames.
 
   *Fast DDS* extends the standard `Locator` class with a new kind for ethernet communication,
@@ -150,7 +150,7 @@ Supported transports
 
   .. note::
 
-    The *Fast DDS* |Pro| installation provides a helper file ``rtps_eth.lua`` under the ``share/fastdds``
+    The *Fast DDS Pro* installation provides a helper file ``rtps_eth.lua`` under the ``share/fastdds``
     subfolder.
     This script allows to easily dissect packets from this transport in Wireshark.
     For details on installing custom plugins, see the

docs/fastdds/use_cases/use_cases.rst

@@ -10,13 +10,17 @@ Use-Cases
 This section provides configuration examples for the following typical use cases when dealing
 with distributed systems:
 
-+ :ref:`use-case-dds-tsn` |Pro|.
++ :ref:`DDS-TSN <use-case-dds-tsn>` |Pro|.
   Describes how to configure *Fast DDS* to use DDS over Time-Sensitive Networking (TSN).
   This configuration leverages IEEE 802.1 standards to provide deterministic, real-time data delivery
   over Ethernet.
   It ensures predictable latency and high reliability for critical applications by mapping DDS QoS policies
   to TSN capabilities and supporting both UDP/IP and raw Ethernet transports.
 
++ :ref:`IP mobility <ip-mobility>` |Pro|.
+  If the network interfaces are expected to change while the application is running, *Fast DDS Pro* provides an
+  automatic way of re-scanning the available interfaces and including them.
+
 + :ref:`use-case-tcp`.
   Describes how to configure *Fast DDS* to use the ``LARGE_DATA`` builtin transports mode.
   This mode enables efficient utilization of TCP transport without the need for constant reconfiguration
@@ -83,10 +87,6 @@ with distributed systems:
   This use case illustrates the APIs that allow for the request of unique network flows, and for the identification
   of those in use.
 
-+ :ref:`dynamic-network-interfaces`.
-  If the network interfaces are expected to change while the application is running, *Fast DDS* provides an easy way
-  of re-scanning the available interfaces and including them.
-
 + :ref:`statistics_module`.
   This use case explains how to enable the Statistics module within the monitored application, and how to create a
   statistics monitoring application.
@@ -125,7 +125,7 @@ with distributed systems:
     /fastdds/use_cases/zero_copy/zero_copy.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
+    /fastdds/use_cases/ip_mobility/ip_mobility.rst
     /fastdds/use_cases/dds_record_and_replay/dds_record_and_replay.rst
     /fastdds/use_cases/request_reply/request_reply.rst
     /fastdds/use_cases/remote_type_discovery_matching/remote_type_discovery_matching.rst