Erebus is a rescue simulation competition environment designed for semi-experienced to highly experienced programmers.
- Python 3.6+
- Webots
Currently installable automated builds are not yet available; all components
must be built before running. The Webots controllers have
additional runtime Python dependencies; these can be installed by their
respective requirements.txt
files:
# from repository root, after builds are performed
$ pip -r game/controllers/erebus-robot-controller/requirements.txt \
-r game/controllers/erebus-supervisor-controller/requirements.txt
Once these dependencies are installed, launch Webots and open
game/worlds/GeneratedWorld.wbt
, and press the "Run the simulation in
real-time" button located on the toolbar next to the clock if the world has not
started yet (if the console is empty except for a line stating INFO: MainSupervisor: Starting controller: python -u "MainSupervisor.py"
, then it has
not started yet). The simulation should pause immediately.
Ignore the controls in the left-hand panel; they are currently not-implemented, and the starting, stopping, and resetting of the simulation, as well as the connecting of competitors' controllers, is handled by the CLI.
The broker control CLI is currently the primary way of controlling the simulation, which includes starting, stopping, and resetting the world, and connecting a competitor's controller to a virtual robot.
Its source is located at broker-control-cli/
, and running make
will produce a
binary broker-control-cli
. Run broker-control-cli help
to learn how to use
it (better documentation coming soon).
First, install the client library (see the section on building it).
Docs are available in the client library's directory, and an example controller demonstrating reading sensors and controlling motors is also available in the examples directory
- Go 1.13+
- Poetry
- GRPC tools
gox
Assuming $GOPATH/bin
is in your PATH
, the GRPC tools and gox can be
installed like so:
$ GO111MODULE=off go get -u google.golang.org/grpc github.com/golang/protobuf/protoc-gen-go github.com/mitchellh/gox
Erebus runs in a client-server architecture, with the broker as the master server that everything else connects to. The broker is responsible for relaying data between a virtual robot and a client controller (what a competitor writes - referred to hereafter as simply a "client"), and also handles starting, stopping, and resetting the environment (although currently it just forwards this to all connected services).
Each virutal robot runs a Webots controller which connects to the broker and awaits a peer client to be connected to it. Likewise, each client connects to the broker and awaits a robot controller to be connected to it. The broker provides an interface to connect pairs of Webots robot controllers and client controllers together by their names, at which point the controllers exchange messages for sensor data and commands.
The supervisor controller (wb-controllers/erebus-supervisor-controller
) is
responsible for making sure that the state of the Webots simulation matches the
state in the broker by starting, pausing, and resetting the simulation when
appropriate.
The broker control CLI issues commands to the broker, and allows a game administrator to list connected clients and robots, connect / disconnect robots to clients, and set the state of the simulation.
A top-level Makefile exists with a convenience target proto
to generate code
for all components depending on protobuf:
$ make proto
This is necessary for developing all Python components (the generated code is
excluded from Git), and you should always run this after editing the proto
definitions (in shared/proto
) to ensure that generated code is up-to-date. Be
sure to commit changes to generated Go sources (*/gen/*.pb.go
)
The broker (broker/
) is a go-modules-enabled project, and includes a Makefile
for generating protobuf files (make proto
). After proto sources are generated,
it can be built using the standard go build
, and a convenience target is also
set up in the Makefile so you can build using make
.
The broker control CLI (broker-control-cli/
) is set up the same way as the
main broker itself. Use make
to build.
The Python client library (client/python
) is managed using
Poetry and a Makefile for handling GRPC / Protobuf
generated code (see GRPC / Protobuf). To build an
installable library, first run make
, then run poetry build
; the resulting
packages can be found in client/python/dist
and installed using pip install
.
The Webots controllers are located at wb-controllers
and are symlinked into
the Webots project directory (game/controllers
) as needed. As they depend on
GRPC / Protobuf generated code, each controller has a Makefile to generate this
code. The controllers' sources are not managed by Poetry, thus the GRPC Python
tools must be available in the Python path when the Makefile is run. These
dependencies are listed in the requirements-dev.txt
files of each controller.
The erebus-supervisor-controller
has an additional build step (invoked by
make build
) which performs a cross-build for the broker, and copies
the resulting executables into the build output along-side the Python code for
the controller.