Skip to content

Latest commit

 

History

History
168 lines (117 loc) · 5.99 KB

README_DEVELOPER.md

File metadata and controls

168 lines (117 loc) · 5.99 KB
Raw

Scope

This document is intended to be used by someone running the ARIAC competition. If you are competing in ARIAC, you may ignore this file. It describes how to update and release docker images for competitors to use.

Overview

Two Docker images are distributed to teams: the ARIAC server image (runs the simulation), and the competitor base image (has ARIAC but not Gazebo installed) that team's will build their Docker image on top of. These are generated by the prepare_team_system.bash script and distributed via Dockerhub (see "Releasing a new version of ariac3 Docker images" below).

At run-time, (after teams' Docker images have been created), run_trial.bash is the core script that starts the two containers. The containers communicate using a Docker network. The Gazebo server running in the ARIAC server container is configured to not accept communication from external clients such as the competitor container. A custom version of the Gazebo-ROS interface that runs in the ARIAC server container is used, which does not expose ROS interfaces that can be used to interface with the simulator. Only the ARIAC ROS interface is exposed.

A number of convenience scripts are provided for running the competition: see "Running the competition" below).

Releasing a new version of ariac3 Docker images.

Before you begin, you must release a new version of the ARIAC debian package. In 2017 this package is ariac, in 2018 ariac2, and in 2019 ariac3. If you are running a competition later than 2019 you will need to create and release a new debian package.

1. Build the base Docker images.

The most recent version of packages will be installed from apt. Packages installed from apt include:

  • ariac3
  • gazebo9
  • ROS packages except those in gazebo_ros_pkgs

The gazebo_ros_pkgs metapackage is built from source using this branch specific to ARIAC.

./prepare_ariac_system.bash

2. Test using local images.

Replace references to ariac/ariac3-*:latest images with the local image name, where images are being used for (1) building team images and (2) running trials.

To do this, re-tag the built images:

docker tag ariac-competitor-base-melodic ariac/ariac3-competitor-base-melodic:latest
docker tag ariac-server-melodic ariac/ariac3-server-melodic:latest

Now test by building a docker image for the example team.

./prepare_team_system.bash example_team

Make sure a trial can be run using the built image.

./run_trial.bash example_team sample

While the trial is running, confirm the ARIAC version running in the container is correct:

docker exec -it ariac-server-system /bin/bash
dpkg -s ariac3

3. Push the images to Dockerhub.

Configure Dockerhub credentials, then:

./push_dockerhub_images.bash <ariac_version> <gazebo_version
# e.g.:
# ./push_dockerhub_images.bash ariac3.0.0 gazebo_9.6

This will also update the lastest tag on Dockerhub images.

Running the competition.

1. Fetch the latest Docker images.

Fetch the most recent ariac3 Docker images from Dockerhub.

./pull_dockerhub_images.bash

2. Download team systems.

Create a directory for each team in team_config and place their system's files in it, following the layout in team_config/example_team.

3. Prepare Docker images for all team systems.

There is a convenience script for preparing all teams at the same time, but it is inconvenient when one team's image fails to build.

./prepare_all_team_systems.bash

Instead it makes sense to build the team's docker images one at a time using prepare_team_system.bash directly.

4. Download the trial config files.

Make sure the trial_config directory contains only the trial configs you want to use. All of them will be run. Each trial config must have gazebo_state_logging: true so that the log file used for playback (gazebo/state.log) is created.

5. Run all trials for all teams.

./run_all_trials.bash

This will output results to the logs directory with the following structure:

logs
└── example_team  # team name
    └── sample  # trial name
        ├── gazebo
        │   └── state.log  # gazebo state log file
        ├── generated  # the specific files generated by gear.py based on team/trial config files
        │   ├── gear.launch
        │   ├── gear.urdf.xacro
        │   └── gear.world
        ├── performance.log  # scoring log file
        ├── ros  # ROS logs copied from ARIAC server container
        │   └── rosout.log
        └── ros-competitor  # ROS logs copied from competitor container
            └── example_node-1-stdout.log

6. Generate videos from Gazebo state logs.

./run_all_team_videos.bash

This will add a video directory to each trial found in the logs directory with a screen capture of the state log playback, e.g.:

logs
└── example_team
    └── sample
        ├── gazebo
        ├── generated
        ├── performance.log
        ├── ros
        ├── ros-competitor
        └── video
            └── example_team_sample.ogv

7. Re-run trials as necessary.

Before re-running any trials, copy the logs directory to one with another name.

A single trial for a single team can be re-run using ./run_trial.bash example_team final_01 where example_team is the name of a folder in team_config/ and final_o1 is the name of a yaml file (excluding .yaml) in trial_config/.

All trials can be re-run for a single team using ./run_all_trials.bash example_team.

All trials can be re-run for a set of teams by using ./run_all_teams.bash after editing the LIST_OF_TEAMS variable in run_all_teams.bash.

A single trial can be re-run for all teams using ./run_all_teams.bash after editing the LIST_OF_TRIALS variable in run_all_trials.bash.