Grex Machina: Multi-Agent Framework for ROS 2

This framework allows for simulation of complex agents in a multi-agent system (MAS). We use ROS 2 to allow for plug-and-play addition of new agent capabilities.

Our goal is to make the following interchangeable:

• Simulator: Easily change between simulators, such as Gazebo or Flatland. Use the same agents and environments in different simulators.
• Agents: Define custom agents, from simple standalone ROS 2 nodes to complex agents involving tens of nodes and the myriad third-party packages offered by ROS.
• Networking: We plan to integrate the NS-3 network simulator for realistic communication models and disturbances.

Please reach out to Anthony Goeckner <[email protected]> with any questions.

Manual Installation Instructions (Recommended)

Installation is simple, but prerequisites must first be installed:

• ROS 2: Follow the official instructions here to install ROS 2 Humble to your system. Use the desktop-full variant, which includes the Gazebo simulator.

  • Install the Eclipse Cyclone DDS middleware for ROS. We use this because the default middleware currently causes problems in our application.

    apt install ros-humble-rmw-cyclonedds-cpp

    The above will install Cyclone DDS for Ubuntu. Adapt as needed for your system.

  • Install other ROS 2 packages.

    apt install ros-dev-tools ros-humble-turtlebot3* ros-humble-navigation2*

    Adapt as needed for your system.

• Optional for Windows: Users may find it easier to install prerequisites and operate the simulator using the Windows Subsystem for Linux (WSL). Install WSL, and then use it to install the Ubuntu version of ROS 2.

Once prerequisites are installed, perform the following:

1. Use Git to download the Grex framework repository.

   git clone --recurse https://github.com/NU-IDEAS-Lab/grex.git

2. Change to the grex folder:

   cd ./grex/

3. Source the correct ROS 2 installation.

   source /opt/ros/humble/setup.bash

4. Build the simulation environment using Colcon, the ROS 2 build system.

   colcon build

5. Follow instructions below to run the simulation.

Docker Installation Instructions (Alternative Method)

Installation via Docker may be performed as follows for use on systems where packages cannot be installed.

Follow the steps below:

1. Install rocker:

   pip install rocker

2. Build the Docker image:

   docker build . -t grex:sim
   

3. Launch a container using rocker:

   rocker --cuda --user --home --network=none grex:sim

4. Change to the grex folder:

   cd ~/grex/

5. Source the correct ROS 2 installation.

   source /opt/ros/humble/setup.bash

6. Build the simulation environment using Colcon, the ROS 2 build system.

   colcon build

Operation Instructions

To operate the simulator, perform the following steps:

1. Change to the grex root directory:

   cd ./grex/
   

2. Source the installed packages, plus the Gazebo simulator, and set environment variables.

   source ./install/setup.bash
   source /usr/share/gazebo/setup.sh
   export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
   

3. Run the simulation:

   ros2 launch grex simulation.launch.py agent_count:=3
   

   • Note: To view available launch arguments, add a -s flag to the end of the command.

Available Simulators

We currently support the following simulators with all agents:

• flatland (default simulator)
• gazebo

To change the simulator, add the sim:=SIM_NAME to your launch command:

   ros2 launch grex simulation.launch.py sim:=gazebo