Setup ROS Coding Environment - ika-rwth-aachen/acdc GitHub Wiki

In this unit we will setup the ROS Coding environment, which is necessary to complete the ROS programming exercises.

• Contents
• Integrated Development Environment (IDE)
• Clone acdc Repository
• Install Docker
• Install docker-run-cli
• Download Docker Images
• Start Docker Container
• Docker GUI Test
• Docker RVIZ Test
• Hints
• Troubleshooting GUI and Docker
  • RVIZ is not showing content / RVIZ crashing (libGL error)

To view and work on the ROS Code in ACDC, we recommend you to use a modern Integrated Development Environment (IDE), such as Visual Studio Code (VS Code). Install VS Code to your Ubuntu now by following this guide: https://code.visualstudio.com/docs/setup/linux Then, follow these tutorials to get familiar with VS Code:

• Introduction to VS Code

Of course, if you already know how to use a different IDE, you may also choose not to use VS Code.

Start a terminal on your Ubuntu system and navigate to a directory where you want to store the acdc repository. If you have never used a Unix-Shell (terminal) before, we strongly suggest you to do an online tutorial before you start this course.

We suggest you to navigate to the directory ~/Documents which is located in you home directory and clone the acdc repository there with the following command

git clone --recurse-submodules https://github.com/ika-rwth-aachen/acdc.git

• Note that we use --recurse-submodules, because we are using several other open source repositories that we have integrated into our repository as a submodule. If you do not use that flag, you might experience problems when compiling the workspace.
• Note that you can clone the repository to any directory on your machine you want. This might be ~/Documents/acdc or ~/acdc or some other directory. In the following exercises we will use the placeholder ${REPOSITORY} to denote the location of your own acdc repository on you machine.

After cloning, your local acdc directory should have the same contents like you can see in the following:

.
├── assets
│   ├── ACDC_YT_Thumbnail.png
│   └── header_image.png
├── bag
│   ├── .gitkeep
├── catkin_workspace
│   └── src
├── colcon_workspace
│   └── src
├── docker
│   ├── Dockerfile.ros1    
│   ├── Dockerfile.ros2
│   ├── Makefile
│   ├── TensorFlowConfig.cmake
│   ├── ros1_run.sh
│   └── ros2_run.sh
├── .gitignore
├── .gitlab-ci.yml
├── .gitmodules
├── LICENSE
└── README.md

Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. Containers are a standardized unit of software that allows developers to isolate their application from its environment and distribute safely it to any other environment. For the ACDC course, we created such a standardized container that allows every student to run our code without any manual installations of libraries or other programs. The requirements to use our container are an installation of Docker Version 19.03 or later.

For the installation of docker, we refer to the official installation guide:

• Ubuntu: https://docs.docker.com/engine/install/ubuntu/
• MacOS: https://docs.docker.com/desktop/install/mac-install/
• Test your installation of docker with

  sudo docker run hello-world

• Note that you will have to execute the docker commands with root-privileges (sudo) if you have not added your user to a docker group https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user
• Now it should work without sudo(You need to restart your machine after the previous step):

  docker run hello-world

• Check out the official documentation for more details and in case this does not work.
• If your machine has a Nvidia GPU, and if you want to use that GPU for faster computation you can also try to install nvidia-docker. However, this is not required as all exercises can be executed on CPU.

The docker-run-cli is necessary to execute our docker container in a very convinient way. Please install the pip package with the following command

pip install docker-run-cli --break-system-packages

Warning
Outside of a virtual environment, pip may default to a user-site installation of executables to ~/.local/bin, which may not be present in your shell's PATH. If running docker-run errors with docker-run: command not found, add the directory to your path. (More information)

echo "export PATH=\$HOME/.local/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc

For this ACDC course we already created and compiled a container and uploaded it to Dockerhub. Dockerhub is a public registry where it is possible to upload and download docker images. You can find the docker image that is necessary for executing this repository in the following link

• https://hub.docker.com/r/rwthika/acdc/tags

You can check out our Dockerfile which basically contains all commands that install ROS and all necessary libraries used within the upcoming workshops.

All libraries are already compiled into the image and you can simply download it and use it on your host machine. You can pull (download) the image with the following command

docker pull rwthika/acdc:ros1

This might need some time, depending on your internet connection. Also make sure, that you Linux/MacOS system has enough disk space available. We recommend in total 80GB of free disk space.

We prepared some scripts, that help you to to pull/remove/build the docker image. Open a terminal and change to the directory (with cd) ${REPOSITORY}/docker. Then you can execute one of the following commands in the terminal

• make pull: Pulls the docker image
• make clean: Removes the image from your machine.
• make build : Compiles the docker container on your machine with but warning ⚠️ this may take up to 30 minutes. Simply use the pre-compiled image.

Navigate to the local directory ${REPOSITORY}/docker and execute ./ros1_run.sh. This will start an Docker container instance based on the Docker image rwthika/acdc:ros1, in which ROS and all required libraries are preinstalled. You can stop the container by pressing Ctrl+C in the terminal. If everything is set up correctly, you will see the following:

