.. _tutorial-simplified-installation:

**************************************
Tutorial: RTI Connext Robotics Toolkit  
**************************************

This tutorial describes the simplest way to set up a complete ROS 2 and
|CONNEXT| development environment on Ubuntu using the RTI Connext Robotics Toolkit.

This information is intended for users who want a fully functional system 
with minimal manual installation steps. On completion, this installation 
includes support for running ROS 2 applications with the |CONNEXT| RMW,
as well as standalone |CONNEXT| DDS applications, RTI Infrastructure 
Services, and RTI Tools.

The following instructions step you through the installation and basic 
verification steps required to get started.


New ROS 2 Users
===============

To get started with ROS 2 + |CONNEXT|, follow these steps:

1. Add the ROS APT repository:

.. code-block:: bash

   sudo apt install software-properties-common
   sudo add-apt-repository universe
   sudo apt update && sudo apt install curl -y

   export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')

   curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
   sudo dpkg -i /tmp/ros2-apt-source.deb

2. Add the RTI APT repository:

.. code-block:: bash

   sudo curl -sSL -o /usr/share/keyrings/rti-official-archive.gpg \
     https://packages.rti.com/deb/official/repo.key

   printf -- "deb [arch=%s, signed-by=%s] %s %s main\n" \
     $(dpkg --print-architecture) \
     /usr/share/keyrings/rti-official-archive.gpg \
     https://packages.rti.com/deb/official \
     $(. /etc/os-release && echo ${VERSION_CODENAME}) | \
     sudo tee /etc/apt/sources.list.d/rti.list >/dev/null

   sudo apt-get update

3. Install the RTI Connext Robotics Toolkit:

.. code-block:: bash

   sudo apt-get install rti-connext-robotics-toolkit-kilted-7.3.0-desktop

4. (Optional) Install your RTI license activation file (``rti_license.dat``):

.. code-block:: bash

   sudo cp /path/to/rti_license.dat /opt/rti.com/rti_connext_dds-7.3.0/rti_license.dat

The RTI Connext Robotics Toolkit package already installs an ``rti_license.dat`` file that enables
core ROS 2 + |CONNEXT| features. To use additional |CONNEXT| services and
tools, replace it with an RTI-provided ``rti_license.dat`` file. If you do
not have one, get it at https://www.rti.com/ros.

5. Load ROS 2 through the environment script provided by the RTI Connext Robotics Toolkit:

.. code-block:: bash

   source /opt/rti.com/ros/kilted-7.3.0/setup.bash

6. Verify the installation:

.. code-block:: bash

   echo $RMW_IMPLEMENTATION

The output should be ``rmw_connextdds``.

Run example nodes to verify end-to-end communication:

.. code-block:: bash

   ros2 run demo_nodes_py listener &
   ros2 run demo_nodes_cpp talker


Existing ROS 2 Kilted Installations
===================================

If ROS 2 Kilted is already installed, follow these steps to migrate to the
RTI Connext Robotics Toolkit:

1. Fully remove (i.e. "purge") any version of |CONNEXT| that was previously installed using packages from the ROS 2 APT repository. For example, purge version 7.3.0 with:

.. code-block:: bash

   sudo apt-get purge -y --auto-remove "rti-connext-dds-7.3.0*"

2. Add the RTI APT repository:

.. code-block:: bash

   sudo curl -sSL -o /usr/share/keyrings/rti-official-archive.gpg \
     https://packages.rti.com/deb/official/repo.key

   printf -- "deb [arch=%s, signed-by=%s] %s %s main\n" \
     $(dpkg --print-architecture) \
     /usr/share/keyrings/rti-official-archive.gpg \
     https://packages.rti.com/deb/official \
     $(. /etc/os-release && echo ${VERSION_CODENAME}) | \
     sudo tee /etc/apt/sources.list.d/rti.list >/dev/null

   sudo apt-get update

3. Install the toolkit:

.. code-block:: bash

   sudo apt-get install rti-connext-robotics-toolkit-kilted-7.3.0-desktop

4. (Optional) Install your RTI license activation file (``rti_license.dat``):

.. code-block:: bash

   sudo cp /path/to/rti_license.dat /opt/rti.com/rti_connext_dds-7.3.0/rti_license.dat

The RTI Connext Robotics Toolkit package already installs an ``rti_license.dat`` file that enables
core ROS 2 + |CONNEXT| features. To use additional |CONNEXT| services and
tools, replace it with an RTI-provided ``rti_license.dat`` file. If you do
not have one, get it at https://www.rti.com/ros.

5. Load ROS 2 through the environment script provided by the RTI Connext Robotics Toolkit:

.. code-block:: bash

   source /opt/rti.com/ros/kilted-7.3.0/setup.bash

6. Verify the installation:

.. code-block:: bash

   echo $RMW_IMPLEMENTATION

The output should be ``rmw_connextdds``.

Run example nodes to verify end-to-end communication:

.. code-block:: bash

   ros2 run demo_nodes_py listener &
   ros2 run demo_nodes_cpp talker


Unattended Installation (Advanced)
==================================

Use unattended installation only after reviewing and accepting the licenses on
behalf of users/systems. For most users, interactive installation is
recommended first.

To perform an unattended installation of the 
``rti-connext-robotics-toolkit-kilted-7.3.0-desktop`` Debian package, choose 
one of the following two methods.

Managing the default free license
---------------------------------

During unattended installations, the package can install an included free
license file as the global ``rti_license.dat``. This free license supports
core libraries only. This behavior applies to both unattended methods below.

If you plan to use your own RTI-provided license activation file and want to
avoid having it overwritten by packages, disable the automatic installation of
the included free license before installing:

.. code-block:: bash

   echo "rti-connext-dds-7.3.0-ros rti-connext-dds-7.3.0/license-ros2-free/install select false" | \
     sudo debconf-set-selections

.. note::

   To ensure the unattended installation, explicitly preselect this option as
   either ``true`` or ``false`` before installing.

Via debconf
-----------
The license acceptance key is set for ``rti-connext-dds-7.3.0-common``, which
is a dependency of the RTI Connext Robotics Toolkit package and the component
that prompts for license acceptance.

.. code-block:: bash

   echo "rti-connext-dds-7.3.0-common rti-connext-dds-7.3.0/license/accepted select true" | \

     sudo debconf-set-selections
   sudo apt install -y rti-connext-robotics-toolkit-kilted-7.3.0-desktop

Via environment variables
-------------------------

This method is supported only from a root shell.

.. code-block:: bash

   RTI_LICENSE_AGREEMENT_ACCEPTED=accepted \
   apt install -y rti-connext-robotics-toolkit-kilted-7.3.0-desktop