Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix connext references #1266

Merged
merged 2 commits into from
Mar 29, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 7 additions & 20 deletions source/Concepts/About-Different-Middleware-Vendors.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@ ROS 2 is built on top of DDS/RTPS as its middleware, which provides discovery, s
`This article <https://design.ros2.org/articles/ros_on_dds.html>`__ explains the motivation behind using DDS implementations, and/or the RTPS wire protocol of DDS, in detail.
In summary, DDS is an end-to-end middleware that provides features which are relevant to ROS systems, such as distributed discovery (not centralized like in ROS 1) and control over different "Quality of Service" options for the transportation.

`DDS <https://www.omg.org/omg-dds-portal>`__ is an industry standard which is implemented by a range of vendors, such as RTI's implementation `Connext <https://www.rti.com/products/>`__, ADLINK's implementation `OpenSplice <https://github.com/ADLINK-IST/opensplice>`__ or `Eclipse's Cyclone DDS <https://projects.eclipse.org/projects/iot.cyclonedds>`__.
`DDS <https://www.omg.org/omg-dds-portal>`__ is an industry standard which is implemented by a range of vendors, such as RTI's `Connext DDS <https://www.rti.com/products/>`__, eProsima's `Fast-DDS <https://fast-dds.docs.eprosima.com/>`__, or Eclipse's `Cyclone DDS <https://projects.eclipse.org/projects/iot.cyclonedds>`__.
RTPS (a.k.a. `DDSI-RTPS <https://www.omg.org/spec/DDSI-RTPS/About-DDSI-RTPS/>`__\ ) is the wire protocol used by DDS to communicate over the network.
There are implementations of that which do not fulfill the full DDS API, but provide sufficient functionality for ROS 2, such as eProsima's implementation `Fast RTPS <http://www.eprosima.com/index.php/products-all/eprosima-fast-rtps>`__.

ROS 2 supports multiple DDS/RTPS implementations because it is not necessarily "one size fits all" when it comes to choosing a vendor/implementation.
There are many factors you might consider while choosing a middleware implementation: logistical considerations like the license, or technical considerations like platform availability, or computation footprint.
Expand All @@ -31,43 +30,33 @@ Supported RMW implementations
- License
- RMW implementation
- Status
* - eProsima *Fast RTPS*
* - eProsima *Fast DDS*
- Apache 2
- ``rmw_fastrtps_cpp``
- Full support. Default RMW in Foxy and before. Packaged with binary releases.
* - Eclipse *Cyclone DDS*
- Eclipse Public License v2.0
- ``rmw_cyclonedds_cpp``
- Full support. Default RMW since Galactic. Packaged with binary releases.
* - RTI *Connext*
* - RTI *Connext DDS*
- commercial, research
- ``rmw_connext_cpp``
- ``rmw_connextdds``
- Full support. Support included in binaries, but Connext installed separately.
* - RTI *Connext* (dynamic implementation)
- commercial, research
- ``rmw_connext_dynamic_cpp``
- Support paused. Full support until alpha 8.*
* - ADLINK *Opensplice*
- Apache 2, commercial
- ``rmw_opensplice_cpp``
- Partial support. Support included in binaries before Foxy, but OpenSplice installed separately.

*"Partial support" means that one or more of the features required by the rmw interface is not implemented.*

For practical information on working with multiple RMW implementations, see the `"Working with multiple RMW implementations" <../Guides/Working-with-multiple-RMW-implementations>` tutorial.

Multiple RMW implementations
----------------------------

The ROS 2 binary releases for currently active distros have built-in support for several RMW implementations out of the box (Fast DDS, RTI Connext Pro, ADLINK Eclipse Cyclone DDS).
The ROS 2 binary releases for currently active distros have built-in support for several RMW implementations out of the box (Fast DDS, RTI Connext Pro, Eclipse Cyclone DDS).
Since Galactic, the default is Cyclone DDS, which works without any additional installation steps, because we distribute it with our binary packages.
Prior to Galactic, the default was Fast DDS, which works without any additional installation steps.

