From 45e6cd9a428fd26246f3d27917d83576bff05cf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Hern=C3=A1ndez=20Cordero?= Date: Thu, 24 Apr 2025 19:35:18 +0200 Subject: [PATCH] Document Zenoh (#5231) Signed-off-by: Alejandro Hernandez Cordero (cherry picked from commit 05a4bc3bf3150d5b7734c819eebbb03b4de65490) --- source/Installation.rst | 2 +- source/Installation/RMW-Implementations.rst | 27 ++++++ .../DDS-Implementations.rst | 9 +- .../Working-with-Eclipse-CycloneDDS.rst | 4 +- .../Working-with-GurumNetworks-GurumDDS.rst | 7 +- .../Working-with-RTI-Connext-DDS.rst | 2 +- .../Working-with-eProsima-Fast-DDS.rst | 4 +- .../Non-DDS-Implementations.rst | 15 +++ .../Working-with-Zenoh.rst | 95 +++++++++++++++++++ 9 files changed, 148 insertions(+), 17 deletions(-) create mode 100644 source/Installation/RMW-Implementations.rst rename source/Installation/{ => RMW-Implementations}/DDS-Implementations.rst (61%) rename source/Installation/{ => RMW-Implementations}/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst (92%) rename source/Installation/{ => RMW-Implementations}/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst (89%) rename source/Installation/{ => RMW-Implementations}/DDS-Implementations/Working-with-RTI-Connext-DDS.rst (98%) rename source/Installation/{ => RMW-Implementations}/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst (91%) create mode 100644 source/Installation/RMW-Implementations/Non-DDS-Implementations.rst create mode 100644 source/Installation/RMW-Implementations/Non-DDS-Implementations/Working-with-Zenoh.rst diff --git a/source/Installation.rst b/source/Installation.rst index d8d55fe99c0..390dd7dc08e 100644 --- a/source/Installation.rst +++ b/source/Installation.rst @@ -16,7 +16,7 @@ Options for installing ROS 2 {DISTRO_TITLE_FULL}: Installation/Alternatives Installation/Maintaining-a-Source-Checkout Installation/Testing - Installation/DDS-Implementations + Installation/RMW-Implementations Binary packages --------------- diff --git a/source/Installation/RMW-Implementations.rst b/source/Installation/RMW-Implementations.rst new file mode 100644 index 00000000000..f96f028230f --- /dev/null +++ b/source/Installation/RMW-Implementations.rst @@ -0,0 +1,27 @@ +.. redirect-from:: + + Installation/DDS-Implementations + +RMW implementations +=================== + +By default, ROS 2 uses DDS as its `middleware `__. +It is compatible with multiple DDS or RTPS (the DDS wire protocol) vendors. +There is currently support for eProsima's Fast DDS, RTI's Connext DDS, Eclipse Cyclone DDS, and GurumNetworks GurumDDS. + +It also supports non DDS RMW implementations such us Zenoh. + +See `REP-2000 `__ for supported RMW vendors by distribution. + +The default RMW vendor is eProsima's Fast DDS. + +Review all the possible options: + +.. toctree:: + :hidden: + :glob: + + RMW-Implementations/* + +* :doc:`DDS implementations ` explains how to use DDS. +* :doc:`Non DDS implementations ` explains how to use non DDS implementations. diff --git a/source/Installation/DDS-Implementations.rst b/source/Installation/RMW-Implementations/DDS-Implementations.rst similarity index 61% rename from source/Installation/DDS-Implementations.rst rename to source/Installation/RMW-Implementations/DDS-Implementations.rst index bbf635de3c7..f9f7b3cc8ce 100644 --- a/source/Installation/DDS-Implementations.rst +++ b/source/Installation/RMW-Implementations/DDS-Implementations.rst @@ -1,12 +1,7 @@ DDS implementations =================== -By default, ROS 2 uses DDS as its `middleware `__. -It is compatible with multiple DDS or RTPS (the DDS wire protocol) vendors. -There is currently support for eProsima's Fast DDS, RTI's Connext DDS, Eclipse Cyclone DDS, and GurumNetworks GurumDDS. -See `REP-2000 `__ for supported DDS vendors by distribution. - -The default DDS vendor is eProsima's Fast DDS. +These are the available DDS implementaions: * :doc:`Working with Eclipse Cyclone DDS ` explains how to utilize Cyclone DDS. * :doc:`Working with eProsima Fast DDS ` explains how to utilize Fast DDS. @@ -22,4 +17,4 @@ The default DDS vendor is eProsima's Fast DDS. If you would like to use one of the other vendors you will need to install their software separately before building. The ROS 2 build will automatically build support for vendors that have been installed and sourced correctly. -Once you've installed a new DDS vendor, you can change the vendor used at runtime: :doc:`Working with Multiple RMW Implementations <../How-To-Guides/Working-with-multiple-RMW-implementations>`. +Once you've installed a new RMW vendor, you can change the vendor used at runtime: :doc:`Working with Multiple RMW Implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>`. diff --git a/source/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst similarity index 92% rename from source/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst rename to source/Installation/RMW-Implementations/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst index d872fff5e6b..5a585a605f7 100644 --- a/source/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst +++ b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst @@ -13,7 +13,7 @@ See also: https://projects.eclipse.org/projects/iot.cyclonedds Prerequisites ------------- -Have :doc:`rosdep installed <../../Tutorials/Intermediate/Rosdep>`. +Have :doc:`rosdep installed <../../../Tutorials/Intermediate/Rosdep>`. Install packages ---------------- @@ -59,7 +59,7 @@ Switch from other rmw to rmw_cyclonedds by specifying the environment variable. export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp -See also: :doc:`Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>` +See also: :doc:`Working with multiple RMW implementations <../../../How-To-Guides/Working-with-multiple-RMW-implementations>` Run the talker and listener --------------------------- diff --git a/source/Installation/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst similarity index 89% rename from source/Installation/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst rename to source/Installation/RMW-Implementations/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst index 97a5472b7cf..60de2a94224 100644 --- a/source/Installation/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst +++ b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst @@ -10,7 +10,7 @@ For more information about GurumDDS, visit the `GurumNetworks website ` or :doc:`Building ROS 2 from source on Ubuntu <../Alternatives/Ubuntu-Development-Setup>`. +This guide assumes you have completed the ROS 2 environment setup process, either by :doc:`Installing ROS 2 via Deb Packages <../../Ubuntu-Install-Debs>` or :doc:`Building ROS 2 from source on Ubuntu <../../Alternatives/Ubuntu-Development-Setup>`. Version Requirements (`see the README for details `_): @@ -57,7 +57,7 @@ Option 2: Build from source code cd .. rosdep install --from src -i --rosdistro {DISTRO} -3. Build the worksapce using Colcon: +3. Build the workspace using Colcon: .. code-block:: bash @@ -72,8 +72,7 @@ Switch from other RMW implementations to rmw_gurumdds by setting the environment export RMW_IMPLEMENTATION=rmw_gurumdds_cpp -For more information on working with multiple RMW implementations, see :doc:`Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>`. - +For more information on working with multiple RMW implementations, see :doc:`Working with multiple RMW implementations <../../../How-To-Guides/Working-with-multiple-RMW-implementations>`. Testing the installation ------------------------ diff --git a/source/Installation/DDS-Implementations/Working-with-RTI-Connext-DDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-RTI-Connext-DDS.rst similarity index 98% rename from source/Installation/DDS-Implementations/Working-with-RTI-Connext-DDS.rst rename to source/Installation/RMW-Implementations/DDS-Implementations/Working-with-RTI-Connext-DDS.rst index 4816c55b834..e09a343b57b 100644 --- a/source/Installation/DDS-Implementations/Working-with-RTI-Connext-DDS.rst +++ b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-RTI-Connext-DDS.rst @@ -106,7 +106,7 @@ Set the environment variable ``RMW_IMPLEMENTATION`` to tell ROS 2 which RMW to u export RMW_IMPLEMENTATION=rmw_connextdds -See also: :doc:`Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>` +See also: :doc:`Working with multiple RMW implementations <../../../How-To-Guides/Working-with-multiple-RMW-implementations>` Run the talker and listener --------------------------- diff --git a/source/Installation/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst similarity index 91% rename from source/Installation/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst rename to source/Installation/RMW-Implementations/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst index 3aa4c0a5d0d..82d5c62dc59 100644 --- a/source/Installation/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst +++ b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst @@ -8,7 +8,7 @@ See also: https://www.eprosima.com/index.php/products-all/eprosima-fast-dds Prerequisites ------------- -Have :doc:`rosdep installed <../../Tutorials/Intermediate/Rosdep>`. +Have :doc:`rosdep installed <../../../Tutorials/Intermediate/Rosdep>`. Install packages ---------------- @@ -54,7 +54,7 @@ The eProsima Fast DDS RMW can be selected by specifying the environment variable export RMW_IMPLEMENTATION=rmw_fastrtps_cpp -See also: :doc:`Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>` +See also: :doc:`Working with multiple RMW implementations <../../../How-To-Guides/Working-with-multiple-RMW-implementations>` Run the talker and listener --------------------------- diff --git a/source/Installation/RMW-Implementations/Non-DDS-Implementations.rst b/source/Installation/RMW-Implementations/Non-DDS-Implementations.rst new file mode 100644 index 00000000000..33f8fcecf0b --- /dev/null +++ b/source/Installation/RMW-Implementations/Non-DDS-Implementations.rst @@ -0,0 +1,15 @@ +Non-DDS-Implementations +======================= + +* :doc:`Working with Zenoh ` explains how to utilize Zenoh. + +.. toctree:: + :hidden: + :glob: + + Non-DDS-Implementations/* + +If you would like to use one of the other vendors you will need to install their software separately before building. +The ROS 2 build will automatically build support for vendors that have been installed and sourced correctly. + +Once you've installed a new RMW vendor, you can change the vendor used at runtime: :doc:`Working with Multiple RMW Implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>`. diff --git a/source/Installation/RMW-Implementations/Non-DDS-Implementations/Working-with-Zenoh.rst b/source/Installation/RMW-Implementations/Non-DDS-Implementations/Working-with-Zenoh.rst new file mode 100644 index 00000000000..81e41510c46 --- /dev/null +++ b/source/Installation/RMW-Implementations/Non-DDS-Implementations/Working-with-Zenoh.rst @@ -0,0 +1,95 @@ +Zenoh +===== + +Zenoh is an open source communication protocol and middleware designed to facilitate efficient data distribution across heterogeneous systems. +It provides location-transparent abstractions for high performance pub/sub and distributed queries. +See also: https://zenoh.io/docs/getting-started/first-app/ + +Prerequisites +------------- + +Have :doc:`rosdep installed <../../../Tutorials/Intermediate/Rosdep>`. + +Installation packages +--------------------- + +The rmw implementation Zenoh can be installed via binaries, recommended for stable development. + +Binary packages for supported ROS 2 distributions (see distro branches) are available on respective Tier-1 platforms for the distributions. +First ensure that your system is set up to install ROS 2 binaries by following the instructions here. + +Then install rmw_zenoh binaries using the command + +.. code-block:: bash + + sudo apt install ros-{DISTRO}-rmw-zenoh-cpp + +Build from source code +---------------------- + +Built from source, recommended if latest features are needed. + +By default, we vendor and compile ``zenoh-cpp`` with a subset of zenoh features. +The ``ZENOHC_CARGO_FLAGS`` CMake argument may be overwritten with other features included if required. +See `zenoh_cpp_vendor/CMakeLists.txt `__ for more details. + +1. Clone the repository + +.. code-block:: bash + + mkdir ~/ws_rmw_zenoh/src -p && cd ~/ws_rmw_zenoh/src + git clone https://github.com/ros2/rmw_zenoh.git -b {DISTRO} + +1. Install dependencies: + +.. code-block:: bash + + cd ~/ws_rmw_zenoh + rosdep install --from-paths src --ignore-src --rosdistro {DISTRO} -y + +3. Build the workspace using Colcon: + +.. code-block:: bash + + source /opt/ros/{DISTRO}/setup.bash + colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release + + +Switch to rmw_zenoh_cpp +------------------------ + +Switch from other rmw to rmw_zenoh_cpp by specifying the environment variable. + +.. code-block:: bash + + export RMW_IMPLEMENTATION=rmw_zenoh_cpp + +Run the talker and listener +--------------------------- + +Now run ``talker`` and ``listener`` to test Zenoh. + +Start the Zenoh router + +.. code-block:: bash + + # terminal 1 + ros2 run rmw_zenoh_cpp talker rmw_zenohd + +.. note:: Without the Zenoh router, nodes will not be able to discover each other since multicast discovery is disabled by default in the node's session config. + Instead, nodes will receive discovery information about other peers via the Zenoh router's gossip functionality. + +.. code-block:: bash + + # terminal 2 + export RMW_IMPLEMENTATION=rmw_zenoh_cpp + ros2 run demo_nodes_cpp talker + +.. code-block:: bash + + # terminal 3 + export RMW_IMPLEMENTATION=rmw_zenoh_cpp + ros2 run demo_nodes_cpp listener + +.. note:: Remember to source your ROS 2 setup script before running these commands. +