Running the Orb Docker sim

Prerequisites

1. A Unix based system (Linux, etc.), but we've only tested on Ubuntu 24.xx
2. Docker Engine or Docker Desktop installed on your system
3. A virtual Python >=3.12 environment with RobotSwarmSimulator installed If you have Python 3.11 or lower, you can use pyenv to install a newer version of Python.
4. If you're cloning via git, you should also install git lfs (run git lfs install in the root directory of the repository)

Note

The Docker simulation must be run on a Unix based system (Linux, MacOS, etc.). This is because the Windows version of Docker does not properly support the --net=host option. Workarounds may exist, but we were unable to get them to work.

Create a virtual Python environment and install dependencies

The following commands will create a virtual Python environment and install the RobotSwarmSimulator package. We'll use uv to speed up the installation process, but if you experience any errors, try removing uv from the command.

First, open a terminal where you'd like to place the project. You should not place the .venv folder inside the repository (the orb_sitl folder). I'll use the following directory structure in this example:

┬ ~/orbsim  # Unzip to here if you downloaded it as a `.zip` file
├── orb_sitl/  # this repository
│   ├── .git/...
│   ├── rss/
│   │   ├── world.yaml
│   │   ├── SITLUTMWorld.py
│   │   ├── SITLOrbAgent.py
│   │   └── ...
│   ├── README.md
│   ├── requirements.txt
│   ├── rssitl.py
│   ├── orbs-gmu-docker-v1.tar  # this should be > 100MB
│   └── ...
└── .venv/  # the virtual environment that you create
    └── bin/
        └── activate

mkdir -p ~/orbsim
cd ~/orbsim

Now, create a virtual Python environment.

Install and use uv to create the virtual environment:

pip install uv
uv venv

Note

If uv is giving you issues, use virtualenv instead:

pip install virtualenv
virtualenv .venv --prompt .

Now activate the virtual environment. Make sure you're in the orbsim directory, where you should be able to see the .venv folder.

source .venv/bin/activate

Click Here for 🔧 Development RobotSwarmSimulator installation

If you need a newer version of swarmsim, you can install the RobotSwarmSimulator as editable from GitHub:

cd orbsim  # make sure you're in the project folder
# make sure your virtual environment is activated. 
source .venv/bin/activate  # SKIP THIS IF (orbsim) IS ALREADY IN YOUR PROMPT
git clone https://github.com/kenblu24/RobotSwarmSimulator.git
cd RobotSwarmSimulator
uv pip install -e .

You should now see (orbsim) at the beginning of your bash prompt.

cd to the orb_sitl directory and install the dependencies:

cd orb_sitl
uv pip install -r requirements.txt

Load the image

You only need to load the image once, unless the image has been updated.

docker load -i orbs-gmu-docker-v1.tar

Note

If you cloned the repository via git, you may not have downloaded the image yet. If this is the case, you'll see that the file size of orbs-gmu-docker-v1.tar is very small. You can check the file size with ls -l, and you'll see the file size in bytes. If this is the case, make sure you have git-lfs with git lfs install and then run git lfs pull to download the image. The file size should be > 100MB. If the docker image is updated at some point, you may need to re-run git lfs pull to download the new image.

Run the Image

With a Single Orb

docker run  -it --net=host scruffy.jhuapl.edu:7654/kmm-flight-stack/imperium/imperium-runtime:gmu-docker-v1

With Multiple Orbs

docker run  -it --net=host scruffy.jhuapl.edu:7654/kmm-flight-stack/imperium/imperium-runtime:gmu-docker-v1 /bin/bash

Tip

If you receive a permission error when running any of the docker commands, try prefacing the command with sudo

./launch_swarm.sh NUMBER_OF_ORBS

NUMBER_OF_ORBS should be set to 6 for now as the python script used speciically waits for 6 orbs to come online before sending commands. This can be updated by changing the agents: 6 line within the file orb_sitl/rss /world.yaml.

Sending commands to orbs and visualizing the outputs

Once the docker image is running, in a separate terminal, activate a virtual python environment:

cd ~/orbsim
source .venv/bin/activate 

Then, run the simulation script.

cd orb_sitl

python rssitl.py

Arguments

The rssitl.py script accepts the following arguments:

Argument	Description	Allowed Values
-h or --help	Prints help message
--viz --vizonly	Disables sending commands to the orbs

Explanation

Docker & Orbs

Docker is a virtualization technology that allows you to run an application in a container. Containers are isolated from the host system, like a virtual machine.

The docker image orbs-gmu-docker-v1 is a container that runs SITL (Software in the Loop) simulations of the Orb. This means that for each Orb in the simulation, your computer will run a copy of the Orb's onboard software. The --net=host option allows the Orbs to break network boundaries and communicate with each other and with anything else on your computer and network.

When you run ./launch_swarm.sh 6, the script will spawn 6 Orbs on the "ground". The orbs have simulated physical dynamics to approximate the flight dynamics of real Orbs, as well as simulated GPS and IMU, but no collisions. Additionally, AFAIK, the world is an infinite plane.

You can see or edit the networking and spawn parameters at the docker terminal:

nano imperium/config/orbs/jawbreaker/sitl/sitl.cfg.toml

When spawned, the Orbs are in a semi-dormant state. They will report their position and status only partially.

The Orbs communicate by sending UDP packets in broadcast or multicast mode. The format of the packets is defined by EpuC2.proto. This is a protobuf file written by JHUAPL. We've generated the python code for this file using protoc, and the resulting code is in EpuC2_pb2.py. This file should not be manually edited. It allows Python to read and send messages to/from the Orbs.

RobotSwarmSimulator

RobotSwarmSimulator is a python package that allows you to run 2D simulations of multiple robots. We're using it to visualize the Orbs' movements, store the state of the world, simulate the 2D BinaryFOVSensor, and send movement commands to the Orbs. We're not using it to simulate any kinds of physical dynamics; it just reads the positions and orientations of Orbs coming out of the Docker container. Technically, you DO NOT need RobotSwarmSimulator to interact with the Orbs, but it has some quality-of-life features that make it easier to configure and use. You can find the RobotSwarmSimulator documentation here.

When you run rssitl.py, the script will create a RobotSwarmSimulator world based on the world.yaml file. This is also when the agent definitions are loaded (in orb.yaml), which specifies things like the controllers (speed and turning rate), sensors (FOV and range), and other parameters for each agent. Then, it begins to run the simulation loop.

Here's what happens in the loop (starting from SITLUTMWorld.step()):

1. The script reads the Orbs' positions and orientations from the Docker container.
   1. Each Orb in the simulation has a unique name. If RSS hasn't seen the Orb before, it creates a new SITLOrbAgent with the name of the Orb.
   2. Otherwise, it updates the agent's position and orientation.
2. Each of the SITLOrbAgents runs its step() function.
   1. Each agent has a BinaryFOVSensor attached to it. It checks if any other agents are within its top-down 2D FOV.
   2. Then, the agent's SITLBinaryOrbController reads the 0 or 1 from the sensor, and chooses to turn left or right.
   3. Finally, the agent sends a movement command to the respective Orb in the Docker container. This command consists of a velocity command and a heading command.

However, because the Orbs operate asynchronously, we've also added a delay before the simulation sends a launch command to wake up the Orbs. This delay is specified in the world.yaml file. It waits for 6 unique Orbs to come online before sending commands.