fsTimer documentation

Section 1 Installing fsTimer
Section 2 Overview
Section 3 Checklist for timing with fsTimer
Section 4 Detailed descriptions of fsTimer components
4.1 Setting up for a new race
4.2 Importing preregistration - details
4.3 Registration - details
4.4 Compiling registrations - details
4.5 Race timing - details
Section 5 Additional details for developers

Section 4.5 - Race timing - details


Finally we reach the details about the Timing window. When loading the Timing window, you will have to specify:



Once these have been specified, the timing window loads. The first thing you will do in a race will be to press "Start!" at the exact moment that the race begins. This starts the clock ticking (of course, in reality it uses the system clock which is always "ticking") and all marked times will be recorded relative to this moment. When you press "Start!", to the right of that button is "t0:" and a very long number will appear after that. This long number is the starting time for the race, given in seconds since the Unix epoch began. What that means isn't really important.



Pressing the "Edit" button next to the "Start!" button will allow you to change the t0, to adjust the start time for the race. Exercise caution doing this, as the old time is not saved and this change cannot be (automatically) undone. It is very unlikely that you will ever need to modify the start time, but if you do, then simply add or subtract to the large t0 number the number of seconds that you wish to change the start time by. For the image above, if we wanted to move the start time to be 5 minutes earlier, then we would subtract 300 seconds from the t0 and change it to be 1384731797.14. It is important to note that fsTimer records all times relative to this t0 start time. If you change t0 mid-race, it will not adjust any times that have already been recorded.

At the bottom of the window in the screenshot above it says "0 racers checked in out of 26 registered." The 26 registered are the number of unique IDs in the timing dictionary. This will generally be the number of people registered for the race, but can differ from the actual number if, for instance, there were overloaded IDs that were de-assigned during compilation. It can also differ from the actual number of racers on the course if there are racers who register and pick up a bib (and thus are in the timing dictionary), but don't end up running the race. As you check in racers (by entering their bib numbers into the timing window), if the bib number is one of those in the timing dictionary, then the number at the bottom of the window will increment.

All of the tasks related to the timing process take place in the entrybox at the bottom of the window. Make sure that you have clicked in that entrybox, otherwise any input (like pressing spacebar to mark a time, or entering a bib ID) will not be recognized.

Pressing spacebar (or whichever key you chose for marking times when opening the Timing window) will record the current time (relative to the Start! time) as a blank time in the window. The time is listed as hr:min:sec, and the "ID" column will be blank. As multiple times are marked, they will be recorded in their proper order.



This is the stack of marked times, and their corresponding bib IDs must be entered (although there is no hurry; as long as the record of bib IDs stays synchronized with the list of marked times, you can enter them all in at your convenience). In our suggested finish line design in Section 3.1, Crew 2 is the individual entering the times. Bib IDs are entered by typing them into the entrybox (the same one that must be selected to mark times) and pressing Enter. Note that if you use a USB barcode scanner, then the default behavior of most (all?) USB barcode scanners is to type whatever is in the barcode followed by Enter, so the software will work very naturally with a barcode scanner. Entering "109" will assign that bib ID to the oldest time that has not yet been assigned an ID:



Thus as long as the bib IDs are entered in the same order that they crossed the finish line, they will be correlated with their correct marked times. Entering "101" and "110" fills in the IDs for the next two times:



If an ID is entered and there aren't any "blank" times available (that is, any times that haven't already been assigned bib IDs), then it will be assigned the current time. Here we have entered "102" without any un-assigned marked times, and so the current time (8:32) is given to that entry:



Marked times can also always be filled with the pass ID (we usually choose 0) the same way it would be assigned to a bib ID:



As a note, if you just hit Enter without anything entered into the entrybox, then it will do a usual ID entry where the ID is a blank string ''. Blank IDs are not included in the results printouts (they behave in the same way as the pass ID).

The "Edit" button on the right side of the window allows you to edit the ID and/or time of any of the marked times. For instance, suppose one of the pass IDs used in the above screenshot was a placeholder for a runner whose bib ID could not be obtained immediately (see Section 3.1 for some situations where you might want to do this). We can later go back and replace the pass ID (the 0) with his true ID by pressing "Edit", and replacing "0" with his true ID:



As the red warning states, you should exercise extreme caution when making these edits, as they cannot be undone if you forget the original values.

There are actually two editing modes in the timing window. The first is shown above, when a single entry is selected and "Edit" is pressed. Then, the ID and time of that entry can be modified as desired. Alternative, an entire block of times can be modified together. This is accomplished by selecting the block of times (using shift) and pressing "Edit":