Other RMWs like Fast-DDS or Connext can be enabled by `installing additional packages <../Installation/DDS-Implementations>`, but without having to rebuild anything or replace any existing packages.

A ROS 2 workspace that has been built from source may build and install multiple RMW implementations simultaneously.
While the core ROS 2 code is being compiled, any RMW implementation that is found will be built if the relevant DDS/RTPS implementation has been installed properly and the relevant environment variables have been configured.
For example, if the code for the `RMW package for RTI Connext <https://github.com/ros2/rmw_connext/tree/master/rmw_connext_cpp>`__ is in the workspace, it will be built if an installation of RTI's Connext Pro can also be found.
For example, if the code for the `RMW package for RTI Connext DDS <https://github.com/ros2/rmw_connextdds>`__ is in the workspace, it will be built if an installation of RTI's Connext Pro can also be found.

For many cases you will find that nodes using different RMW implementations are able to communicate, however this is not true under all circumstances.
Here is a list of inter-vendor communication configurations that are not supported:
Expand All @@ -80,16 +69,14 @@ Here is a list of inter-vendor communication configurations that are not support
- ``WString`` is mapped to ``String`` which has a different wire representation
- Connext <-> Cyclone DDS
- does not support pub/sub communication for ``WString``
- Connext Dynamic <-> Connext Dynamic
- does not support C services

Default RMW implementation
--------------------------

If a ROS 2 workspace has multiple RMW implementations, the default RMW implementation since Galactic is selected as Cyclone DDS if it's available.
If the Cyclone DDS RMW implementation is not installed, the RMW implementation with the first RMW implementation identifier in alphabetical order will be used.
The implementation identifier is the name of the ROS package that provides the RMW implementation, e.g. ``rmw_cyclonedds_cpp``.
For example, if both ``rmw_fastrtps_cpp`` and ``rmw_connext_cpp`` ROS packages are installed, ``rmw_connext_cpp`` would be the default.
For example, if both ``rmw_fastrtps_cpp`` and ``rmw_connextdds`` ROS packages are installed, ``rmw_connextdds`` would be the default.
If ``rmw_cyclonedds_cpp`` is ever installed, it would be the default.

See the `guide <../Guides/Working-with-multiple-RMW-implementations>` for how to specify which RMW implementation is to be used when running the ROS 2 examples.
6 changes: 3 additions & 3 deletions source/Concepts/About-Internal-Interfaces.rst
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,9 @@ For middleware vendors based on DDS, and specifically those which generate code
From these OMG IDL files, vendor specific code is created and then used within the type specific functions which are referenced by the type support for a given type.
The above diagram shows this on the left hand side, where the ``.msg`` files are consumed by the ``rosidl_dds`` package to produce ``.idl`` files, and then those ``.idl`` files are given to language specific and DDS vendor specific type support generation packages.

For example, consider the Connext DDS implementation, it has a package called ``rosidl_typesupport_connext_cpp``.
This package is responsible for generating code to handle do things like publish to a topic for the C++ version of a given message type, using the ``.idl`` files generated by the ``rosidl_dds`` package to do so.
Again, this code, while specific to Connext, is still not exposed to the user because of the abstraction in the type support.
For example, consider the Fast DDS implementation, which has a package called ``rosidl_typesupport_fastrtps_cpp``.
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.

Dynamic Type Support
^^^^^^^^^^^^^^^^^^^^
Expand Down
19 changes: 7 additions & 12 deletions source/Concepts/About-Middleware-Implementations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Common Packages for DDS Middleware Packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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-RTPS.
For example, there is a middleware implementation that uses RTI's Connext DDS and an implementation which uses eProsima's Fast-DDS.
Because of this, there are some shared |packages| amongst most DDS based middleware implementations.

