Usage

Using the RCLL Referee Box

After successfully installing and configuring the refbox you are ready to run it. The refbox is split into a core program, which is the actual refbox and game controller, and a user interface to interact with the human referee. This controller can be either the graphical user interface (GUI) or the textual shell. At the moment the GUI is still work in progress, therefore we will explain how to use the textual shell with the refbox. The refbox implements the rules and regulations.

Concepts and Terminology

The refbox has certain concepts and terminology that we are going to explain first. Game Phase:: The phase describes what part of the game (as described in the rulebook) is currently active. There is one phase and one phase only active at any one time. The possible phases are:

• PRE_GAME: The game is prepared but not yet started. Teams are free to perform setup preparations. When the refbox is started it defaults to this phase. Setting the state to RUNNING (see below) will automatically advance to the PRODUCTION phase.
• EXPLORATION: exploration phase as utilized in the rulebook prior to the 2022 release. It lasts for 3 minute after which the refbox automatically switches to the PRODUCTION phase.
• PRODUCTION: production phase as described in the rulebook. It lasts for 20 minutes after which the refbox automatically switches to the POST_GAME phase.
• POST_GAME: The game has ended.

Game State

The state describes whether the game is currently waiting to be started, active and running, or paused. There is one state and one state only active at any one time. The possible states are:

• INIT: The refbox is currently being initialized. If you set this state the refbox will be completely reset as if it were just started. It automatically advances to WAIT_START once initialization has completed.
• WAIT_START: The refbox has finished initializing and is awaiting the game start.
• RUNNING: The game is active. The robots must perform their tasks according to the rules and the game time is advancing.
• PAUSED: The game has been interrupted. All robots must stop moving immediately. In the production phase machine processing will be suspended and in the exploration phase all signals will be turned off.

Robots

Robots are any hosts that communicate with the refbox via peer-to-peer communication. This includes the field robots, but also any other machine the team has connected to the network participating in refbox communication.

Game time

The game time is a duration measured in seconds and announced periodically in the !GameState message. The game time is advanced in the EXPLORATION and PRODUCTION phases while in the RUNNING state. The game time is reset per game phase, i.e. after the exploration phase the time is reset to zero and starts again for the production phase.

Active orders

In the production phase orders are posted that the robot must process. Orders have a delivery time in which higher points are awarded. And order is active if it is published, even if the game time is out of the delivery period. Inactive orders are not posted at all. This is used for late orders. At certain (random) points in time a late order is activated and from then on published.

Starting the refbox

Firts you need to start the refbox. To do so go to the base directory of the rcll-refbox build. Then execute the refbox. It will print two lines indicating that the refbox environment is being created.

$ bin/rcll-refbox
16:05:19.129533 RefBox: Creating CLIPS environment
16:05:19.137786 C: Loading refbox main file 'refbox'

The refbox is now waiting for the start signal from one of the controllers.

Docker

If you run the refbox from a container, run:

$ docker run --rm --net=host robocuplogistics/rcll-refbox

The --net=host is necessary as the refbox is supposed to communicate with the robots through its public IP address, with --net=host we use the host's network stack instead of creating a separate Docker bridge network.

If you want to run a custom config, mount the config into the container with -v:

$ docker run --rm --net=host -v /absolute/path/to/config:/etc/rcll-refbox/config.yml robocuplogistics/rcll-refbox

e.g.,

$ docker run --rm --net=host -v $(realpath ./config.yml):/etc/rcll-refbox/config.yml robocuplogistics/rcll-refbox

to use the local ./config.yml.

Using the Web Frontend

The refbox can be controlled via a web-based frontend.

Using the shell

The shell is deprecated in favor of the web-based frontend. The shell is started with the command bin/rcll-refbox-shell. You can quit in the main screen (when no menu is open) typing 'q'. Note that quitting the shell will not end the refbox itself. After startup the shell will automatically connect to the configured refbox host and port. The shell will try to reconnect automatically whenever the connection to the refbox is lost.

Docker

To run the shell in a container, run:

$ docker run --rm --net=host -ti -e TERM robocuplogistics/rcll-refbox llsf-refbox-shell

The additional arguments -ti are necessary to run the shell in an interactive terminal. Additionally, -e TERM passes the TERM environment variable to the container. This is necessary to have the correct terminal colors in the shell.