High-level Proposal for SoloTimer

[Brian G]

Purpose
-------------------------------------------------------------------------

The goal of SoloTimer is to provide a reliable cross-platform, easy-to-
learn timing and scoring software for autocross and rallycross
events. The software must run on modern but not cutting edge
computers typically affordable for such low-to-medium revenue
programs. It must accommoodate an agreed-upon majority of event
styles without compromising its goals for very narrow use cases.


Overview
-------------------------------------------------------------------------

In listening to customers of MotorsportReg.com, I have heard loud and
clear that there is an unmet need in timing and scoring software for
solo events. While Solo has a complex set of rules and a wide variety
of event-day implementations, SoloTimer will begin with the 80/20 rule
in mind, focused on building a rock-solid, reliable core on modular
programming principles and modern software design and then focus on
growing the feature set. To express our goals mathematically like
nerds, it would be:

Reliability >> Usability >> Flexibility

It can be incredibly difficult to cultivate enough trained timing and
scoring staff for any given season. The end result is usually the
same handful of people running the computers each event which puts the
club in a predicament if those volunteers are unable to attend or move
on to other pursuits. It is therefore more important, once the basic
functional requirements are met, that the software is easy to use than
it is flexible. This will help make T&S as easy as shagging cones.

I have a background in usability and interaction design and can
contribute resources here with prototyping, wireframing, user
observation and so forth. All the stuff that comes before the UI.


Moving Pieces
-------------------------------------------------------------------------

Built upon modern programming principles, SoloTimer will use off-the-
shelf software and libraries to leverage existing work. By specifying
interfaces rather than implementations, we will pave the way for
future development to handle situations we may not consider today.
Generally speaking I'm advocating a loosely coupled server-client
architecture. The pieces might roughly be defined as:


1. Timing and Scoring Server

The most critical component of the system, this service would run on
the computer physically attached to the timing hardware, recording the
inputs into a relational database. My recommendation is for
PostgreSQL which has a very liberal open source license (BSD) and
extensive date/time datatype and function support that would be quite
useful for timing and scoring. It runs very reasonably as an embedded
database for a system and requires no real maintenance making it ideal
for an installed application.

On top of the relational database would be a service layer or API that
we define and expose to (authenticated) clients. I believe there
would be value in adhering to something simple such as a REST API
which leverages the verbs of HTTP and web-style data transfer (XML and
JSON are the two common formats) as the communication medium. Using
simple, text-based, standards-based protocols and communication
channels mean we can leverage existing libraries and not reinvent the
wheel. If we're experiencing problems with a request for example,
there are dozens, if not hundreds, of ways to debug an HTTP session.

The core would need to support an adapter pattern so any timing
hardware could be plugged in (commercial or home-built). We need to
understand the capabilities of common systems. These adapters need to
be mockable for unit testing so we can emulate live data without
actually running an event.


2. Timing and Scoring Client

The most important client interface is used by one or more timing and
scoring volunteers to monitor results, make adjustments (in the case
of penalties, DNFs, etc) and verify results. Timing should support
recording n segment times as wireless transmitters drop in price and
more than just a start/finish becomes more common. I don't think it's
important whether this is a separate program from the following
clients, but they should each have their own specialized view when
there are enough computers. This is the first client to be built as
it's the must-have functionality for actually timing the event.

I believe we can build an online backup system (perhaps using
something a la Amazon S3) to allow a T/S volunteer to back up their
database remotely or retrieve it as needed for a fresh install or
different computer. The laptops used for T/S are not always treated
well: inclement weather, they get dropped or stolen or they simply die
of old age. We should make it easy to protect that data and
centralizing it to a reliable source would be a good first step. Make
it one-click.

This client would also be probably the principal report generator
although with the open API you could export the raw data and then
process it however you like. As Nick mentioned, XML with XSLT would
be very powerful and a handful of default XSLTs would provide a
starting point for organizations to customize for their use.


3. Registration Client

In an ideal world, everyone would pre-register online, like at
MotorsportReg.com. :) Until then, we need the ability to add, edit
and delete registration data on-site. It's critical for a strong
import and export feature here as well as an interface to synchronize
with a remote system (interface TBD such that *any* registration
system could be integrated). Nothing particularly mind-blowing here,
but we want to separate the responsibilities to spread the work
around.

Automating the workflow via barcodes or RFID or some other mechanism
here makes sense but we should be cost-conscious. Some hybrid such
as 2D barcodes which could include more information (like their ID
along with car number, class, etc) are also a possibility. Readers
are relatively inexpensive and there are even libraries that can read
a barcode via a webcam attached to a computer. I have some experience
in an RFID project and while the technology definitely has a future,
it can still be rough to work with, especially when it comes to
distance from reader to tag. It does not suffer though from things
like inclement weather which is nice.


4. Announcer Client

With the data that can be stored in the relational database, there are
a thousand useful facts that could be culled on the fly for an
announcer. Information about historical runs, how they're doing in
the season, who their main competition is and their deltas. With a
client/interface dedicated to this, something really impressive could
be built to make the play-by-play as good as a professional sports
team announcer (or... at least as informed! :)


