ROS2 Installation and Configuration Guide
=========================================

For this project, we use the ROS2 Jazzy Jalisco version in Ubuntu 24.04. Here is the Installation tutorial from `ROS2 Documentation <https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html>`_.

Installing ROS2
-----------------

System setup
~~~~~~~~~~~~

**Set locale**

.. code-block:: bash

   locale  # check for UTF-8

   sudo apt update && sudo apt install locales
   sudo locale-gen en_US en_US.UTF-8
   sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
   export LANG=en_US.UTF-8

   locale  # verify settings

**Enable required repositories**  
First, ensure that the `Ubuntu Universe repository <https://help.ubuntu.com/community/Repositories/Ubuntu>`_ is enabled.

.. code-block:: bash

   sudo apt install software-properties-common
   sudo add-apt-repository universe

Now add the ROS 2 GPG key with apt.

.. code-block:: bash

   sudo apt update && sudo apt install curl -y
   sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

Then add the repository to your sources list.

.. code-block:: bash

   echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

**Install development tools (optional)**  
Necessary if you need to build ROS packages.

.. code-block:: bash

   sudo apt update && sudo apt install ros-dev-tools

Install ROS2
------------

Update your apt repository and ensure your system is up to date before installing new packages.

.. code-block:: bash

   sudo apt update
   sudo apt upgrade

Install ROS2 Desktop:

.. code-block:: bash

   sudo apt install ros-jazzy-desktop

Install communication libraries, message packages, and command line tools.

.. code-block:: bash

   sudo apt install ros-jazzy-ros-base

Configuring ROS2
----------------
concurrent-log-handler~~

.. code-block:: bash

   echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc

Check environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sourcing ROS 2 setup files will set several environment variables necessary for operating ROS 2. If you ever have problems finding or using your ROS 2 packages, make sure that your environment is properly set up using the following command:

.. code-block:: bash

   printenv | grep -i ROS

Check that variables like ``ROS_DISTRO`` and ``ROS_VERSION`` are set:

- ``ROS_VERSION=2``
- ``ROS_PYTHON_VERSION=3``
- ``ROS_DISTRO=jazzy``

The ``ROS_DOMAIN_ID`` variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once you have determined a unique integer for your group of ROS 2 nodes, you can set the environment variable with the following command:

.. code-block:: bash

   export ROS_DOMAIN_ID=<your_domain_id>

To maintain this setting between shell sessions, you can add the command to your shell startup script:

.. code-block:: bash

   echo "export ROS_DOMAIN_ID=<your_domain_id>" >> ~/.bashrc

The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, ROS 2 communication is not limited to localhost. The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS2 discovery range. Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in certain settings, such as classrooms, where multiple robots may publish to the same topic, causing strange behaviors.