Home

#Welcome to the Row Times Wiki

Row Times is an application used by organisers and supporters of rowing events. The organisers use it to mark the start time and end time of crews in a head race (or other time trial format). One timing official at the begining of the course starts a timer and another official at the end stops the timer. The start and stop times are both recorded in real time so that the supporters can view the times as the crews are rowing. This adds excitement to the racing support.

For the techies this is an application with a server side in Google App Engine written in Python and a Client side in javascript and HTML using jinja2 to create dynamic content.

This wiki contains the following:

• The User Stories that describe the functionality of the system
• The Technical Design describing the technical implementation of the server and client modules

##User stories for the Row Times Application

The application is built to be used by organisers of events and supporters of events. The Organisers will:

• provide the event details, contestent details and format of the event
• act as timing officials.

The supporters will:

• be able to watch the progress of the race and see the timing of crews in real time

###For timing officials:

As a timing official using a mobile device on the river bank timing an event, I can get a List of crews participating in the event. Each crew has a number, name, crew configuration, picture of their rowing blade colours and empty boxes for their start time, end time and calculated delta.

PASTED INFORMATION THAT NEED FURTHER SORTED - WIP PV

timer boxes representing each stage of the race. in the timer boxes is the current start time and split time of each stage with the current stage counting up as time passes. Each crew on the list has a button next to them and if I press this button I will record an observed time against the crew for the stage they are at. The first press of the button enters a start time subsequent presses enters a time for each stage until the finish time is recorded . A press after the finish offers a pop up to validate and publish the time. Later I will want to validate times against other users also timing the race but initially it will be a single option: Validate and record the time record which also publishes for others to see or cancel validation.

Technical design overview

The application is built using google app engine with Python on the server and a choice of apps in the front end. We will start with a JavaScript client and html5

Using the login screen initiates logon and registration. This passes the user to the event screen which allows selection of an event. Choosing an event passes control to the Crews List page which shows a list of crews about to race in the chosen event with current status of timing for each crew and an optional button if the user is authorised to time crews. options for managing timing are:

1. Google app engine channels will send updates from other users when they record times by calling a broadcast function on asynchronous mode after updating the time event in the database at the backend.
2. Google app engine will be called every few seconds with an API call to get timing events since the last numbered event received
3. Google app engine will be called every few seconds for the complete list of crews and their times and stages using API end points
4. Google app engine is called using jquery to get an HTML segment to update the current crew times. Pols every 5 seconds. I prefer option 1 or 2 because while the screen is refreshing it will reduce sensitivity to button press events and in a timing application we want the button press to be uninterrupted. In practice the crews timing will only be updated every 1.5minutes or so and only 3 or 4 crews will be running at any one time so polling a lot seems to be excessive while channel service seems to be most efficient. However, channel services is more difficult and can only be used with JavaScript so perhaps a 2 or 3 second polling frequency with an API endpoint is a better option. I think I have talked myself into option 2. Which uses Google API end points.

So the key software components will be:

Client (JavaScript and Html5): - Page for login/register page - Header page with navigation tabs - Page to enter event and crews for event - Page to choose event from list - Page with crews listed, times and start/split/stop button JavaScript to keep the time and button stage updated - Page with validation options

Server (Python) - Load login/register page - Process successful login and load main header and event list page - Process loading a page with crews, times, start/stop button) - Process adding an event and crews for event - Process API to record an observed time - Process API to retrieve observed times from other users since the last successful request: return JSON - Process loading a validation page for a set of times for a crew - Process posting a valid set of times for a crew

Database Object entities

• User Accounts (Account)
• Regatta and head events (Event)
• Crews taking part in an event (Crew)
• Observed Times for a crew at a particular stage of the race (ObservedTime)
• Validated times and splits for a crew in an event (ValidatedCrewTime) More details on the components

Python in the backend: Process loading a page with crews, times, start/stop button)

• retrieve each crew from the database for an event and where they haven't started or finished less than 10mins ago
• create an iterable object with each crews timing record, which includes the crew number, name, number of stages in the race, timestamp for each stage.
• Pass this list of records to the jinja2 HTML template. The template: - uses the list of records in a for loop to create a list of crews with time data and a start/stage/finish button. - If the button is pressed then an action will run a JavaScript function to call the API to record an observed time - The function will be passed the crew-id, the DoM element[array] that should be updated with the time, the time the button was pressed, the DoM element containing the stage of the race.

The JS function on timer button press will:

• If race stage not finished then ○ Update the record for the crew with the new timestamp and calculate the split times ○ Post the updated record to the backend with the stage just recorded (using API) ○ Update DoM elements showing the timestamp and the split on the screen ○ Change the button colour and text to reflect the next stage to be recorded ○ If race now finished then change button colour and text to "validate"

• If race stage at validate then ○ Go to the validate times page The JS function onload of page will:

• Use API to retrieve list of crews and their current time and race stage

• Create an array representing each crew and their observed times so far.

• Use the array to create the page with list of crews and their times

• Set up a polling function to retrieve new observations every 5s and use them to update the array and the page objects that have changed. Backend:

Python for recording observed times - Parse JSON data into crew time observation for a specific stage by a specific user - Check stage correct, one not missed, time within tolerance etc, - Record observation in Observation database entity with server timestamp as well as supplied time from the front end - Return time recorded and split calculated and any error codes or warnings

Python for validate page load and record results: - Get all time event observations for the specified Crew - Construct a ProposedCrewTimeRecord with optional times for each stage - Create a jinja2 template to allow the validator to chose the times or the average for each stage or to type in alternatives with comments Validate post - Receive the validated times for each stage and the comments for adjustments - Record a ValidatedCrewTimeRecord with crew-id, name, validator, times validated with comments for any manual amended, splits calculated, total time calculated.

Data model notes - Observed time events needs to be keyed on event, crew, stage, user. We can then allow multiple users to record an observed time. In the validation process we can work out the one validated record by choosing specific users or an average of observed times and record a full ValidatedCrewTime record.

The user can select which post they are at so they can only see boats that have yet to go to their post and only press the button for boats about to get to their post next.