Installation
============

The packages support recent versions of ROS1 (melodic, noetic) and ROS2 (foxy, galactic).

===========  =================  =================
ROS-VERSION  ROS-ASEBA-BRANCH   ROS-THYMIO-BRANCH
===========  =================  =================
melodic      ros1               melodic
noetic       ros1               noetic
foxy         ros2               master
galactic     ros2               master
===========  =================  =================

The functionality of ROS-Aseba and ROS-Thymio are the same for all supported ROS versions.
You don't know which ROS version to use? Pick the one that works with your OS
(look at the targeted platforms for `ROS 1 <https://www.ros.org/reps/rep-0003.html>`_ and
`ROS 2 <https://www.ros.org/reps/rep-2000.html>`_). Consider that ROS1 will reach end-of-live in 2025,
and that noetic will be the last official ROS1 release.
If you still have a doubt, go for ROS2: foxy is the current long-term-release (2020--2023)
while galactic is the current short-term-release (2021--2022).

.. note::

  ROS-Aseba is using Aseba version 1.6 from the `aseba-community repository <https://github.com/aseba-community/aseba>`_
  that implements Aseba protocol version 5. Aseba is also actively developed in the `Mobsya repository <https://github.com/Mobsya/aseba>`_.
  Mobsya development specifically targets the Thymio robot and has extended the Aseba protocol.
  Currently, and for the foreseeable future, Mobsya's Aseba protocol will remain compatible with Aseba 1.6; therefore
  Thymios running the newest firmware by Mobsya can be used with ROS-Aseba, provided that the
  parameter :ref:`param-highest_acceptable_protocol_version` is set to the correct value.


Supported Operating Systems
---------------------------

ROS-Aseba can be installed on Linux, macOS, and Windows because they are all supported by ROS and Aseba.

:Linux: Ubuntu is the reference platform for ROS1 and ROS2; ROS can be installed very easily using package managers
  (`ROS1 <http://wiki.ros.org/Installation/Ubuntu>`_, `ROS2 <https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Binary.html>`_).

:macOS: macOS is not officially supported in ROS1 and has currently only Tier 3 support in ROS2.
  For most users, installing ROS on macOS requires building it from source and possibly tinkering a bit.
  Therefore, we only suggest using ROS natively on macOS to expert users. We suggest non-expert macOS users to
  run ROS in an Ubuntu virtual machine or through docker.

:Windows: Windows support increased from ROS1 to ROS2 but for both versions `you can install pre-built packages <http://wiki.ros.org/Installation/Windows>`_ using Chocolately.
  In particular, we suggest to follow `installation instructions <https://ms-iot.github.io/ROSOnWindows/GettingStarted/SetupRos2.html>`_ from Microsoft.

Below we refer to the Linux installation. Windows instructions follows the links above to install ROS and then only differ by
the way you source the workspace

.. tabs::

   .. code-tab:: console Linux and macOS

      source <installation_directory>/setup.bash

   .. code-tab:: console Windows

      C:<installation_directory>\setup.bat

In particular, catkin, colcon and ros commands are the same for any operating system.
In Windows and macOS, we suggest to add the option ``--merge-install`` to the ``colcon build`` commands.

ROS
----

Before installing ROS-Aseba and ROS-Thymio, you need to setup ROS on your machine.
Please refer to the `official instructions <http://wiki.ros.org/ROS/Installation>`_ to install
at least ``ROS-Base`` distribution (we recommend ``ROS-Desktop`` to also install the GUI tools) of your version of choice,
which on Linux Ubuntu may just require you to run

.. code-block:: console

    sudo apt install ros-<ROS-VERSION>-ros-desktop


For ROS1, to follow the instructions below, install also `catkin-tools <https://catkin-tools.readthedocs.io/en/latest/installing.html>`_.

For ROS2, `install colcon <https://docs.ros.org/en/galactic/Tutorials/Colcon-Tutorial.html#install-colcon>`_:

.. code-block:: console

    sudo apt install python3-colcon-common-extensions

If you don't already have one, create a ROS workspace in a folder ``<WORKSPACE>`` of you choice.

.. tabs::

   .. code-tab:: console ROS1

      mkdir -p <WORKSPACE>/src
      cd <WORKSPACE>
      source /opt/ros/<ROS-VERSION>/setup.bash
      catkin init
      // This is optional: it will install packages instead of
      // just linking them in the develop folder.
      // This is the same behavior as ROS2 using colcon.
      catkin config --install

   .. code-tab:: console ROS2

      mkdir -p <WORKSPACE>/src
      cd <WORKSPACE>
      source /opt/ros/<ROS-VERSION>/setup.bash
      colcon build


ROS-Aseba
------------

1. Install ``libudev-dev``, ``libxml2-dev``, ``git`` and ``ros-<ROS-VERSION>-diagnostic-updater``

.. code-block:: console

    sudo apt install libudev-dev libxml2-dev git ros-<ROS-VERSION>-diagnostic-updater

.. note:: The installation ``diagnostic-updater`` is optional. If it available,
  ``asebaros`` will use it to expose diagnostics informations at runtime.
  If ``diagnostic-updater`` is not available through a package manager (e.g., on Windows),
  you can install it from source, cloning the correspoding branch (for ROS1 use ``noetic-devel``)
  of the repository https://github.com/ros/diagnostics

  .. code-block:: console

    cd <WORKSPACE>
    git clone https://github.com/ros/diagnostics --branch <BRANCH> src/diagnostics




2. Download and install ROS-Aseba

.. tabs::

   .. code-tab:: console ROS1

      cd <WORKSPACE>
      source install/setup.bash
      git clone https://github.com/jeguzzi/ros-aseba.git --branch ros1 --recurse-submodules src/ros-aseba
      catkin build


   .. code-tab:: console ROS2

      cd <WORKSPACE>
      source install/setup.bash
      git clone https://github.com/jeguzzi/ros-aseba.git --branch ros2 --recurse-submodules src/ros-aseba
      colcon build


3. On Linux, you may need to add the user to the dialout group to connect to a Thymio (and logout once after doing it)

.. code-block:: console

    sudo adduser $USER dialout

ROS-Thymio
------------

1. Install ``ros-<ROS-VERSION>-xacro``, ``ros-<ROS-VERSION>-tf``, ``ros-<ROS-VERSION>-robot-state-publisher``

.. code-block:: console

    sudo apt install ros-<ROS-VERSION>-xacro ros-<ROS-VERSION>-tf ros-<ROS-VERSION>-robot-state-publisher


2. Download and install ROS-Thymio

.. tabs::

   .. code-tab:: console ROS1

      cd <WORKSPACE>
      source install/setup.bash
      git clone https://github.com/jeguzzi/ros-thymio.git --branch <ROS-THYMIO-BRANCH> --recurse-submodules src/ros-thymio
      catkin build

   .. code-tab:: console ROS2

      cd <WORKSPACE>
      source install/setup.bash
      git clone https://github.com/jeguzzi/ros-thymio.git --branch master --recurse-submodules src/ros-thymio
      colcon build