ssl-game-controller

The ssl-refbox replacement that was introduced at RoboCup 2019.

Usage

If you just want to use this app, simply download the latest release binary. The binary is self-contained. No dependencies are required.

The controller will generate a default config file to config/ssl-game-controller.yaml on the first start. Afterwards, you can change all settings there.

Runtime Requirements

• No software dependencies (except for development, see below)
• 64bit Linux, Windows, OSX (build your 32bit binaries yourself...)
• Display Resolution of 1920x1080 is recommended
• A reasonable Web-Browser (mostly tested on Chrome)
• (optional) To view the field, you need the ssl-vision-client

Reference Clients

There are some reference clients:

• ssl-ref-client: A client that receives referee messages
• ssl-auto-ref-client: A client that connects to the controller as an autoRef
• ssl-team-client: A client that connects to the controller as a team
• ssl-remote-control-client: A client that connects to the controller as a remote-control
• ssl-ci-test-client: A client that connects to the CI interface of the controller

Comparison to ssl-refbox

The ssl-game-controller replaces the ssl-refbox. With the introduction of automatic referees, there was demand for several new features. To accommodate these, the ssl-refbox has been rewritten to take advantage of modern technologies.

The referee message, that is send to the teams, has no breaking changes. Teams do not need to change their systems. Additional data will be send with the referee messages though. To read those changes, teams can update their .proto files from this repository to take advantage of it.

Teams will also have the possibility to connect to a new interface, where they can change their goalkeeper number.

List of new features:

• Modern, scalable Web-UI
• More control of the state (change almost all values)
• Automatically save and restore state
• State history with undo button
• Includes state that was previously located in all autoRefs
• New Game Event concept for better interaction with multiple autoRefs
• Game protocol that documents all changes in the state
• New interfaces for autoRefs and teams
• A graphical client can be integrated

FAQ

How to start a new game?

• Go to Settings (top left button)
• Start new game
• Select team names
• Switch sides, if necessary (button)
• Select division, if necessary (button switch)
• Set goalkeeper ids
• Choose which team will start with kickoff
• divB: set ball placement capability

How to end a game?

• Stop the game
• Make sure you are in the second half, extra second half or in shootout
• An 'End of Game' button should show up on the top

Purpose: Notify team AI about end of game and log it in log files.

How to give a goal?

If an autoRef has sent a 'possible goal', this event can be accepted on the right.

To add a goal manually:

• New Event (on the top)
• Select Goal
• Insert parameters
• Add

How to correct the current state of a team?

Most of the state can be changed with the edit buttons. Either in the settings modal, or in the team overview. This should only be used in case of misbehavior! Goals, yellow cards, etc. should be given through the respective events ('New event' button) or in the manual view.

How to revert a change?

The game control allows reverting certain actions like game events or stage changes. For these actions, a revert button will show up in the protocol table. The button reverts this line and all following.

How to disable certain game events?

Go to 'Configure Behaviors' in the settings modal and select the game event.
A game event can be set to be:

• Always accepted
• Only accepted when there is a majority between all connected autoRefs (if only one autoRef is connected, it will always get a majority)
• Ignored (logged as an ignored event in the table)

How does the continue button work?

Based on the current game events, the next command will be determined. This command is sent, when the continue button is pressed. The button shows the command that it will trigger.

How can I see if my team is connected?

Active connections to teams are shown as an icon in the team overview.

The controller crashes on start. What can I do?

Try deleting the state-store.json.stream file in the working directory. It may got corrupted.

How can I use TLS?

Generate a new server.crt for the game-controller with tools/newX509KeyPair.sh. See instructions for the client part in the reference clients mentioned above.

Integration into your own framework

The game-controller can easily be integrated into your own AI framework, if you do not want to implement your own controller for testing purposes.

Download the release binary from the Github release and run it from inside your framework. Then, attach to the WebSocket API that is used by the UI as well to control the game. The API is defined in proto/ssl_gc_api.proto and available at the path /api/control.

If you don't want to run the controller in real time, you can change the time acquisition mode in the ssl-game-controller.yaml file:

1. system (default): Use system time
2. vision: Receive messages from ssl-vision and use the timestamps from these messages as the time source. This is mostly useful, when you produce your own ssl-vision frames from simulation.
3. ci: Connect your software directly to the GC via TCP. You can send the current timestamp and tracker packets and will receive the resulting referee message.

The ci mode also disables all multicast messages. This is especially useful, if you run integration tests on your build server in parallel and/or in a container. The GC does not receive vision or tracker packages and does not produce referee messages. Instead, you should set the correct geometry in ssl-game-controller.yaml and send the tracker packages via the CI protocol along the timestamp. The referee messages are send from the GC to you via the CI protocol as well. For every CiInput there will be one or more CiOutput responses. This is, because some changes will generate multiple messages. CiOutput messages will also be pushed to the CI client for manual changes from the UI or UI API.

For details, see: ssl-ci-test-client

Examples

• Integration of the binary: https://github.com/TIGERs-Mannheim/AutoReferee/blob/master/modules/moduli-referee/src/main/java/edu/tigers/sumatra/referee/SslGameControllerProcess.java
• WebSocket API in Java: https://github.com/TIGERs-Mannheim/AutoReferee/blob/master/modules/moduli-referee/src/main/java/edu/tigers/sumatra/referee/control

Development

Requirements

You need to install following dependencies first:

• Go >= 1.13
• Node
• Yarn

Prepare

Download and install to GOPATH:

go get -u github.com/RoboCup-SSL/ssl-game-controller/...

Switch to project root directory

cd $GOPATH/src/github.com/RoboCup-SSL/ssl-game-controller/

Download dependencies for frontend

yarn install

Run

Run the backend:

go run cmd/ssl-game-controller/main.go

Run the UI:

# compile and hot-reload
yarn serve

Or use the provided IntelliJ run configurations.

Build self-contained release binary

First, build the UI resources

# compile and minify UI
yarn build

Then build the backend with packr

# get packr
go get github.com/gobuffalo/packr/packr
# install the binary
cd cmd/ssl-game-controller
packr install

Update generated protobuf code

Generate the code for the .proto files with ./generateProto.sh, after you've changed anything in a .proto file.