FEATURE/FIX: GPS fix validity flag in loop() to prevent ghost crossings

[FabioRoss]

What problem are you trying to solve?

GPS receivers — including the uBlox-based modules recommended in the library's
README — continue emitting NMEA sentences even when they lose satellite fix.
The stale coordinates in those sentences are typically the last known position
(or sometimes (0,0) depending on the receiver's NMEA mode).

If loop() processes those stale coordinates:

• Ghost crossings: stale lat/lng may be on the wrong side of a sector line,
  triggering a spurious confirmed crossing
• Odometer spikes: the stale position may be far from the actual last known
  position, causing totalDistanceTraveled to jump by hundreds of meters
• Delta corruption: a GPS trace point at an incorrect position corrupts the
  reference lap comparison (Issue FEATURE: GPS-based real-time lap delta (gap to reference lap) #29)

The user typically knows whether the fix is valid — their GPS library exposes
a fixQuality or isFixed flag. But there's no way to tell DovesLapTimer
"this fix is bad, skip it" without refactoring the call site to skip loop()
entirely.

Skipping loop() at the call site means the user has to replicate the timing
tick inside their main loop — they may still want millisecondsSinceMidnight
to update, or they may need to call loop() for the state machine to progress
correctly.

Proposed solution

Add an optional bool fixOK = true parameter to loop():

int loop(double currentLat, double currentLng,
         float currentAltitudeMeters,
         float currentSpeedKnots,
         bool fixOK = true);   // backward compatible — default true

When fixOK == false:

• Skip odometer update (no distanceTraveled += haversine(...))
• Skip all crossing detection (checkStartFinish, checkSectorLine)
• Skip delta update (updateDelta)
• Skip circuit auto-load (if that feature is used — Issue [ON HOLD] FEATURE: GPS proximity circuit auto-detection (instant, no lap required) #35)
• Still update millisecondsSinceMidnight (time ticks regardless of fix)
• Still update prevFix* snapshot? Probably NO — a bad fix shouldn't become
  the Catmull-Rom pre-crossing control point

Alternatively: encode "fix invalid" as a distinct loop() return value (e.g. -2),
which some callers may find more natural. Default true parameter is simpler.

EXAMPLE USAGE:

// With TinyGPS++:
bool hasFix = gps.location.isValid() && gps.location.age() < 2000;
lapTimer.loop(
  gps.location.lat(),
  gps.location.lng(),
  gps.altitude.meters(),
  gps.speed.knots(),
  hasFix
);

Alternatives considered

1. Caller wraps loop() in an if(hasFix) check — simplest workaround.
   Downside: millisecondsSinceMidnight doesn't advance; state machine may
   stall if any internal timing depends on loop() being called regularly.

2. Separate method updateTimeOnly(unsigned long ms) — allows time to tick
   without running detection. Workable but adds API surface. The fixOK flag
   is more ergonomic: one call site, always.

3. Library auto-detects bad fix via coordinate sanity check (lat/lng == 0.0) —
   fragile. (0,0) is a valid ocean location; a module in Italy reporting
   (0,0) after fix loss is obvious, but the library can't reliably distinguish
   this from a module correctly reporting (0,0). User code knows best.

[TheAngryRaven]

Accepted — ghost crossings and odometer spikes from stale NMEA on fix-loss are a real problem on the exact uBlox modules the README recommends, and the user's GPS library always knows fix validity. The bool fixOK = true default keeps it fully backward-compatible. Design:

When fixOK == false:

• Skip odometer accumulation (no totalDistanceTraveled += haversine(...))
• Skip all crossing detection (checkStartFinish, checkSectorLine)
• Skip the delta update (FEATURE: GPS-based real-time lap delta (gap to reference lap) #29)
• Do NOT update prevFix* or positionPrev* — your instinct is right; a bad fix must never become the Catmull-Rom pre-crossing control point, and it must not become the origin for the next haversine
• Still advance millisecondsSinceMidnight — time ticks regardless of fix
• Return -2 when skipped, so callers get a clear "fix ignored" signal alongside the existing 0/-1. Keep the bool param too (one call site, always).
• Forward the flag through CourseManager::loop() and WaypointLapTimer::loop() so the whole stack honors it.

The special one — guard the re-acquisition fix, or you trade a ghost crossing for a weird delta + odometer spike. This is the bit that's easy to miss: skipping bad fixes is only half the job. When the fix comes back, the very first good fix sits potentially hundreds of meters from the last good position (the kart kept moving through the dropout). If you process it normally:

• the odometer adds one giant straight-line haversine across the whole gap → distance spike, and
• the FEATURE: GPS-based real-time lap delta (gap to reference lap) #29 delta trace gets a huge position/time jump → either a bogus sampled point or a nonsense getLapDelta() reading as the nearest-point search snaps to the wrong reference point.

So treat fix re-acquisition exactly like firstPositionReceived: the first good fix after any fixOK == false run should re-seed positionPrev/prevFix without accumulating that odometer delta and without feeding the delta trace. Implement with a one-shot flag — set lostFix = true whenever fixOK == false, and on the next good fix consume it: re-seed position state, skip the distance + delta update for that single tick, then resume normally. Net effect: the dropout interval contributes no distance and no delta garbage, and timing picks up cleanly from re-acquisition.

Tests (Layer-2):

• fixOK == false near a sector line does NOT trigger a crossing (the ghost-crossing case)
• odometer does not spike across a dropout, and does not spike on the re-acquisition fix either
• millisecondsSinceMidnight still advances while fixOK == false
• delta (FEATURE: GPS-based real-time lap delta (gap to reference lap) #29) produces no garbage value across a dropout + re-acquisition

To merge: Doxygen on the new param + the -2 return semantics, ## [Unreleased] CHANGELOG entry, README mention (and the TinyGPS++ isValid() && age() < 2000 example is a good one to include). One logical change per PR, branch off master.

---

Generated by Claude Code