Introduction to this repository

This repository contains the development environment that you will need during the AI-on-Demand Winter School. This environment is a Docker container that contains all the necessary components for you to develop in. The container and instructions have been tested using the following environments:

• Ubuntu 20.04
• Ubuntu 22.04
• Ubuntu 24.04
• Windows 11
• MacOS BigSur (Intel)
• MacOS Sonoma (Intel)

Other versions of Ubuntu and other Linux-based systems should work with minor changes. For Windows users, we recommend installing WSL. For MacOs users, we recommend installing UTM.

The container provides:

• Python 3 installation
• ROS2 Humble full installation
• Classic Gazebo installation
• Unified Planning Framework
• RDFLib

All you will need during the school is already pre-installed and you should not need to add anything else. To get your environment running, check the requirements and follow the installation instructions.

Requirements

• Docker (installation instructions available at https://docs.docker.com/engine/install/)
• Visual Studio Code
• Two VSCode Plugins that can be added through the plugin marketplace:
  • Remote development extension pack
  • Python plugin

Installation instructions (Windows 11)

If you don’t already have a Linux subsystem on Windows or if you’d like to install the Ubuntu 22.04 version. Open a terminal in Windows (as administrator), and install Ubuntu 22.04 using wsl by running the command:

wsl --install -d Ubuntu-22.04

Follow the Installation instructions for Ubuntu. If you have installed Ubuntu 22.04 using WSL, then you have the choice to either use the docker or to build the system from source. If have installed another version of Ubuntu, then you must use the docker container.

Installation instructions (MacOS)

In principle, you should be able to run the Docker container directly under MacOS. However, GUI forwarding may be tricky and we are not able to give you a solution that reliably works for all Mac models. If you find one, please let us know.

The best solution if you use MacOS is therefore to run Ubuntu in an UTM virtual machine. Do as follows:

1. Install UTM on your machine: https://docs.getutm.app/
2. Create a new UTM virtual machine running Ubuntu 22.04, or your favorite version: https://docs.getutm.app/guides/ubuntu/
3. Open your Ubuntu virtual machine and follow the instructions for Ubuntu below

If you have installed Ubuntu 22.04 in your UTM, then you have the choice to either use the docker or to build the system from source. If have installed another version of Ubuntu, then you must use the docker container.

Installation instructions (Ubuntu)

Enabling GUI Forwarding

Since the container contains a Gazebo simulator, you need to enable GUI forwarding before you can use the container. On Ubuntu, use

$ xhost +local:root

Other operating systems have not been tested, you may need to search online about how to enable GUI forwarding on your device.

Installing using the Docker Hub Image (RECOMMENDED)

The container is available as a Docker Hub Image. To get started:

1. clone the current repository with using the command

$ git clone https://gitsvn-nt.oru.se/jennifer.renoux/winter-school-docker-students.git

2. open the root folder of the repository in VSCode.

3. In the command palette (Ctrl+Shift+P), search for "Dev Containers: Rebuild and Reopen in container"

A new window will open, pull the image from DockerHub, create and launch the container, and attach to it. A couple of post-creation command will be executed. Once they are done, the terminal will show "Click on any key to close this terminal". Click on a key, and a new command prompt should open. If this is not the case, you can open a new one by clicking on the + icon.

If you obtain this error:

Current user does not have permission to run docker

If you've not already created a docker group, run the following commands:

sudo groupadd docker
sudo usermod -aG docker $USER

A reboot is required to make the changes effective.

Installing from Source (only works on Ubuntu 22.04)

This is definitely not the recommended way to install the environment. For the school, only go forward if every other method failed and if you are running Ubuntu 22.04. Note that even if you already have ROS2 and Classic Gazebo installed on your computer, please prefer using the docker environment as some configurations and versions might be different.

1. Install ROS2 Humble, colcon, and Classic Gazebo
2. Install the Unified Planning framework and RDFLib :

pip install numpy==1.26.4 unified-planning[fast-downward] rdflib

3. Install the necessary dependencies.

$ sudo apt install libgazebo-dev xterm nano gedit ros-humble-gazebo-ros ros-humble-gazebo-ros-pkgs ros-humble-turtlebot3-gazebo ros-humble-xacro ros-humble-teleop-twist-keyboard ros-humble-robot-state-publisher ros-humble-gazebo-ros2-control ros-humble-ros2-controllers ros-humble-geographic-msgs -y 

4. Clone this repository using the command

$ git clone https://gitsvn-nt.oru.se/jennifer.renoux/winter-school-docker-students.git

5. Build using colcon.

$ colcon build --symlink-install && source install/setup.bash

6. Set key environment variables:

$ GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:<path/to/your/workspace>/src/pmb2_robot

7. (Optional) Add the source command to your shell startup script

echo "source <path/to/your/workspace>/install/setup.bash" >> ~/.bashrc

Installing using Dockerfile

This is not the recommended method, only attempt if for some reasons the recommended method did not work or if you want to tinker with the Dockerfile (DO NOT DO THAT FOR THE SCHOOL).

1. Clone this repository using the command

$ git clone https://gitsvn-nt.oru.se/jennifer.renoux/winter-school-docker-students.git

2. Open the root folder of the repository in VSCode
3. In the file .devcontainer/devcontainer.json, comment the "image" line (line 6) and uncomment the "build" lines (lines 8 to 13).
4. In the command palette (Ctrl+Shift+P), search for "Dev Containers: Rebuild and Reopen in container"

A new window will open, build the Dockerfile, create and launch the container, and attach to it. A couple of post-creation command will be executed. Once they are done, the terminal will show "Click on any key to close this terminal". Click on a key, and a new command prompt should open. If this is not the case, you can open a new one by clicking on the + icon. Test that the setup worked properly by running the following command :

$ ros2 launch atlantis_gazebo robot_sim_launch.py

To move the robot around use the teleop_keyboard opened in the other window. Note that Gazebo's first launch can take a very long time since the system needs to process all the models. Your computer may ask you if you want to kill the process. DO NOT KILL GAZEBO, and simply wait a couple of minutes. All should resolve itself.

Coding and running the project

Coding within the container

Once you have opened a VSCode instance within the container (following the installation instruction), you can simply modify the code present in the src folder. All changes are synchronized between your host machine and the container, so even after you close VSCode and stop the container, you will not lose your changes and don't need to re-build the workspace.

To re-open the container, simply open the cloned repository root folder in VSCode, and a pop-up should appear on the bottom right proposing to re-open in container. If this is not the case, simply go to the command palette (Ctrl+Shift+P) and select "Dev Containers : Reopen in Container".

Testing

Test that the ROS installation is successfully done, run the following command:

$ ros2 topic list

which should give the following output:

/parameter_events
/rosout

Test that the setup worked properly by running the following command (window takes very long to be filled, be patient):

$ gazebo src/atlantis/atlantis_scenarios/scenarios/apartment/apartment.world --verbose

Note that Gazebo's first launch can take a very long time since the system needs to process all the models. Your computer may ask you if you want to kill the process. DO NOT KILL GAZEBO, and simply wait a couple of minutes. All should resolve itself. To move the robot around, use the teleop_keyboard opened in the other window.

If you obtain this error:

qt.qpa.xcb: could not connect to display :0

You will need to open a command line on your host computer, and type the following:

$ xhost +local:root

and try again.

Once you have tested the installation, close the Gazebo.

Then, test the simulation by running the command

$ ros2 launch atlantis_gazebo robot_sim_launch.py

To move the robot around use the teleop_keyboard opened in the other window. Once you have tested the installation, close the Gazebo and the teleop windows.

Developing the nodes

During the school, you will be working towards an integrated system combining three different components.

Runing the school task

To run the lab for the school, run the following command (note that all other instances of gazebo must be closed):

$ ros2 launch atlantis_gazebo robot_sim_launch.py lab:="<lab/to/run>"

where <lab/to/run> can be one of {fuzzy_controller_lab, planning_lab, planning_lab}.

Advanced usage

Content of the repository

TODO The repository is organized as follows :

ws
|_ .devcontainer
|_ src
   |_atlantis