Skip to content


Tarik Viehmann edited this page Nov 21, 2021 · 7 revisions

RCLL Referee Box Configuration

The refbox supports several configuration values that are stored in YAML files. YAML is a structured document format. For the configuration, especially note that the indentation is crucial. The document forms a tree where values are addressed by paths. Especially network related parameters might need to be changed.

YAML Example

A simple excerpt of a configuration file is used to explain the YAML structure.

    level: debug
    general: refbox.log

This defines two configuration values. One has the path /llsfrb/log/level and the value is debug. The second is /llsfrb/log/general with the value refbox.log. The types of the values are implicitly determined to be one of unsigned integer, signed integer, float, boolean (true or false) or string (in that detection order).

Customizing the Referee Box with YAML

The refbox comes with default configurations, that may be tweaked for your specific setup.

To ease the effort, the configuration setup distinguishes between different components, which allows for fine-grained customization through running the refbox executable with additional command-line parameters.

For example, in case you want to run the refbox, but do not wish to connect to one/several/all real machines, you may need to either adapt the connection settings to fit your simulation setup or disable connections to functional OPCUA servers. The latter can be achieved by using the mockup setting. If a machine is set locally to mockup the refbox may locally mockup machine interactions.

In such a case, all the other configurations are irrelevant and do not need to be adapted, only those for the component machine need to be changed.

Components are defined through the directory layout within the cfg/ directory of the refbox. If a file cfg/component/default_component.yaml is present, the refbox recognizes and loads that file per default. If you wish to modify these options without modifying the default file, the refbox offers a command-line option *--cfg-component yaml-file to load yaml-file instead of default_component.yaml. In case of the mockup machine configuration, you can simply provide the path for the pre-existing mockup configuration, or rename the mockup file as default file, such that it will be loaded without additional CL options.

In the example above, the refbox already provides a component mps and an alternative file cfg/mps/mockup_mps.yaml, which configures all MPS conections to the mockup modus. So running the refbox with options --cfg-mps mps/mockup_mps.yaml would do the trick.

Run the refbox with option -h for more information.

Predefined Configuration Components

All components contain configuration paths with the common prefix llsrfb/. Default components are distinguished based on the different prefixes they have. A component component usually contains configuration values under the prefix llsfrb/component/.


As an exception to the naming convention, in main/default_main.yaml multiple second-level keywords are grouped together:

Connection options to various external tools can be found under the follwoing prefixes:

  1. llsfrb/shell/ regarding the refbox shell
  2. llsfrb/webshop/ to use the webshop
  3. llsfrb/websocket/ and webview/ to interact with the web frontend
  4. llsfrb/workpiece-tracking/ to play with workpiece tracking devices

Additionally, there are:

  1. llsfrb/log/ to tweak logging output
  2. llsfrb/clips/ for CLIPS environment options (The engine that controls the refbox)


Prefix: llsfrb/mps/

Purpose: Options to connect to MPS machines

Note the two different connection modes plc and mockup. The former causes the refbox to connect to an OPC-UA server, the latter mocks up answers from the respective OPC-UA server under the assumption that the MPS works without errors.


Prefix: llsfrb/mongodb/

Purpose: Connect to a mongodb backend for advanced logging

Some advanced refbox features may require a connected mongodb backend, such as those in the game component.


Prefix: llsfrb/game/

Purpose: Control randomization options of RCLL games

Options under this prefix are useful if you aim to play multiple games with the same field and/or order setup.


Prefix: llsfrb/game/

Purpose: Add your teamname and crypto key here

These configurable options are also stored under the game prefix, but are specific to the teams that use the refbox. Since you most likely want to adapt these settings to your own needs, this is separed from the game component.


Prefix: llsfrb/comm/

Purpose: Connection settings for the protobuf communication with the refbox

You will most likely adapt the setting regarding the different host ip addresses according to your local network setup.


Prefix: llsfrb/simulation/

Purpose: Tweaks to sync up with a simulation environment

The refbox can synchronize its time to a running gazebo environment, which allows for realistic simulations, when the real-time factor significantly deviates from 1. Alternatively, the realtime factor of the refbox itself can be changed.


Prefix: llsfrb/challenges/

Purpose: Play specific challenges instead of a full RCLL game

The refbox allows to play a fully customized game through its challenge mode. This includes games played on smaller fields, deterministic orders, reduced number of machines and more.

These customization options are also the baseline for the official RCLL challenge mode. Hence various different configuration options are provided.

Consider using the helper scripts to conveniently start the refbox with the official challenges.

Tools and the RefBox Configuration

Several companion tools require to know the RefBox configuration, e.g., the rcll-refbox-instruct tool. For those to work, you need to command the refbox to dump its current configuration, which can be done via the --dump-cfg option.