Home
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.
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.
SRComp is highly modular, with each of its components addressing a specific need and occupying its own git repository.
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.
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.
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.
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:
srcomp-puppet.git provides a puppet configuration suitable for creating the central "compbox" at the competition event. The "compbox" hosts all the SRComp related services needed to run the competition.
A Vagrantfile is provided to simplify both development and deployment.
srcomp-kiosk.git provides a puppet configuration suitable for provisioning any of the Raspberry Pi based screens at the competition. See the INSTALL.md file for setup instructions, including how to bootstrap the Pis.
The ranker provides a generalised mechanism for ranking the participants results of an arbitrary game and awarding normalised points. It supports disqualifications and allows for ties and is used for calculating league points and in determining progression in knockouts.
This repository provides a Python API to accessing information about the state of the competition. It also includes some utilities for operating on compstate repos.
Python clients should submodule this repo and then import it.
from srcomp import SRComp
comp = SRComp('/path/to/compstate')
This repository provides a JSON API to accessing information about the state of the competition. It is a lightweight Flask application which wraps the SRComp core.
Most clients are expected to use this to get their information about the competition.
srcomp-dev.git provides a development wrapper around the above HTTP application as well as including most of http clients via submodules.
srcomp-cli.git provides a collection of command-line tools for operating on or showing data from compstate repos.
To display information about the competition state to competitors and the general public over the competition weekend, there are a number of special web pages.
There are two parts to these pages:
- a collection of pages which assume that they sit in the
/comp/url of the host website - a replacement for the site's homepage (
/)
Both of these are implemented as interactive [https://angularjs.org/ AngularJS] single-page applications on top of the HTTP API.
A node.js service which polls the HTTP API for changes and issues events based on any detected.
This repository contains the following screens:
- The
arena.htmlscreens go in the four corners of the arena and display the current match information. - The
outside.htmlscreens go around the competition venue and display 4 rotating pieces of information: Knockout diagram, Leaderboard, Match Schedule and Scores. - The
shepherding.htmlscreen is used by the shepherds and contains information about the current and upcoming matches so the teams can be located in time. This replaced the previous srcomp-shepherding.git in 2015. - The
staging.htmlscreen is used by the shepherds and contains information about the current and upcoming matches so the teams can be placed in the right arenas.
These are implemented using a lightweight SR JavaScript library which interfaces with the HTTP API.
A Flask application which manages score entry into the compstate. It ensures that scores are entered into the proper format as well as validating that the submitted scores pass validation by the compstate's scorer.