diff --git a/docs/rst/tutorials/core/ros2_tutorials.rst b/docs/rst/tutorials/core/ros2_tutorials.rst index 4c88ee25..b2ba287d 100644 --- a/docs/rst/tutorials/core/ros2_tutorials.rst +++ b/docs/rst/tutorials/core/ros2_tutorials.rst @@ -11,6 +11,7 @@ This section provides a collection of tutorials on the use and application of th .. toctree:: :maxdepth: 1 + wifi/wifi_tutorials discoveryserver/discoveryserver_tutorials security/security_tutorials qos/qos_tutorials diff --git a/docs/rst/tutorials/core/wifi/large_data/large_data.rst b/docs/rst/tutorials/core/wifi/large_data/large_data.rst new file mode 100644 index 00000000..da31c366 --- /dev/null +++ b/docs/rst/tutorials/core/wifi/large_data/large_data.rst @@ -0,0 +1,249 @@ +.. include:: ../../../../exports/alias.include + +.. _tutorials_large_data_video_streaming: + +How to handle large data video streaming in ROS 2 +================================================= + +.. contents:: + :depth: 2 + :local: + :backlinks: none + +Have you ever faced problems streaming video in ROS 2? +------------------------------------------------------ + +If you've experienced issues streaming video in ROS 2, such as video freezing, packet loss, or jitter, especially over WiFi, you can enable Fast DDS’s **Large Data Mode** with a simple environment variable configuration. +This allows you to bypass some of the limitations of UDP transport by using TCP or Shared Memory (SHM) for large data transmission, enhancing the reliability and quality of your video stream. + +**Quick Solution Overview** + +To apply this solution, set the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable to ``LARGE_DATA`` in every ROS 2 node involved in transmitting large data messages: + +.. code:: bash + + export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA + +Overview +-------- + +In this tutorial, we will demonstrate how to efficiently transmit large data, specifically a video stream, over WiFi between two hosts using Fast DDS. +The tutorial will guide you through two scenarios: + +1. *Default UDP Transmission*: We will first configure a basic video transmission using the default UDP transport, allowing you to observe the potential issues, such as packet loss or jitter, commonly encountered when transmitting large data over unreliable networks like WiFi. + +2. *Large Data Mode*: Next, we will enable Fast DDS's Large Data Mode, which leverages TCP or Shared Memory for data transmission, offering more reliability for large data transfers. You will see how this configuration improves the stability and quality of the video reception on the receiving host. + +3. *Advanced Large Data Mode*: Finally, we will explore additional custom configurations within the Large Data Mode to further optimize video streaming performance. By adjusting network parameters, such as socket buffer sizes and non-blocking mode, and setting a TCP negotiation timeout, this configuration enhances stability and responsiveness, especially when streaming large data over networks prone to instability. + +By comparing the three performances, we'll understand the impact of transport configuration on large data transfers and learn how to optimize Fast DDS for reliable communication in scenarios that involve sending large data over networks prone to instability, such as WiFi. + +.. warning:: + + A brief theoretical overview of the Large Data Mode will be provided for additional context. + However, readers may skip directly to the :ref:`tutorials_large_data_video_streaming_prerequisites` section if they prefer to start with the setup steps. + +Background +---------- + +When working with large data transfers in DDS (Data Distribution Service), it's important to consider certain aspects of how data is transmitted, especially when relying on UDP as the default network protocol. +UDP offers flexibility and control over key aspects of message delivery, such as allowing users to configure messages as either best-effort or reliable, depending on their needs. This control is a major advantage for many real-time applications. + +However, due to the nature of UDP, there are certain factors that need attention when handling larger data, such as images or point clouds, commonly seen in robotics or other high-bandwidth applications. +While UDP is flexible, it has not received the same performance optimizations as TCP, which is widely used in modern networking. +For example, Linux systems often allocate small default buffer sizes for UDP (around 256 KB), which may not be enough for larger data like images or point clouds. Combined with unreliable networks, like WiFi, this can cause issues like repeated retransmissions and buffer overflows. + +Manual tuning options +^^^^^^^^^^^^^^^^^^^^^ + +For handling large data efficiently, Fast DDS offers various tuning options to avoid issues like buffer overflows and retransmissions when using UDP. +Key configurations include increasing socket buffer sizes, adjusting the transmit queue length, and using flow controllers to control data transmission rates. +For more details and advanced configurations, refer to the official documentation `here `__. + +Large Data Mode +^^^^^^^^^^^^^^^ + +In addition to manual tuning options, Fast DDS offers a more straightforward solution for large data handling that doesn’t require deep network knowledge: the `Large Data Mode `__. +This configuration allows Fast DDS DomainParticipants to perform the PDP discovery phase using UDP multicast, while transmitting large data samples over more reliable transports like TCP or Shared Memory (SHM). +This approach provides the flexibility of UDP-based discovery with the reliability of TCP or SHM for large data transfers. + +Large Data Mode can be easily enabled using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable, XML profiles, or code: + +.. code:: bash + + export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA + +This simplifies the configuration process and helps optimize large data transmission without needing extensive network adjustments. + +Large Data with Configuration options +""""""""""""""""""""""""""""""""""""" + +In addition to the default setup, Large Data Mode offers advanced configuration options to enhance performance when handling large data, such as video streaming. +Fast DDS provides these key parameters to adjust transport behavior in ``LARGE_DATA`` mode: + +- ``max_msg_size``: Maximum message size before fragmentation, up to (2^32)-1 B bytes for TCP and SHM, and 65500 KB for UDP. +- ``sockets_size``: Size of the send and receive buffers; should match or exceed max_msg_size and defines the SHM size. +- ``non_blocking``: Avoids application blocking when buffers are full, though some message loss may occur. Default is false. +- ``tcp_negotiation_timeout``: Sets a timeout for TCP port negotiation, helping prevent initial message loss. + +Tuning these parameters for large messages and enabling non-blocking mode can optimize performance for high-bandwidth data flows like video. + +The following snippets show how to configure the ``LARGE_DATA`` mode: + +.. code-block:: bash + + export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=1MB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50 + +.. _tutorials_large_data_video_streaming_prerequisites: + +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 `__ + +Additionally, you need to have OpenCV installed. +You can follow the `OpenCV documentation `__ for detailed installation instructions. + +You will also need the ROS package ``image_tools``, which can be installed by running: + +.. code:: bash + + sudo apt-get install ros-humble-image-tools + +Lastly, ensure you have a working webcam connected to one of the hosts. + +.. note:: + + Make sure to source Vulcanexus setup file on every working terminal of the tutorial. + +Run this tutorial +------------------ + +UDP Streaming +^^^^^^^^^^^^^ + +In the first part of the tutorial, we will use the default UDP settings. +Follow these steps: + +1. Source your Vulcanexus setup file on both computers: + +.. code:: bash + + source /opt/vulcanexus/jazzy/setup.bash + +2. On the receiving computer, run the subscriber node: + +.. code:: bash + + ros2 run image_tools showimage + +At this point, nothing will happen yet, as ``showimage`` is waiting for a publisher on the image topic. +Remember to terminate this process with ``Ctrl-C`` later; closing the window alone will not stop it. + +3. On the sending computer, source the install file again and run the publisher node: + +.. code:: bash + + ros2 run image_tools cam2image + +This will start publishing images from your webcam. +If you don't have a camera connected, you can use the following command to publish predefined images: + +.. code:: bash + + ros2 run image_tools cam2image --ros-args -p burger_mode:=True + +You should see terminal output like: + +.. code:: bash + + Publishing image #1 + Publishing image #2 + Publishing image #3 + ... + +This occurs because the default buffer sizes for UDP are relatively small, which can lead to overflow when dealing with larger data packets, such as video streams. +As a result, packets may be dropped during transmission, causing interruptions in the video feed. +Furthermore, the inherent unreliability of UDP, especially in WiFi environments, can significantly compound these challenges, making it difficult to sustain a stable connection for real-time streaming. + +Large Data Mode +^^^^^^^^^^^^^^^ + +In the second part, we will switch to using the Large Data mode for improved performance. +This is done by exporting the environment variable in the terminal on both computers: + +.. code:: bash + + export FASTDDS_BUILTIN_TRANSPORTS="LARGE_DATA" + +With this setting, run the same publisher and subscriber commands again. +This time, you should experience smooth and uninterrupted video streaming with no freezing or image loss. + +Advanced Large Data Mode +^^^^^^^^^^^^^^^^^^^^^^^^ + +In the final part of this tutorial, we’ll guide you through more advanced settings to improve video streaming performance in ROS 2 using Fast DDS. +These additional steps are aimed at optimizing reliability and quality, particularly over unstable or high-bandwidth networks. + +Increasing Socket Buffer Sizes on Linux +""""""""""""""""""""""""""""""""""""""" + +First, we’ll increase the socket buffer sizes, which can help prevent packet loss and improve the stability of the video stream. +To adjust the send and receive socket buffers on Linux, follow these steps: + +1. Check the current buffer sizes: + + * For send buffers: + + .. code:: bash + + sudo sysctl -a | grep net.core.wmem_max + + * For receive buffers: + + .. code:: bash + + sudo sysctl -a | grep net.core.rmem_max + +2. Increase the buffer sizes if needed: + + * For send buffers: + + .. code:: bash + + sudo sysctl -w net.core.wmem_max=12582912 + + * For receive buffers: + + .. code:: bash + + sudo sysctl -w net.core.rmem_max=12582912 + +Large Data Mode with Custom Configuration +""""""""""""""""""""""""""""""""""""""""" + +After adjusting the socket buffer sizes, we’ll configure Fast DDS’s Large Data Mode with additional parameters to further optimize performance. +Use the following environment variable to apply these settings: + +.. code:: bash + + export FASTDDS_BUILTIN_TRANSPORTS="LARGE_DATA?max_msg_size=1MB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50" + +This configuration sets the ``maximum_message_size`` and ``socket_buffer_sizes`` to handle larger data without fragmentation, enables ``non-blocking`` mode to avoid blocking the application when buffers are full, and adds a ``timeout`` for TCP port negotiation to prevent initial packet loss. + +Conclusion +---------- + +In this tutorial, we explored various configurations to optimize large data transmission, specifically video streaming, using Fast DDS over WiFi in ROS 2. +We began with a basic UDP transmission setup to highlight the common challenges of packet loss and jitter in high-bandwidth scenarios. +By enabling Fast DDS’s Large Data Mode, we saw how switching to TCP can improve the reliability of video transmission. + +For even better performance, we applied advanced configurations within Large Data Mode, such as increasing maximum message sizes and socket buffer sizes, enabling non-blocking mode, and setting a TCP negotiation timeout. +These settings provide greater stability and responsiveness, making Fast DDS a powerful tool for handling high-throughput data like video over potentially unreliable networks. + +With these techniques, you can enhance the reliability of ROS 2 video streaming, reducing issues related to packet loss, freezing, and jitter. +Whether streaming video or other large data types, these configurations can be applied to build more robust communication systems in your ROS 2 applications. diff --git a/docs/rst/tutorials/core/wifi/wifi_issues_tutorial/wifi_issues_tutorial.rst b/docs/rst/tutorials/core/wifi/wifi_issues_tutorial/wifi_issues_tutorial.rst new file mode 100644 index 00000000..cb7f14f6 --- /dev/null +++ b/docs/rst/tutorials/core/wifi/wifi_issues_tutorial/wifi_issues_tutorial.rst @@ -0,0 +1,350 @@ +.. include:: ../../../../exports/alias.include + +.. _tutorials_wifi_issues_in_ros2: + +How to solve wireless network issues in ROS 2 +============================================= + +.. contents:: + :depth: 2 + :local: + :backlinks: none + +Have you ever faced issues deploying your ROS 2 application over WiFi? +---------------------------------------------------------------------- + +Deploying ROS 2 applications over WiFi networks can often be challenging. +You may encounter issues with node discovery due to the limitations of multicast, or experience poor performance when streaming large data, such as video, across unstable or lossy networks. +Fortunately, there's a straightforward solution: leveraging the **Discovery Server** and **Large Data** mode in Fast DDS. + +**Quick Solution Overview** + +To address these issues, follow these simple steps: + +1. **Configure a Discovery Server** to replace multicast-based discovery with a more reliable client-server setup. + +.. code-block:: bash + + fastdds discovery -t -q 42100 + +2. Create the JSON configuration file for each client, setting up **Large Data** mode and the **Discovery Server** to point to: + +.. code-block:: xml + + { + "ROS_DISCOVERY_SERVER": "TCPv4:[]:42100", + "ROS_SUPER_CLIENT": "TRUE", + "FASTDDS_BUILTIN_TRANSPORTS"="LARGE_DATA" + } + +3. Apply the JSON file in each client by setting the environment variable: + +.. code-block:: bash + + export FASTDDS_ENVIRONMENT_FILE="" + +Overview +-------- + +This tutorial will demonstrate how to address common issues encountered when connecting ROS 2 nodes over a WiFi network. +In this tutorial, two ``image_tools`` `publisher` nodes will communicate with two `subscriber` nodes, with each `publisher`-`subscriber` pair running on separate hosts. +The discovery process will use a Discovery Server instead of multicast, and the builtin transport will be configured to TCP, to handle large data transfers over a reliable protocol rather than the default UDP. +This setup provides a network architecture that overcomes node discovery challenges in environments where multicast is not possible, while facilitating the transmission of large data over WiFi or other lossy networks. + +.. figure:: /rst/figures/tutorials/core/discovery_server/ros2_wifi.svg + :align: center + :scale: 100% + +The goal of this tutorial is to configure the Discovery Server and Large Data mode for reliable discovery, connectivity and communication across nodes in constrained network environments, ensuring that the ``image_tools`` subscriber nodes can seamlessly receive large data video frames from the publisher nodes. + +.. warning:: + + A brief theoretical background of the Discovery Server and TCP configuration will be provided for additional context. + However, readers may skip directly to the :ref:`tutorials_wifi_issues_in_ros2_prerequisites` section if they prefer to start with the setup steps. + +Background +---------- + +By default, ROS 2 uses the Simple Discovery Protocol (SDP), which relies on multicast communication for discovering other nodes. +However, when dealing with large, complex, or WiFi-based networks, **ROS 2 Discovery Server** offers a more robust and flexible solution. + +Fast DDS allows ROS 2 nodes to connect to a centralized Discovery Server that simplifies and accelerates the discovery phase. +This server-based approach improves network stability, optimizes resource usage, and eliminates the challenges +typically faced in more complex network environments. +Additionally, Fast DDS supports a **Large Data mode** configuration, which facilitates the efficient transfer of large data types, such as video streams or point clouds, making it ideal for WiFi architectures where data transmission needs are high. + +With a few configuration steps, *ROS 2 Discovery Server* and *Large Data mode* enhance node discovery process and data transfer, particularly well-suited for: + + * Large-scale networks + * Complex network topologies + * WiFi networks with potential multicast limitations and large data requirements + +By introducing the *Discovery Server* and *Large Data mode* into your ROS 2 setup, you gain better control over node registration, communication efficiency, and large data handling, creating a highly effective solution for demanding network scenarios. + +Discovery Server Architecture +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Discovery Server `__ in Fast DDS offers a robust alternative to the default ROS 2 `Simple Discovery Protocol (SDP) `__, designed to improve discovery efficiency in large or complex networks. Unlike SDP, which uses multicast to broadcast discovery information across all nodes, the Discovery Server introduces a Client-Server Architecture that reduces unnecessary metatraffic (message exchange among `DomainParticipants `__ to identify each other) by centralizing the discovery process. + +In this architecture: + +- A |SERVER| acts as a centralized hub that gathers and redistributes discovery information from connected Clients and other servers. + It ensures that each client only receives the information needed to communicate with its relevant peers, thereby significantly reducing network bandwidth usage and improving the discovery phase's speed. + +- A |CLIENT| is a node that sends its discovery data to the server it connects to. + The client receive back only the data it needs for its specific communication requirements (matching topics, publishers, and subscribers), minimizing overhead compared to SDP, where all nodes discover and track all other nodes. + +- 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. + +Advantages of ROS 2 DDS Discovery Server +"""""""""""""""""""""""""""""""""""""""" + +- Efficient Communication: Clients only receive the discovery information they need, rather than all possible data as in the SDP approach. + +- Network Optimization: Reduces the bandwidth usage (see `this `__ comparison of the reduction in traffic when deploying discovery with SDP to Discovery Server). + Crucially, it eliminates the reliance on multicast, which is essential for environments with strict performance requirements or for networks that do not support multicast—such as many WiFi networks. + By removing the need for multicast, the Discovery Server makes ROS 2 deployment possible in diverse and constrained network conditions. + +- Scalability: Well-suited for large and complex networks, where centralized discovery management simplifies node communication. + +.. figure:: /rst/figures/tutorials/core/discovery_server/discovery_server_complex.svg + :align: center + :scale: 100% + +Comparison of Simple Discovery Protocol and Discovery Server mechanisms + +Large Data Mode +^^^^^^^^^^^^^^^ + +Fast DDS provides a simpler solution for handling large data without requiring extensive network expertise: `Large Data Mode `__. +This configuration enables Fast DDS DomainParticipants to utilize UDP multicast for the PDP discovery phase while employing more reliable transport protocols, such as TCP or Shared Memory (SHM), for transmitting large data samples. +This method combines the flexibility of UDP-based discovery with the dependability of TCP or SHM for large data transfers. + +*Large Data mode* can be easily enabled using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable, XML profiles, or code: + +.. code:: bash + + export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA + +This simplifies the configuration process and helps optimize large data transmission without needing extensive network adjustments. + +If further adjustments are necessary, it is important to assess the specific requirements of your architecture to ensure optimal performance. +Fast DDS provides various tuning options to prevent issues such as buffer overflows and retransmissions when using UDP. +Key configurations include increasing socket buffer sizes, adjusting the transmit queue length, and employing flow controllers to manage data transmission rates. + +For more details and advanced configurations, refer to the official documentation `here `__. + +.. note:: + + For compatibility issues, Discovery Server has to be configured with TCP transport protocol when Large Data is set. + +.. _tutorials_wifi_issues_in_ros2_prerequisites: + +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 `__ + +Additionally, you need to have OpenCV installed. +You can follow the `OpenCV documentation `__ for detailed installation instructions. + +You will also need the ROS package ``image_tools``, which can be installed by running: + +.. code:: bash + + sudo apt-get install ros-jazzy-image-tools + +Lastly, ensure you have a working webcam connected to both of the hosts. + +Considerations for Video Streaming +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before proceeding with the tutorial, consider these factors and tips to optimize video streaming over WiFi: + +1. Network Bandwidth: + To support video streaming over WiFi, ensure your network bandwidth meets the demands of the video’s bitrate, especially if multiple devices are connected. + Higher-resolution or higher-frame-rate video streams demand more bandwidth, so consider compressing the video or reducing the resolution if the WiFi network has limitations. + Future tutorials will cover ways to adjust these settings in ROS 2. + Additionally, you can `adjust the socket buffer sizes `__ in your system’s network settings to accommodate larger data rates, which can help stabilize high-bandwidth streams. + +2. Network Congestion: + Multiple devices using the same network can lead to congestion, resulting in buffering or dropped frames during video streaming. + Tools like ``netstat`` or ``iptraf`` can monitor current network traffic, helping you assess if limiting other network activities—such as downloads or additional video streams—would improve performance. + +3. Video Compression and Encoding: + Utilizing efficient video codecs can significantly reduce the amount of data needed for transmission without compromising quality. + If high-quality video isn't essential, try lowering the encoding bitrate, which can significantly reduce bandwidth requirements. + +Run this tutorial +------------------ + +Configure Discovery Server entities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On Host A, start by launching the ROS 2 Discovery Server. +Open a terminal and configure the Fast DDS server as follows: + +.. code-block:: bash + + docker run \ + -it \ + --name discovery_server_container \ + --privileged \ + --net host \ + --ipc host \ + -e DISPLAY=$DISPLAY \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + ubuntu-vulcanexus:jazzy-desktop + +Once the container is running, configure Fast DDS *server* using the `Fast DDS Discovery CLI `__. + +.. code-block:: bash + + fastdds discovery -t 192.168.1.165 -q 42100 -t 127.0.0.1 -q 42101 + +The output should look similar to the following: + +.. code-block:: bash + + ### Server is running ### + Participant Type: SERVER + Security: YES + Server GUID prefix: 01.0f.33.0a.3a.14.27.73.00.00.00.00 + Server Addresses: TCPv4:[192.168.1.165]:42100-42100 + TCPv4:[127.0.0.1]:42101-42101 + +The output displays the security and server GUID prefix. +Server address ``TCPv4:[192.168.1.165]`` tells *Fast DDS* to listen on WiFi 192.168.1.165 interface with the ``42100`` connection port. +Server address ``TCPv4:[127.0.0.1]`` tells *Fast DDS* to listen on localhost with the ``42101`` connection port. + +After setting up the Discovery Server, you need to launch four additional Docker containers, two in each host, that will act as clients. +First, open two new terminals in each machine and run the following command to start each container in the same network: + +.. code-block:: bash + + docker run \ + -it \ + --name \ + --privileged \ + --net host \ + --ipc host \ + -e DISPLAY=$DISPLAY \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + ubuntu-vulcanexus:jazzy-desktop + +Replace ```` with a unique name for each container. +Once the containers are running, and after sourcing the Vulcanexus environment within each container, the easiest way to configure the clients to point to the *Discovery Server* is by setting `Environment Variables `__. +To simplify the configuration of all the environmental variables, we will use ``FASTDDS_ENVIRONMENT_FILE``. +This variable allows you to specify the path to a JSON file that contains all the environment variables. +You can specify the IP addresses and ports of the Discovery Servers the clients should contact. +It provides a lot of flexibility, as you can modify the locators (i.e., server addresses) dynamically at runtime. +To use this option, create a JSON file with the following structure: + +.. code-block:: xml + + { + "ROS_DISCOVERY_SERVER": ":" + } + +Then save the file in a known location and set the environment variable to point to it: + +.. code-block:: bash + + export FASTDDS_ENVIRONMENT_FILE="" + +Make sure to set it in each of the containers where the ROS 2 nodes will be running. + +Since the Discovery Server, a *publisher* and a *listener* ``image_tools`` nodes are running on Host A, these two nodes within Host A's containers should be configured to point to localhost. +Additionally, we will configure all nodes to be |SUPER_CLIENT| and `Large Data Mode `__ as builtin transport. +The json file for the nodes in **Host A** will look like: + +.. code-block:: xml + + { + "ROS_DISCOVERY_SERVER": "TCPv4:[127.0.0.1]:42101", + "ROS_SUPER_CLIENT": "TRUE", + "FASTDDS_BUILTIN_TRANSPORTS"="LARGE_DATA" + } + +On Host B, where other *publisher* and *subscriber* ``image_tools`` nodes will be running, the ``ROS_DISCOVERY_SERVER`` variable should point to the IP address of Host A on the WiFi network, as the Discovery Server is running on a different machine. +The json file for the nodes in **Host B** will be: + +.. code-block:: xml + + { + "ROS_DISCOVERY_SERVER": "TCPv4:[192.168.1.165]:42100", + "ROS_SUPER_CLIENT": "TRUE", + "FASTDDS_BUILTIN_TRANSPORTS"="LARGE_DATA" + } + +Finally, make the export of the ``FASTDDS_ENVIRONMENT_FILE`` in every node terminal, pointing to the JSON file path: + +.. code-block:: bash + + export FASTDDS_ENVIRONMENT_FILE="" + +Run ROS 2 demo nodes +^^^^^^^^^^^^^^^^^^^^ + +After all the configurations have been set, run the *publisher* and *subscriber* client nodes in each host: + +Host A +"""""" + +Run the following command to start the ``publisher`` node on topic ``/image_1``: + +.. code-block:: bash + + ros2 run image_tools cam2image --ros-args -r __node:=publisher_1 -r image:=/image_1 + +Then run the ``subscriber`` node on topic ``/image_2``: + +.. code-block:: bash + + ros2 run image_tools showimage --ros-args -r __node:=subscriber_2 -r image:=/image_2 + +Host B +"""""" + +Run the following command to start the ``publisher`` node on topic ``/image_2``: + +.. code-block:: bash + + ros2 run image_tools cam2image --ros-args -r __node:=publisher_2 -r image:=/image_2 + +Then run the ``subscriber`` node on topic ``/image_1``: + +.. code-block:: bash + + ros2 run image_tools showimage --ros-args -r __node:=subscriber_1 -r image:=/image_1 + + +This will start publishing images from the webcams. +If you don't have a camera connected, you can use the following command to publish predefined images: + +.. code-block:: bash + + ros2 run image_tools cam2image --ros-args -p burger_mode:=True -r __node:= -r image:= + +You should see terminal outputs like: + +.. code:: bash + + Publishing image #1 + Publishing image #2 + Publishing image #3 + ... + +Conclusion +---------- + +By following this tutorial, you’ve configured ROS 2 nodes to communicate reliably over WiFi using Fast DDS’s Discovery Server and Large Data mode. +This setup replaces multicast-based discovery with a server-client model, making ROS 2 node discovery more robust in complex network conditions or over WiFi networks with limited multicast support. +The Large Data mode, meanwhile, enhances the handling of high-bandwidth data, such as video streams, over TCP, ensuring that large data transfers remain stable on lossy or congested networks. + +This architecture provides a scalable, adaptable solution for deploying ROS 2 applications in network environments where stability and efficiency are critical. +If you’re interested in further optimizing or exploring more advanced configurations, consult the Fast DDS documentation on `Discovery Server `__ and `Large Data Mode `__, where additional performance tuning options are detailed. diff --git a/docs/rst/tutorials/core/wifi/wifi_tutorials.rst b/docs/rst/tutorials/core/wifi/wifi_tutorials.rst new file mode 100644 index 00000000..2fe38cb8 --- /dev/null +++ b/docs/rst/tutorials/core/wifi/wifi_tutorials.rst @@ -0,0 +1,13 @@ +.. _tutorials_wifi_ros2_tutorials: + +Vulcanexus WiFi & Large Data Tutorials +====================================== + +Configuring ROS 2 applications over WiFi networks can present multiple challenges. +This series of tutorials is designed to help address common issues that arise when using ROS 2 over WiFi networks, where latency, packet loss, and bandwidth limitations can affect application performance and reliability. + +.. toctree:: + :maxdepth: 1 + + wifi_issues_tutorial/wifi_issues_tutorial + large_data/large_data.rst