In the `ros2/rosidl_dds <https://github.com/ros2/rosidl_dds>`_ repository on |GitHub|_, there is the following |package|:
Expand All @@ -30,8 +30,9 @@ A ROS middleware implementation is typically made up of a few |packages| in a si
- ``rosidl_typesupport_<implementation_name>_<language>``: contains tools to generate static type support code for ``rosidl`` files, tailored to the implementation in a particular language, typically C or C++

The ``<implementation_name>_cmake_module`` |package| contains any CMake Modules and functions needed to find the supporting dependencies for the middleware implementation.
In the case of ``connext_cmake_module`` it has CMake Modules for finding the RTI Connext implementation in different places on the system since it does not ship with a CMake Module itself.
Not all repositories will have a package like this, for example eProsima's Fast-RTPS provides a CMake module and so no additional one is required.
For example, ``rti_connext_dds_cmake_module`` provides wrapper logic around the CMake Module shipped with RTI Connext DDS to make sure that all packages that depend on it will select the same installation of RTI Connext DDS.
Similarly, ``fastrtps_cmake_module`` includes a CMake Module to find eProsima's Fast-DDS.
Not all implementations will have a package like this: for example, Eclipe's Cyclone DDS already provides a CMake Module which is used directly by its RMW implementation without the need of additional wrappers.

The ``rmw_<implementation_name>_<language>`` |package| implements the ``rmw`` C |API| in a particular language.
The implementation itself can be C++, it just must expose the header's symbols as ``extern "C"`` so that C applications can link against it.
Expand All @@ -45,18 +46,12 @@ As mentioned above, the ``rosidl_typesupport_introspection_<language>`` may be u
This ability to programmatically send and receive types over topics without generating code beforehand is achieved by supporting the `DDS X-Types Dynamic Data standard <http://www.omg.org/spec/DDS-XTypes>`_.
As such, rmw implementations may provide support for the X-Types standard, and/or provide a package for type support generated at compile time specific to their DDS implementation.

As an example of an rmw implementation repository, the ``opensplice`` ROS middleware implementation lives on |GitHub|_ at `ros2/rmw_opensplice <https://github.com/ros2/rmw_opensplice>`_ and has these |packages|:
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>`_.

- ``opensplice_cmake_module``
- ``rmw_opensplice_cpp``
- ``rosidl_typesupport_opensplice_c``
- ``rosidl_typesupport_opensplice_cpp``
The rmw implementation for ``Fast-DDS`` is on |GitHub|_ at `ros2/rmw_fastrtps_cpp <https://github.com/ros2/rmw_fastrtps_cpp>`_.

In addition to the ``opensplice`` repository of |packages|, there is the ``connext`` implementation on |GitHub|_ at `ros2/rmw_connext <https://github.com/ros2/rmw_connext>`_.
It contains mostly the same |packages|, but it additionally contains a |package| to support the type support introspection using the DDS X-Types standard.
The rmw implementation for ``Connext DDS`` is on |GitHub|_ at `ros2/rmw_connextdds <https://github.com/ros2/rmw_connextdds>`_.

The rmw implementation using ``FastRTPS`` is on |GitHub|_ at `eProsima/ROS-RMW-Fast-RTPS-cpp <https://github.com/eProsima/ROS-RMW-Fast-RTPS-cpp>`_.
As ``FastRTPS`` currently only supports the type support introspection, there is no vendor specific type support package in this repository.

To learn more about what is required to create a new middleware implementation for ROS see this page:

Expand Down
8 changes: 4 additions & 4 deletions source/Contributing/Developer-Guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -339,14 +339,14 @@ Changes to RMW API
^^^^^^^^^^^^^^^^^^

When updating `RMW API <https://github.com/ros2/rmw>`__, it is required that RMW implementations for the Tier 1 middleware libraries are updated as well.
For example, a new function ``rmw_foo()`` introduced to the RMW API must be implemented in the following packages (as of ROS Foxy):
For example, a new function ``rmw_foo()`` introduced to the RMW API must be implemented in the following packages (as of ROS Galactic):

