Add rmw implementation tutorial (#5927)

Signed-off-by: Christophe Bedard <[email protected]>
Co-authored-by: gavanderhoorn <[email protected]>
Co-authored-by: William Woodall <[email protected]>
Co-authored-by: Chris Lalancette <[email protected]>
(cherry picked from commit e831830)

# Conflicts:
#	source/Concepts/Advanced/About-Middleware-Implementations.rst

Author: christophebedard

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
 -------------------------

source/Concepts/Advanced/About-Middleware-Implementations.rst

@@ -12,8 +12,15 @@ ROS 2 middleware implementations
 
 ROS middleware implementations are sets of |packages| that implement some of the internal ROS interfaces, e.g. the ``rmw``, ``rcl``, and ``rosidl`` |APIs|.
 
+<<<<<<< HEAD
 Common Packages for DDS Middleware Packages
 -------------------------------------------
+=======
+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
+--------------------------------------------------
+>>>>>>> e831830 (Add rmw implementation tutorial (#5927))
 
 All of the current ROS middleware implementations are based on full or partial DDS implementations.
 For example, there is a middleware implementation that uses RTI's Connext DDS and an implementation which uses eProsima's Fast DDS.
@@ -26,7 +33,13 @@ In the `ros2/rosidl_dds <https://github.com/ros2/rosidl_dds>`_ repository on |Gi
 The ``rosidl_generator_dds_idl`` |package| generates a DDS ``.idl`` file for each ``rosidl`` file, e.g. ``.msg`` file, defined by |packages| containing messages.
 Currently DDS based ROS middleware implementations make use of this generator's output ``.idl`` files to generate pre-compiled type support that is vendor specific.
 
+<<<<<<< HEAD
 Structure of ROS Middleware Implementations
+=======
+.. _about-middleware-impls_struct_dds:
+
+Structure of DDS Middleware Implementations
+>>>>>>> e831830 (Add rmw implementation tutorial (#5927))
 -------------------------------------------
 
 A ROS middleware implementation is typically made up of a few |packages| in a single repository:
@@ -54,7 +67,55 @@ As such, rmw implementations may provide support for the X-Types standard, and/o
 
 As an example of an rmw implementation repository, the ``Eclipse Cyclone DDS`` ROS middleware implementation is on |GitHub|_ at `ros2/rmw_cyclonedds <https://github.com/ros2/rmw_cyclonedds>`_.
 
+<<<<<<< HEAD
 The rmw implementation for ``Fast DDS`` is on |GitHub|_ at `ros2/rmw_fastrtps_cpp <https://github.com/ros2/rmw_fastrtps_cpp>`_.
+=======
+| The ``Eclipse Cyclone DDS`` ROS middleware implementation is on |GitHub|_ at `ros2/rmw_cyclonedds <https://github.com/ros2/rmw_cyclonedds>`_.
+| The RMW implementation for ``Fast DDS`` is on |GitHub|_ at `ros2/rmw_fastrtps_cpp <https://github.com/ros2/rmw_fastrtps_cpp>`_.
+| 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
+------------------------------------------------
+
+For data to be sent and received over Zenoh using ROS 2, the middleware package, ``rmw_zenoh_cpp``, maps the ROS 2 middleware |API| to Zenoh's |APIs| using `zenoh-c <https://github.com/eclipse-zenoh/zenoh-c>`_.
+Unlike DDS-based implementations, this middleware relies on a Zenoh router to discover peers and pass discovery information along via Zenoh's 'gossip scouting'.
+Therefore, ``rmw_zenoh_cpp`` requires the Zenoh router (``zenohd``) to be active on the local system or reachable over the network.
+
+In ROS 2's Zenoh integration, each `context <https://docs.ros.org/en/rolling/p/rclcpp/generated/classrclcpp_1_1Context.html>`_ is mapped to a single Zenoh session.
+This session is shared across all publishers, subscriptions, services, and clients within that context.
+The context maintains a local graph cache that tracks the network topology of ROS 2 entities and the presence of each entity is managed through unique liveliness tokens issued on creation and revoked during destruction.
+
+Here is an inexhaustive list of how the Zenoh middleware |API| adapts ROS 2 entities over its communication protocol:
+
+**Nodes:** Nodes in ROS 2 have been referred to as "units of computation" in a ROS 2 graph, whereby each node should be responsible for a single, modular purpose.
+Zenoh has no direct counterpart to the node, so ``rmw_zenoh_cpp`` creates no Zenoh entities for them.
+However, when a node is created through the RMW |API|, a liveliness token of type ``NN`` is declared.
+
+**Publishers:** A ROS 2 publisher sends data to a specific topic.
+Because Zenoh publishers function very similarly with Keys, ``rmw_zenoh_cpp`` maps these entities directly.
+When a publisher is created through the RMW |API|, a liveliness token of type ``MP`` is declared.
+
+**Subscribers:** Subscribers in ROS 2 listen on topics for new data.
+They are conceptually equivalent to subscribers in Zenoh so ``rmw_zenoh_cpp`` maps these entities directly.
+When new data arrives, Zenoh's middleware |package| invokes an internal callback that takes ownership of the data and signals availability to ``rmw_wait``.
+When a subscriber is created through the RMW |API|, a liveliness token of type ``MS`` is declared.
+
+**Service clients:** ``rmw_zenoh_cpp`` uses Zenoh queryables to implement ROS 2 services.
+Clients use ``rmw_send_request`` to make requests in ROS 2.
+A request will carry metadata that will be used to correlate a response, like its sequence number and the GUID of the client that sent it.
+Zenoh's middleware |package| can then use ``z_get`` to send a query out into the network.
+When a client is created through the RMW |API|, a liveliness token of type ``SC`` is declared.
+
+**Service server:** ``rmw_zenoh_cpp`` uses Zenoh queryables to implement ROS 2 services.
+ROS 2 nodes use ``rmw_create_service`` to advertise services to the network and the Zenoh |API|, ``z_declare_queryable``, is used to create the server-side representation of a ROS 2 service.
+``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 `ros2/rmw_zenoh <https://github.com/ros2/rmw_zenoh/tree/rolling>`_.
+>>>>>>> e831830 (Add rmw implementation tutorial (#5927))
 
 The rmw implementation for ``Connext DDS`` is on |GitHub|_ at `ros2/rmw_connextdds <https://github.com/ros2/rmw_connextdds>`_.
 

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
 --------------

source/How-To-Guides/Ament-CMake-Documentation.rst

@@ -459,6 +459,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
 ----------------
 

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
 ------------------
 

source/Tutorials/Advanced.rst

@@ -14,5 +14,6 @@ Advanced
    Advanced/Recording-A-Bag-From-Your-Own-Node-Py
    Advanced/Reading-From-A-Bag-File-CPP
    Advanced/ROS2-Tracing-Trace-and-Analyze
+   Advanced/Creating-An-RMW-Implementation
    Advanced/Simulators/Simulation-Main
    Advanced/Security/Security-Main