5. Leaderboard Client

As I mentioned previously, my consulting company built a Flash-based
leaderboard for the DARPA Grand Challenge which was displayed on
plasma TVs at the event. It showed updated status, position and
background information on the entrants. This could be viewed on a big
TV but it could also be accessed over a local WiFi network by
competitors as well to access T/S data and keep track of how the
results are shaping up. I think this has a lot of potential despite
being a low priority but I think bigger programs would appreciate
this.



Development Methodology
-------------------------------------------------------------------------

Because a run cannot be undone nor re-run, it is important that the
software be demonstrably reliable. We can achieve this through an
iterative, test-driven programming methodology. It is not important
that we adhere necessarily to every tenet of something like Agile for
example, but I believe we need to focus on the following:

* Agree upon interfaces
* Write tests for those interfaces
* Write implementations

Code should be compiled and tested on commit so that everyone will be
alerted when non-functioning code is checked into the source control
system. Continuous integration may be idealistic but we must
absolutely have complete and robust test coverage. We do not want to
ever lose a single run.

I'm personally a fan of Trac but have also worked with Unfuddle and
github is quite popular these days. I don't think it matters much so
long as it supports our effort without much overhead.


Implementation
-------------------------------------------------------------------------

Of the existing projects in motion, I know we have at least a couple
of Java-based apps, a Python, a REALBasic, a C++/.NET and there are
probably a few more. I am not a Java developer but I believe it has
the best chance of being a reliable, cross-platform timing and scoring
server (the core component) that can be developed by a wide audience.

I do not believe the clients need to be Java and for UI reasons, they
may be better if they are not. I'm thinking of Adobe AIR apps which
leverage Flash and/or Flex because the UI can be highly customized and
very powerful but we would need to look into reliability as well as
the ability to work with potentially large datasets. Keeping the
80/20 rule in mind however, I would suggest we begin with a Java
client for the T/S client in order to focus our development effort in
a single, narrow field. I believe it's the open communication
patterns and API that will allow us to innovate quickly in the future
but we should stay focused at the outset. The hardest part for a
community project is to get to a first functional build and reducing
the complexity to make that happen as quickly as possible is critical
to building momentum.

On a final note, I have stressed cross-platform here even though I
think it's something of a red herring. Mac's comprise around 8% of
the market (although probably more of the laptop market?) but I
sincerely doubt anyone is going to bring out their Mac Book Pro for
use as a T/S computer. Realistically Windows is the target platform
of choice. However, Java is a solid, common language with a LOT of
third party support and one that I think we can successfully rally
around for the relatively small core server.


Next Steps
-------------------------------------------------------------------------

Pros, cons, opinions, flames? Let's hear 'em! :) I'd also love to
start throwing out some assumptions or understandings and seeing if
they hold water. Such as:

1. How many programs have a *single* laptop at an event? Are they
really running with no backup hardware? If we find this to be common,
we will need some kind of a mashup-client that has multiple functions
in one screen.

2. We can probably build a feature list out of existing commercial
apps... I know things like barcodes and so forth will be on that
list. From that feature list we can start to model our domain, API
and schema.

3. Is anyone a die-hard Java hater that would pack up and go home if
that was the platform?

4. What else?

[digitalseance]

On Jun 26, 2:04 am, Brian G <brian-goo...@vfive.com> wrote:
> On top of the relational database would be a service layer or API that
> we define and expose to (authenticated) clients.  I believe there
> would be value in adhering to something simple such as a REST API
> which leverages the verbs of HTTP and web-style data transfer (XML and
> JSON are the two common formats) as the communication medium.  Using
> simple, text-based, standards-based protocols and communication
> channels mean we can leverage existing libraries and not reinvent the
> wheel.  If we're experiencing problems with a request for example,
> there are dozens, if not hundreds, of ways to debug an HTTP session.

While proven and reliable, REST and SOAP calls are expensive to make.
In the portal world, we put lots of emphasis on making minimal calls
to web servers due to the overall expensive operations these types of
calls require. While I'm sure we're all familiar with the HTTP
methods, perhaps some research should be put into JMS or our own
custom messaging to minimize the data that must be transfered and
interpreted.

> Timing should support
> recording n segment times as wireless transmitters drop in price and
> more than just a start/finish becomes more common.

While I don't disagree, I feel this functionality should be put aside
until a fundamental and elementry version is functioning. Perhaps it
could be addressed in release 3.

> I believe we can build an online backup system (perhaps using
> something a la Amazon S3) to allow a T/S volunteer to back up their
> database remotely or retrieve it as needed for a fresh install or
> different computer.  The laptops used for T/S are not always treated
> well: inclement weather, they get dropped or stolen or they simply die
> of old age.  We should make it easy to protect that data and
> centralizing it to a reliable source would be a good first step.  Make
> it one-click.

Perhaps just a backup to a zip is ideal. One click is good, but I have
yet to be at an event that had internet access from the timing
vehicle. Creating the backup file can be done easy enough but the
transfering of the file off the computer, while "neat", isn't feasible
during an event other than the user coping the backup file
themselves.

