Introduction to MAES

MAES is a tool for simulating and testing multi robot online exploration algorithms in a realistic continuous space environment. MAES is visualised and physics driven using the Unity Game Engine. MAES was created as part of a Master's Thesis at Aalborg University, Denmark, on the subject of distributed systems.

A video trailer for MAES can be found here

<p float="left"> <img src=".readmeAssets/example_image_1.png" width="400" alt="Screenshots taken in MAES"/> <img src=".readmeAssets/example_image_2.png" width="400" /> </p>

Table of Contents

• Introduction to MAES
• Getting started
  • Running in UnityMode
    • Creating your own algorithm
  • Running in ROSMode
    • ROSMode with Docker
      • RVIZ visualisation in Windows 10
    • ROSMode running natively (Without Docker)
• ROS Workspace packages
• Extracting Statistics (Applies to both ROSMode and UnityMode)
• Headless Runs (Only UnityMode)
• Performance Testing (Linux only)
• Adding Dependencies To MAES
• Testing Procedure
  • System Tests
  • Unit Tests
• Simulator Parameters Explanations
• Contributors

Getting started

MAES can be run in two different configurations, either ROSMode or UnityMode. UnityMode requires an installed Unity editor (last tested with version 2022.3.13f1), and allows for developing algorithm in C#. It has been tested to work on both Linux (Ubuntu 20.04, 21.04, 21.10, 22.04, and Arch), MacOS Monterey 12, Windows (10 and 11). Click here to get started in UnityMode.

ROSMode enables ROS2 Galactic integration, where the robots can be controlled from ROS (Robot Operating System) nodes. In ROSMode development is done in either Python or C++. A Docker image with ROS preinstalled is supplied to make it easier to get started. Click here to get started running in ROSMode.

Running in UnityMode

Install MAES by opening Unity's Package Manager (Window -> Package Manager) and clicking on the plus -> 'Add package from git url'

Then paste the following address:

https://github.com/DEIS-Tools/MAES.git?path=/Assets

Once the package has been downloaded and installed you are ready to use MAES!

Start by creating a script and attaching it to any Unity GameObject. Then inside the Start() method of the script enter the following code:

// Get/instantiate simulation prefab - This will cause the simulator to appear in Unity
var simulator = Simulator.GetInstance();

// Setup a very simple configuration for a scenario (cave map, random seed: 123)
var caveConfig = new CaveMapConfig(123, widthInTiles: 75, heightInTiles: 75);
var scenario = new SimulationScenario(123, mapSpawner: generator => generator.GenerateMap(caveConfig));
// Add the scenario to the simulator
simulator.EnqueueScenario(scenario);
// Start simulating immediately
simulator.PressPlayButton();

(An example can also be found in ExampleProgram)

A scenario is a configuration, that can be injected into a simulation, that the simulator can then execute. Several different sets of scenarios can be generated by the preconfigured methods inside the ScenarioGenerator.cs file.

A scenario contains a random seed, a SimulationEndCriteriaDelegate, a map spawner delegate, a robot spawner delegate and robot constraints. Additionally, a scenario contains a file name, that is used if the statistics of the given run are set to be exported. This can be configured inside the GlobalSettings.cs file.

Creating your own algorithm

In order to implement your own algorithm, you must create a class that implements the IExplorationAlgorithm.cs interface. This provides the algorithm with access to the robot controller, which in turn provides access to movement controls, slam map and all sensor data available on the agent given the constraints of the scenario.

Once you have defined the class for your algorithm you can inject it into the simulator by providing an algorithm factory:

// Define algorithm factory for your custom 
RobotSpawner.CreateAlgorithmDelegate algorithmFactory = seed => new YourAlgorithm(seed);
// Add the factory to the scenario 
var scenario = new SimulationScenario(seed: 123, robotSpawner:(map, spawner) => spawner.SpawnRobotsTogether(
    map, 
    seed: 123, 
    numberOfRobots: 3, 
    suggestedStartingPoint: Vector2Int.zero, 
    createAlgorithmDelegate: algorithmFactory));