* `rmw_fastrtps <https://github.com/ros2/rmw_fastrtps>`__
* `rmw_connext <https://github.com/ros2/rmw_connext>`__
* `rmw_connextdds <https://github.com/ros2/rmw_connextdds>`__
* `rmw_cyclonedds <https://github.com/ros2/rmw_cyclonedds>`__
* `rmw_fastrtps <https://github.com/ros2/rmw_fastrtps>`__

Updates for non-Tier 1 middleware libraries should also be considered if feasible (e.g. depending on the size of the change).
See `REP-2000 <https://www.ros.org/reps/rep-2000.html#crystal-clemmys-december-2018-december-2019>`__ for the list of middleware libraries and their tiers.
See `REP-2000 <https://www.ros.org/reps/rep-2000.html>`__ for the list of middleware libraries and their tiers.

Tracking tasks
^^^^^^^^^^^^^^
Expand Down
5 changes: 2 additions & 3 deletions source/Feature-Ideas.rst
Original file line number Diff line number Diff line change
Expand Up @@ -128,9 +128,8 @@ The trailing stars indicate the rough effort: 1 star for small, 2 stars for medi
* Implement C client library ``rclc`` [\*\*]
* Support more DDS / RTPS implementations:

* Connext 6, see `ros2/rmw_connext#375 <https://github.com/ros2/rmw_connext/issues/375>`_
* Connext dynamic [\*]
* RTI's micro implementation [\*]
* RTI Connext DDS 6.x (implemented, not enabled by default).
* RTI Connext DDS Micro (implemented, not enabled by default or officially supported).

* security improvements:

Expand Down
4 changes: 2 additions & 2 deletions source/Features.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Features Status
===============

The features listed below are available in the current ROS 2 release.
Unless otherwise specified, the features are available for all supported platforms (Ubuntu 18.04, macOS 10.12.x, Windows 10), DDS implementations (eProsima Fast RTPS, RTI Connext and ADLINK Opensplice) and programming language client libraries (C++ and Python).
Unless otherwise specified, the features are available for all supported platforms (Ubuntu 20.04, macOS 10.14.x, Windows 10), DDS implementations (eProsima Fast DDS, RTI Connext DDS, and Eclipse Cyclone DDS) and programming language client libraries (C++ and Python).
For planned future development, see the :ref:`Roadmap <Roadmap>`.

.. list-table::
Expand All @@ -18,7 +18,7 @@ For planned future development, see the :ref:`Roadmap <Roadmap>`.
-
* - Support for `multiple DDS implementations <Concepts/About-Different-Middleware-Vendors>`, chosen at runtime
- `Concept <Concepts/About-Different-Middleware-Vendors>`, `Guide <Guides/Working-with-multiple-RMW-implementations>`
- Currently ADLINK CycloneDDS, eProsima Fast RTPS, and RTI Connext are fully supported.
- Currently Eclipse Cyclone DDS, eProsima Fast DDS, and RTI Connext DDS are fully supported.
* - Common core client library that is wrapped by language-specific libraries
- `Details <Concepts/About-ROS-2-Client-Libraries>`
-
Expand Down
20 changes: 10 additions & 10 deletions source/Guides/Working-with-multiple-RMW-implementations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -35,36 +35,36 @@ To run the talker demo using the C++ and listener using Python with the RMW impl

.. code-block:: bash

RMW_IMPLEMENTATION=rmw_connext_cpp ros2 run demo_nodes_cpp talker
RMW_IMPLEMENTATION=rmw_connextdds ros2 run demo_nodes_cpp talker

# Run in another terminal
RMW_IMPLEMENTATION=rmw_connext_cpp ros2 run demo_nodes_py listener
RMW_IMPLEMENTATION=rmw_connextdds ros2 run demo_nodes_py listener

.. group-tab:: macOS

.. code-block:: bash

RMW_IMPLEMENTATION=rmw_connext_cpp ros2 run demo_nodes_cpp talker
RMW_IMPLEMENTATION=rmw_connextdds ros2 run demo_nodes_cpp talker

