Skip to content

Launch Workflow with Docker and Docker Compose

To mimic interacting with multiple real world robots, we use Docker Compose to manage Docker containers that isolate the simulation, each robot, and the ground control station.

The details of the docker compose setup is in the project root's docker-compose.yaml.

In essence, the compose file launches:

  • Isaac Sim
  • ground control station
  • robots

all get created on the same default Docker bridge network. This lets them communicate with ROS2 on the same network.

Each robot has its own ROS_DOMAIN_ID.

Pull Images

To use the AirLab docker registry:

cd AirStack/
docker login airlab-storage.andrew.cmu.edu:5001
## <Enter your andrew id (without @andrew.cmu.edu)>
## <Enter your andrew password>

## Pull the images in the docker compose file
docker compose pull

The available image tags are listed here.

Build Images From Scratch

docker compose build

Start, Stop, and Remove

Start

docker compose up --scale robot=[NUM_ROBOTS] -d

# see running containers
docker ps -a

Stop

docker compose stop

Remove

docker compose down

Launch only specific services:

# only robot
docker compose up robot --scale robot=[NUM_ROBOTS] -d
# only isaac
docker compose up isaac-sim -d
# only ground control station
docker compose up gcs -d

Isaac Sim

Start a bash shell in the Isaac Sim container:

# if the isaac container is already running, execute a bash shell in it
docker exec -it isaac-sim bash
# or if not, start a new container
docker compose run isaac-sim bash

Within the isaac-sim Docker container, the alias runapp launches Isaac Sim. The --path argument can be passed with a path to a .usd file to load a scene.

It can also be run in headless mode with ./runheadless.native.sh to stream to Omniverse Streaming Client or ./runheadless.webrtc.sh to stream to a web browser.

The container also has the isaacsim ROS2 package within that can be launched with ros2 launch isaacsim run_isaacsim.launch.py.

Robot

Start a bash shell in a robot container, e.g. for robot_1:

docker exec -it airstack-robot-1 bash

The previous docker compose up launches robot_bringup in a tmux session. To attach to the session within the docker container, e.g. to inspect output, run tmux attach.

The following commands are available within the robot container:

# in robot docker
cws  # cleans workspace
bws  # builds workspace
bws --packages-select [your_packages] # builds only desired packages
sws  # sources workspace
ros2 launch robot_bringup robot.launch.xml  # top-level launch

These aliases are in AirStack/robot/.bashrc.

Each robot has ROS_DOMAIN_ID set to its ID number. ROBOT_NAME is set to robot_$ROS_DOMAIN_ID.

Ground Control Station

Currently the ground control station uses the same image as the robot container. This may change in the future.

Start a bash shell in a robot container:

docker exec -it ground-control-station bash

The available aliases within the container are currently the same.

On the GCS ROS_DOMAIN_ID is set to 0.

SSH into Robots

The containers mimic the robots' onboard computers on the same network. Therefore we intend to interface with the robots through ssh.

The ground-control-station and docker-robot-* containers are setup with ssh daemon, so you can ssh into the containers using the IP address.

You can get the IP address of each container by running the following command:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' [CONTAINER-NAME]

Then ssh in, for example:

ssh [email protected]

The ssh password is airstack.

Container Details

graph TD
    A(Isaac Sim) <-- Sensors and Actuation --> B
    A <-- Sensors and Actuation --> C
    B(Robot 1) <-- Global Info --> D(Ground Control Station)
    C(Robot 2) <-- Global Info --> D

    style A fill:#76B900,stroke:#333,stroke-width:2px
    style B fill:#fbb,stroke:#333,stroke-width:2px
    style C fill:#fbb,stroke:#333,stroke-width:2px
    style D fill:#fbf,stroke:#333,stroke-width:2px

Automated Testing

To perform automated tests for the configured packages, please use the autotest service which extends the robot service with testing specific commands. Presently only takeoff_landing_planner is configured to be tested.

# On your development PC, do:

docker compose up autotest

This command will spin up a robot container, build the ROS2 workspace, source the workspace and run all the configured tests for the provided packages using colcon test. Excessive output log from the build process is presently piped away to preserve readability.

Docker Compose Variable Overrides

Sometimes you may want to test different configurations of the autonomy stack. For example, you may want to disable automatically playing the sim on startup, or to change a child launch file.

The docker compose workflow is designed to support these overrides for local development. docker compose uses .env files to set docker-compose variables that get propagated and interpolated into docker-compose.yaml files. See the docker compose documentation for more details.

The default .env file is in the project root directory. When no --env-file argument is passed to docker compose, it automatically uses this default .env file.

To override the default .env file, you can pass the --env-file argument to docker compose with a path to your custom .env file.

For example, this command disables playing the simulation on startup by overriding the PLAY_SIM_ON_START variable: 

docker compose --env-file .env --env-file overrides/no_play_sim_on_start.env up -d

As another example, this command changes the perception launch file to perception_no_macvo.launch.xml: 

docker compose --env-file .env --env-file overrides/no_macvo.env up -d

When overriding, the default .env file must be loaded first. The overrides are applied on top of it.