Add rmw implementation tutorial (#5927)

christophebedard · gavanderhoorn · wjwwood · web-flow · commit e831830713ff · 2025-10-16T13:04:53.000-07:00
Signed-off-by: Christophe Bedard &lt;bedard.christophe@gmail.com&gt;
Co-authored-by: gavanderhoorn &lt;g.a.vanderhoorn@tudelft.nl&gt;
Co-authored-by: William Woodall &lt;wjwwood@gmail.com&gt;
Co-authored-by: Chris Lalancette &lt;clalancette@gmail.com&gt;
diff --git a/source/Concepts/Advanced/About-Internal-Interfaces.rst b/source/Concepts/Advanced/About-Internal-Interfaces.rst
@@ -65,6 +65,8 @@ In this context, type support means: meta data or functions that are specific to
 The type support for a given message might include things like a list of the names and types for each field in the message.
 It might also contain a reference to code that can perform particular tasks for that type, e.g. publish a message.
 
+.. _internal-interfaces_static-type-support:
+
 Static Type Support
 ^^^^^^^^^^^^^^^^^^^
 
@@ -84,6 +86,8 @@ For example, consider the Fast DDS implementation, which has a package called ``
 This package is responsible for generating code to handle things like converting a C++ message object into a serialized octet buffer to be written over the network.
 This code, while specific to Fast DDS, is still not exposed to the user because of the abstraction in the type support code.
 
+.. _internal-interfaces_dynamic-type-support:
+
 Dynamic Type Support
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -137,13 +141,14 @@ The ``rmw`` repository
 
 The ROS middleware interface (``rmw`` |API|) is the minimal set of primitive middleware capabilities needed to build ROS on top.
 Providers of different middleware implementations must implement this interface in order to support the entire ROS stack on top.
-Currently all of the middleware implementations are for different DDS vendors.
+Currently most of the middleware implementations are for different DDS vendors.
 
 The ``rmw`` |API| is located in the `ros2/rmw <https://github.com/ros2/rmw>`_ repository.
 The ``rmw`` |package| contains the C headers which define the interface, the implementation of which is provided by the various |packages| of rmw implementations for different DDS vendors.
 
 For a definition of the ``rmw`` |API|, see `the rmw docs <http://docs.ros.org/en/{DISTRO}/p/rmw/>`_.
 
+For a more practical in-depth overview of how ROS 2 integrates with different middleware implementations, see :doc:`the middleware implementation tutorial <../../Tutorials/Advanced/Creating-An-RMW-Implementation>`.
 
 The ``rosidl`` repository
 -------------------------
diff --git a/source/Concepts/Advanced/About-Middleware-Implementations.rst b/source/Concepts/Advanced/About-Middleware-Implementations.rst
@@ -14,6 +14,8 @@ ROS middleware implementations are sets of |packages| that provide the underlyin
 These packages interact with core ROS 2 interfaces such as the ``rmw``, ``rcl``, and ``rosidl`` |APIs| to integrate with external protocols like Zenoh, DDS, or others.
 For example, ``rmw_fastrtps_cpp`` adapts eProsima's Fast DDS implementation to ROS 2's middleware |API|, while ``rmw_zenoh_cpp`` provides similar integration for the Zenoh protocol.
 
+For a more practical in-depth overview of how ROS 2 integrates with different middleware implementations, see :doc:`the middleware implementation tutorial <../../Tutorials/Advanced/Creating-An-RMW-Implementation>`.
+
 Common Packages for DDS Middleware Implementations
 --------------------------------------------------
 
@@ -29,6 +31,8 @@ The ``rosidl_generator_dds_idl`` |package| generates a DDS ``.idl`` file for eac
 These interface definition files specify the data structures used for topics, services, and actions in ROS 2.
 DDS-based ROS middleware implementations then use these generated ``.idl`` files to create vendor-specific pre-compiled type support.
 
+.. _about-middleware-impls_struct_dds:
+
 Structure of DDS Middleware Implementations
 -------------------------------------------
 
@@ -62,6 +66,8 @@ For examples of example of DDS RMW implementation repositories,
 | The RMW implementation for ``Connext DDS`` is on |GitHub|_ at `ros2/rmw_connextdds <https://github.com/ros2/rmw_connextdds>`_.
 | The RMW implementation for ``GurumDDS`` is on |GitHub|_ at `ros/rmw_gurumdds <https://github.com/ros2/rmw_gurumdds>`_.
 
+.. _about-middleware-impls_struct_zenoh:
+
 Structure of the Zenoh Middleware Implementation
 ------------------------------------------------
 
@@ -99,6 +105,6 @@ ROS 2 nodes use ``rmw_create_service`` to advertise services to the network and
 ``rmw_take_request`` delivers the query to the use callback to be processed and after the computation is complete, ``rmw_send_reponse`` returns the result to the requester.
 When a server is created, a liveliness token of type ``SS`` is declared.
 
-The RMW implementation for ``Zenoh`` is on |GitHub|_ at `ros/rmw_zenoh <https://github.com/ros2/rmw_zenoh/tree/rolling>`_.
+The RMW implementation for ``Zenoh`` is on |GitHub|_ at `ros2/rmw_zenoh <https://github.com/ros2/rmw_zenoh/tree/rolling>`_.
 
 
diff --git a/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst b/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst
@@ -121,6 +121,7 @@ The currently defined QoS profiles are:
 `Click here <https://github.com/ros2/rmw/blob/{REPOS_FILE_BRANCH}/rmw/include/rmw/qos_profiles.h>`__ for the specific policies in use for the above profiles.
 The settings in these profiles are subject to further tweaks, based on the feedback from the community.
 
+.. _about-qos_compatibilities:
 
 QoS compatibilities
 -------------------
@@ -279,6 +280,7 @@ Comparison to ROS 1
 Historically in ROS 1, any publisher and subscriber with the same message type on the same topic would be connected.
 The possibility of incompatible requested and offered QoS profiles is something new to be aware of when using ROS 2.
 
+.. _about-qos_qos-events:
 
 QoS events
 ----------
@@ -314,6 +316,7 @@ Developers may subscribe to the following QoS events that are associated with a
 
   The subscription has encountered a publisher on the same topic that is offering a QoS profile that does not satisfy the requested QoS profile, resulting in no connection between the subscription and that publisher.
 
+.. _about-qos_matched-events:
 
 Matched events
 --------------
diff --git a/source/How-To-Guides/Ament-CMake-Documentation.rst b/source/How-To-Guides/Ament-CMake-Documentation.rst
@@ -442,6 +442,8 @@ To do so:
 Ament extensions work by defining a variable containing the name of the extension point and filling it with the macros to be executed.
 Upon calling ``ament_execute_extensions``, the scripts defined in the variable are then executed one after another.
 
+.. _ament-cmake-doc_adding-resources:
+
 Adding resources
 ----------------
 
diff --git a/source/How-To-Guides/DDS-tuning.rst b/source/How-To-Guides/DDS-tuning.rst
@@ -96,6 +96,8 @@ Fast RTPS tuning
 
 See the solutions under :ref:`Cross-vendor tuning <cross-vendor-tuning>`.
 
+.. _cyclonedds-tuning:
+
 Cyclone DDS tuning
 ------------------
 
diff --git a/source/Tutorials/Advanced.rst b/source/Tutorials/Advanced.rst
@@ -17,5 +17,6 @@ Advanced
    Advanced/Reading-From-A-Bag-File-CPP
    Advanced/Reading-From-A-Bag-File-Python
    Advanced/ROS2-Tracing-Trace-and-Analyze
+   Advanced/Creating-An-RMW-Implementation
    Advanced/Simulators/Simulation-Main
    Advanced/Security/Security-Main
diff --git a/source/Tutorials/Advanced/Creating-An-RMW-Implementation.rst b/source/Tutorials/Advanced/Creating-An-RMW-Implementation.rst
