====== Using ROS ======

To successfully use ROS, you need to be able to perform basic tasks in Linux. Refer e.g. to [[https://raw.githubusercontent.com/ctu-mrs/mrs_cheatsheet/gh-pages/mrs_cheatsheet.pdf|MRS Cheatsheet]] to get a quick reference guide.
===== Singularity 101 =====

==== What is Singularity ====

Singularity is a virtualization technology somewhat similar to Docker. But there are some key differences:

   * Singularity does not fully isolate the containers from the host system.
     * Code running in the container runs under the same user who launched it (as opposed to Docker which usually offers a root user). This also means you do not have ''sudo'' permissions inside the container if you don't have them in the host system.
     * Code running inside the container has direct access to your home directory and to ''/tmp'' from the host system. You can add more shared directories by passing the ''-B <dir>'' CLI option to Singularity.
     * Code running inside the container has direct access to the host network interfaces and you don't need to do anything to have a working network.
     * Code running inside the container has direct access to the graphical stack of the host so rendering applications work out of the box.
       * There is, however, a catch - most rendering applications use client libraries to do the rendering, and if those differ too much from the host system, there might be compatibility problems.
   * Singularity images can be distributed as a single large file, as opposed to Docker which is usually distributed via online registries.
   * Singularity does not know the concept of image layers.
   * Containers run in Singularity have no "runtime presence". You do not need to start and stop them explicitly. The container lives as long as the program running inside it.
   * Singularity images can be converted from Docker images.
   * Singularity images are immutable. You cannot change or update the system in the image (unless using overlays, which is way beyond the scope of ARO).

We choose Singularity over Docker because it is friendlier with GUI applications and it is the framework used in HPC (High-performance Computing) clusters such as the RCI cluster running at CTU, or Metacentrum. Also, running Singularity containers doesn't require administrator privileges. We also used Singularity with success for running local multi-robot simulation tests for DARPA SubT Challenge.

==== Singularity vs. Apptainer ====

[[https://sylabs.io/singularity/|Singularity CE]] == [[https://apptainer.org/|Apptainer]] (the latter is just a newer name). You can find both terms when googling.

Apptainer is the newer one, but it installs the backwards-compatible ''singularity'' command to the system.

We use exclusively ''singularity'' everywhere to make it possible to use both newer and older versions.


===== At Lab Computers / Turtlebots =====

At [[https://cyber.felk.cvut.cz/study/computer-labs/|labs]] (e.g., E130, E132) and the Turtlebot robots, Robot Operating System (ROS) is available through pre-downloaded [[https://en.wikipedia.org/wiki/Singularity_(software)|Singularity]] containers. The computers and robots automatically handle updating the images so you can be sure you're always using the latest image.

A general guide for connecting to the desktops/robots in the lab is here: [[courses:aro:tutorials:turtlebots|TurtleBot Lab Guide]]. You need a special password to login to these machines. [[https://cw.felk.cvut.cz/password/|Set the password here]].

To start using ROS in Singularity, clone the deploy repository somewhere to your home directory. Once you have the deploy repository, you can run singularity image with Ubuntu 20.04 + ROS Noetic using: ''scripts/start_singularity_aro'' .

First-time run:

 <code>
 git clone https://gitlab.fel.cvut.cz/robolab/deploy.git
 deploy/scripts/start_singularity_aro
 # console prompt should start with AROSingularity now</code>

Following runs:

 <code>
 deploy/scripts/start_singularity_aro
 # console prompt should start with AROSingularity now</code>


The script will create (or update) a ROS workspace in folder ''workspace'' next to ''deploy''. The codes you need to edit for homeworks are all in ''workspace/src/student-packages''.

You can make use of the fact that the home directory in labs is a shared network mount, so changes you do on the desktop computer are almost instantly available also on the turtlebots.

===== On Your Computer =====

You will get the smoothest and easiest experience on Ubuntu 20.04. Newer Ubuntus still offer a smooth experience. Other Linux distros can be used, but may require a few manual setup steps. Singularity only runs on Linux. If you need to use a different operating system, there are [[alternative_install|alternatives, which are, however, not officially supported by the teaching team]]. We think it is good for you to get an Ubuntu installation and familiarize yourself with it during the study of Cybernetics.

First time, choose a folder on your computer that has enough disk space (at least 3 GB) and is preferably on an SSD. ''cd'' to the folder and run the following commands that will download the deploy repository, install Singularity, download the image and finally start a container.

The ''install_singularity'' script works on Ubuntu 20.04+. If you have a different Linux flavor, you will need to install Singularity manually. The ''install_singularity'' script will point you to the relevant documentation.

 <code>
 git clone https://gitlab.fel.cvut.cz/robolab/deploy.git
 deploy/scripts/install_singularity
 deploy/scripts/download_singularity_image
 deploy/scripts/start_singularity_aro
 # console prompt should start with AROSingularity now</code>

The script will create (or update) a ROS workspace in folder ''workspace'' next to ''deploy''. The codes you need to edit for homeworks are all in ''workspace/src/student-packages/aro_exploration''.

Once you have the initial installation done, running the singularity with ROS is as easy as:

 <code>
 deploy/scripts/start_singularity_aro
 # console prompt should start with AROSingularity now</code>

The script will automatically check for new releases of the Singularity ARO image and download them if necessary.

===== Using IDEs with Singularity =====

By default, Singularity makes your normal home directory accessible inside the container, so you can edit files using any editor you like. However, to get a fully-featured IDE experience, it is better to start an IDE from within the container, as then it has access to all the ROS programs that are needed to test your code. The provided Singularity image comes with several IDEs preinstalled:

<code>
code .  # Start VSCode inside the Singularity container
pycharm  # Start Pycharm inside the Singularity container
subl  # Start Sublime editor inside the Singularity container</code>

===== Updates of student-packages repository =====


The ''start_singularity_aro'' script will also auto-update the copy of student-packages repository where you work on your homeworks. We expect the updates of this repository should not be frequent, but we reserve the right to push updates during the semester. The automatic update works by calling ''git fetch origin && git merge origin/master'' in the repository. If you only edit the parts of files you are supposed to, the update should be seamless. If your local changes are not compatible with the update, you will be informed by the script and it will guide you through the next possible steps.

===== Behind the Scenes =====

For the curious, here's a short summary what all the provided scripts do for you:

  * Check that Singularity is installed and install it if possible from PPA https://launchpad.net/~peci1/+archive/ubuntu/singularity-ce-v3 .
  * Autoupdate the deploy repository to pull new fixes.
  * Download the latest ARO Singularity image from https://gitlab.fel.cvut.cz/robolab/deploy/ choosing the correct CPU architecture.
  * Run ''singularity exec robolab_noetic.simg initialize_workspace_aro''. Script ''initialize_workspace_aro'' running inside the Singularity container does the following:
    * Create the necessary folder structure
    * Clone or update https://gitlab.fel.cvut.cz/robolab/aro/student-packages
    * Call ''%%catkin init && catkin config --extend /opt/ros/aro%%'' to set up the catkin workspace
    * Build the workspace using ''catkin build'', but only once, as we only use Python packages (with C++ nodes, we would need to build after every change).
    * Source the workspace using ''source ~/workspace/devel/setup.bash'' to activate it in the current console.

===== Common problems =====

   * If you have automatic activation of Conda base env in your ''.bashrc'' file, it will most probably break ROS. You can see errors like <code>ImportError: "from catkin_pkg.package import parse_package" failed: No module named 'catkin_pkg'</code>
     * To fix this, either remove the automatic conda activation, or make it conditional to not run inside Singularity. E.g. <code>if [ -z "$SINGULARITY_NAME" ]; then ORIGINAL_CONDA_ACTIVATION_CODE; fi</code>
   * If you see errors about missing Numpy functions, you probably have a pip-installed Numpy that is too new. This can happen if you e.g. ''%%pip3 install --user --upgrade numpy%%''. Never do this on Ubuntu. pip was not designed to manage distribution-wide Python packages and doing this can break your system. Fix this by ''pip3 uninstall numpy''. If numpy is broken after this, call ''%%sudo apt install --reinstall python3-numpy%%''.
   * ROS packages ''aro_exploration'' is not found by ''roslaunch''. You probably source some ROS workspaces in your ''~/.bashrc''. Make that sourcing conditional, i.e. move the sourcing into a block like <code>if [ -z "$SINGULARITY_NAME" ]; then YOUR_ROS_SOURCING_COMMANDS; fi</code>
     * Also make sure you have the following code block in your ''~/.profile'': <code>
if [ -n "$BASH_VERSION" ]; then
    # include .bashrc if it exists
    if [ -f "$HOME/.bashrc" ]; then
        . "$HOME/.bashrc"
    fi
fi</code>
   * Command completion using ''<Tab>'' doesn't work in tmux: Add the following in your ''.bashrc'': <code>[ -n "$SINGULARITY_NAME" ] && [ -n "$TMUX" ] && source /path/to/your/workspace/devel/setup.bash</code>