Running in ROSMode

MAES can be run with ROS running either in a docker image or natively installed on your operation system. The docker image has everything preinstalled and is thus easier to set up. ROSMode has been tested to work with the Galactic release of ROS2.

ROSMode with Docker

1. Install Docker https://docs.docker.com/get-docker/ (On Windows 10 we recommend using the WSL2 backend for Docker)
2. Download MAES package from our releases-page, and extract the content to an empty folder
3. Open a terminal in the root of this folder
4. Pull our docker image with the following command (x86_64 architecture only)

docker pull aaumaes/ros4maes

or, build the image locally with the following command (x86_64 and arm64v8)

docker build --force-rm -t aaumaes/ros4maes -f Docker/Dockerfile .

5. Spinup a container either with RVIZ visualisation or not.

5.1a Without RVIZ (Works on Windows, macOS and Linux)

docker run --rm -it \
  -p 10000:10000 \
  -p 10022:22 \
  -v "$(pwd)"/maes-ros-slam-ws:/home/maes-user/code \
  --name ros4maes \
  aaumaes/ros4maes

5.1b With RVIZ (Only tested on Ubuntu 20.04, 21.04, 21.10 and 22.04. Possible workaround for Windows 10 here)

xhost +local:docker

docker run --rm -it \
  -p 10000:10000 \
  -p 10022:22 \
  -v "$(pwd)"/maes-ros-slam-ws:/home/maes-user/code \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  --env=DISPLAY \
  --name ros4maes \
  aaumaes/ros4maes

6. Launch multiple robots with following command

6.1a Without RVIZ

ros2 launch maes_ros2_interface maes_ros2_multi_robot_launch.py

6.1b With RVIZ

ros2 launch maes_ros2_interface maes_ros2_multi_robot_launch.py use_rviz:=true

7. Open Maes executable called MAES.x86_64

HOW TO CONFIGURE:

The workspace (maes-ros-slam-ws) inside the MAES package is shared with the docker container. It is thus possible to change these files directly using your favorite editor or IDE.

The logic controlling the behavior of the robots can be found in maes_robot_controller.py. Actionservers, subscriptions and services are already setup and can be used in the main function to control the robot.

The configuration of the ROS2 system can be changed by tuning parameters in maes_config.yaml found inside the maes_ros2_interface package in the workspace. Note: The field-names must be written in snake_case. Explanations for all configuration parameters can be seen in Section Simulation Parameters Explanations. MAES and ROS synchronize parameters from this configuration file automatically.

Remember to execute a colcon build after each change in config file or controller to recompile the ROS project.

RVIZ visualisation in Windows 10

If you are on Windows 10, you will have to install VcXsrv, an X-server for Windows. After installation, open the XLaunch program from the start menu:

Going through the configuration, choose the default values for the first two windows and add a checkmark to the third window in the "Disable access control" box:

^{^{(Be aware: this is an unsafe setting to leave on for a prolonged time. Therefore, do not have this setting enabled unless you are about to launch the ROS-container)}}

Finally, you can choose to save this configuration to local storage, and use it as a shortcut for starting up XLaunch. To launch an X-server with the settings now, press "finish".

Now, in your WSL terminal, go to the root MAES directory and enter the following commands:

export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0.0

docker run --rm -it \
  -p 10000:10000 \
  -p 10022:22 \
  -v "$(pwd)"/maes-ros-slam-ws:/home/maes-user/code \
  -e DISPLAY \
  --name ros4maes \
  aaumaes/ros4maes

Once the container is up and running, you can test to see if a GUI will render by executing a program with a GUI. rviz2 for instance. If the configuration has worked correctly, a program window should appear.

Other OS?

On other operating systems it will be necessary to research how to allow a docker container to render GUI on its host system.

ROSMode running natively (Without Docker)

This has only been tested on Ubuntu 20.04

1. Install ROS2 galactic desktop (https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html)
2. Install Nav2 for galactic (https://navigation.ros.org/build_instructio