.. _ros-connextrmw-install: ************************** Installing the Connext RMW ************************** There are multiple vendor-specific implementations of the ROS 2 RMW API, including |CONNEXT|. (See https://docs.ros.org/en/kilted/Installation/RMW-Implementations.html.) This chapter describes how to install the |CONNEXT| RMW. Installing the |CONNEXT| RMW for ROS 2 involves three basic steps: #. Install ROS 2. #. Install |CONNEXT|. #. Install the |CONNEXT| RMW. .. _ros-version-compatibility: Version Compatibility ===================== Each ROS 2 version is built and tested with a specific |CONNEXT| version to ensure functional and ABI compatibility. Using the versions in the table below guarantees that all libraries and tools work together as intended. .. list-table:: ROS 2 and Connext Compatibility :name: ROS2ConnextVersionComp :header-rows: 1 * - ROS 2 Version - Connext Version * - Kilted - 7.3.0 * - Jazzy - 6.0.1 * - Humble - 6.0.1 This documentation distinguishes between: - Officially supported combinations of ROS 2 and |CONNEXT| as shown in :numref:`ROS2ConnextVersionComp`, tested by RTI and eligible for support. - Other combinations that may work but are not supported by RTI and are used at your own risk. Using a |CONNEXT| version with a binary ROS 2 installation not shown in :numref:`ROS2ConnextVersionComp` may result in unexpected behavior. - |CONNEXT| standalone applications with ROS 2, regardless of the RMW that is used. See :numref:`getting-started-connext` or :numref:`enable-connext750-index`. If you need to use a different |CONNEXT| version than what's shown for the ROS 2 version in :numref:`ROS2ConnextVersionComp`, you must build both ROS 2 and the |CONNEXT| RMW from source to ensure compatibility. See :ref:`limitations-ki`. .. _connext-installation-options: Connext Installation Options ============================ A |CONNEXT| installation provides the libraries needed by the |CONNEXT| RMW. Without a |CONNEXT| installation, the |CONNEXT| RMW won't be able to find the libraries and will not work. To install |CONNEXT| for ROS 2, there are several options. The choice depends on your needs, platform, and licensing requirements. All options ultimately provide the same |CONNEXT| libraries and headers, but differ in licensing, features, and installation process. Which |CONNEXT| installation option to use depends on your use case: .. list-table:: Connext for ROS 2 - Installation Options :name: InstallationOptions :widths: 50 50 :header-rows: 1 * - Option / Use Case - Pros/Cons * - | `ROS-hosted .deb packages `__ | Typically used by the ROS 2 community - - Pros - Easiest option for early prototyping - No RTI-provided license required - Recommended for getting started - Cons - Very stripped-down |CONNEXT| installation - Non-commercial license. Not eligible for production - Notes - Available on Ubuntu via apt installation - Provided by the ROS 2 project - Includes only the |CONNEXT| versions listed in :numref:`ROS2ConnextVersionComp` * - | `RTI official .deb packages `__ | Typically used by prospects or customers evaluating the |CONNEXT| RMW - - Pros - Easy installation - Complete set of Connext tools - Suitable for production use - Cons - Requires RTI-provided license - Only available for Debian-based systems via apt * - | `RTI official .rtipkg installation (download) `__ | Typically used by RTI customers who require the full |CONNEXT| DDS feature set, including security, additional transports, etc. Use the 7.3.0 installation instructions `here `__. - - Pros - Full feature set for production - Available for Linux, Windows, and macOS - Cons - Requires RTI-provided license - Installed manually (unlike .deb installations, which are done with a single command) ROS 2 and Connext RMW Installation ================================== To run ROS 2 with the |CONNEXT| RMW, you need two things: 1. ROS 2 itself 2. A |CONNEXT| installation (see :ref:`connext-installation-options`) Once |CONNEXT| is installed, install ROS 2 with the |CONNEXT| RMW by following the official ROS 2 installation guide for your chosen distribution: for example, https://docs.ros.org/en/kilted/Installation.html. Before you start, note that ROS 2 is available in different installation formats, and the best choice depends on your system and needs: * **Binary packages:** * Debian (``.deb``) packages (Ubuntu systems only). This is the recommended and easiest way to get started. It uses your system's package manager for installation. * Binary archives (Linux and Windows systems). This is a good option if you do not have administrator privileges or prefer not to use a package manager. * **Source build** (available in Linux, Windows, and macOS systems). This is useful if you want to install specific packages or modify packages, or no binary packages are available for your specific platform. Ubuntu AMD/ARM -------------- This section explains how to install ROS 2 with the |CONNEXT| RMW on Ubuntu, whether you are using an AMD64 or ARM64 system. It covers three main steps: * Installing ROS 2 * Installing |CONNEXT| * Installing the |CONNEXT| RMW ROS 2 installation ^^^^^^^^^^^^^^^^^^ Follow the official ROS 2 instructions for your chosen installation format: * ``.deb`` **packages:** https://docs.ros.org/en/kilted/Installation/Ubuntu-Install-Debs.html * **Binary archives:** https://docs.ros.org/en/kilted/Installation/Alternatives/Ubuntu-Install-Binary.html * **Source build:** https://docs.ros.org/en/kilted/Installation/Alternatives/Ubuntu-Development-Setup.html Connext installation ^^^^^^^^^^^^^^^^^^^^ Once ROS 2 is installed, you need a |CONNEXT| installation for the |CONNEXT| RMW to work. Install |CONNEXT| using any of the methods described in :ref:`connext-installation-options`. For quick prototyping without an RTI-provided license, you can install the ROS-hosted ``.deb`` package for |CONNEXT|: .. code-block:: bash $ sudo apt update && sudo apt install -q -y rti-connext-dds-7.3.0-ros # Connext 7.3.0 $ sudo apt update && sudo apt install -q -y rti-connext-dds-6.0.1 # Connext 6.0.1 As with RTI official ``.deb`` packages, the installation will be located in: ``/opt/rti.com/rti_connext_dds-/``. You can have multiple |CONNEXT| installations in your system as long as you source the correct one. If you try to use a |CONNEXT| installation other than the one used to build the |CONNEXT| RMW in the first place (as given in :numref:`ROS2ConnextVersionComp`), the one used for building will be used by default. This mechanism is in place to avoid possible ABI incompatibilities. If you want, at your own risk, to use a |CONNEXT| installation other than given in :numref:`ROS2ConnextVersionComp`, set the environment variable ``CONNEXTDDS_IGNORE_BUILD=1`` to override the default behavior and use a different |CONNEXT| installation. See :ref:`limitations-ki`. Connext RMW installation ^^^^^^^^^^^^^^^^^^^^^^^^ As with ROS 2, the |CONNEXT| RMW also comes in multiple installation formats, described below: * ``.deb`` **packages** * **Binary archives** * **Source build** If you installed ROS 2 through binary archives, the |CONNEXT| RMW should already be included in the archive. If you built ROS 2 from source and compiled every package (like the instructions indicate), the |CONNEXT| RMW should then be compiled, too, and included in the installation. If you are an advanced user, you can tweak the ``colcon`` build system for more specific use cases. The following instructions assume ROS 2 was installed using ``.deb`` packages. Examples are shown for the Kilted distribution, but you can adapt them for other versions, such as Rolling or Jazzy. Debian packages """"""""""""""" When installed through Debian (``.deb``) packages, ROS 2 comes with the default RMW, which is ``rmw_fastdds``. To use any other RMW, you need to install the corresponding ``.deb`` package. To install the |CONNEXT| RMW via ``.deb`` package, use the following command: .. code-block:: bash $ sudo apt update && sudo apt install -q -y ros-kilted-rmw-connextdds This command installs the |CONNEXT| RMW package along with its dependency packages: * ``ros-kilted-rmw-connextdds``: Package with the |CONNEXT| RMW library. * ``ros-kilted-rmw-connextdds-common``: Package that contains the common implementation of the |CONNEXT| *Professional* RMW and the |CONNEXT| *Micro* RMW (deprecated). * ``ros-kilted-rti-connext-dds-cmake-module``: CMake utils to find the |CONNEXT| installation. * ``rti-connext-dds-7.3.0-ros``: ROS-hosted ``.deb`` package. This command should install all the libraries required by the RMW in the ROS 2 installation directory. Connext RMW source build """""""""""""""""""""""" Building from source code can ensure the |CONNEXT| RMW is matched to your system and installed correctly. The following instructions assume a Linux x86_64 |CONNEXT| host and target, such as ``rti_connext_dds-7.3.0-pro-host-x64Linux.run`` and ``rti_connext_dds-7.3.0-pro-target-x64Linux4gcc7.3.0.rtipkg``. Use the following commands to clone the repository for ``rmw_connextdds`` into your ROS 2 workspace and select the branch that matches the ROS 2 distribution in use: .. code-block:: bash $ mkdir -p ros2_ws/src $ cd ros2_ws $ git clone -b kilted https://github.com/ros2/rmw_connextdds src/rmw_connextdds Set up the environment to help ``colcon`` discover where *RTI* |CONNEXT| is installed. Do this by manually setting the environment variable ``NDDSHOME`` to the location of the |CONNEXT| installation, or by using a script that comes with the |CONNEXT| installation: .. code-block:: bash $ source ${RTI_CONNEXT_INSTALL_LOCATION}/resource/scripts/rtisetenv_x64Linux4gcc7.3.0.bash Make sure you have the ROS 2 environment set up: .. code-block:: bash $ source /opt/ros/kilted/setup.bash Build the |CONNEXT| RMW using ``colcon``: .. code-block:: bash $ colcon build --symlink-install After the build completes successfully, be sure to source the setup file for the workspace: .. code-block:: bash $ source install/setup.bash Windows ------- On Windows systems, ROS 2 does not provide |CONNEXT| binaries, so you must install |CONNEXT| first. `Download `__ and install |CONNEXT| following the `RTI Connext Professional Installation Guide `__. ROS 2 releases for Windows systems are available from the GitHub releases page: https://github.com/ros2/ros2/releases. You can install ROS 2 in two ways: * **Binary archives.** Follow the official guide: https://docs.ros.org/en/kilted/Installation/Windows-Install-Binary.html. The |CONNEXT| RMW is already included in the binary archive, so no separate installation is required. * **ROS 2 source build.** Follow the official guide: https://docs.ros.org/en/kilted/Installation/Alternatives/Windows-Development-Setup.html. When building from source, the |CONNEXT| RMW will be compiled along with the rest of ROS 2. Other systems ------------- To build ROS 2 in any other environment, check the alternatives provided by the ROS 2 documentation: https://docs.ros.org/en/kilted/Installation/Alternatives.html. .. _limitations-ki: Binary ROS 2 Packages and Connext Version ========================================= Each ROS 2 version (Kilted, Jazzy, etc.), when it's a binary package, is attached to a single version of |CONNEXT|. See :ref:`ros-version-compatibility`. Providing binary packages allows ROS 2 users to get started more quickly and easily. Binary packages are normally provided in two formats: * **Debian (.deb) and Red Hat (RPM) packages**: These are available for specific operating systems and distributions. * **Binary archives**: Compressed files with all the libraries needed for ROS 2 to work, along with ROS 2-specific tools and RMWs. While convenient, binary packages are tied to the |CONNEXT| version they were built with. ROS 2 and |CONNEXT| must be ABI-compatible, so replacing the installed |CONNEXT| version with a different one can lead to runtime failures. For example, Kilted binaries are compiled using |CONNEXT| 7.3.0. If you want to use the |CONNEXT| RMW with an underlying |CONNEXT| 7.5.0 installation (instead of a 7.3.0 one), the ABIs are not going to match, resulting in application crashes or unpredictable behavior. ABI-mismatch errors can be cryptic and hard to diagnose. For that reason, if you want to use a |CONNEXT| version that's not the default one in a specific ROS 2 release, you should build the |CONNEXT| RMW from source. This will ensure you are using the correct |CONNEXT| libraries in the RMW.