diff --git a/docs/rst/tutorials/core/ros2_tutorials.rst b/docs/rst/tutorials/core/ros2_tutorials.rst index b2ba287d..0b52cdc0 100644 --- a/docs/rst/tutorials/core/ros2_tutorials.rst +++ b/docs/rst/tutorials/core/ros2_tutorials.rst @@ -12,6 +12,7 @@ This section provides a collection of tutorials on the use and application of th :maxdepth: 1 wifi/wifi_tutorials + scalability/scalability_tutorials discoveryserver/discoveryserver_tutorials security/security_tutorials qos/qos_tutorials diff --git a/docs/rst/tutorials/core/scalability/discovery_server/discovery_server_scalability.rst b/docs/rst/tutorials/core/scalability/discovery_server/discovery_server_scalability.rst new file mode 100644 index 00000000..57bd5185 --- /dev/null +++ b/docs/rst/tutorials/core/scalability/discovery_server/discovery_server_scalability.rst @@ -0,0 +1,107 @@ +.. _tutorials_discovery_server_scalability: + +How to Use a Discovery Server to Optimize ROS 2 Node Discovery +============================================================== + +.. contents:: + :depth: 2 + :local: + :backlinks: none + +Facing Scalability Challenges in Your ROS 2 System? +--------------------------------------------------- + +Have you ever struggled with scaling your ROS 2 network as it grows in size? +As more nodes, topics, and services are added to a ROS 2 system, the underlying DDS (Data Distribution Service) quickly forms a fully-connected graph, meaning that every node discovers and communicates with every other node. +While this setup guarantees robust connectivity, it can also lead to network congestion and high discovery traffic as the system scales, impacting performance and reliability. + +The Fast DDS Discovery Server offers a centralized mechanism for managing node discovery, allowing nodes to connect through a server instead of relying on the default multicast-based Simple Discovery Protocol (SDP). +This reduces discovery traffic, provides better control over network management, and improves scalability in complex or large network scenarios. + +**Quick Solution Overview** + +Launch the Discovery Server locally on the default port (11811) using the following command: + +.. code-block:: bash + + fastdds discovery + +Overview +-------- + +In this tutorial, we will explore how to set up and use the Fast DDS Discovery Server with ROS 2. +Both a ``talker`` and a ``listener`` nodes from the ``demo_nodes_cpp`` ROS 2 package are created: the talker node will publish a "hello world" message every second, while the listener node will listen to these messages. +By using the Discovery Server, nodes register and discover each other through a centralized server instead of communicating directly with every other node. + +.. figure:: /rst/figures/tutorials/core/discovery_server/Discovery_Server.svg + :align: center + :scale: 150% + +Background +---------- + +By default, ROS 2 uses the Simple Discovery Protocol (SDP), which relies on multicast communication to discover other nodes. +While SDP is suitable for many scenarios, it may not be the best choice in complex and large-scale network configurations. +This is where the Fast DDS Discovery Server comes into play. Fast DDS offers an alternative discovery mechanism that allows ROS 2 nodes to connect to a Discovery Server. +This server acts as a centralized point for node registration and discovery, providing more flexibility and control in managing the network of nodes and is particularly advantageous in scenarios such as: + +* Large networks + +* Complex networks + +* WiFi networks + +In this tutorial, we will explore how to set up and use the Fast DDS Discovery Server with ROS 2, enabling robust and dynamic node discovery communication. + +Prerequisites +------------- + +It is required to have previously installed Vulcanexus using one of the following installation methods: + +* `Linux binary installation `__ +* `Linux installation from sources `__ +* `Docker installation `__ + + +Run this tutorial +------------------ + +Once we finish with the set up of Vulcanexus environment we are ready to start with the *talker-listener* demo tutorial. +By sourcing Vulcanexus you will get access to the CLI tool ``fastdds``, together with the ROS 2 environment. +This tool gives access to the `discovery tool `__, which can be used to launch a discovery server. + +.. important:: + + Do not forget to source ROS 2 every time you open another session to have access to the ROS 2 environment and the CLI tool ``fastdds``. + +Setup Discovery Server +^^^^^^^^^^^^^^^^^^^^^^ +Start by launching a discovery server on port 11811 (default port) and listening on all available interfaces. +The role of the server is to re-distribute the clients (and servers) discovery information to their known clients (and servers). + +.. code-block:: bash + + fastdds discovery + + +Launch Talker Node +^^^^^^^^^^^^^^^^^^^ +Execute the Talker demo to publish on the ``/chatter`` topic. When setting the ``ROS_DISCOVERY_SERVER`` environment variable you are indicating that ROS node should act as a client that connects to a discovery server to discover other nodes on the network. +Use the argument ``--remap __node:=talker_discovery_server`` to change the node’s name for this tutorial. + +.. code-block:: bash + + export ROS_DISCOVERY_SERVER=127.0.0.1:11811 + ros2 run demo_nodes_cpp talker --ros-args --remap __node:=talker_discovery_server + + +Launch Listener Node +^^^^^^^^^^^^^^^^^^^^^ +Execute the Listener demo to listen to the ``/chatter`` topic. + +.. code-block:: bash + + export ROS_DISCOVERY_SERVER=127.0.0.1:11811 + ros2 run demo_nodes_cpp listener --ros-args --remap __node:=listener_discovery_server + + diff --git a/docs/rst/tutorials/core/wifi/router_fully_connected/router_fully_connected.rst b/docs/rst/tutorials/core/scalability/router_fully_connected/router_fully_connected.rst similarity index 99% rename from docs/rst/tutorials/core/wifi/router_fully_connected/router_fully_connected.rst rename to docs/rst/tutorials/core/scalability/router_fully_connected/router_fully_connected.rst index 1d09e690..7403a69b 100644 --- a/docs/rst/tutorials/core/wifi/router_fully_connected/router_fully_connected.rst +++ b/docs/rst/tutorials/core/scalability/router_fully_connected/router_fully_connected.rst @@ -2,8 +2,8 @@ .. _tutorials_router_fully_connected: -How to avoid Fully-Connected Graph Networks in ROS 2 -==================================================== +How to Use DDS Router for Scalable ROS 2 Network Communication +============================================================== .. contents:: :depth: 2 diff --git a/docs/rst/tutorials/core/scalability/scalability_tutorials.rst b/docs/rst/tutorials/core/scalability/scalability_tutorials.rst new file mode 100644 index 00000000..52a34a3d --- /dev/null +++ b/docs/rst/tutorials/core/scalability/scalability_tutorials.rst @@ -0,0 +1,13 @@ +.. _tutorials_scalability_ros2_tutorials: + +Scalability and Large Scale Networks Tutorials +============================================== + +Configuring ROS 2 applications over large networks can present multiple challenges. +This series of tutorials is designed to help address common issues that arise when using ROS 2 over large networks, where factors such as latency, packet loss, and network congestion can significantly impact the functionality and performance of distributed systems. + +.. toctree:: + :maxdepth: 1 + + discovery_server/discovery_server_scalability + router_fully_connected/router_fully_connected diff --git a/docs/rst/tutorials/core/wifi/wifi_tutorials.rst b/docs/rst/tutorials/core/wifi/wifi_tutorials.rst index 79031555..83f41eb8 100644 --- a/docs/rst/tutorials/core/wifi/wifi_tutorials.rst +++ b/docs/rst/tutorials/core/wifi/wifi_tutorials.rst @@ -11,5 +11,4 @@ This series of tutorials is designed to help address common issues that arise wh wifi_issues_tutorial/wifi_issues_tutorial large_data/large_data - router_fully_connected/router_fully_connected image_compression/image_compression