The block edit window allows for all of the selected times to be adjusted forward or backwards by a certain amount of time. In the screenshot above, pressing "OK" will add 25 seconds to all of the times:



The "Save" button on the right saves the results (t0, times, and bib IDs) to a file whose name will include the date and time that the Timing window was opened (this way, results will never be accidentally overwritten if you open the Timing window at another time). If the Timing window was opened on Jun 1, 2013 at 2:10pm and 30 seconds, then the results are saved to a file project_name_Sat_Jun_1_141030_2013_times.json.

It is a good idea to save periodically during timing in case something catastrophic happens (like the computer dies), however keep in mind that any time the entrybox in the timing window is not selected (for instance, because you have used the mouse to press the "Save" button), no times may be marked and no IDs may be entered, until the mouse has moved back to select the entrybox. In our suggested finish line setup (Section 3.1), Crew 1 is operating the computer while Crew 2 enters the bib IDs with the barcode scanner. Crew 1 would need to tell Crew 2 to stop scanning for the period of time it takes to save, and then to resume when the entrybox has been reselected.

If you need to reload the results in the Timing window (for instance, to re-print the results after making edits to the registration database), then the "Resume" button is used to load a previously saved results file. You would press Resume, and then load the previously saved file (project_name_Sat_Jun_1_141030_2013_times.json above). Keep in mind that "Resume" will load the marked times, the bib IDs assigned to them, and the Start time. It will not load the timing dictionary (this will still be whatever was selected when opening the Timing window), which allows you to make edits to the timing dictionary, and then re-load the times. We'll give some more details about this later below.

Finally, the "Print" button automatically generates nicely formatted results printouts. As mentioned in Section 2.5, it does not physically print the results, rather it saves them (the overall results and the divisional results) as html files in the project directory. These html files can then be opened in any web browser and printed from there. The actual filenames will again incorporate the date and time at which the Timing window was opened, so as to not be automatically overwritten by a later session in which the Timing window is opened. With the same date and time as above, the filenames would be project_name_Sat_Jun_1_141030_2013_alltimes.html for the overall results and project_name_Sat_Jun_1_141030_2013_divtimes.html for the divisional results.

The overall results might look like this:



The results will automatically be sorted into places, and the name, age, and gender will be filled in from the timing dictionary. If some information is blank in the database, this is not a problem; it will simply be left blank in the results. For example, 5th place in the screenshot above (bib 128) had a blank name in the database, so the name is left blank in the results. 4th place (bib 101) had a blank gender in the database, so it is blank in the results. Notice also bibs 110 and 120. These were the overloaded IDs from Section 4.4 that were left unassigned to any particular racer. They still show up in the results, however they do not have any name/age/gender associated with them. The same will be true for any bib that is not in the registration database, for example, if someone shows up after registration has closed but is given a bib anyway and runs the race.

Notice also that the "pass" IDs (0) do not show up in the results. Any times with pass IDs will be ignored when creating the results.

A final note about the overall results: If, for whatever reason, a bib ID is entered twice (and thus associated with two times), the results will use only the faster of the times.

The divisional times are automatically generated using the age and gender information in the timing dictionary, and the divisions specified when creating the new project. The printed results will look something like this:



Notice that any IDs that do not have both age and gender in the timing dictionary will be left out of the divisional results. From two screenshots up, bibs 109, 110, 101, 120, and 103 do not have complete gender and age information and so are left out of the divisional results. (In a normal race setting, there will usually not be very many entries missing age and gender information - this will usually only happen if there are errors from the people entering information at the registration table, or for individuals that showed up after registration had already closed and were just handed bibs without being entered into fsTimer).

The "Save CSV" button will save the same results (all times, and divisional times) to csv files. The names will be the same as the html files, except the extension.

We will now briefly discuss making corrections to the results, which can typically only be done after the race has finished.

As mentioned above, times and their associated bib IDs can be edited using the "Edit" button in the timing window. You can edit times so that they are no longer in order in the window, like 104 in the screenshot below, and this is not a problem; fsTimer will correctly sort them when generating the results printouts:



When editing times, it is important to keep the leading 0 ("0:22:37" instead of "22:37") or the results will not sort correctly.

Making corrections to anything other than bib IDs and times will require a few more steps. Some examples of the types of corrections you might want to make are: Correcting all of these errors requires making edits to the registration database, which requires leaving the timing window. The following is the procedure you would follow: When all necessary corrections have been made, the whole timing process is finished!

This completes all of the details about using fsTimer - You are now ready to time the race! The next section contains details about the source code that will be useful only for those who are interested in modifying the code. Do not bother with that section unless you are planning to do actual coding on fsTimer.

Continue on to Additional details for developers.