Click in the upper right corner for Table of Contents ↗️

FER - MRS Course Project

Dear students, welcome to the Multi-Robot Systems course. These instructions will help you set up everything needed for the project you will be working on as part of the course requirements.

Note

If you encounter an error or a problem during installation, first check out the Issues tab; maybe the problem has already been solved. If not, create a new issue and/or contact us.

Intro

In this project, you will be developing algorithms for controlling a swarm of robots. In the first part, you will simulate a swarm of Sphero robots¹. You are going to use a simple 2D simulator Stage, and specifically, its bindings to the Robot Operating System (ROS) stage_ros2.

Tip

Don't worry if you have never worked with ROS. For this project, you will need only the basics, and there is probably someone in your group who already has some experience.

Sphero robots are simulated in Stage as simple omnidirectional points (actually squares, but the shape is not important) without mass. This means that they have no inertia, i.e., they can achieve the commanded velocity instantly. Desired velocities are commanded by sending a geometry_msgs/Twist message on robot_x/cmd_vel topic ,where x is the number of the robot in simulation (0, 1, 2, ...). At the same time, the simulator is continuously streaming positions and velocities of the robots on the topic robot_x/odom of type nav_msgs/Odometry.

Important

Even though the simulator does not simulate inertia, your algorithms should be designed with real robots in mind. This means that you should not command large step changes in velocities that are not achievable by real robots. Instead, compute the desired acceleration for swarming and use it to update the velocity gradually.

Reporting problems

If you encounter an error that you can't solve yourself or get stuck on some step of the simulation, please open an Issue in this repository. Specify your operating system and method of installation, describe your problem, and include the entire output of the command that resulted in the error. This will be the quickest way to get feedback and will help other students who may encounter the same error in the future.

Installation

There are two ways you can set up your computer to run the simulation:

1. Using Docker (recommended) - everything you need, including ROS, core ROS tools, Stage simulator, and other packages, is installed and ready to use.
2. If you already have ROS 2 installed, the remaining packages can be installed manually.

1) Docker installation (recommended)

Very briefly, Docker is a tool that provides a simple and efficient way to pack everything needed for a specific application in one container. You can also look at it as a lightweight virtual machine running on your computer.

Basic information about Docker and its main concepts can be found here. Of course, you can also take a look at the official website. Don't follow any instructions from these links just yet. They are provided as a general overview and reference you can use in the future. Detailed step-by-step instructions are given below.

Prerequisites

You must have Ubuntu OS installed on your computer. Ideally, this would be Ubuntu 22.04, but another version should work as well. If you have an NVIDIA GPU, please follow these instructions to prepare for Docker installation.

Step-by-step instructions

Follow these instructions to install the Docker engine.

Then follow these optional steps to manage docker as a non-root user. If you skip this, every docker command will have to be executed with sudo. Skip the "Note: To run Docker without root privileges, see Run the Docker daemon as a non-root user (Rootless mode)." part. This is just a note and we do not need it.

Docker containers are intended to run inside your terminal. In other words, you won't see a desktop like in regular virtual machines. However, graphical applications can still run in the container if you give them permission. To do that, execute

xhost +local:docker

To avoid having to do this every time, we can add that command to our .profile file which executes on every login.

echo "xhost +local:docker > /dev/null" >> ~/.profile

Now, let's prepare the Docker container that will be used for the project. First, clone this repository in your home or any other preferred directory and position yourself in the correct folder.

git clone https://github.com/larics/mrs_simulation.git
cd mrs_simulation/docker

Build a Docker image. You will see a lot of output. Wait until it's done.

docker build -t mrs_2d_sim:humble .

Once you have an image, you need a container. The run_docker.sh script will do everything for you.

bash run_docker.sh

When the script finishes, your terminal prompt should change from

<your username>@<your hostname>

to

root@<your hostname>

This signals that you are currently "inside" the container.

Tip

Short reminder on commands for working with the container:

• Exiting from container - Press Ctrl+d
• Stopping container from the outside (some other terminal) - docker stop mrs_project_1
• Starting container - docker start -i mrs_project_1
• Starting container with your SSH keys (if you want to use git) - bash start_docker.sh
• Open a new terminal connected to the running container - docker exec -it mrs_project_1 bash

More details are available in the main docker_files repo and online.

Bonus section

The provided Docker image comes with a few preinstalled tools and configs which may simplify your life.

Tmuxinator is a tool that allows you to start a tmux session with a complex layout and automatically run commands by configuring a simple yaml configuration file. Tmux is a terminal multiplexer - it can run multiple terminal windows inside a single window. This approach is simpler than having to do docker exec every time you need a new terminal.

You don't need to write new configuration files for your projects, but some examples will use Tmuxinator. You can move between terminal panes by holding down Ctrl key and navigating with arrow keys. Switching between tabs is done with Shift and the arrow keys. If you have a lot of open panes and tabs in your tmux, you can simply kill everything and exit by pressing Ctrl+b and then k.

Here are some links: Tmuxinator, Getting starded with Tmux, Tmux Cheat Sheet

Ranger is a command-line file browser for Linux. While inside the Docker container, you can run the default file browser nautilus with a graphical interface, but it is often easier and quicker to view the files directly in the terminal window. You can start ranger with the command ra. Moving up and down the folders is done with the arrow keys and you can exit with a q. When you exit, the working directory in your terminal will be set to the last directory you opened while in Ranger.

Htop is a better version of top - command line interface task manager. Start it with the command htop and exit with q.

VS Code - If you normally use VS Code as your IDE, you can install Dev Containers extension, which will allow you to continue using it inside the container. Simply start the container in your terminal (docker start -i mrs_project) and then attach to it from VS Code (open action tray with Ctrl+Shift+P and select Dev Containers: Attach to Running Container).

2) Manual installation (if you already have ROS installed)

We are assuming that you have ROS 2 Humble installed.

Even if you have ROS installed, consider using Docker installation as it will simplify debugging and final evaluation, you will learn something new, and the Docker image comes with some extra goodies.

Prerequisites on ROS packages:

sudo apt install -y \
    ros-$ROS_DISTRO-foxglove-bridge \
    ros-$ROS_DISTRO-rosbag2-storage-mcap \
    ros-$ROS_DISTRO-teleop-twist-keyboard \
    ros-$ROS_DISTRO-nav2-map-server \
    ros-$ROS_DISTRO-nav2-lifecycle-manager \
    ros-$ROS_DISTRO-rviz2 \
    ros-$ROS_DISTRO-rqt*

Prerequisites on custom packages:

cd <your_workspace>/src
git clone https://github.com/larics/sphero_simulation.git
cd ..
colcon build --symlink-install
source install/setup.bash

Testing your setup with an example

Now that you have the simulator ready, you can try to move the robots in it. Take a look at the Tmuxinator example in sphero_stage package. When you start the example, a window with the simulation should open. In the top two terminals, you can press keys on your keyboard to send velocity commands to robots. In the bottom four terminals, you can see their current position and velocity.

As explained in the Bonus section about Tmuxinator, switching between windows is achieved by holding down Ctrl key and pressing the arrow keys. If you want to send commands to the robot, one of the top panels (terminals) must be selected.

Move the robot forward and backward with keys i and <. Rotate left and right with j and l. For the holonomic mode (strafing), hold down the Shift button and press i, <, j or l. Try out other keys as well and see what they do.

Working on your project

The sphero_stage package is the main package you will be using for setting up and starting your simulation environment. Detailed instructions are available there.

For developing your solution, create a new package. You can write your code in Python or C++.

More packages will be made available as needed, including the instructions on how to use them.

Footnotes

1. Sphero robots are small educational robots that can be controlled via Bluetooth. Although technically differentially driven, they have a spherical shape and can roll in any direction, so we consider them as holonomic robots. Spheros were used in previous years for the course project, but now we use Crazyflie drones. The Stage simulator can simulate any 2D robot, but we keep calling them Spheros for simplicity. ↩