Skip to content

Commit 5e9e5db

Browse files
Enhance Fast DDS docs with a FAQs section covering every subsection (#902)
* Add FAQs section (#883) * Refs #21416: Add FAQs section Signed-off-by: Denisa <denisa@eprosima.com> * FAQ section Signed-off-by: Denisa <denisa@eprosima.com> * Refs #21416: Frequently Asked Questions-add review comments Signed-off-by: Denisa <denisa@eprosima.com> --------- Signed-off-by: Denisa <denisa@eprosima.com> Co-authored-by: Denisa <denisa@eprosima.com> * [21416] Add FAQs section (#883) (#891) * Refs #21416: Add FAQs section Signed-off-by: Denisa <denisa@eprosima.com> * FAQ section Signed-off-by: Denisa <denisa@eprosima.com> * Refs #21416: Frequently Asked Questions-add review comments Signed-off-by: Denisa <denisa@eprosima.com> --------- Signed-off-by: Denisa <denisa@eprosima.com> Co-authored-by: Denisa <denisa@eprosima.com> * Refs #21416: Fix README.md Signed-off-by: Carlosespicur <carlosespicur@proton.me> * Add review changes Signed-off-by: Denisa <denisa@eprosima.com> * Change format to adapt to standard documentation Signed-off-by: Denisa <denisa@eprosima.com> --------- Signed-off-by: Denisa <denisa@eprosima.com> Signed-off-by: Carlosespicur <carlosespicur@proton.me> Co-authored-by: Carlosespicur <carlosespicur@proton.me>
1 parent 6e60196 commit 5e9e5db

File tree

21 files changed

+1784
-5
lines changed

21 files changed

+1784
-5
lines changed

docs/02-formalia/titlepage.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,3 +212,6 @@ This documentation is organized into the sections below.
212212
* :ref:`Fast DDS <getting_started>`
213213
* :ref:`Fast DDS-Gen <fastddsgen_intro>`
214214
* :ref:`Release Notes <release_notes>`
215+
216+
The documentation includes a :ref:`Frequently Asked Questions (FAQ) <frequently_asked_questions>` section that can be
217+
consulted for a quick overview.

docs/03-exports/aliases-api.include

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -885,6 +885,7 @@
885885
.. |EntityId_t-api| replace:: :cpp:struct:`EntityId_t<eprosima::fastdds::rtps::EntityId_t>`
886886
.. |InitialAnnouncementConfig-api| replace:: :cpp:struct:`InitialAnnouncementConfig<eprosima::fastdds::rtps::InitialAnnouncementConfig>`
887887
.. |InitialAnnouncementConfig::period-api| replace:: :cpp:member:`period<eprosima::fastdds::rtps::InitialAnnouncementConfig::period>`
888+
.. |InitialAnnouncementConfig::count-api| replace:: :cpp:member:`count<eprosima::fastdds::rtps::InitialAnnouncementConfig::count>`
888889
.. |BuiltinAttributes-api| replace:: :cpp:class:`BuiltinAttributes<eprosima::fastdds::rtps::BuiltinAttributes>`
889890
.. |BuiltinAttributes::discovery_config-api| replace:: :cpp:member:`discovery_config<eprosima::fastdds::rtps::BuiltinAttributes::discovery_config>`
890891
.. |BuiltinAttributes::metatrafficUnicastLocatorList-api| replace:: :cpp:member:`metatrafficUnicastLocatorList<eprosima::fastdds::rtps::BuiltinAttributes::metatrafficUnicastLocatorList>`

docs/conf.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,7 @@ def download_css(html_css_dir):
4747
False if not.
4848
"""
4949
url = (
50-
'https://raw.githubusercontent.com/eProsima/all-docs/'
51-
'master/source/_static/css/fiware_readthedocs.css')
50+
'https://raw.githubusercontent.com/eProsima/all-docs/master/source/_static/css/fiware_readthedocs.css')
5251
try:
5352
req = requests.get(url, allow_redirects=True, timeout=10)
5453
except requests.RequestException as e:
@@ -343,7 +342,8 @@ def configure_doxyfile(
343342
'breathe',
344343
'sphinxcontrib.plantuml',
345344
'sphinx.ext.autodoc', # Document Pydoc documentation from Python bindings.
346-
'sphinx_tabs.tabs'
345+
'sphinx_tabs.tabs',
346+
'sphinx_toolbox.collapse'
347347
]
348348

349349
sphinx_tabs_disable_css_loading = False
@@ -471,6 +471,7 @@ def configure_doxyfile(
471471
# Avoid the warning of a wrong reference in the TOC entries,
472472
# because fails the Python API Reference reference.
473473
suppress_warnings.append('toc.excluded')
474+
suppress_warnings.append('config.cache')
474475

475476
# If true, `todo` and `todoList` produce output, else they produce nothing.
476477
todo_include_todos = False
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. rst-class:: api-ref
22

33
ParticipantDiscoveryStatus
4-
----------------------------
4+
--------------------------
55

66
.. doxygenenum:: eprosima::fastdds::rtps::ParticipantDiscoveryStatus
77
:project: FastDDS

docs/fastdds/faq/dds_layer/dds_layer.rst

Lines changed: 564 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. include:: ../../../03-exports/aliases.include
2+
.. include:: ../../../03-exports/aliases-api.include
3+
.. include:: ../../../03-exports/roles.include
4+
5+
.. _freq_discovery_questions:
6+
7+
Discovery Frequently Asked Questions
8+
====================================
9+
10+
.. collapse:: What are the two main phases involved in the discovery process of Fast DDS?
11+
12+
|br| The two main phases involved in the discovery process of Fast DDS are the Participant Discovery Phase (PDP) and the Endpoint Discovery Phase (EDP).
13+
The Participant Discovery Phase (PDP) involves |DomainParticipants-api| recognizing each other by sending periodic announcement messages with their unicast addresses.
14+
Matching occurs when they are in the same DDS Domain, using multicast by default, though unicast and announcement frequency can be customized.
15+
In the Endpoint Discovery Phase (EDP), DataWriters and DataReaders acknowledge each other by sharing information about topics and data types over the established channels.
16+
Matching endpoints with the same topic and data type are then ready to exchange user data.
17+
For further information, refer to :ref:`disc_phases`.
18+
19+
----------
20+
21+
.. collapse:: What discovery mechanisms does FastDDS provide?
22+
23+
|br| There are four discovery mechanisms in DDS: Simple Discovery, which follows the RTPS standard for both PDP and EDP, ensuring compatibility with other DDS implementations; Static Discovery, which uses the Simple Participant Discovery Protocol (SPDP) but skips the Endpoint Discovery phase if endpoint details are pre-known; Discovery Server, which employs a centralized server for meta traffic discovery; and Manual Discovery, which disables the PDP and requires users to manually match RTPS participants and endpoints using external meta-information channels.
24+
For further information, refer to :ref:`disc_mechanisms`.
25+
26+
----------
27+
28+
.. collapse:: How can you improve the chances of successful participant discovery when using the SIMPLE discovery protocol, and what role do initial announcements play in this process?
29+
30+
|br| To improve the chances of successful participant discovery when using the SIMPLE discovery protocol, you can configure initial announcements to send multiple discovery messages at short intervals.
31+
This increases the likelihood that DomainParticipants will detect each other despite potential network disruptions or message loss.
32+
By adjusting the |InitialAnnouncementConfig::count-api| (number of announcements) and |InitialAnnouncementConfig::period-api| (interval between announcements), you can optimize discovery reliability during startup.
33+
For further information, refer to :ref:`simple_disc_settings`.
34+
35+
----------
36+
37+
.. collapse:: What is an initial peer list?
38+
39+
|br| An initial peer list contains one or more IP-port address pairs corresponding to remote DomainParticipants PDP discovery listening resources, so that the local DomainParticipant will not only send its PDP traffic to the default multicast address-port specified by its domain, but also to all the IP-port address pairs specified in the initial peers list.
40+
For further information, refer to :ref:`simple_disc_settings`.
41+
42+
----------
43+
44+
.. collapse:: When could a static configuration of peers be used?
45+
46+
|br| When all DataWriters and DataReaders, and their Topics and data types, are known beforehand, the EDP phase can be replaced with a static configuration of peers.
47+
For further information, refer to :ref:`discovery_static`.
48+
49+
----------
50+
51+
.. collapse:: What is the primary difference between the Discovery Server mechanism and Simple discovery mechanism in terms of managing metatraffic?
52+
53+
|br| The Discovery Server mechanism is based on a client-server discovery paradigm, the metatraffic is managed by one or several server DomainParticipants, as opposed to simple discovery, where metatraffic is exchanged using a message broadcast mechanism like an IP multicast protocol.
54+
For further information, refer to :ref:`discovery_server`.
55+
56+
----------
57+
58+
.. collapse:: What is the primary function of a Discovery Server in the DDS architecture?
59+
60+
|br| The primary function of a Discovery Server in the DDS architecture is to centralize and redistribute discovery information among DomainParticipants, ensuring efficient communication between clients and servers.
61+
The server collects discovery data from clients (and other servers) and redistributes it to relevant participants, running a "matching" algorithm to provide only the necessary information for DataWriters and DataReaders to establish communication.
62+
It also facilitates server-to-server connections, enabling a more scalable discovery process across the network.
63+
For further information, refer to :ref:`discovery_server`.
64+
65+
----------
66+
67+
.. collapse:: What is the primary purpose of a "BACKUP" server in the Discovery Server mechanism?
68+
69+
|br| A ``BACKUP`` server is a server that persists its discovery database into a file.
70+
This type of server can load the network graph from a file on start-up without the need of receiving any client's information.
71+
For further information, refer to :ref:`discovery_server`.
72+
73+
----------
74+
75+
.. collapse:: What is a client in this context?
76+
77+
|br| A ``CLIENT`` is a participant that connects to one or more servers from which it receives only the discovery information they require to establish communication with matching endpoints.
78+
For further information, refer to :ref:`discovery_server`.
79+
80+
----------
81+
82+
.. collapse:: What is the difference between a CLIENT and a SUPER_CLIENT?
83+
84+
|br| A ``SUPER_CLIENT`` is a client that receives the discovery information known by the server, in opposition to clients, which only receive the information they need.
85+
For further information, refer to :ref:`discovery_server`.
86+
87+
----------
88+
89+
.. collapse:: What is the purpose of each server specifying its own locator list in the context of discovery configuration?
90+
91+
|br| Each client must keep a list of locators associated to the servers to which it wants to link.
92+
Each server specifies its own locator list which must be populated with ``RemoteServerAttributes`` objects with a valid ``metatrafficUnicastLocatorList`` or ``metatrafficMulticastLocatorList``.
93+
In XML the server list and its elements are simultaneously specified.
94+
For further information, refer to :ref:`discovery_server`.
95+
96+
----------
97+
98+
.. collapse:: What is the typical interval of time between discovery messages sent by clients to servers, as described in the text?
99+
100+
|br| As explained above the clients send discovery messages to the servers at regular intervals (ping period) until they receive message reception acknowledgement.
101+
The default value for this period is 450 ms.
102+
For further information, refer to :ref:`discovery_server`.
103+
104+
|
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. include:: ../../../03-exports/aliases.include
2+
.. include:: ../../../03-exports/aliases-api.include
3+
.. include:: ../../../03-exports/roles.include
4+
5+
.. _freq_env_variables_questions:
6+
7+
Environment Variables Frequently Asked Questions
8+
================================================
9+
10+
.. collapse:: What are the most important environment variables that affect the behavior of Fast DDS?
11+
12+
|br| ``FASTDDS_DEFAULT_PROFILES_FILE``, ``SKIP_DEFAULT_XML``, ``FASTDDS_BUILTIN_TRANSPORTS``, ``ROS_DISCOVERY_SERVER``, ``ROS_SUPER_CLIENT``, ``FASTDDS_STATISTICS``, ``FASTDDS_ENVIRONMENT_FILE``.
13+
For further information, refer to :ref:`env_vars`.
14+
15+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
16+
17+
.. collapse:: What is the purpose of the "FASTDDS_DEFAULT_PROFILES_FILE" environment variable?
18+
19+
|br| Defines the location of the default profile configuration XML file.
20+
For further information, refer to :ref:`env_vars_fastdds_default_profiles_file`.
21+
22+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
23+
24+
.. collapse:: What happens when the variable "SKIP_DEFAULT_XML" is set to 1?
25+
26+
|br| Skips looking for a default profile configuration XML file.
27+
If this variable is set to 1, Fast DDS will load the configuration parameters directly from the classes' definitions without looking for the ``DEFAULT_FASTDDS_PROFILES.xml`` in the working directory.
28+
For further information, refer to :ref:`env_vars_skip_default_xml`.
29+
30+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
31+
32+
.. collapse:: What is the primary purpose of the "FASTDDS_BUILTIN_TRANSPORTS" environment variable?
33+
34+
|br| Setting this variable allows to modify the builtin transports that are initialized during the |DomainParticipant-api| creation.
35+
For further information, refer to :ref:`env_vars_builtin_transports`.
36+
37+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
38+
39+
.. collapse:: What is the purpose of the "ROS_DISCOVERY_SERVER" environment variable?
40+
41+
|br| Setting this variable configures the DomainParticipant to connect to one or more servers using the Discovery Server discovery mechanism.
42+
For further information, refer to :ref:`env_vars_ros_discovery_server`.
43+
44+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
45+
46+
.. collapse:: What happens to a "DomainParticipant" when its discovery protocol is set to "SIMPLE" and "ROS_SUPER_CLIENT" is set to TRUE?
47+
48+
|br| If the DomainParticipant's discovery protocol is set to ``SIMPLE``, and ``ROS_SUPER_CLIENT`` is set to ``TRUE``, the participant is automatically promoted to a ``SUPER_CLIENT``.
49+
For further information, refer to :ref:`env_vars_ros_super_client`.
50+
51+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
52+
53+
.. collapse:: What is the purpose of setting the "FASTDDS_STATISTICS" environment variable, according to the provided information?
54+
55+
|br| Setting this variable configures the |DomainParticipant-api| to enable the statistics DataWriters which topics are contained in the list set in this environment variable.
56+
For further information, refer to :ref:`env_vars_fastdds_statistics`.
57+
58+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
59+
60+
.. collapse:: What happens when you set the "FASTDDS_ENVIRONMENT_FILE" environment variable to a JSON file?
61+
62+
|br| Setting this environment variable to an existing ``json`` file allows to load the environment variables from the file instead of from the environment.
63+
For further information, refer to :ref:`env_vars_fastdds_environment_file`.
64+
65+
|

docs/fastdds/faq/faq.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. _frequently_asked_questions:
2+
3+
Frequently Asked Questions
4+
==========================
5+
6+
This section answers to frequently asked questions about FastDDS.
7+
8+
9+
.. toctree::
10+
:caption: Frequently Asked Questions
11+
:maxdepth: 2
12+
13+
getting_started/getting_started
14+
dds_layer/dds_layer
15+
rtps_layer/rtps_layer
16+
discovery/discovery
17+
transport_layer/transport_layer
18+
persistence_service/persistence_service
19+
security/security
20+
logging/logging
21+
xml_profiles/xml_profiles
22+
environment_variables/environment_variables
23+
statistics_module/statistics_module
24+
xtypes/xtypes
25+
26+

0 commit comments

Comments
 (0)