Skip to content

Home

Jump to bottom
Peter Law edited this page Apr 4, 2018 · 44 revisions

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 was subsequently improved upon and used in the following three years. It has also been used for a number of other similar, though usually smaller, events.

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.

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

When deployed (via the comp-api puppet manifest), SRComp HTTP is run as a WSGI module within apache. This presents the world with a consistent REST interface to the available data.

This deployment requires a local clone of the state repo, which is configured (by the same puppet manifest) to automatically pull down changes from its canonical remote. While this updates the content of the state repo, it does not cause SRComp HTTP to actually reload the data (which is cached for sanity).

The HTTP layer will instead only reload its data when the modification time of the .update-pls file within root of the state repo. Typically this is changed by manually touching the file.

Details of previous deployments can be found at:

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.

Clone this wiki locally