Starting new container 'acdc' ...
================================================================================

find: '/proc/28/task/28/fdinfo/5': No such file or directory
find: '/proc/28/fdinfo/6': No such file or directory
The container is running.

Execute the run script again from another terminal to open a shell in the container.
Alternatively, the container could have been launched with '-a' to attach directly.
Press Ctrl+Z followed and issue 'bg' to put this process into the background.
Press Ctrl+C to stop the container.

Now, open a second terminal and navigate again to ${REPOSITORY}/docker. Then, execute ./ros1_run.sh again to open a shell inside the running container. You should see this:

Attaching to running container 'acdc' ...
================================================================================

=== ROS Docker Container =======================================================

root@<HOST>:/home/rosuser/ws/catkin_workspace#

The whole acdc folder is mounted from your host file system into the container. That means, all changes in the source codes or other files are mirrored into the container, and vice-versa! Note that your current working directory inside the container is /home/rosuser/ws/catkin_workspace. You basically have now a second Linux System running on your machine inside a Docker container.

Please test if the GUI is working for you. Please run rqt in the terminal. An empty window should pop up now:

⚠️ In case you experienced errors during the GUI test, please revise the Troubleshooting section below.

We also want to test if RVIZ is working for you. RVIZ is an important 3D visualization tool for ROS. Now, you can press Ctrl+C in the terminal where you ran rqt in order to cancel it. Open another (3rd) terminal and run ./ros1_run.sh to enter the container.

Now you have three terminals. Execute roscore in the second one to start a ROS Master and execute rviz in the third one to start RVIZ:

1. Initial ./ros1_run.sh
2. Execute roscore in the container
3. Execute rviz in the container

You should now see an empty RVIZ window as in the image below

Congratulations, you successfully set up your coding environment! You may now press Ctrl+C in the terminal where you opened rviz to close the application again.

If that is working, please read the Hints below and continue with the next tutorial. There, we will compile the code in the workspace and then test the first ROS application.

⚠️ In case you experienced errors during the RVIZ test, please revise the Troubleshooting section below.

• You can escape the container by just writing exit or pressing Ctrl+C in the container's terminal.
• You can attach to the same container multiple times by calling ./ros1_run.sh again in several terminals.
• When using the ./ros1_run.sh script: directories catkin_workspace and bag are shared both on your host machine and the docker container! That means you can drop of files (such as .bag files) into bag and access them from the container. Further, you can edit the code from your local machine and all changes also happen in the container.

Check if your error matches one of the following common errors. If you still have problems open an issue on Github.

Symptoms:

• The LIDAR-points are hardly visible (unlike in the images above)
• libGL error messages are displayed for MESA GPU cards, such as:

Root Cause: This issue arises primarily due to conflicts between RVIZ and hardware acceleration when running inside a Docker container. Additionally, if your system utilizes Mesa graphics drivers (commonly for Intel GPUs or inside a VM), hardware acceleration can cause these problems.

Solutions:

• Temporary fix: Before running RVIZ, disable hardware acceleration in docker terminal:

export LIBGL_ALWAYS_SOFTWARE=1
rosrun rviz rviz

⚠️ Note: This approach requires setting the environment variable every time prior to initiating RVIZ.

• Permanent Fix : Edit the ${REPOSITORY}/docker/ros1_run.sh file:

The script looks like this:

#!/bin/bash

# in order to be able to use this script install:
# pip install docker-run-cli --break-system-packages
DIR="$(cd -P "$(dirname "$0")" && pwd)"
if docker ps --format '{{.Names}}' | grep -q "acdc_ros1"; then
    docker-run --name acdc_ros1
else
    docker-run --no-gpu --volume $(dirname "$DIR"):/home/rosuser/ws --image rwthika/acdc:ros1 --workdir="/home/rosuser/ws/catkin_workspace" --name acdc_ros1 
fi

Modify the docker-run line after the else clause to include the --env LIBGL_ALWAYS_SOFTWARE=1 flag. After modification, the script should look like this:

#!/bin/bash

# in order to be able to use this script install:
# pip install docker-run-cli --break-system-packages
DIR="$(cd -P "$(dirname "$0")" && pwd)"
if docker ps --format '{{.Names}}' | grep -q "acdc_ros1"; then
    docker-run --name acdc_ros1
else
    docker-run --env LIBGL_ALWAYS_SOFTWARE=1 --no-gpu --volume $(dirname "$DIR"):/home/rosuser/ws --image rwthika/acdc:ros1 --workdir="/home/rosuser/ws/catkin_workspace" --name acdc_ros1 
fi

With this command, you ensure the environment variable is set each time the Docker container is launched.

Save and close the file and execute ./ros1_run.sh.

Note: Activating the LIBGL_ALWAYS_SOFTWARE variable compels OpenGL to opt for software rendering, sidestepping hardware acceleration. This often corrects visual glitches in RVIZ when operated in a containerized environment.