SRComp

SRComp is a suite of software for running competition events. It aims to record the entire state of the competition in a single place and provide tooling for working with that data in a consistent and reproducible manner.

SRComp assumes:

• that you have a league section and/or a knockout section; if you have both then the league comes first and seeds the knockout
• that you can generate fair match plan (i.e: who plays who in which match) yourself (though it does provide some tooling to check that a plan is fair)

SRComp includes support for:

• generating match schedules from match plans, by incorporating both time to reset arenas between matches as well as planned and unexpected delays
• games with multiple participants, with graceful handling of no-shows and disqualifications
• normalising per-game scores to allocate league scores and/or determine knockout progression
• resolving ties
• concurrent arenas, though with the caveat that games in multiple arenas start at the same time and are of the same length
• "shepherds"; people who fetch participants before their matches
• large-screen displays of information for shepherds
• large-screen displays of information for the audience
• web pages with information for an external audience
• web pages with information for competitors
• real-time updates of the state of the competition, including consistent distributed hosting of the displays and HTTP API

A more complete overview of the project's original requirements is available at competition software.

History

SRComp was created for Student Robotics' 2014 competition, and has been used for all subsequent competitions. It has also been used for a number of other similar, though usually smaller, events.

SRComp continues to evolve to support the needs of Student Robotics competitions.

Structure

SRComp is highly modular, with each of its components addressing a specific need and occupying its own git repository.

Compstate repositories

Information about the competition is stored in a compstate repo. This includes all the core data about the competition, from when the matches are to what the scores of a given match were. See the dummy-comp repo for an example. This wiki also contains notes on preparing a compstate for a competition.

While the compstate repo for any given event is the ultimate source of truth and (being YAML) is largely human-readable, all interaction with the contained data is expected to be done using the tooling and APIs provided by SRComp, rather than by direct inspection of the files.

This is largely as the data in the compstate is in a fairly raw form, though it also contains a substantial amount of coupling between files. As a couple of examples: the compstate store the game points scored for each match, but doesn't include the normalisation of those scores nor an explicit record of who won the match. Similarly, the scores for a given match are stored separately from the plan of matches, yet they must both agree on which teams were expected to be in the match in order for the state to be valid.

Information access

Python clients can inspect a compstate using the sr.comp package which is provided by the main srcomp repository. This both ensures that the compstate is valid before yielding any information and presents the canonical view of the state of the competition. As well as being more convenient to work with, the presented view includes calculated data, such as the winners of matches and the resulting league points or knockout progression.

Other clients are encouraged to use the HTTP API provided by the srcomp-http repository. In the expected deployment scenario a copy of the HTTP API will be hosted on a central machine (a "compbox") within the venue as well as on an external server. This ensures easy access to the HTTP API for both local and external clients without requiring a reliable internet connection to the venue.

Component summary

The remainder of the SRComp suite builds on top of these two parts:

• SRComp scorer provides a UI for score entry
• SRComp CLI provides command line tools for those handling match operations
• SRComp puppet provides deployment of a compbox, which includes:
  • SRComp HTTP provides the HTTP API as discussed above
  • SRComp stream provides an event stream by wrapping the HTTP API with polling
  • SRComp screens provides web pages suitable for as in-venue full-screen information displays
• SRComp kiosk provides deployment of clients (typically Raspberry Pis) pointed at SRComp screens
• Website pages provides a mini-site of pages suitable for integrating into an existing public website for the event

An overview of the individual components follow, though their READMEs contain more comprehensive summaries.

Deployment

If you are deploying to a "compbox" (a standalone machine intended to host SRComp services), deployment should be achieved using SRComp puppet. This is the recommended route for most deployments as it is the most complete.

Alternatively, if you wish to deploy SRComp services within an existing puppet configuration, there is an example of doing that via the srcomp.pp and comp_api.pp puppet manifests which are part of the configuration for Student Robotics' legacy server. Note that this only includes configuration for the HTTP API and accepting state deployments, but none of the other services.

Details of previous deployments can be found at:

• SR2016-Deployment
• SR2017-Deployment
• SR2019-Deployment

Usage

SRComp aims to provide information in a format which is generally consumable by those at an event, without them needing to have any understanding of the system.

For those operating SRComp at an event, it aims to be easy to use and simple to debug. Common-Operations outlines the main things which will be needed at any competition event.