"Laptimer" Copyright 1994, Roger Ford.

Comments/bugs to raford@oracle.com,
or Roger Ford, c/o Oracle UK, Bittams Lane, Chertsey KT16 9RG, UK.

Laptimer is a stopwatch program written in OPL for the Psion Series 3a.
It stores and displays up to 99 lap times for 3 riders/drivers,
with options to save these to text files.

BATTERY WARNING: While Laptimer is running, the Psion cannot auto switch-off,
even if laptimer is not the "front" application.  Ensure that you pause 
Laptimer by pressing "Menu" before switching to another application,
lest you forget that it is running!

This program is shareware. All revenues go to my motorcycle racing
effort. If you like it, please send 5 UK pounds or $7.50 US to me
at the address above. This is a very fair price - please make the
effort, to support shareware and motorcycle racing!  Registered users
will receive updates as available. I can accept cash or cheques in
either currency.

Files supplied
	Laptimer.txt   - this file
	Laptimer.opl   - main source file
	Laptimer.opa   - translated application
	Laptimer.pic   - icon file (only needed if you wish to translate the OPL)

Installing Laptimer

These instructions are detailed for the novice user. Experienced
Psion users will probably not need them.

1.	Copy Laptimer.opa to the \APP\directory on any drive (A:, B: or M:).

2.	Install "Laptimer" from the system screen. Position the "cursor"
at the icon after where you want to install the laptimer (stopwatch) icon.
Select "Apps", "Install" from the menu, or press Psion-I. Select 
"Laptimer.opa" in the install dialog, and press Enter.

If you wish to install and/or modify the source, follow these additional 
steps:

3.	Copy Laptimer.pic into the \PIC\ directory on your default drive.

4.	Copy Laptimer.opl to the \OPL\ directory on any drive.

5.	Press "System" and choose the "Laptimer" file under the "Program"
item (or use "Control-Word"). Choose the "Translate" option from the
menu (Psion-T).  Exit program with Psion-X. Since this produces an OPA 
application, you are not given the usual option to run the program after
translation.


Using Laptimer
--------------

Laptimer will time up 3 riders/drivers from a simultaneous start.
It allows you to store up to 99 laps per rider, and list these to
the screen or a file. For close-spaced riders, you need only hit the
space bar as each passes, then enter their order afterwards.

Basic instructions: 

	- Choose "Run" from the menu at the start of the race.
	- Press the "1", "2" and "3" keys as each driver passes a fixed point.
		Remember the order of the riders, as you will need to press the same key
		as they next pass.  Entering the driver names (a menu option) makes this
		much easier.
	- Alternatively, press the space bar as each driver passes.  Then enter
		the order they passed. If "Racer3" passes first, followed by "Racer1"
		and "Racer2", you would type "312"
		
The display:

When the timer is running, three displays are show for each 
rider/driver.  The first line shows the number of seconds  for
the most recent lap.  The second line is the best lap time so far
(this and the previous line will be blank until after the first lap).
The third line is continuously updated, and shows either the time
for the current lap or the total time since the start (see below).

Menu options allow you to name the riders, and set details about
the track and/or distance, which are used to calculate average speeds.
Where rider names are specified, you can choose to use their initials
rather than the "1,2,3" keys (rider names must have unique first
characters for this option to succeed).

The diamond key swaps between "lap" and "total" modes.  In "lap" 
mode, the bottom (constantly updated) display shows the time for
the current lap. In "total" mode it displays the time since the start.

Menu Options:

File
	Save
			Saves the current run to a file, with suffix .txt in 
			the \WRD directory. The best way to look at this file is using
			the "text editor". See the Psion user guide for details.
	Show File
			Invokes the text editor to display the contents of a saved file.
			It may be necessary to create the text editor alias for this to
			work. See the 3a user manuals for details of how to do this.
Action
	Run
			Starts a new run. Discards any existing lap times unless "autosave"
			mode is on (see preferences), in which case it appends all times
			from the previous run to the autosave file. If the autosave file
			has not been specified, a dialog will allow you to choose one.
	List
			List lap times (and speeds if circuit and/or distance have been
			specified).
	Continue
			Only present after "run". Continues the stopwatch display. Note
			that the timer is not paused in any way during other menu options.
			In fact, the timer never stops running, it is just reset by the
			"run" option. However, the Psion auto switch-off feature is able
			to work when a menu is showing, but not when the screen is being
			updated continuously with times.
Setup
	Racer Names
			Set names to appear on displays and files.
	Circuit
			Choose the circuit for this and future runs
	Distance
			Choose the lap distance. Overridden by "Circuit" if used later. 
	Add Circuit
			Specify the name and distance for a new circuit.
			This will be saved to a data file "\OPD\Laptimer.opd", and will
			appear in all future runs.
	Clear All Circuits
			Permanently deletes all circuit definitions. To return to my
			defaults (UK bike race circuits), delete the above data file.
	No. of riders
			Needed where the spacebar is being used to enter laps. Can be set
			to 1, 2 or 3.
Special
	Preferences
		Auto save
			If set to "Yes", whenever a new run is started, the previous run
			will be saved to a file. You will be prompted for the name of the
			auto-save file as soon as you set this option.	
		Distance Units
			Can be set to miles or km. Only affects displayed distances and
			speeds, no actual conversion of units is attempted.
		Directory for saved files
			Defaults to "\WRD".
	  (Note: preferences are not saved, they must be set for each run.)
	Clear Best Laps
			Useful if a very short lap has been entered accidentally.
	Use Initials
			Where the rider names have unique first initials, this setting
			allows you to use the rider's first initials rather than the 1, 2
			and 3 keys.
	Exit
			Prompts for confirmation, then exits. Lap times are not saved, 
			even if auto save mode is on. You must start a new run to force
			an auto save.

NB: hitting the lap keys as fast as possible will usually give lap
times of around 0.19 seconds. This does *NOT* indicate that the timer
is only accurate to that level, it merely indicates the time taken
to process a lap event. Actually sampling of the keyboard and clock
is much faster, accurate to the 1/32s granularity of the internal clock.

Bugs
----

The following bugs/limitations are known as of 12th September 1995:

1. The whole concept of starting in the menu and returning to it after a 
choice is inconsistent with other Psion apps. Long term, I would like to 
convert this to a file-based app, where a log file is "opened" for the day, 
and all races are saved to that file.

2. There is no facility to save preferences to file.

3. There may be a slight delay between pressing "run" and the timer
actually starting. This is pretty irrelevant for racing, where the 
first lap is not significant, but could be important in other applications.
Delay is no more than 0.5 seconds.

4. Laptimer invokes the text editor to "show files".  If you exit
from the editor by pressing "system", then go back into Laptimer from
the system screen, you will return to Laptimer - NOT the text editor,
which will remain open in the background. Similarly, stopping Laptimer
by hitting delete on the system line can leave the editor open.

5. Ideally, an associated telemetry system should beam the lap times to
an on-bike display, for immediate feedback to the rider.

6. The battery drain problem is nasty. The Psion assumes that the app is
busy calculating and will not switch off. I need some sort of "yield"
function that will tell the OS to turn off if nothing else has happened.

This program is copyright. Source code is provided and may be modified
for your own personal use. Modified code should not be distributed
without my agreement.

SUPPORT SHAREWARE!  Send 5 UK pounds or $7.50 US to:
Roger Ford, c/o Oracle UK, Bittams Lane, Chertsey KT16 9RG, UK.
raford@oracle.com