> 4. Announcer Client
>
> With the data that can be stored in the relational database, there are
> a thousand useful facts that could be culled on the fly for an
> announcer.  Information about historical runs, how they're doing in
> the season, who their main competition is and their deltas.   With a
> client/interface dedicated to this, something really impressive could
> be built to make the play-by-play as good as a professional sports
> team announcer (or... at least as informed! :)
>
> 5. Leaderboard Client
>
> As I mentioned previously, my consulting company built a Flash-based
> leaderboard for the DARPA Grand Challenge which was displayed on
> plasma TVs at the event.  It showed updated status, position and
> background information on the entrants.  This could be viewed on a big
> TV but it could also be accessed over a local WiFi network by
> competitors as well to access T/S data and keep track of how the
> results are shaping up.  I think this has a lot of potential despite
> being a low priority but I think bigger programs would appreciate
> this.

I see these two as the same thing. Combining these features to one
display would be the most beneficial.

> Development Methodology
> -------------------------------------------------------------------------
>
> Because a run cannot be undone nor re-run, it is important that the
> software be demonstrably reliable.  We can achieve this through an
> iterative, test-driven programming methodology.  It is not important
> that we adhere necessarily to every tenet of something like Agile for
> example, but I believe we need to focus on the following:
>
> * Agree upon interfaces
> * Write tests for those interfaces
> * Write implementations

Here is where I have a fundamental disagreement. I'm from the school
of Model-Driven-Development (MDD) where you design two or three times
and code once. While test-driven-development (TDD) has its place,
simply developing software to "work" and pass a junit is not good
software. The goal of this deliverable is to ensure it can run on a
somewhat old laptop without a lot of horsepower, thus writing it to
"work" isn't necessarily going to deliver a useable product.
Developing in design patterns and interfaces cannot be done
efficiently with TDD. I feel it is *imperative* that proper UML and
design documentation be produced before any code is really written. I
truely believe that 1oz of design is worth 1lb of support and
reusability. It also helps flush out application design flaws at an
early stage instead of having to realize it 2/3 of the way through and
have to re-code 1/2 the project to compensate for the flaw.

Being a "public" project with mutiple developers contributing code and
the lack of a real testing team, automated testing (aka junits or the
like) is imperative and I definitely agree that these tests should be
developed and utilized heavily...even though I usually skip these at
work ;-)

> Implementation
> -------------------------------------------------------------------------
>
> Of the existing projects in motion, I know we have at least a couple
> of Java-based apps, a Python, a REALBasic, a C++/.NET and there are
> probably a few more.  I am not a Java developer but I believe it has
> the best chance of being a reliable, cross-platform timing and scoring
> server (the core component) that can be developed by a wide audience.

I feel that java or C++ is going to be the only way to go to encompass
as many platforms as possible. I'm partial to java b/c it's what I
know.

> I do not believe the clients need to be Java and for UI reasons, they
> may be better if they are not.   I'm thinking of Adobe AIR apps which
> leverage Flash and/or Flex because the UI can be highly customized and
> very powerful but we would need to look into reliability as well as
> the ability to work with potentially large datasets.  Keeping the
> 80/20 rule in mind however, I would suggest we begin with a Java
> client for the T/S client in order to focus our development effort in
> a single, narrow field.  I believe it's the open communication
> patterns and API that will allow us to innovate quickly in the future
> but we should stay focused at the outset.  The hardest part for a
> community project is to get to a first functional build and reducing
> the complexity to make that happen as quickly as possible is critical
> to building momentum.

While utilizing flash sounds neat, or trick, I can't see this falling
into the open source theology we're trying to take. Flash isn't an
open source format like PDF...at least not yet...

> On a final note, I have stressed cross-platform here even though I
> think it's something of a red herring.  Mac's comprise around 8% of
> the market (although probably more of the laptop market?) but I
> sincerely doubt anyone is going to bring out their Mac Book Pro for
> use as a T/S computer.  Realistically Windows is the target platform
> of choice.  However, Java is a solid, common language with a LOT of
> third party support and one that I think we can successfully rally
> around for the relatively small core server.

While I don't disagree windows is the target, we must not forget about
linux. As more clubs look to decrease costs, linux is going to start
cropping up more and more. Fortunately, linux will support any open
source language.

> 1. How many programs have a *single* laptop at an event?

Almost every club I've been a member of has used 1 and only 1 laptop
at an event. In fact, I had to convience CCSCC to move from Excel to
axware. :-/

> Are they
> really running with no backup hardware?  If we find this to be common,
> we will need some kind of a mashup-client that has multiple functions
> in one screen.

Yes, only the paper backup that I've seen. A mash-up client isn't
realistic. Real estate on a screen is valuable. I think "modes" or
"client" screens should be able to be selected without impeeding
background activity. A person running T&S should be able to switch to
teh announcement screen and back to the T&S screen without ever having
to stop timers or kill an event.


I'd like to see the software have small one-purpose panels that could
be added or hidden from view on demand. I'm thinking like the
"perspectives" in eclipse for "modes" or "clients" and "views" for
these one-purpose panels.



-Philip