sailing-analytics/wiki/racelog-tracking.md

RaceLog Tracking

RaceLog-tracking allows fully self-sustained tracking with the Sailing Analytics, with no need for an additional tracking provider. Instead, any source of positional data (e.g. smartphones, providers such as Igtimi without race management) can be integrated.

The term itself should be revised at some point, and currently refers to the technical implementation on how master data related to a race (e.g. competitor registrations, course layout) is recorded and stored persistently: namely in a RaceLog.

This is the second iteration of implementing this idea. For previous documentation, see smartphone tracking.

[[TOC]]

Development Infos

Currently, RaceLog tracking has not been merged into the master branch. Instead, refer to the following branches:

• ftes-rltracking: The main RaceLog-tracking development
• ftes-rltracking-equestrian: Serves as a reference implementation of a tracking adapter built for RaceLog-tracking.

Architectural Overview

The basic architecture of Racelog-tracking is presented in this diagram (download as PDF):

Following the numbers in the diagram, this is a possible race log tracking scenario:

1. The race is defined through events that are added to the RaceLog.
2. The RaceTracker is created.
3. As soon as the "StartTrackingEvent" is added to the RaceLog, the RaceTracker creates the TrackedRace.
4. Tracking devices submit GPS fixes to the tracking adapter.
5. If these fixes match the mappings defined for this race in the RaceLog, they are added to the TrackedRace.

Not all identifiers represent actual class or bundle names. For a more technical documentation, refer to the JavaDoc in the various *.racelog.tracking packages and the com.sap.sailing.domain.racelogtrackingadapter bundle. The following interfaces and classes are good starting points:

• DeviceIdentifier
• DeviceIdentifierSerializationHandler
• Revokable
• DeviceMappingFinder
• PingDeviceIdentifier, PlaceHolderDeviceIdentifier

AdminConsole Components

Currently, RaceLogs can be filled with the race metadata via the RaceLog Tracking panel in the AdminConsole. Here one can denote RaceColumn/Fleet combinations within RegattaLeaderboards for RaceLog-tracking, register competitors, define the course layout, add device mappings, and finally start tracking.

When thinking about smartphone tracking, it would of course be a good idea to also integrate similar functionality into the tracking app. Some parts of the communication (registering competitors, defining the course, mapping devices) can be handled via the existing RaceLog communication mechanism. Other parts (creating the Leaderboard structure in the first place, adding the RaceLog tracker) have to be dealt with separately, e.g. via a REST API.

Steps for setting up a racelog-tracked race in the AdminConsole

1. Precondition: A RegattaLeaderboard with one race (and automatically RaceLog) has to exist.
2. Denote the race for racelog-tracking and add a race tracker.
3. Register competitors for the race (these need to exist in the CompetitorStore).
4. Define the course layout, including the definition of marks. Optionally, the course layout and competitor registrations can be copied from a different race in the same leaderboard.
5. Create the mappings from tracking devices to competitors and/or marks.
6. Start tracking the race.
7. Change the course layout, or add device mappings during tracking. Removing mappings will not have the effect of removing the fixes from the race, as this is not currently supported by the underlying GPSFixTrack.
8. Stop tracking (stop the tracker).

ToDos

Archiving old Races

Since RaceLog-tracking allows for fully independent tracking, storing and reloading of races, it may be a good foundation for archiving old races. Currently, we rely on tracking providers to retain all data indefinitely, so that it can be reloaded, e.g., after restarting the server. Also see bug 2 for more details.

Smartphone Tracking

RaceLog-tracking provides the server-side abilities for independent tracking. Therefore, using smartphones for tracking is one possible application. So far, there is no implementation in terms of a smartphone app. The relation to the existing RaceCommittee app has be be considered, as both should share a common code base, and as there should be certain points of integration (e.g., first defining the race in the tracking app, then setting the start time in the RC-app, and finally tracking one boat with that smartphone - again with the tracking app).

The first option is to simply share code through a Android library module, the second option is integrating everything into one app with two launchers (one for tracking, one for the RaceCommittee functionality).

How to create a Tracking Adapter

By using the OSGi service registry, adapters are completely decoupled from the Sailing Analytics code. In future, it should be possible to simply deploy one additional bundle to the OSGi server in addition to the Sailing Analytics bundles. This requires provisioning the relevant bundles containing interfaces for the development of the adapter.

The first attempt so far (ftes-rltracking-equestrian branch) is completely restricted to one bundle. However, this is a branch branched from master, and the new bundle has been added to the existing launch configurations and build and deployment descriptors (pom.xml, feature.xml, raceanalysis.product). This makes developing and testing easy, but is not in line with the goal stated above.

Steps for creating an adapter:

1. Create a new project: com.sap.sailing.domain.<adaptername>. Think about duplicating an existing project, such as com.sap.sailing.domain.racelogtrackingadapter. In this case, don't forget to adapt the project's pom.xml, META-INF/MANIFEST.MF and .project files.
2. Add the new project to the maven build in java/pom.xml.
3. Add the project as an auto-start bundle to the eclipse launch configs. The bundle needs to be started before the central com.sap.sailing.server bundle, for which currently a startup-level of 3 is sufficient.
4. Add the bundle to the com.sap.sailing.feature/feature.xml, and also to the com.sap.sailing.feature.p2build/raceanalysis.product with the same startup properties as before.
5. Implement a DeviceIdentifier and the appropriate DeviceIdentifierSerializationHandlers (refer to the JavaDoc of DeviceIdentifier).
6. Register your serialization handlers through the OSGi service registry (refer to the JavaDoc of DeviceIdentifierSerializationHandler for an example on how to do so).
7. Add some kind of Servlet or similar that adds fixes to the GPSFixStore by calling storeFix(DeviceIdentifier device, GPSFix fix).
8. Fire up the server, let OSGi work its magic, define the race metadata and start adding fixes.