From 24495726adef23b64c531f932b2f027cab18e0dc Mon Sep 17 00:00:00 2001 From: jparisu <69341543+jparisu@users.noreply.github.com> Date: Wed, 18 Nov 2020 22:59:33 +0100 Subject: [PATCH] ROS 2 section [9292] (#194) * Refs #9273: added ROS2 section Signed-off-by: jparisu * Refs #9273: Some changes from revisions Signed-off-by: jparisu * Refs #9273: Applying changes firsts steps Signed-off-by: jparisu * Refs #9273: Minor changes Signed-off-by: imontesino * Refs #9273: added help to tool Signed-off-by: imontesino * Refs #9273: Changed Server-Client to Discovery Service Signed-off-by: imontesino * Refs #9273: Fix misspelling Signed-off-by: imontesino * Refs #9273: apply all changes Signed-off-by: jparisu * Refs #9237: first changes apply Signed-off-by: jparisu * Refs #9273: apply changes from review Signed-off-by: jparisu * Refs #9237: fixing XML Signed-off-by: jparisu Co-authored-by: imontesino --- code/XMLTester.xml | 48 +- .../fast_dds/discovery/discovery-server.svg | 4 +- .../fast_dds/discovery/discovery_packets.svg | 369 +++++++++++++++ .../discovery_server_v2_performance.svg | 1 + docs/01-figures/fast_dds/discovery/ds1vs2.svg | 3 + .../fast_dds/discovery/ds_backup_example.svg | 227 +++++++++ .../fast_dds/discovery/ds_explanation.svg | 434 ++++++++++++++++++ .../discovery/ds_partition_example.svg | 3 + .../discovery/ds_redundancy_example.svg | 252 ++++++++++ docs/02-formalia/titlepage.rst | 2 +- ...server_client.rst => discovery_server.rst} | 30 +- .../discovery/general_disc_settings.rst | 6 +- .../discovery/includes/disc_mechanisms.rst | 2 +- .../discovery/includes/disc_settings.rst | 2 +- docs/fastdds/env_vars/env_vars.rst | 10 +- .../includes/functionalities.rst | 2 +- .../discovery_server/discovery_packets.py | 75 +++ .../generate_discovery_packages.bash | 120 +++++ .../ros2_discovery_server.rst | 361 +++++++++++++++ docs/fastdds/ros2/ros2.rst | 47 ++ .../ros2/ros2.rst => ros2/ros2_configure.rst} | 100 ++-- docs/fastdds/use_cases/use_cases.rst | 13 +- ...very.rst => discovery_server_use_case.rst} | 10 +- docs/fastdds/use_cases/wifi/wifi.rst | 4 +- docs/fastddscli/cli/cli.rst | 6 +- docs/index.rst | 1 + docs/notes/previous_versions/v1.2.0.rst | 2 +- 27 files changed, 2004 insertions(+), 130 deletions(-) create mode 100644 docs/01-figures/fast_dds/discovery/discovery_packets.svg create mode 100644 docs/01-figures/fast_dds/discovery/discovery_server_v2_performance.svg create mode 100644 docs/01-figures/fast_dds/discovery/ds1vs2.svg create mode 100644 docs/01-figures/fast_dds/discovery/ds_backup_example.svg create mode 100644 docs/01-figures/fast_dds/discovery/ds_explanation.svg create mode 100644 docs/01-figures/fast_dds/discovery/ds_partition_example.svg create mode 100644 docs/01-figures/fast_dds/discovery/ds_redundancy_example.svg rename docs/fastdds/discovery/{server_client.rst => discovery_server.rst} (97%) create mode 100644 docs/fastdds/ros2/discovery_server/discovery_packets.py create mode 100644 docs/fastdds/ros2/discovery_server/generate_discovery_packages.bash create mode 100644 docs/fastdds/ros2/discovery_server/ros2_discovery_server.rst create mode 100644 docs/fastdds/ros2/ros2.rst rename docs/fastdds/{use_cases/ros2/ros2.rst => ros2/ros2_configure.rst} (56%) rename docs/fastdds/use_cases/wifi/{server_discovery.rst => discovery_server_use_case.rst} (98%) diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 6c0321ec8..0e87dfa04 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -312,7 +312,7 @@ - + TopicName @@ -326,14 +326,14 @@ - + TopicName TopicDataTypeName - + TopicName @@ -347,7 +347,7 @@ - + TopicName @@ -361,7 +361,7 @@ - + TopicName @@ -375,7 +375,7 @@ - + TopicName @@ -389,7 +389,7 @@ - + TopicName @@ -1861,14 +1861,14 @@ 3 0 - + 3 3 0 - + 1 @@ -1958,7 +1958,7 @@ - + @@ -1967,7 +1967,7 @@ 0 - + @@ -1976,7 +1976,7 @@ 0 - + @@ -2159,7 +2159,7 @@ - + 75.63.2D.73.76.72.63.6C.6E.74.2D.32 @@ -2318,7 +2318,7 @@ - + HelloWorldTopic @@ -2344,7 +2344,7 @@ - + HelloWorldTopic @@ -2355,15 +2355,17 @@ <--> -CONF_ROS2_DEFAULT_PROFILE<--> - - - profile_for_ros2_node - - -<--> - CONF_ROS2_EXAMPLE<--> + + + + profile_for_ros2_node + + + diff --git a/docs/01-figures/fast_dds/discovery/discovery-server.svg b/docs/01-figures/fast_dds/discovery/discovery-server.svg index f539bf0f3..4e693d986 100644 --- a/docs/01-figures/fast_dds/discovery/discovery-server.svg +++ b/docs/01-figures/fast_dds/discovery/discovery-server.svg @@ -1,7 +1,7 @@ Simple DiscoveryServer-client Discoveryparticipant 1participant 2participant 3participant 4Discovery Serverparticipant 1participant 2participant 3participant 4Server(s)client 1client 2client 3client 4CONF_ROS2_DEFAULT_PROFILE | +| :start-after: CONF_ROS2_EXAMPLE | | :end-before: <--> | +| :lines: 2-3,5-9 | +| :append: | +---------------------------------------------------------+ Configure Publication Mode and History Memory Policy -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------------- By default, ``rmw_fastrtps`` sets some of the *Fast DDS* configurable parameters, ignoring whatever configuration is provided in the XML file. @@ -116,9 +88,9 @@ Said parameters, and their default values under ROS 2, are: However, it is possible to fully configure *Fast DDS* (including the history memory policy and the publication mode) -using an XML file in combination with environment variable ``RMW_FASTRTPS_USE_QOS_FROM_XML``. +using an XML file in combination with an environment variable ``RMW_FASTRTPS_USE_QOS_FROM_XML``. -:: +.. code-block:: bash export FASTRTPS_DEFAULT_PROFILES_FILE= export RMW_FASTRTPS_USE_QOS_FROM_XML=1 @@ -129,8 +101,8 @@ using an XML file in combination with environment variable ``RMW_FASTRTPS_USE_QO Example ------- -The following example uses the ROS 2 talker/listener demo, configuring *Fast DDS* to publish synchronously, -and to have a dynamically allocated publisher and subscriber histories. +The following example uses the ROS 2 talker/listener demo, configuring *Fast DDS* to publish synchronously, and to have +dynamically allocated publisher and subscriber histories. #. Create a XML file `ros_example.xml` and save it in `path/to/xml/` @@ -141,11 +113,13 @@ and to have a dynamically allocated publisher and subscriber histories. | :language: xml | | :start-after: CONF_ROS2_EXAMPLE | | :end-before: <--> | + | :lines: 2-3,5- | + | :append: | +---------------------------------------------------------+ #. Open one terminal and run: - :: + .. code-block:: bash export RMW_IMPLEMENTATION=rmw_fastrtps_cpp export FASTRTPS_DEFAULT_PROFILES_FILE=path/to/xml/ros_example.xml @@ -154,7 +128,7 @@ and to have a dynamically allocated publisher and subscriber histories. #. Open one terminal and run: - :: + .. code-block:: bash export RMW_IMPLEMENTATION=rmw_fastrtps_cpp export FASTRTPS_DEFAULT_PROFILES_FILE=path/to/xml/ros_example.xml diff --git a/docs/fastdds/use_cases/use_cases.rst b/docs/fastdds/use_cases/use_cases.rst index e11a49cce..16bebe629 100644 --- a/docs/fastdds/use_cases/use_cases.rst +++ b/docs/fastdds/use_cases/use_cases.rst @@ -19,7 +19,7 @@ with distributed systems: - Disable the multicast discovery mechanism (see :ref:`use-case-disabling-multicast-discovery`). - - Configure a SERVER discovery mechanism (see :ref:`server-client-discovery-use-case`). + - Configure a SERVER discovery mechanism (see :ref:`discovery-server-use-case`). + :ref:`well_known_deployments`. Describes a situation where the entire entity network topology (Participants, Publishers, Subscribers, @@ -55,15 +55,15 @@ with distributed systems: - Limit the blocking time of API functions to have a predictable response time (see :ref:`non-blocking-calls`). -+ :ref:`fastrtps_ros2`. - Since *Fast DDS* is the default middleware implementation in the `OSRF`_ `Robot Operation System 2 (ROS 2)`_, - this tutorial is an explanation of how to take full advantage of *Fast DDS* wide set of capabilities in a ROS 2 - project. - + :ref:`use-case-reduce-memory`. For use cases with memory consumption constraints, *Fast DDS* can be configured to reduce memory footprint to a minimum by adjusting different QoS policies. ++ :ref:`ros2`. + Since *Fast DDS* is the default middleware implementation in the `OSRF`_ `Robot Operation System 2 (ROS 2)`_, + this documentation includes a whole independent section to show the use of the library in ROS 2, + and how to take full advantage of *Fast DDS* wide set of capabilities in a ROS 2 project. + .. toctree:: :maxdepth: 2 @@ -72,5 +72,4 @@ with distributed systems: /fastdds/use_cases/large_data/large_data.rst /fastdds/use_cases/many_subscribers/many_subscribers.rst /fastdds/use_cases/realtime/realtime.rst - /fastdds/use_cases/ros2/ros2.rst /fastdds/use_cases/reduce_memory/reduce_memory.rst diff --git a/docs/fastdds/use_cases/wifi/server_discovery.rst b/docs/fastdds/use_cases/wifi/discovery_server_use_case.rst similarity index 98% rename from docs/fastdds/use_cases/wifi/server_discovery.rst rename to docs/fastdds/use_cases/wifi/discovery_server_use_case.rst index 16bc5da59..3bf8c5529 100644 --- a/docs/fastdds/use_cases/wifi/server_discovery.rst +++ b/docs/fastdds/use_cases/wifi/discovery_server_use_case.rst @@ -1,7 +1,7 @@ -.. _server-client-discovery-use-case: +.. _discovery-server-use-case: -Server-Client Discovery -======================= +Discovery Server +================= During :ref:`discovery`, the Participant Discovery Phase (PDP) relies on meta traffic announcements sent to multicast addresses so that all the :ref:`DomainParticipants` @@ -30,7 +30,7 @@ The following subsections present configurations for different discovery server UDPv4 basic example setup ------------------------- -To configure the client-server discovery scenario, two types of participants are created: the server participant and +To configure the Discovery Server scenario, two types of participants are created: the server participant and the client participant. Two parameters to be configured in this type of implementation are outlined: @@ -194,7 +194,7 @@ Likewise, several servers can share the same port if their IP addresses are diff UDPv4 persistency example ------------------------- -On server-client discovery, servers gather and maintain the information of all connected endpoints, +On Discovery Server, servers gather and maintain the information of all connected endpoints, and distribute it to the clients. In case of a server failure, all this information is lost and the server needs to recover it on restart. In the :ref:`basic setup` this is done diff --git a/docs/fastdds/use_cases/wifi/wifi.rst b/docs/fastdds/use_cases/wifi/wifi.rst index 22535040f..7c595140e 100644 --- a/docs/fastdds/use_cases/wifi/wifi.rst +++ b/docs/fastdds/use_cases/wifi/wifi.rst @@ -18,7 +18,7 @@ This way, the use of multicast is not needed to discover these initial peers. Furthermore, if all the peers are known and configured beforehand, all multicast communication can be removed. -Alternatively, SERVER-CLIENT discovery can be used to avoid multicast discovery. +Alternatively, **Discovery Server** can be used to avoid multicast discovery. A DomainParticipant with a well-know address acts as a discovery server, providing the rest of the participants the information required to connect among them. If all the peers are known and configured beforehand, STATIC discovery can be used instead, @@ -31,5 +31,5 @@ STATIC discovery. /fastdds/use_cases/wifi/initial_peers.rst /fastdds/use_cases/wifi/disable_multicast.rst - /fastdds/use_cases/wifi/server_discovery.rst + /fastdds/use_cases/wifi/discovery_server_use_case.rst diff --git a/docs/fastddscli/cli/cli.rst b/docs/fastddscli/cli/cli.rst index 0d49afdf2..76d2fadeb 100644 --- a/docs/fastddscli/cli/cli.rst +++ b/docs/fastddscli/cli/cli.rst @@ -30,7 +30,7 @@ There are two verbs whose functionality is described in the following table: +--------------------------+-------------------------------------------------------------------------------------------+ | Verbs | Description | +==========================+===========================================================================================+ -| ``discovery`` | Launches a server for :ref:`Server-Client Discovery`. | +| ``discovery`` | Launches a server for :ref:`Discovery Server `. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``shm`` | Allows manual cleaning of garbage files that may be generated by | | | :ref:`transport_sharedMemory_sharedMemory` | @@ -41,7 +41,7 @@ There are two verbs whose functionality is described in the following table: discovery --------- -Launches a server for :ref:`Server-Client Discovery`. This server will manage the messages of the +Launches a server for :ref:`Discovery Server `. This server will manage the messages of the clients which are pointed to its IP address. Clients must be aware of how to reach the server by specifying an IP address and a transport protocol like UDP or TCP. @@ -73,7 +73,7 @@ Where the parameters are: Examples ^^^^^^^^ -1. Launch a default server with id 0 (first on ``ROS_DISCOVERY_SERVER``) +1. Launch a **default server** with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening on all available interfaces on UDP port '11811'. Only one server can use default values per machine. diff --git a/docs/index.rst b/docs/index.rst index 9dc091c20..0ac5fca71 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,6 +48,7 @@ /fastdds/env_vars/env_vars /fastdds/dynamic_types/dynamic_types /fastdds/use_cases/use_cases + /fastdds/ros2/ros2 /fastdds/api_reference/api_reference .. _index_gen: diff --git a/docs/notes/previous_versions/v1.2.0.rst b/docs/notes/previous_versions/v1.2.0.rst index fba2de37d..28dd74557 100644 --- a/docs/notes/previous_versions/v1.2.0.rst +++ b/docs/notes/previous_versions/v1.2.0.rst @@ -12,7 +12,7 @@ This release introduced two important new features: But there is more: -* Full ROS2 Support: Fast RTPS is used by ROS2, the upcoming release of the Robot Operating System (ROS). +* Full ROS 2 Support: Fast RTPS is used by ROS 2, the upcoming release of the Robot Operating System (ROS). * Better documentation: More content and examples. * Improved performance. * Bug fixing.