From 973b2e67bea81015da0f3d6e527948b68790e9fe Mon Sep 17 00:00:00 2001 From: Juan Lopez Fernandez Date: Thu, 5 Sep 2024 07:24:16 +0200 Subject: [PATCH] Update documentation and examples: guid-less discovery server Signed-off-by: Juan Lopez Fernandez --- .../examples/ros_discovery_client.yaml | 21 ++++-------- docs/resources/examples/wan_ds_client.yaml | 32 +++++++------------ docs/resources/examples/wan_ds_server.yaml | 21 +++++------- docs/rst/user_manual/configuration.rst | 24 +++++--------- .../participants/local_discovery_server.rst | 7 ++-- .../participants/wan_discovery_server.rst | 10 +++--- .../examples/ros_discovery_client.yaml | 21 ++++-------- .../examples/wan_ds_client.yaml | 16 +++------- .../examples/wan_ds_server.yaml | 25 ++++++--------- .../test/application/CMakeLists.txt | 2 +- ...ion_v3.yaml => complex_configuration.yaml} | 9 +----- .../configurations/ds_configuration.yaml | 8 +---- tools/ddsrouter_tool/test/labels/XTSAN.list | 4 +-- 13 files changed, 67 insertions(+), 133 deletions(-) rename tools/ddsrouter_tool/test/application/configurations/{complex_configuration_v3.yaml => complex_configuration.yaml} (92%) diff --git a/docs/resources/examples/ros_discovery_client.yaml b/docs/resources/examples/ros_discovery_client.yaml index c87679851..21cd5c2ff 100644 --- a/docs/resources/examples/ros_discovery_client.yaml +++ b/docs/resources/examples/ros_discovery_client.yaml @@ -36,13 +36,10 @@ participants: ros-discovery-server: true # 7 id: 2 # 8 connection-addresses: # 9 - - discovery-server-guid: - ros-discovery-server: true # 10 - id: 1 # 11 - addresses: - - domain: localhost # 12 - port: 11888 # 13 - # 14 + - addresses: + - domain: localhost # 10 + port: 11888 # 11 + # 12 ################################## # CONFIGURATION DESCRIPTION @@ -77,15 +74,11 @@ participants: # 9: Add the addresses where this Client will try to reach a Discovery Server. -# 10: Connecting to a Discovery Server with ROS 2 GuidPrefix <44.53. .5f.45.50.52.4f.53.49.4d.41>. +# 10: Connect to a Discovery Server in IP localhost listening. This domain will be translated as ip: "127.0.0.1" -# 11: Set the Remote Discovery Server GuidPrefix to <44.53.01.5f.45.50.52.4f.53.49.4d.41>. +# 11: Discovery Server listening port is 11888. -# 12: Connect to a Discovery Server in IP localhost listening. This domain will be translated as ip: "127.0.0.1" - -# 13: Discovery Server listening port is 11888. - -# 14: This is the same configuration as the result using Fast DDS environment variable: +# 12: This is the same configuration as the result using Fast DDS environment variable: # $> export ROS_DISCOVERY_SERVER=";127.0.0.1:11888" # Add every other address where trying to reach this same remote Discovery Server, # or add every other Discovery Server connection required. diff --git a/docs/resources/examples/wan_ds_client.yaml b/docs/resources/examples/wan_ds_client.yaml index eef344465..5b8da788d 100644 --- a/docs/resources/examples/wan_ds_client.yaml +++ b/docs/resources/examples/wan_ds_client.yaml @@ -34,18 +34,14 @@ participants: - name: WANClient # 6 kind: wan-ds # 7 - discovery-server-guid: - id: 2 # 8 - connection-addresses: # 9 - - discovery-server-guid: - id: 1 # 10 - addresses: # 11 + connection-addresses: # 8 + - addresses: # 9 - ip: 1.1.1.1 port: 11666 - listening-addresses: # 12 - - ip: 2.2.2.2 # 13 - port: 11670 # 14 - transport: udp # 15 + listening-addresses: # 10 + - ip: 2.2.2.2 # 11 + port: 11670 # 12 + transport: udp # 13 ################################## # CONFIGURATION DESCRIPTION @@ -76,26 +72,22 @@ participants: # 7: Kind of WANClient: . # WAN communication with another DDS Router via Discovery Server. -# 8: Set the Discovery Server GuidPrefix to <01.0f.02.00.00.00.00.00.00.00.ca.fe> for WANClient. - -# 9: Add the addresses where to reach the remote DDS Routers that will connect to. +# 8: Add the addresses where to reach the remote DDS Routers that will connect to. # Add as many connection-addresses as needed. -# 10: Set the Remote Discovery Server GuidPrefix to <01.0f.01.00.00.00.00.00.00.00.ca.fe>. - -# 11: Connect to a Discovery Server in IP <1.1.1.1> listening in port 11666 over UDP transport (default). +# 9: Connect to a Discovery Server in IP <1.1.1.1> listening in port 11666 over UDP transport (default). # This is the same configuration that must be set in the DDS Router that works as a Server in its listening-addresses. # Add every other address where trying to reach this same remote WAN Discovery Server. -# 12: Add the interfaces where this Participant will listen in WAN. +# 10: Add the interfaces where this Participant will listen in WAN. # This is only needed if Remote WAN Server is using only UDP. # Add as many listening-addresses as needed. -# 13: Listen in public IP (2.2.2.2) for remote traffic. +# 11: Listen in public IP (2.2.2.2) for remote traffic. # This IP must be set to the public IP of the host where this DDS Router will run. -# 14: Listening port is 11670. +# 12: Listening port is 11670. # Remember that if the host is under a NAT, the IP must be the public one and must be forwarded from network # router to this host to the same port. -# 15: It uses UDP transport by default if not set. Could be set to "udp" or "tcp". +# 13: It uses UDP transport by default if not set. Could be set to "udp" or "tcp". diff --git a/docs/resources/examples/wan_ds_server.yaml b/docs/resources/examples/wan_ds_server.yaml index 279a1bfdc..3526dcb14 100644 --- a/docs/resources/examples/wan_ds_server.yaml +++ b/docs/resources/examples/wan_ds_server.yaml @@ -34,12 +34,10 @@ participants: - name: WANServer # 6 kind: wan-ds # 7 - discovery-server-guid: - id: 1 # 8 - listening-addresses: # 9 - - ip: 1.1.1.1 # 10 - port: 11666 # 11 - transport: udp # 12 + listening-addresses: # 8 + - ip: 1.1.1.1 # 9 + port: 11666 # 10 + transport: udp # 11 ################################## # CONFIGURATION DESCRIPTION @@ -70,17 +68,14 @@ participants: # 7: Kind of WANServer: . # WAN communication with another DDS Router via Discovery Server. -# 8: Set this Discovery Server GuidPrefix to <01.0f.01.00.00.00.00.00.00.00.ca.fe> for WANServer. -# This GuidPrefix is needed in order from a remote DDS Router to connect with this one. - -# 9: Add the interfaces where this Participant will listen in WAN. +# 8: Add the interfaces where this Participant will listen in WAN. # Add as many listening-addresses as needed. -# 10: Listen in public IP (1.1.1.1) for remote traffic. +# 9: Listen in public IP (1.1.1.1) for remote traffic. # This IP must be set to the public IP of the host where this DDS Router will run. -# 11: Listening port is 11666. +# 10: Listening port is 11666. # Remember that if the host is under a NAT, the IP must be the public one and must be forwarded from network # router to this host to the same port. -# 12: It uses UDP transport by default if not set. Could be set to "udp" or "tcp". +# 11: It uses UDP transport by default if not set. Could be set to "udp" or "tcp". diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index 705e224b0..10d29e6ef 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -741,7 +741,8 @@ For more information, check section :ref:`user_manual_wan_configuration_nat_trav Discovery Server GuidPrefix --------------------------- -A :term:`Discovery Server` requires a DDS :term:`GuidPrefix` in order for other Participants to connect to it. +In |fastdds| versions previous to *v3.0.0*, a :term:`Discovery Server` requires a DDS :term:`GuidPrefix` in order for other Participants to connect to it. +Although this parameter is no longer mandatory, it is still possible to set it so that a Discovery Server client from an older release may still stablish connection with a Discovery Server server from the newer ones. Under the ``discovery-server-guid`` tag, there are several possibilities for configuring a GuidPrefix. @@ -840,21 +841,17 @@ Discovery Server Connection Addresses ------------------------------------- Tag ``connection-addresses`` configure a connection with one or multiple remote Discovery Servers. -``connection-addresses`` is the *key* for an array in which each element has a GuidPrefix referencing the Discovery -Server to connect with; and a tag ``addresses`` configuring the addresses of such Discovery Server. +``connection-addresses`` is the *key* for an array in which each element has a tag ``addresses`` configuring the +addresses of such Discovery Server. Each element inside ``addresses`` must follow the configuration for :ref:`user_manual_configuration_network_address`. .. code-block:: yaml connection-addresses: - - discovery-server-guid: - guid: 44.53.0d.5f.45.50.52.4f.53.49.4d.41 - addresses: + - addresses: - ip: 127.0.0.1 port: 11666 - - discovery-server-guid: - id: 4 - addresses: + - addresses: - ip: 2001:4860:4860::8888 port: 11667 transport: tcp @@ -1113,10 +1110,7 @@ A complete example of all the configurations described on this page can be found transport: tcp # Transport = TCP connection-addresses: - - discovery-server-guid: - id: 2 - ros-discovery-server: true - addresses: + - addresses: - domain: "localhost" port: 22000 @@ -1133,9 +1127,7 @@ A complete example of all the configurations described on this page can be found id: 2 # Internal WAN Discovery Server id => GuidPrefix = 01.0f.02.00.00.00.00.00.00.00.ca.fe connection-addresses: # WAN Discovery Server Connection Addresses - - discovery-server-guid: - id: 4 # External WAN Discovery Server id => GuidPrefix = 01.0f.04.00.00.00.00.00.00.00.ca.fe - addresses: + - addresses: - ip: 8.8.8.8 # IP = 8.8.8.8 port: 11666 # Port = 11666 transport: udp # Transport = UDP diff --git a/docs/rst/user_manual/participants/local_discovery_server.rst b/docs/rst/user_manual/participants/local_discovery_server.rst index 75f7f2c26..3292a7a0e 100644 --- a/docs/rst/user_manual/participants/local_discovery_server.rst +++ b/docs/rst/user_manual/participants/local_discovery_server.rst @@ -53,8 +53,7 @@ Configure a Local Discovery Server setting the GuidPrefix used for ROS 2 deploym (``44.53.02.5f.45.50.52.4f.53.49.4d.41``). It listens for clients in *localhost* in ports ``11600`` in ``UDP`` and ``11601`` in ``TCP``. This example connects the local Discovery Server Participant with a remote Discovery Server listening in IPv6 address -``2001:4860:4860::8888`` and port ``11666`` and configured with ``01.0f.04.00.00.00.00.00.00.00.ca.fe`` -Discovery Server GuidPrefix. +``2001:4860:4860::8888`` and port ``11666``. .. code-block:: yaml @@ -74,8 +73,6 @@ Discovery Server GuidPrefix. transport: tcp # Use TCP transport connection-addresses: # External Discovery Server Listening Addresses - - discovery-server-guid: - id: 4 # External Discovery Server id => GuidPrefix = 01.0f.04.00.00.00.00.00.00.00.ca.fe - addresses: + - addresses: - ip: 2001:4860:4860::8888 # Use UDP by default port: 11666 diff --git a/docs/rst/user_manual/participants/wan_discovery_server.rst b/docs/rst/user_manual/participants/wan_discovery_server.rst index 9a5c7990c..c37b2bd16 100644 --- a/docs/rst/user_manual/participants/wan_discovery_server.rst +++ b/docs/rst/user_manual/participants/wan_discovery_server.rst @@ -62,8 +62,8 @@ Configuration Example Configure a WAN Discovery Server with GuidPrefix id ``2`` (``01.0f.02.00.00.00.00.00.00.00.ca.fe``). It listens for clients in public IP ``82.0.0.1`` in port ``11600`` in ``TCP``. -It connects with a remote WAN Participant in IPv6 address ``2001:4860:4860::8888`` and port ``11666`` which Discovery -Server GuidPrefix is ``01.0f.04.00.00.00.00.00.00.00.ca.fe`` using ``UDP`` transport. +It connects with a remote WAN Participant in IPv6 address ``2001:4860:4860::8888`` and port ``11666`` +using ``UDP`` transport. .. code-block:: yaml @@ -72,16 +72,14 @@ Server GuidPrefix is ``01.0f.04.00.00.00.00.00.00.00.ca.fe`` using ``UDP`` trans kind: wan-discovery-server discovery-server-guid: - id: 2 # GuidPrefix = 01.0f.02.00.00.00.00.00.00.00.ca.fe + id: 2 # GuidPrefix = 01.0f.02.00.00.00.00.00.00.00.ca.fe [optional] listening-addresses: # WAN Discovery Server Listening Addresses - ip: 82.0.0.1 # Use UDP by default port: 11600 connection-addresses: # Another WAN Participant Listening Addresses - - discovery-server-guid: - id: 4 # External Discovery Server id => GuidPrefix = 01.0f.04.00.00.00.00.00.00.00.ca.fe - addresses: + - addresses: - ip: 2001:4860:4860::8888 port: 11666 transport: udp # Use UDP transport diff --git a/resources/configurations/examples/ros_discovery_client.yaml b/resources/configurations/examples/ros_discovery_client.yaml index c87679851..21cd5c2ff 100644 --- a/resources/configurations/examples/ros_discovery_client.yaml +++ b/resources/configurations/examples/ros_discovery_client.yaml @@ -36,13 +36,10 @@ participants: ros-discovery-server: true # 7 id: 2 # 8 connection-addresses: # 9 - - discovery-server-guid: - ros-discovery-server: true # 10 - id: 1 # 11 - addresses: - - domain: localhost # 12 - port: 11888 # 13 - # 14 + - addresses: + - domain: localhost # 10 + port: 11888 # 11 + # 12 ################################## # CONFIGURATION DESCRIPTION @@ -77,15 +74,11 @@ participants: # 9: Add the addresses where this Client will try to reach a Discovery Server. -# 10: Connecting to a Discovery Server with ROS 2 GuidPrefix <44.53. .5f.45.50.52.4f.53.49.4d.41>. +# 10: Connect to a Discovery Server in IP localhost listening. This domain will be translated as ip: "127.0.0.1" -# 11: Set the Remote Discovery Server GuidPrefix to <44.53.01.5f.45.50.52.4f.53.49.4d.41>. +# 11: Discovery Server listening port is 11888. -# 12: Connect to a Discovery Server in IP localhost listening. This domain will be translated as ip: "127.0.0.1" - -# 13: Discovery Server listening port is 11888. - -# 14: This is the same configuration as the result using Fast DDS environment variable: +# 12: This is the same configuration as the result using Fast DDS environment variable: # $> export ROS_DISCOVERY_SERVER=";127.0.0.1:11888" # Add every other address where trying to reach this same remote Discovery Server, # or add every other Discovery Server connection required. diff --git a/resources/configurations/examples/wan_ds_client.yaml b/resources/configurations/examples/wan_ds_client.yaml index 1ce2ff768..f384d1fc6 100644 --- a/resources/configurations/examples/wan_ds_client.yaml +++ b/resources/configurations/examples/wan_ds_client.yaml @@ -34,12 +34,8 @@ participants: - name: WANClient # 6 kind: wan-discovery-server # 7 - discovery-server-guid: - id: 2 # 8 - connection-addresses: # 9 - - discovery-server-guid: - id: 1 # 10 - addresses: # 11 + connection-addresses: # 8 + - addresses: # 9 - ip: 1.1.1.1 port: 11777 transport: tcp @@ -73,13 +69,9 @@ participants: # 7: Kind of WANClient: . # WAN communication with another DDS Router via Discovery Server. -# 8: Set the Discovery Server GuidPrefix to <01.0f.02.00.00.00.00.00.00.00.ca.fe> for WANClient. - -# 9: Add the addresses where to reach the remote DDS Routers that will connect to. +# 8: Add the addresses where to reach the remote DDS Routers that will connect to. # Add as many connection-addresses as needed. -# 10: Set the Remote Discovery Server GuidPrefix to <01.0f.01.00.00.00.00.00.00.00.ca.fe>. - -# 11: Connect to a Discovery Server in IP <1.1.1.1> listening in port 11666 over UDP transport (default). +# 9: Connect to a Discovery Server in IP <1.1.1.1> listening in port 11666 over UDP transport (default). # This is the same configuration that must be set in the DDS Router that works as a Server in its listening-addresses. # Add every other address where trying to reach this same remote WAN Discovery Server. diff --git a/resources/configurations/examples/wan_ds_server.yaml b/resources/configurations/examples/wan_ds_server.yaml index ba878049d..13fb0a6fe 100644 --- a/resources/configurations/examples/wan_ds_server.yaml +++ b/resources/configurations/examples/wan_ds_server.yaml @@ -34,13 +34,11 @@ participants: - name: WANServer # 6 kind: wan-discovery-server # 7 - discovery-server-guid: - id: 1 # 8 - listening-addresses: # 9 - - ip: 1.1.1.1 # 10 - port: 11666 # 11 - external-port: 11777 # 12 - transport: tcp # 13 + listening-addresses: # 8 + - ip: 1.1.1.1 # 9 + port: 11666 # 10 + external-port: 11777 # 11 + transport: tcp # 12 ################################## # CONFIGURATION DESCRIPTION @@ -71,21 +69,18 @@ participants: # 7: Kind of WANServer: . # WAN communication with another DDS Router via Discovery Server. -# 8: Set this Discovery Server GuidPrefix to <01.0f.01.00.00.00.00.00.00.00.ca.fe> for WANServer. -# This GuidPrefix is needed in order from a remote DDS Router to connect with this one. - -# 9: Add the interfaces where this Participant will listen in WAN. +# 8: Add the interfaces where this Participant will listen in WAN. # Add as many listening-addresses as needed. -# 10: Listen in public IP (1.1.1.1) for remote traffic. +# 9: Listen in public IP (1.1.1.1) for remote traffic. # This IP must be set to the public IP of the host where this DDS Router will run. -# 11: Listening port is 11666. +# 10: Listening port is 11666. # Remember that if the host is under a NAT, this port is the one that the host will open, but not the one # used as public in the router. -# 12: External port is 11777. +# 11: External port is 11777. # This port is used in case the host is under a NAT. This is the public port accessible from any external point # in the network, and should be forwarded from the network router to the "port" value. -# 13: It uses TCP. UDP transport is used by default if not set. Could be set to "udp" or "tcp". +# 12: It uses TCP. UDP transport is used by default if not set. Could be set to "udp" or "tcp". diff --git a/tools/ddsrouter_tool/test/application/CMakeLists.txt b/tools/ddsrouter_tool/test/application/CMakeLists.txt index cfc411d9a..722a718c4 100644 --- a/tools/ddsrouter_tool/test/application/CMakeLists.txt +++ b/tools/ddsrouter_tool/test/application/CMakeLists.txt @@ -22,7 +22,7 @@ find_package(PythonInterp 3 REQUIRED) set(TEST_CONFIGURATIONS simple_configuration ds_configuration - complex_configuration_v3 + complex_configuration wan_configuration ) diff --git a/tools/ddsrouter_tool/test/application/configurations/complex_configuration_v3.yaml b/tools/ddsrouter_tool/test/application/configurations/complex_configuration.yaml similarity index 92% rename from tools/ddsrouter_tool/test/application/configurations/complex_configuration_v3.yaml rename to tools/ddsrouter_tool/test/application/configurations/complex_configuration.yaml index 8b36cc50e..8100bdfad 100644 --- a/tools/ddsrouter_tool/test/application/configurations/complex_configuration_v3.yaml +++ b/tools/ddsrouter_tool/test/application/configurations/complex_configuration.yaml @@ -55,21 +55,14 @@ participants: - name: local-ds kind: local-discovery-server - discovery-server-guid: - id: 0 - listening-addresses: - ip: "127.0.0.1" port: 11666 - name: wan kind: wan-ds - discovery-server-guid: - id: 1 connection-addresses: - - discovery-server-guid: - id: 2 - addresses: + - addresses: - ip: "127.0.0.1" port: 11667 external-port: 11678 diff --git a/tools/ddsrouter_tool/test/application/configurations/ds_configuration.yaml b/tools/ddsrouter_tool/test/application/configurations/ds_configuration.yaml index 79b5dbf82..c22896284 100644 --- a/tools/ddsrouter_tool/test/application/configurations/ds_configuration.yaml +++ b/tools/ddsrouter_tool/test/application/configurations/ds_configuration.yaml @@ -20,20 +20,14 @@ participants: - name: local-ds kind: local-discovery-server - discovery-server-guid: - id: 0 listening-addresses: - ip: "127.0.0.1" port: 11666 - name: wan kind: wan-ds - discovery-server-guid: - id: 1 connection-addresses: - - discovery-server-guid: - id: 2 - addresses: + - addresses: - ip: "127.0.0.1" port: 11667 transport: tcp diff --git a/tools/ddsrouter_tool/test/labels/XTSAN.list b/tools/ddsrouter_tool/test/labels/XTSAN.list index 5b24a583c..3bf7919df 100644 --- a/tools/ddsrouter_tool/test/labels/XTSAN.list +++ b/tools/ddsrouter_tool/test/labels/XTSAN.list @@ -2,7 +2,7 @@ tool.application.ddsrouter.simple_configuration.sigint tool.application.ddsrouter.simple_configuration.sigint.sigterm tool.application.ddsrouter.ds_configuration.sigint tool.application.ddsrouter.ds_configuration.sigint.sigterm -tool.application.ddsrouter.complex_configuration_v3.sigint -tool.application.ddsrouter.complex_configuration_v3.sigint.sigterm +tool.application.ddsrouter.complex_configuration.sigint +tool.application.ddsrouter.complex_configuration.sigint.sigterm tool.application.ddsrouter.wan_configuration.sigint tool.application.ddsrouter.wan_configuration.sigint.sigterm