# Run in another terminal
RMW_IMPLEMENTATION=rmw_connext_cpp ros2 run demo_nodes_py listener
RMW_IMPLEMENTATION=rmw_connextdds ros2 run demo_nodes_py listener

.. group-tab:: Windows

.. code-block:: bat

set RMW_IMPLEMENTATION=rmw_connext_cpp
set RMW_IMPLEMENTATION=rmw_connextdds
ros2 run demo_nodes_cpp talker

REM run in another terminal
set RMW_IMPLEMENTATION=rmw_connext_cpp
set RMW_IMPLEMENTATION=rmw_connextdds
ros2 run demo_nodes_py listener

Adding RMW implementations to your workspace
--------------------------------------------

Suppose that you have built your ROS 2 workspace with only Cyclone DDS installed and therefore only the Cyclone DDS RMW implementation built.
The last time your workspace was built, any other RMW implementation packages, ``rmw_connext_cpp`` for example, were probably unable to find installations of the relevant DDS implementations.
The last time your workspace was built, any other RMW implementation packages, ``rmw_connextdds`` for example, were probably unable to find installations of the relevant DDS implementations.
If you then install an additional DDS implementation, Connext for example, you will need to re-trigger the check for a Connext installation that occurs when the Connext RMW implementation is being built.
You can do this by specifying the ``--cmake-force-configure`` flag on your next workspace build, and you should see that the RMW implementation package then gets built for the newly installed DDS implementation.

Expand All @@ -81,13 +81,13 @@ If the ``RMW_IMPLEMENTATION`` environment variable is set to an RMW implementati

.. code-block:: bash

Expected RMW implementation identifier of 'rmw_connext_cpp' but instead found 'rmw_fastrtps_cpp', exiting with 102.
Expected RMW implementation identifier of 'rmw_connextdds' but instead found 'rmw_fastrtps_cpp', exiting with 102.

If you have support for multiple RMW implementations installed and you request use of one that is not installed, you will see something similar to:

.. code-block:: bash

Error getting RMW implementation identifier / RMW implementation not installed (expected identifier of 'rmw_connext_cpp'), exiting with 1.
Error getting RMW implementation identifier / RMW implementation not installed (expected identifier of 'rmw_connextdds'), exiting with 1.

If this occurs, double check that your ROS 2 installation includes support for the RMW implementation that you have specified in the ``RMW_IMPLEMENTATION`` environment variable.

Expand All @@ -96,7 +96,7 @@ For example, if you run:

.. code-block:: bash

RMW_IMPLEMENTATION=rmw_connext_cpp ros2 run demo_nodes_cpp talker
RMW_IMPLEMENTATION=rmw_connextdds ros2 run demo_nodes_cpp talker

and

Expand Down
2 changes: 1 addition & 1 deletion source/Installation/Linux-Install-Binary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Set your rosdistro according to the release you downloaded.

.. code-block:: bash

rosdep install --from-paths ~/ros2_rolling/ros2-linux/share --ignore-src --rosdistro rolling -y --skip-keys "console_bridge fastcdr fastrtps osrf_testing_tools_cpp poco_vendor rmw_connext_cpp rosidl_typesupport_connext_c rosidl_typesupport_connext_cpp rti-connext-dds-5.3.1 tinyxml_vendor tinyxml2_vendor urdfdom urdfdom_headers"
rosdep install --from-paths ~/ros2_rolling/ros2-linux/share --ignore-src --rosdistro rolling -y --skip-keys "console_bridge fastcdr fastrtps osrf_testing_tools_cpp poco_vendor rmw_connextdds rti-connext-dds-5.3.1 tinyxml_vendor tinyxml2_vendor urdfdom urdfdom_headers"

#. *Optional*\ : if you want to use the ROS 1<->2 bridge, then you must also install ROS 1.
Follow the normal install instructions: http://wiki.ros.org/noetic/Installation/Ubuntu
Expand Down
Loading