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. 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

First 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/./refbox
    16:42:37.674050 RefBox: Creating CLIPS environment
    16:42:37.674437 RefBox:  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 quay.io/robocup-logistics/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/refbox/config.yml quay.io/robocup-logistics/rcll-refbox

e.g.,

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

to use the local ./config.yml.

Using the Web Frontend

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